Web.LTI13

A basic 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

Eq Role

Defined in Web.LTI13

Methods

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

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

Show Role

Defined in Web.LTI13

Methods

showsPrec :: Int -> Role -> ShowS

show :: Role -> String

showList :: [Role] -> ShowS

ToJSON Role

Defined in Web.LTI13

Methods

toJSON :: Role -> Value

toEncoding :: Role -> Encoding

toJSONList :: [Role] -> Value

toEncodingList :: [Role] -> Encoding

FromJSON Role

Defined in Web.LTI13

Methods

parseJSON :: Value -> Parser Role

parseJSONList :: Value -> Parser [Role]

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

Eq LisClaim

Defined in Web.LTI13

Methods

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

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

Show LisClaim

Defined in Web.LTI13

Methods

showsPrec :: Int -> LisClaim -> ShowS

show :: LisClaim -> String

showList :: [LisClaim] -> ShowS

ToJSON LisClaim

Defined in Web.LTI13

Methods

toJSON :: LisClaim -> Value

toEncoding :: LisClaim -> Encoding

toJSONList :: [LisClaim] -> Value

toEncodingList :: [LisClaim] -> Encoding

FromJSON LisClaim

Defined in Web.LTI13

Methods

parseJSON :: Value -> Parser LisClaim

parseJSONList :: Value -> Parser [LisClaim]

data ContextClaim

LTI spec § 5.4.1 context claim

Constructors

ContextClaim

Fields

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

Instances

Eq ContextClaim

Defined in Web.LTI13

Methods

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

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

Show ContextClaim

Defined in Web.LTI13

Methods

showsPrec :: Int -> ContextClaim -> ShowS

show :: ContextClaim -> String

showList :: [ContextClaim] -> ShowS

ToJSON ContextClaim

Defined in Web.LTI13

Methods

toJSON :: ContextClaim -> Value

toEncoding :: ContextClaim -> Encoding

toJSONList :: [ContextClaim] -> Value

toEncodingList :: [ContextClaim] -> Encoding

FromJSON ContextClaim

Defined in Web.LTI13

Methods

parseJSON :: Value -> Parser ContextClaim

parseJSONList :: Value -> Parser [ContextClaim]

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

Eq UncheckedLtiTokenClaims

Defined in Web.LTI13

Methods

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

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

Show UncheckedLtiTokenClaims

Defined in Web.LTI13

Methods

showsPrec :: Int -> UncheckedLtiTokenClaims -> ShowS

show :: UncheckedLtiTokenClaims -> String

showList :: [UncheckedLtiTokenClaims] -> ShowS

ToJSON UncheckedLtiTokenClaims

Defined in Web.LTI13

Methods

toJSON :: UncheckedLtiTokenClaims -> Value

toEncoding :: UncheckedLtiTokenClaims -> Encoding

toJSONList :: [UncheckedLtiTokenClaims] -> Value

toEncodingList :: [UncheckedLtiTokenClaims] -> Encoding

FromJSON UncheckedLtiTokenClaims

Defined in Web.LTI13

Methods

parseJSON :: Value -> Parser UncheckedLtiTokenClaims

parseJSONList :: Value -> Parser [UncheckedLtiTokenClaims]

newtype LtiTokenClaims

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

Constructors

LtiTokenClaims

Fields

• unLtiTokenClaims :: UncheckedLtiTokenClaims

Instances

Eq LtiTokenClaims

Defined in Web.LTI13

Methods

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

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

Show LtiTokenClaims

Defined in Web.LTI13

Methods

showsPrec :: Int -> LtiTokenClaims -> ShowS

show :: LtiTokenClaims -> String

showList :: [LtiTokenClaims] -> ShowS

Anonymizing tokens for logging

newtype AnonymizedLtiTokenClaims

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

Constructors

AnonymizedLtiTokenClaims UncheckedLtiTokenClaims

Instances

Eq AnonymizedLtiTokenClaims

Defined in Web.LTI13

Methods

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

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

Show AnonymizedLtiTokenClaims

Defined in Web.LTI13

Methods

showsPrec :: Int -> AnonymizedLtiTokenClaims -> ShowS

show :: AnonymizedLtiTokenClaims -> String

showList :: [AnonymizedLtiTokenClaims] -> ShowS

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

Show LTI13Exception

Defined in Web.LTI13

Methods

showsPrec :: Int -> LTI13Exception -> ShowS

show :: LTI13Exception -> String

showList :: [LTI13Exception] -> ShowS

Exception LTI13Exception

Defined in Web.LTI13

Methods

toException :: LTI13Exception -> SomeException

fromException :: SomeException -> Maybe LTI13Exception

displayException :: LTI13Exception -> String

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 :: m (Maybe State, Maybe Nonce)
• 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)