Safe Haskell	None
Language	Haskell2010

Web.LTI13

Contents

Token contents/data model
Anonymizing tokens for logging
Validation and auth

Description

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.

Synopsis

data Role
- = Administrator
- | ContentDeveloper
- | Instructor
- | Learner
- | Mentor
- | Other Text
data LisClaim = LisClaim {
- personSourcedId :: Maybe Text
- outcomeServiceUrl :: Maybe Text
- courseOfferingSourcedId :: Maybe Text
- courseSectionSourcedId :: Maybe Text
- resultSourcedId :: Maybe Text
}
data ContextClaim = ContextClaim {
- contextId :: Text
- contextLabel :: Maybe Text
- contextTitle :: Maybe Text
}
data UncheckedLtiTokenClaims = UncheckedLtiTokenClaims {
- 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
}
newtype LtiTokenClaims = LtiTokenClaims {
- unLtiTokenClaims :: UncheckedLtiTokenClaims
}
newtype AnonymizedLtiTokenClaims = AnonymizedLtiTokenClaims UncheckedLtiTokenClaims
anonymizeLtiTokenForLogging :: UncheckedLtiTokenClaims -> AnonymizedLtiTokenClaims
validateLtiToken :: PlatformInfo -> IdTokenClaims UncheckedLtiTokenClaims -> Either Text (IdTokenClaims LtiTokenClaims)
data LTI13Exception
data PlatformInfo = PlatformInfo {
- platformIssuer :: Issuer
- platformClientId :: ClientId
- platformOidcAuthEndpoint :: Text
- jwksUrl :: String
}
type Issuer = Text
type ClientId = Text
data SessionStore (m :: Type -> Type) = SessionStore {
- sessionStoreGenerate :: m ByteString
- sessionStoreSave :: State -> Nonce -> m ()
- sessionStoreGet :: m (Maybe State, Maybe Nonce)
- sessionStoreDelete :: m ()
}
data AuthFlowConfig m = AuthFlowConfig {
- getPlatformInfo :: (Issuer, Maybe ClientId) -> m PlatformInfo
- haveSeenNonce :: Nonce -> m Bool
- myRedirectUri :: Text
- sessionStore :: SessionStore m
}
type RequestParams = Map Text Text
initiate :: MonadIO m => AuthFlowConfig m -> RequestParams -> m (Issuer, ClientId, Text)
handleAuthResponse :: MonadIO m => Manager -> AuthFlowConfig m -> RequestParams -> PlatformInfo -> m (Text, IdTokenClaims LtiTokenClaims)

Token contents/data model

data Role Source #

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

Instances details

Eq Role Source #
Instance details Defined in Web.LTI13 Methods (==) :: Role -> Role -> Bool # (/=) :: Role -> Role -> Bool #
Show Role Source #
Instance details Defined in Web.LTI13 Methods showsPrec :: Int -> Role -> ShowS # show :: Role -> String # showList :: [Role] -> ShowS #
ToJSON Role Source #
Instance details Defined in Web.LTI13 Methods toJSON :: Role -> Value # toEncoding :: Role -> Encoding # toJSONList :: [Role] -> Value # toEncodingList :: [Role] -> Encoding #
FromJSON Role Source #
Instance details Defined in Web.LTI13 Methods parseJSON :: Value -> Parser Role # parseJSONList :: Value -> Parser [Role] #

data LisClaim Source #

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

Instances details

Eq LisClaim Source #
Instance details Defined in Web.LTI13 Methods (==) :: LisClaim -> LisClaim -> Bool # (/=) :: LisClaim -> LisClaim -> Bool #
Show LisClaim Source #
Instance details Defined in Web.LTI13 Methods showsPrec :: Int -> LisClaim -> ShowS # show :: LisClaim -> String # showList :: [LisClaim] -> ShowS #
ToJSON LisClaim Source #
Instance details Defined in Web.LTI13 Methods toJSON :: LisClaim -> Value # toEncoding :: LisClaim -> Encoding # toJSONList :: [LisClaim] -> Value # toEncodingList :: [LisClaim] -> Encoding #
FromJSON LisClaim Source #
Instance details Defined in Web.LTI13 Methods parseJSON :: Value -> Parser LisClaim # parseJSONList :: Value -> Parser [LisClaim] #

data ContextClaim Source #

LTI spec § 5.4.1 context claim

Constructors

ContextClaim
Fields contextId :: Text contextLabel :: Maybe Text contextTitle :: Maybe Text

Instances

Instances details

Eq ContextClaim Source #
Instance details Defined in Web.LTI13 Methods (==) :: ContextClaim -> ContextClaim -> Bool # (/=) :: ContextClaim -> ContextClaim -> Bool #
Show ContextClaim Source #
Instance details Defined in Web.LTI13 Methods showsPrec :: Int -> ContextClaim -> ShowS # show :: ContextClaim -> String # showList :: [ContextClaim] -> ShowS #
ToJSON ContextClaim Source #
Instance details Defined in Web.LTI13 Methods toJSON :: ContextClaim -> Value # toEncoding :: ContextClaim -> Encoding # toJSONList :: [ContextClaim] -> Value # toEncodingList :: [ContextClaim] -> Encoding #
FromJSON ContextClaim Source #
Instance details Defined in Web.LTI13 Methods parseJSON :: Value -> Parser ContextClaim # parseJSONList :: Value -> Parser [ContextClaim] #

data UncheckedLtiTokenClaims Source #

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

Instances details

Eq UncheckedLtiTokenClaims Source #
Instance details Defined in Web.LTI13 Methods (==) :: UncheckedLtiTokenClaims -> UncheckedLtiTokenClaims -> Bool # (/=) :: UncheckedLtiTokenClaims -> UncheckedLtiTokenClaims -> Bool #
Show UncheckedLtiTokenClaims Source #
Instance details Defined in Web.LTI13 Methods showsPrec :: Int -> UncheckedLtiTokenClaims -> ShowS # show :: UncheckedLtiTokenClaims -> String # showList :: [UncheckedLtiTokenClaims] -> ShowS #
ToJSON UncheckedLtiTokenClaims Source #
Instance details Defined in Web.LTI13 Methods toJSON :: UncheckedLtiTokenClaims -> Value # toEncoding :: UncheckedLtiTokenClaims -> Encoding # toJSONList :: [UncheckedLtiTokenClaims] -> Value # toEncodingList :: [UncheckedLtiTokenClaims] -> Encoding #
FromJSON UncheckedLtiTokenClaims Source #
Instance details Defined in Web.LTI13 Methods parseJSON :: Value -> Parser UncheckedLtiTokenClaims # parseJSONList :: Value -> Parser [UncheckedLtiTokenClaims] #

newtype LtiTokenClaims Source #

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

Constructors

LtiTokenClaims
Fields unLtiTokenClaims :: UncheckedLtiTokenClaims

Instances

Instances details

Eq LtiTokenClaims Source #
Instance details Defined in Web.LTI13 Methods (==) :: LtiTokenClaims -> LtiTokenClaims -> Bool # (/=) :: LtiTokenClaims -> LtiTokenClaims -> Bool #
Show LtiTokenClaims Source #
Instance details Defined in Web.LTI13 Methods showsPrec :: Int -> LtiTokenClaims -> ShowS # show :: LtiTokenClaims -> String # showList :: [LtiTokenClaims] -> ShowS #

Anonymizing tokens for logging

newtype AnonymizedLtiTokenClaims Source #

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

Constructors

AnonymizedLtiTokenClaims UncheckedLtiTokenClaims

Instances

Instances details

Eq AnonymizedLtiTokenClaims Source #
Instance details Defined in Web.LTI13 Methods (==) :: AnonymizedLtiTokenClaims -> AnonymizedLtiTokenClaims -> Bool # (/=) :: AnonymizedLtiTokenClaims -> AnonymizedLtiTokenClaims -> Bool #
Show AnonymizedLtiTokenClaims Source #
Instance details Defined in Web.LTI13 Methods showsPrec :: Int -> AnonymizedLtiTokenClaims -> ShowS # show :: AnonymizedLtiTokenClaims -> String # showList :: [AnonymizedLtiTokenClaims] -> ShowS #

anonymizeLtiTokenForLogging :: UncheckedLtiTokenClaims -> AnonymizedLtiTokenClaims Source #

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) Source #

A direct implementation of Security § 5.1.3

data LTI13Exception Source #

(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

Instances details

Show LTI13Exception Source #
Instance details Defined in Web.LTI13 Methods showsPrec :: Int -> LTI13Exception -> ShowS # show :: LTI13Exception -> String # showList :: [LTI13Exception] -> ShowS #
Exception LTI13Exception Source #
Instance details Defined in Web.LTI13 Methods toException :: LTI13Exception -> SomeException # fromException :: SomeException -> Maybe LTI13Exception # displayException :: LTI13Exception -> String #

data PlatformInfo Source #

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 Source #

Issuer/iss field

type ClientId = Text Source #

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 Source #

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 Source #

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) Source #

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) Source #

Handle the § 5.1.1.3 Step 3 response sent to the myRedirectUri

Returns (State, Token)