Jose.Jwt

High-level JWT encoding and decoding.

See the Jose.Jws and Jose.Jwe modules for specific JWS and JWE examples.

Example usage with a key stored as a JWK:

>>> import Jose.Jwe
>>> import Jose.Jwa
>>> import Jose.Jwk
>>> import Data.ByteString
>>> import Data.Aeson (decodeStrict)
>>> let jsonJwk = "{\"kty\":\"RSA\", \"kid\":\"mykey\", \"n\":\"ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddxHmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMsD1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSHSXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdVMTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ\", \"e\":\"AQAB\", \"d\":\"Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97IjlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYTCBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLhBOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ\"}" :: ByteString
>>> let Just jwk = decodeStrict jsonJwk :: Maybe Jwk
>>> Right (Jwt jwtEncoded) <- encode [jwk] (JwsEncoding RS256) (Claims "public claims")
>>> Right jwtDecoded <- Jose.Jwt.decode [jwk] (Just (JwsEncoding RS256)) jwtEncoded
>>> jwtDecoded
Jws (JwsHeader {jwsAlg = RS256, jwsTyp = Nothing, jwsCty = Nothing, jwsKid = Just (KeyId "mykey")},"public claims")

Documentation

newtype Jwt

An encoded JWT.

Constructors

Jwt

Fields

• unJwt :: ByteString

Instances

Eq Jwt

Defined in Jose.Types

Methods

(==) :: Jwt -> Jwt -> Bool

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

Show Jwt

Defined in Jose.Types

Methods

showsPrec :: Int -> Jwt -> ShowS

show :: Jwt -> String

showList :: [Jwt] -> ShowS

ToJSON Jwt

Defined in Jose.Types

Methods

toJSON :: Jwt -> Value

toEncoding :: Jwt -> Encoding

toJSONList :: [Jwt] -> Value

toEncodingList :: [Jwt] -> Encoding

FromJSON Jwt

Defined in Jose.Types

Methods

parseJSON :: Value -> Parser Jwt

parseJSONList :: Value -> Parser [Jwt]

type Jwe = (JweHeader, ByteString)

The header and claims of a decoded JWE.

type Jws = (JwsHeader, ByteString)

The header and claims of a decoded JWS.

data JwtClaims

Registered claims defined in section 4 of the JWT spec.

Constructors

JwtClaims

Fields

• jwtIss :: !(Maybe Text)
• jwtSub :: !(Maybe Text)
• jwtAud :: !(Maybe [Text])
• jwtExp :: !(Maybe IntDate)
• jwtNbf :: !(Maybe IntDate)
• jwtIat :: !(Maybe IntDate)
• jwtJti :: !(Maybe Text)

Instances

Show JwtClaims

Defined in Jose.Types

Methods

showsPrec :: Int -> JwtClaims -> ShowS

show :: JwtClaims -> String

showList :: [JwtClaims] -> ShowS

Generic JwtClaims

Defined in Jose.Types

Associated Types

type Rep JwtClaims :: * -> *

Methods

from :: JwtClaims -> Rep JwtClaims x

to :: Rep JwtClaims x -> JwtClaims

ToJSON JwtClaims

Defined in Jose.Types

Methods

toJSON :: JwtClaims -> Value

toEncoding :: JwtClaims -> Encoding

toJSONList :: [JwtClaims] -> Value

toEncodingList :: [JwtClaims] -> Encoding

FromJSON JwtClaims

Defined in Jose.Types

Methods

parseJSON :: Value -> Parser JwtClaims

parseJSONList :: Value -> Parser [JwtClaims]

type Rep JwtClaims

Defined in Jose.Types

type Rep JwtClaims = D1 (MetaData "JwtClaims" "Jose.Types" "jose-jwt-0.8.0-GBpTa5MhSG69KadbsXDas1" False) (C1 (MetaCons "JwtClaims" PrefixI True) ((S1 (MetaSel (Just "jwtIss") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe Text)) :*: (S1 (MetaSel (Just "jwtSub") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe Text)) :*: S1 (MetaSel (Just "jwtAud") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe [Text])))) :*: ((S1 (MetaSel (Just "jwtExp") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe IntDate)) :*: S1 (MetaSel (Just "jwtNbf") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe IntDate))) :*: (S1 (MetaSel (Just "jwtIat") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe IntDate)) :*: S1 (MetaSel (Just "jwtJti") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Maybe Text))))))

data JwsHeader

Header content for a JWS.

Constructors

JwsHeader

Fields

• jwsAlg :: JwsAlg
• jwsTyp :: Maybe Text
• jwsCty :: Maybe Text
• jwsKid :: Maybe KeyId

Instances

Eq JwsHeader

Defined in Jose.Types

Methods

(==) :: JwsHeader -> JwsHeader -> Bool

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

Show JwsHeader

Defined in Jose.Types

Methods

showsPrec :: Int -> JwsHeader -> ShowS

show :: JwsHeader -> String

showList :: [JwsHeader] -> ShowS

Generic JwsHeader

Defined in Jose.Types

Associated Types

type Rep JwsHeader :: * -> *

Methods

from :: JwsHeader -> Rep JwsHeader x

to :: Rep JwsHeader x -> JwsHeader

ToJSON JwsHeader

Defined in Jose.Types

Methods

toJSON :: JwsHeader -> Value

toEncoding :: JwsHeader -> Encoding

toJSONList :: [JwsHeader] -> Value

toEncodingList :: [JwsHeader] -> Encoding

FromJSON JwsHeader

Defined in Jose.Types

Methods

parseJSON :: Value -> Parser JwsHeader

parseJSONList :: Value -> Parser [JwsHeader]

type Rep JwsHeader

Defined in Jose.Types

type Rep JwsHeader = D1 (MetaData "JwsHeader" "Jose.Types" "jose-jwt-0.8.0-GBpTa5MhSG69KadbsXDas1" False) (C1 (MetaCons "JwsHeader" PrefixI True) ((S1 (MetaSel (Just "jwsAlg") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 JwsAlg) :*: S1 (MetaSel (Just "jwsTyp") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Text))) :*: (S1 (MetaSel (Just "jwsCty") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Text)) :*: S1 (MetaSel (Just "jwsKid") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe KeyId)))))

data JweHeader

Header content for a JWE.

Constructors

JweHeader

Fields

• jweAlg :: JweAlg
• jweEnc :: Enc
• jweTyp :: Maybe Text
• jweCty :: Maybe Text
• jweZip :: Maybe Text
• jweKid :: Maybe KeyId

Instances

Eq JweHeader

Defined in Jose.Types

Methods

(==) :: JweHeader -> JweHeader -> Bool

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

Show JweHeader

Defined in Jose.Types

Methods

showsPrec :: Int -> JweHeader -> ShowS

show :: JweHeader -> String

showList :: [JweHeader] -> ShowS

Generic JweHeader

Defined in Jose.Types

Associated Types

type Rep JweHeader :: * -> *

Methods

from :: JweHeader -> Rep JweHeader x

to :: Rep JweHeader x -> JweHeader

ToJSON JweHeader

Defined in Jose.Types

Methods

toJSON :: JweHeader -> Value

toEncoding :: JweHeader -> Encoding

toJSONList :: [JweHeader] -> Value

toEncodingList :: [JweHeader] -> Encoding

FromJSON JweHeader

Defined in Jose.Types

Methods

parseJSON :: Value -> Parser JweHeader

parseJSONList :: Value -> Parser [JweHeader]

type Rep JweHeader

Defined in Jose.Types

type Rep JweHeader = D1 (MetaData "JweHeader" "Jose.Types" "jose-jwt-0.8.0-GBpTa5MhSG69KadbsXDas1" False) (C1 (MetaCons "JweHeader" PrefixI True) ((S1 (MetaSel (Just "jweAlg") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 JweAlg) :*: (S1 (MetaSel (Just "jweEnc") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Enc) :*: S1 (MetaSel (Just "jweTyp") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Text)))) :*: (S1 (MetaSel (Just "jweCty") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Text)) :*: (S1 (MetaSel (Just "jweZip") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Text)) :*: S1 (MetaSel (Just "jweKid") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe KeyId))))))

data JwtContent

A decoded JWT which can be either a JWE or a JWS, or an unsecured JWT.

Constructors

Unsecured !ByteString

Jws !Jws

Jwe !Jwe

Instances

Eq JwtContent

Defined in Jose.Types

Methods

(==) :: JwtContent -> JwtContent -> Bool

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

Show JwtContent

Defined in Jose.Types

Methods

showsPrec :: Int -> JwtContent -> ShowS

show :: JwtContent -> String

showList :: [JwtContent] -> ShowS

data JwtEncoding

Defines the encoding information for a JWT.

Used for both encoding new JWTs and validating existing ones.

Constructors

JwsEncoding JwsAlg

JweEncoding JweAlg Enc

Instances

Eq JwtEncoding

Defined in Jose.Types

Methods

(==) :: JwtEncoding -> JwtEncoding -> Bool

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

Show JwtEncoding

Defined in Jose.Types

Methods

showsPrec :: Int -> JwtEncoding -> ShowS

show :: JwtEncoding -> String

showList :: [JwtEncoding] -> ShowS

data JwtError

Decoding errors.

Constructors

KeyError Text

No suitable key or wrong key type

BadAlgorithm Text

The supplied algorithm is invalid

BadDots Int

Wrong number of "." characters in the JWT

BadHeader Text

Header couldn't be decoded or contains bad data

BadClaims

Claims part couldn't be decoded or contains bad data

BadSignature

Signature is invalid

BadCrypto

A cryptographic operation failed

Base64Error String

A base64 decoding error

Instances

Eq JwtError

Defined in Jose.Types

Methods

(==) :: JwtError -> JwtError -> Bool

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

Show JwtError

Defined in Jose.Types

Methods

showsPrec :: Int -> JwtError -> ShowS

show :: JwtError -> String

showList :: [JwtError] -> ShowS

data Payload

The payload to be encoded in a JWT.

Constructors

Nested Jwt

Claims ByteString

Instances

Eq Payload

Defined in Jose.Types

Methods

(==) :: Payload -> Payload -> Bool

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

Show Payload

Defined in Jose.Types

Methods

showsPrec :: Int -> Payload -> ShowS

show :: Payload -> String

showList :: [Payload] -> ShowS

encode

Arguments

:: MonadRandom m

=> [Jwk]

The key or keys. At least one must be consistent with the chosen algorithm

-> JwtEncoding

The encoding algorithm(s) used to encode the payload

-> Payload

The payload (claims)

-> m (Either JwtError Jwt)

The encoded JWT, if successful

Use the supplied JWKs to create a JWT. The list of keys will be searched to locate one which is consistent with the chosen encoding algorithms.

decode

Arguments

:: MonadRandom m

=> [Jwk]

The keys to use for decoding

-> Maybe JwtEncoding

The expected encoding information

-> ByteString

The encoded JWT

-> m (Either JwtError JwtContent)

The decoded JWT payload, if successful

Uses the supplied keys to decode a JWT. Locates a matching key by header kid value where possible or by suitable key type for the encoding algorithm.

The algorithm(s) used can optionally be supplied for validation by setting the JwtEncoding parameter, in which case an error will be returned if they don't match. If you expect the tokens to use a particular algorithm, then you should set this parameter.

For unsecured tokens (with algorithm "none"), the expected algorithm must be set to Just (JwsEncoding None) or an error will be returned.

decodeClaims :: FromJSON a => ByteString -> Either JwtError (JwtHeader, a)

Convenience function to return the claims contained in a JWS. This is needed in situations such as client assertion authentication, https://tools.ietf.org/html/rfc7523, where the contents of the JWT, such as the sub claim, may be required in order to work out which key should be used to verify the token.

Obviously this should not be used by itself to decode a token since no integrity checking is done and the contents may be forged.