Web.LTI13

A simple LTI 1.3 library. It's intended to be used by implementing routes for initiate and handleAuthResponse, and work out the associated parameters thereof.

This is written based on the LTI 1.3 specification <http://www.imsglobal.org/spec/lti/v1p3/ available from the IMS Global website>. Users will probably also find the <https://lti-ri.imsglobal.org/ LTI Reference Implementation> helpful.

Token contents/data model

data Role

Roles in the target context (≈ course/section); see LTI spec § A.2.2 and LTI spec § 5.3.7 for details

Constructors

Administrator

ContentDeveloper

Instructor

Learner

Mentor

Other Text

Instances

FromJSON Role

Defined in Web.LTI13

Methods

parseJSON :: Value -> Parser Role

parseJSONList :: Value -> Parser [Role]

ToJSON Role

Defined in Web.LTI13

Methods

toJSON :: Role -> Value

toEncoding :: Role -> Encoding

toJSONList :: [Role] -> Value

toEncodingList :: [Role] -> Encoding

Show Role

Defined in Web.LTI13

Methods

showsPrec :: Int -> Role -> ShowS

show :: Role -> String

showList :: [Role] -> ShowS

Eq Role

Defined in Web.LTI13

Methods

(==) :: Role -> Role -> Bool

(/=) :: Role -> Role -> Bool

data LisClaim

LTI spec § D LIS claim

Constructors

LisClaim

Fields

• personSourcedId :: Maybe Text

  LIS identifier for the person making the request.

• outcomeServiceUrl :: Maybe Text

  URL for the Basic Outcomes service, unique per-tool.

• courseOfferingSourcedId :: Maybe Text

  Identifier for the course

• courseSectionSourcedId :: Maybe Text

  Identifier for the section.

• resultSourcedId :: Maybe Text

  An identifier for the position in the gradebook associated with the assignment being viewed.

Instances

FromJSON LisClaim

Defined in Web.LTI13

Methods

parseJSON :: Value -> Parser LisClaim

parseJSONList :: Value -> Parser [LisClaim]

ToJSON LisClaim

Defined in Web.LTI13

Methods

toJSON :: LisClaim -> Value

toEncoding :: LisClaim -> Encoding

toJSONList :: [LisClaim] -> Value

toEncodingList :: [LisClaim] -> Encoding

Show LisClaim

Defined in Web.LTI13

Methods

showsPrec :: Int -> LisClaim -> ShowS

show :: LisClaim -> String

showList :: [LisClaim] -> ShowS

Eq LisClaim

Defined in Web.LTI13

Methods

(==) :: LisClaim -> LisClaim -> Bool

(/=) :: LisClaim -> LisClaim -> Bool

data ContextClaim

LTI spec § 5.4.1 context claim

Constructors

ContextClaim

Fields

• contextId :: Text
• contextLabel :: Maybe Text
• contextTitle :: Maybe Text

Instances

FromJSON ContextClaim

Defined in Web.LTI13

Methods

parseJSON :: Value -> Parser ContextClaim

parseJSONList :: Value -> Parser [ContextClaim]

ToJSON ContextClaim

Defined in Web.LTI13

Methods

toJSON :: ContextClaim -> Value

toEncoding :: ContextClaim -> Encoding

toJSONList :: [ContextClaim] -> Value

toEncodingList :: [ContextClaim] -> Encoding

Show ContextClaim

Defined in Web.LTI13

Methods

showsPrec :: Int -> ContextClaim -> ShowS

show :: ContextClaim -> String

showList :: [ContextClaim] -> ShowS

Eq ContextClaim

Defined in Web.LTI13

Methods

(==) :: ContextClaim -> ContextClaim -> Bool

(/=) :: ContextClaim -> ContextClaim -> Bool

data UncheckedLtiTokenClaims

LTI specific claims on a token. You should not accept this type, and instead prefer the newtype LtiTokenClaims which has had checking performed on it.

Constructors

UncheckedLtiTokenClaims

Fields

• messageType :: Text
• ltiVersion :: Text
• deploymentId :: Text
• targetLinkUri :: Text
• roles :: [Role]
• email :: Maybe Text
• displayName :: Maybe Text
• firstName :: Maybe Text
• lastName :: Maybe Text
• context :: Maybe ContextClaim
• lis :: Maybe LisClaim

Instances

FromJSON UncheckedLtiTokenClaims

Defined in Web.LTI13

Methods

parseJSON :: Value -> Parser UncheckedLtiTokenClaims

parseJSONList :: Value -> Parser [UncheckedLtiTokenClaims]

ToJSON UncheckedLtiTokenClaims

Defined in Web.LTI13

Methods

toJSON :: UncheckedLtiTokenClaims -> Value

toEncoding :: UncheckedLtiTokenClaims -> Encoding

toJSONList :: [UncheckedLtiTokenClaims] -> Value

toEncodingList :: [UncheckedLtiTokenClaims] -> Encoding

Show UncheckedLtiTokenClaims

Defined in Web.LTI13

Methods

showsPrec :: Int -> UncheckedLtiTokenClaims -> ShowS

show :: UncheckedLtiTokenClaims -> String

showList :: [UncheckedLtiTokenClaims] -> ShowS

Eq UncheckedLtiTokenClaims

Defined in Web.LTI13

Methods

(==) :: UncheckedLtiTokenClaims -> UncheckedLtiTokenClaims -> Bool

(/=) :: UncheckedLtiTokenClaims -> UncheckedLtiTokenClaims -> Bool

newtype LtiTokenClaims

An object representing in the type system a token whose claims have been validated.

Constructors

LtiTokenClaims

Fields

• unLtiTokenClaims :: UncheckedLtiTokenClaims

Instances

Show LtiTokenClaims

Defined in Web.LTI13

Methods

showsPrec :: Int -> LtiTokenClaims -> ShowS

show :: LtiTokenClaims -> String

showList :: [LtiTokenClaims] -> ShowS

Eq LtiTokenClaims

Defined in Web.LTI13

Methods

(==) :: LtiTokenClaims -> LtiTokenClaims -> Bool

(/=) :: LtiTokenClaims -> LtiTokenClaims -> Bool

Anonymizing tokens for logging

newtype AnonymizedLtiTokenClaims

LTI token claims from which all student data has been removed. For logging.

Constructors

AnonymizedLtiTokenClaims UncheckedLtiTokenClaims

Instances

Show AnonymizedLtiTokenClaims

Defined in Web.LTI13

Methods

showsPrec :: Int -> AnonymizedLtiTokenClaims -> ShowS

show :: AnonymizedLtiTokenClaims -> String

showList :: [AnonymizedLtiTokenClaims] -> ShowS

Eq AnonymizedLtiTokenClaims

Defined in Web.LTI13

Methods

(==) :: AnonymizedLtiTokenClaims -> AnonymizedLtiTokenClaims -> Bool

(/=) :: AnonymizedLtiTokenClaims -> AnonymizedLtiTokenClaims -> Bool

anonymizeLtiTokenForLogging :: UncheckedLtiTokenClaims -> AnonymizedLtiTokenClaims

Removes PII of the user from the token, retaining only information about the system in general or the context.

Fields that are Maybe are kept as Maybe, with the contents replaced with "**" if they were Just and otherwise kept as Nothing.

Validation and auth

validateLtiToken :: PlatformInfo -> IdTokenClaims UncheckedLtiTokenClaims -> Either Text (IdTokenClaims LtiTokenClaims)

A direct implementation of Security § 5.1.3

data LTI13Exception

(most of) the exceptions that can arise in LTI 1.3 handling. Some may have been forgotten, and this is a bug that should be fixed.

Constructors

InvalidHandshake Text

Error in the handshake format

DiscoveryException Text

GotHttpException HttpException

InvalidLtiToken Text

Token validation error. Per Security § 5.1.3 if you get this, you should return a 401.

Instances

Exception LTI13Exception

Defined in Web.LTI13

Methods

toException :: LTI13Exception -> SomeException

fromException :: SomeException -> Maybe LTI13Exception

displayException :: LTI13Exception -> String

Show LTI13Exception

Defined in Web.LTI13

Methods

showsPrec :: Int -> LTI13Exception -> ShowS

show :: LTI13Exception -> String

showList :: [LTI13Exception] -> ShowS

data PlatformInfo

Preregistered information about a learning platform

Constructors

PlatformInfo

Fields

• platformIssuer :: Issuer

  Issuer value

• platformClientId :: ClientId

  client_id

• platformOidcAuthEndpoint :: Text

  URL the client is redirected to for auth stage 2. See also Security spec § 5.1.1

• jwksUrl :: String

  URL for a JSON object containing the JWK signing keys for the platform

type Issuer = Text

Issuer/iss field

type ClientId = Text

client_id, one or more per platform; LTI spec § 3.1.3

data SessionStore (m :: Type -> Type)

Manages state and nonce. (Maybe OIDC should have them)

Constructors

SessionStore

Fields

• sessionStoreGenerate :: m ByteString

  Generate state and nonce at random

• sessionStoreSave :: State -> Nonce -> m ()
• sessionStoreGet :: State -> m (Maybe Nonce)

  Returns Nothing if State is unknown

• sessionStoreDelete :: m ()

  Should delete at least nonce

data AuthFlowConfig m

Structure you have to provide defining integration points with your app

Constructors

AuthFlowConfig

Fields

• getPlatformInfo :: (Issuer, Maybe ClientId) -> m PlatformInfo

  Access some persistent storage of the configured platforms and return the PlatformInfo for a given platform by name

• haveSeenNonce :: Nonce -> m Bool
• myRedirectUri :: Text
• sessionStore :: SessionStore m

  Note that as in the example for haskell-oidc-client, this is intended to be partially parameterized already with some separate cookie you give the browser. You should also store the iss from the initiate stage in the session somewhere for the handleAuthResponse stage.

type RequestParams = Map Text Text

Parameters to a request, either in the URL with a GET or in the body with a POST

initiate :: MonadIO m => AuthFlowConfig m -> RequestParams -> m (Issuer, ClientId, Text)

Makes the URL for IMS Security spec § 5.1.1.2 upon the § 5.1.1.1 request coming in

Returns (Issuer, RedirectURL).

handleAuthResponse :: MonadIO m => Manager -> AuthFlowConfig m -> RequestParams -> PlatformInfo -> m (Text, IdTokenClaims LtiTokenClaims)

Handle the § 5.1.1.3 Step 3 response sent to the myRedirectUri

Returns (State, Token)