Crypto.JWT

JSON Web Token implementation (RFC 7519). A JWT is a JWS with a payload of claims to be transferred between two parties.

JWTs use the JWS compact serialisation. See Crypto.JOSE.Compact for details.

import Crypto.JWT

mkClaims :: IO ClaimsSet
mkClaims = do
  t <- currentTime
  pure $ emptyClaimsSet
    & claimIss ?~ "alice"
    & claimAud ?~ Audience ["bob"]
    & claimIat ?~ NumericDate t

doJwtSign :: JWK -> ClaimsSet -> IO (Either JWTError SignedJWT)
doJwtSign jwk claims = runJOSE $ do
  alg <- bestJWSAlg jwk
  signClaims jwk (newJWSHeader ((), alg)) claims

doJwtVerify :: JWK -> SignedJWT -> IO (Either JWTError ClaimsSet)
doJwtVerify jwk jwt = runJOSE $ do
  let config = defaultJWTValidationSettings (== "bob")
  verifyClaims config jwk jwt

Some JWT libraries have a function that takes two strings: the "secret" (a symmetric key) and the raw JWT. The following function achieves the same:

verify :: L.ByteString -> L.ByteString -> IO (Either JWTError ClaimsSet)
verify k s = runJOSE $ do
  let
    k' = fromOctets k      -- turn raw secret into symmetric JWK
    audCheck = const True  -- should be a proper audience check
  jwt <- decodeCompact s    -- decode JWT
  verifyClaims (defaultJWTValidationSettings audCheck) k' jwt

For applications that use additional claims, define a data type that wraps ClaimsSet and includes fields for the additional claims. You will also need to define FromJSON if verifying JWTs, and ToJSON if producing JWTs. The following example is taken from RFC 7519 §3.1.

import qualified Data.Aeson.KeyMap as M

data Super = Super { jwtClaims :: ClaimsSet, isRoot :: Bool }

instance HasClaimsSet Super where
  claimsSet f s = fmap (\a' -> s { jwtClaims = a' }) (f (jwtClaims s))

instance FromJSON Super where
  parseJSON = withObject Super $ \o -> Super
    <$> parseJSON (Object o)
    <*> o .: "http://example.com/is_root"

instance ToJSON Super where
  toJSON s =
    ins "http://example.com/is_root" (isRoot s) (toJSON (jwtClaims s))
    where
      ins k v (Object o) = Object $ M.insert k (toJSON v) o
      ins _ _ a = a

Use signJWT and verifyJWT when using custom payload types (instead of signClaims and verifyClaims which are specialised to ClaimsSet).

Creating a JWT

type SignedJWT = CompactJWS JWSHeader

A digitally signed or MACed JWT

signClaims :: (MonadRandom m, MonadError e m, AsError e) => JWK -> JWSHeader () -> ClaimsSet -> m SignedJWT

Create a JWS JWT. Specialisation of signJWT with payload type fixed at ClaimsSet.

Does not set any fields in the Claims Set, such as "iat" ("Issued At") Claim. The payload is encoded as-is.

signJWT :: (MonadRandom m, MonadError e m, AsError e, ToJSON payload) => JWK -> JWSHeader () -> payload -> m SignedJWT

Create a JWS JWT. The payload can be any type with a ToJSON instance. See also signClaims which uses ClaimsSet as the payload type.

Does not set any fields in the Claims Set, such as "iat" ("Issued At") Claim. The payload is encoded as-is.

Validating a JWT and extracting claims

defaultJWTValidationSettings :: (StringOrURI -> Bool) -> JWTValidationSettings

Acquire the default validation settings.

RFC 7519 §4.1.3. states that applications MUST identify itself with a value in the audience claim, therefore a predicate must be supplied.

The other defaults are:

• defaultValidationSettings for JWS verification
• Zero clock skew tolerance when validating nbf, exp and iat claims
• iat claim is checked
• issuer claim is not checked

verifyClaims :: (MonadTime m, HasAllowedSkew a, HasAudiencePredicate a, HasIssuerPredicate a, HasCheckIssuedAt a, HasValidationSettings a, AsError e, AsJWTError e, MonadError e m, VerificationKeyStore m (JWSHeader ()) ClaimsSet k) => a -> k -> SignedJWT -> m ClaimsSet

Variant of verifyJWT that uses ClaimsSet as the payload type.

verifyJWT :: (MonadTime m, HasAllowedSkew a, HasAudiencePredicate a, HasIssuerPredicate a, HasCheckIssuedAt a, HasValidationSettings a, AsError e, AsJWTError e, MonadError e m, VerificationKeyStore m (JWSHeader ()) payload k, HasClaimsSet payload, FromJSON payload) => a -> k -> SignedJWT -> m payload

Cryptographically verify a JWS JWT, then validate the Claims Set, returning it if valid. The claims are validated at the current system time.

This is the only way to get at the claims of a JWS JWT, enforcing that the claims are cryptographically and semantically valid before the application can use them.

This function is abstracted over any payload type with HasClaimsSet and FromJSON instances. The verifyClaims variant uses ClaimsSet as the payload type.

See also verifyClaimsAt which allows you to explicitly specify the time of validation (against which time-related claims will be validated).

class HasAllowedSkew s where

Maximum allowed skew when validating the nbf, exp and iat claims.

Methods

allowedSkew :: Lens' s NominalDiffTime

Instances

HasJWTValidationSettings a => HasAllowedSkew a

Defined in Crypto.JWT

Methods

allowedSkew :: Lens' a NominalDiffTime

class HasAudiencePredicate s where

Predicate for checking values in the aud claim.

Methods

audiencePredicate :: Lens' s (StringOrURI -> Bool)

Instances

HasJWTValidationSettings a => HasAudiencePredicate a

Defined in Crypto.JWT

Methods

audiencePredicate :: Lens' a (StringOrURI -> Bool)

class HasIssuerPredicate s where

Predicate for checking the iss claim.

Methods

issuerPredicate :: Lens' s (StringOrURI -> Bool)

Instances

HasJWTValidationSettings a => HasIssuerPredicate a

Defined in Crypto.JWT

Methods

issuerPredicate :: Lens' a (StringOrURI -> Bool)

class HasCheckIssuedAt s where

Whether to check that the iat claim is not in the future.

Methods

checkIssuedAt :: Lens' s Bool

Instances

HasJWTValidationSettings a => HasCheckIssuedAt a

Defined in Crypto.JWT

Methods

checkIssuedAt :: Lens' a Bool

data JWTValidationSettings

Instances

HasJWTValidationSettings JWTValidationSettings

Defined in Crypto.JWT

Methods

jWTValidationSettings :: Lens' JWTValidationSettings JWTValidationSettings

jwtValidationSettingsAllowedSkew :: Lens' JWTValidationSettings NominalDiffTime

jwtValidationSettingsAudiencePredicate :: Lens' JWTValidationSettings (StringOrURI -> Bool)

jwtValidationSettingsCheckIssuedAt :: Lens' JWTValidationSettings Bool

jwtValidationSettingsIssuerPredicate :: Lens' JWTValidationSettings (StringOrURI -> Bool)

jwtValidationSettingsValidationSettings :: Lens' JWTValidationSettings ValidationSettings

class HasJWTValidationSettings c where

Minimal complete definition

jWTValidationSettings

Methods

jWTValidationSettings :: Lens' c JWTValidationSettings

jwtValidationSettingsAllowedSkew :: Lens' c NominalDiffTime

jwtValidationSettingsAudiencePredicate :: Lens' c (StringOrURI -> Bool)

jwtValidationSettingsCheckIssuedAt :: Lens' c Bool

jwtValidationSettingsIssuerPredicate :: Lens' c (StringOrURI -> Bool)

jwtValidationSettingsValidationSettings :: Lens' c ValidationSettings

Instances

HasJWTValidationSettings JWTValidationSettings

Defined in Crypto.JWT

Methods

jWTValidationSettings :: Lens' JWTValidationSettings JWTValidationSettings

jwtValidationSettingsAllowedSkew :: Lens' JWTValidationSettings NominalDiffTime

jwtValidationSettingsAudiencePredicate :: Lens' JWTValidationSettings (StringOrURI -> Bool)

jwtValidationSettingsCheckIssuedAt :: Lens' JWTValidationSettings Bool

jwtValidationSettingsIssuerPredicate :: Lens' JWTValidationSettings (StringOrURI -> Bool)

jwtValidationSettingsValidationSettings :: Lens' JWTValidationSettings ValidationSettings

Specifying the verification time

newtype WrappedUTCTime

Constructors

WrappedUTCTime

Fields

• getUTCTime :: UTCTime

Instances

Monad m => MonadTime (ReaderT WrappedUTCTime m)

Defined in Crypto.JWT

Methods

currentTime :: ReaderT WrappedUTCTime m UTCTime

monotonicTime :: ReaderT WrappedUTCTime m Double

verifyClaimsAt :: (HasAllowedSkew a, HasAudiencePredicate a, HasIssuerPredicate a, HasCheckIssuedAt a, HasValidationSettings a, AsError e, AsJWTError e, MonadError e m, VerificationKeyStore (ReaderT WrappedUTCTime m) (JWSHeader ()) ClaimsSet k) => a -> k -> UTCTime -> SignedJWT -> m ClaimsSet

Variant of verifyJWT that uses ClaimsSet as the payload type and where validation time is provided by caller.

verifyJWTAt :: (HasAllowedSkew a, HasAudiencePredicate a, HasIssuerPredicate a, HasCheckIssuedAt a, HasValidationSettings a, AsError e, AsJWTError e, MonadError e m, VerificationKeyStore (ReaderT WrappedUTCTime m) (JWSHeader ()) payload k, HasClaimsSet payload, FromJSON payload) => a -> k -> UTCTime -> SignedJWT -> m payload

Variant of verifyJWT where the validation time is provided by caller. If you process many tokens per second this lets you avoid unnecessary repeat system calls.

Claims Set

class HasClaimsSet a where

Minimal complete definition

claimsSet

Methods

claimsSet :: Lens' a ClaimsSet

claimIss :: Lens' a (Maybe StringOrURI)

The issuer claim identifies the principal that issued the JWT. The processing of this claim is generally application specific.

claimSub :: Lens' a (Maybe StringOrURI)

The subject claim identifies the principal that is the subject of the JWT. The Claims in a JWT are normally statements about the subject. The subject value MAY be scoped to be locally unique in the context of the issuer or MAY be globally unique. The processing of this claim is generally application specific.

claimAud :: Lens' a (Maybe Audience)

The audience claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the aud claim when this claim is present, then the JWT MUST be rejected.

claimExp :: Lens' a (Maybe NumericDate)

The expiration time claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of exp claim requires that the current date/time MUST be before expiration date/time listed in the exp claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew.

claimNbf :: Lens' a (Maybe NumericDate)

The not before claim identifies the time before which the JWT MUST NOT be accepted for processing. The processing of the nbf claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the nbf claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew.

claimIat :: Lens' a (Maybe NumericDate)

The issued at claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT.

claimJti :: Lens' a (Maybe Text)

The JWT ID claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object. The jti claim can be used to prevent the JWT from being replayed. The jti value is a case-sensitive string.

Instances

HasClaimsSet ClaimsSet

Defined in Crypto.JWT

Methods

claimsSet :: Lens' ClaimsSet ClaimsSet

claimIss :: Lens' ClaimsSet (Maybe StringOrURI)

claimSub :: Lens' ClaimsSet (Maybe StringOrURI)

claimAud :: Lens' ClaimsSet (Maybe Audience)

claimExp :: Lens' ClaimsSet (Maybe NumericDate)

claimNbf :: Lens' ClaimsSet (Maybe NumericDate)

claimIat :: Lens' ClaimsSet (Maybe NumericDate)

claimJti :: Lens' ClaimsSet (Maybe Text)

data ClaimsSet

The JWT Claims Set represents a JSON object whose members are the registered claims defined by RFC 7519. To construct a ClaimsSet use emptyClaimsSet then use the lenses from this class to set relevant claims.

For applications that use additional claims beyond those defined by RFC 7519, define a new data type and instance HasClaimsSet. See the module synopsis for more details and an example.

Instances

FromJSON ClaimsSet

Defined in Crypto.JWT

Methods

parseJSON :: Value -> Parser ClaimsSet

parseJSONList :: Value -> Parser [ClaimsSet]

ToJSON ClaimsSet

Defined in Crypto.JWT

Methods

toJSON :: ClaimsSet -> Value

toEncoding :: ClaimsSet -> Encoding

toJSONList :: [ClaimsSet] -> Value

toEncodingList :: [ClaimsSet] -> Encoding

Show ClaimsSet

Defined in Crypto.JWT

Methods

showsPrec :: Int -> ClaimsSet -> ShowS

show :: ClaimsSet -> String

showList :: [ClaimsSet] -> ShowS

Eq ClaimsSet

Defined in Crypto.JWT

Methods

(==) :: ClaimsSet -> ClaimsSet -> Bool

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

HasClaimsSet ClaimsSet

Defined in Crypto.JWT

Methods

claimsSet :: Lens' ClaimsSet ClaimsSet

claimIss :: Lens' ClaimsSet (Maybe StringOrURI)

claimSub :: Lens' ClaimsSet (Maybe StringOrURI)

claimAud :: Lens' ClaimsSet (Maybe Audience)

claimExp :: Lens' ClaimsSet (Maybe NumericDate)

claimNbf :: Lens' ClaimsSet (Maybe NumericDate)

claimIat :: Lens' ClaimsSet (Maybe NumericDate)

claimJti :: Lens' ClaimsSet (Maybe Text)

emptyClaimsSet :: ClaimsSet

Return an empty claims set.

addClaim :: Text -> Value -> ClaimsSet -> ClaimsSet

Deprecated: unregisteredClaims is deprecated; use a sub-type

Add a non-RFC 7519 claim. Use the lenses from the HasClaimsSet class for setting registered claims.

unregisteredClaims :: Lens' ClaimsSet (Map Text Value)

Deprecated: use a sub-type

Claim Names can be defined at will by those using JWTs. Use this lens to access a map non-RFC 7519 claims in the Claims Set object.

validateClaimsSet :: (MonadTime m, HasAllowedSkew a, HasAudiencePredicate a, HasIssuerPredicate a, HasCheckIssuedAt a, AsJWTError e, MonadError e m) => a -> ClaimsSet -> m ClaimsSet

Validate the claims made by a ClaimsSet.

You should never need to use this function directly. These checks are always performed by verifyClaims and verifyJWT. The function is exported mainly for testing purposes.

JWT errors

data JWTError

Constructors

JWSError Error

A JOSE error occurred while processing the JWT

JWTClaimsSetDecodeError String

The JWT payload is not a JWT Claims Set

JWTExpired

JWTNotYetValid

JWTNotInIssuer

JWTNotInAudience

JWTIssuedAtFuture

Instances

Show JWTError

Defined in Crypto.JWT

Methods

showsPrec :: Int -> JWTError -> ShowS

show :: JWTError -> String

showList :: [JWTError] -> ShowS

Eq JWTError

Defined in Crypto.JWT

Methods

(==) :: JWTError -> JWTError -> Bool

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

AsError JWTError

Defined in Crypto.JWT

Methods

_Error :: Prism' JWTError Error

_AlgorithmNotImplemented :: Prism' JWTError ()

_AlgorithmMismatch :: Prism' JWTError String

_KeyMismatch :: Prism' JWTError Text

_KeySizeTooSmall :: Prism' JWTError ()

_OtherPrimesNotSupported :: Prism' JWTError ()

_RSAError :: Prism' JWTError Error

_CryptoError :: Prism' JWTError CryptoError

_CompactDecodeError :: Prism' JWTError CompactDecodeError

_JSONDecodeError :: Prism' JWTError String

_NoUsableKeys :: Prism' JWTError ()

_JWSCritUnprotected :: Prism' JWTError ()

_JWSNoValidSignatures :: Prism' JWTError ()

_JWSInvalidSignature :: Prism' JWTError ()

_JWSNoSignatures :: Prism' JWTError ()

AsJWTError JWTError

Defined in Crypto.JWT

Methods

_JWTError :: Prism' JWTError JWTError

_JWSError :: Prism' JWTError Error

_JWTClaimsSetDecodeError :: Prism' JWTError String

_JWTExpired :: Prism' JWTError ()

_JWTNotYetValid :: Prism' JWTError ()

_JWTNotInIssuer :: Prism' JWTError ()

_JWTNotInAudience :: Prism' JWTError ()

_JWTIssuedAtFuture :: Prism' JWTError ()

class AsJWTError r where

Minimal complete definition

_JWTError

Methods

_JWTError :: Prism' r JWTError

_JWSError :: Prism' r Error

_JWTClaimsSetDecodeError :: Prism' r String

_JWTExpired :: Prism' r ()

_JWTNotYetValid :: Prism' r ()

_JWTNotInIssuer :: Prism' r ()

_JWTNotInAudience :: Prism' r ()

_JWTIssuedAtFuture :: Prism' r ()

Instances

AsJWTError JWTError

Defined in Crypto.JWT

Methods

_JWTError :: Prism' JWTError JWTError

_JWSError :: Prism' JWTError Error

_JWTClaimsSetDecodeError :: Prism' JWTError String

_JWTExpired :: Prism' JWTError ()

_JWTNotYetValid :: Prism' JWTError ()

_JWTNotInIssuer :: Prism' JWTError ()

_JWTNotInAudience :: Prism' JWTError ()

_JWTIssuedAtFuture :: Prism' JWTError ()

Miscellaneous

newtype Audience

Audience data. In the general case, the aud value is an array of case-sensitive strings, each containing a StringOrURI value. In the special case when the JWT has one audience, the aud value MAY be a single case-sensitive string containing a StringOrURI value.

The ToJSON instance formats an Audience with one value as a string (some non-compliant implementations require this.)

Constructors

Audience [StringOrURI]

Instances

FromJSON Audience

Defined in Crypto.JWT

Methods

parseJSON :: Value -> Parser Audience

parseJSONList :: Value -> Parser [Audience]

ToJSON Audience

Defined in Crypto.JWT

Methods

toJSON :: Audience -> Value

toEncoding :: Audience -> Encoding

toJSONList :: [Audience] -> Value

toEncodingList :: [Audience] -> Encoding

Show Audience

Defined in Crypto.JWT

Methods

showsPrec :: Int -> Audience -> ShowS

show :: Audience -> String

showList :: [Audience] -> ShowS

Eq Audience

Defined in Crypto.JWT

Methods

(==) :: Audience -> Audience -> Bool

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

data StringOrURI

A JSON string value, with the additional requirement that while arbitrary string values MAY be used, any value containing a : character MUST be a URI.

Note: the IsString instance will fail if the string contains a : but does not parse as a URI. Use stringOrUri directly in this situation.

Instances

FromJSON StringOrURI

Defined in Crypto.JWT

Methods

parseJSON :: Value -> Parser StringOrURI

parseJSONList :: Value -> Parser [StringOrURI]

ToJSON StringOrURI

Defined in Crypto.JWT

Methods

toJSON :: StringOrURI -> Value

toEncoding :: StringOrURI -> Encoding

toJSONList :: [StringOrURI] -> Value

toEncodingList :: [StringOrURI] -> Encoding

IsString StringOrURI

Non-total. A string with a : in it MUST parse as a URI

Defined in Crypto.JWT

Methods

fromString :: String -> StringOrURI

Show StringOrURI

Defined in Crypto.JWT

Methods

showsPrec :: Int -> StringOrURI -> ShowS

show :: StringOrURI -> String

showList :: [StringOrURI] -> ShowS

Eq StringOrURI

Defined in Crypto.JWT

Methods

(==) :: StringOrURI -> StringOrURI -> Bool

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

stringOrUri :: (Cons s s Char Char, AsEmpty s) => Prism' s StringOrURI

string :: Prism' StringOrURI Text

uri :: Prism' StringOrURI URI

newtype NumericDate

A JSON numeric value representing the number of seconds from 1970-01-01T0:0:0Z UTC until the specified UTC date/time.

Constructors

NumericDate UTCTime

Instances

FromJSON NumericDate

Defined in Crypto.JWT

Methods

parseJSON :: Value -> Parser NumericDate

parseJSONList :: Value -> Parser [NumericDate]

ToJSON NumericDate

Defined in Crypto.JWT

Methods

toJSON :: NumericDate -> Value

toEncoding :: NumericDate -> Encoding

toJSONList :: [NumericDate] -> Value

toEncodingList :: [NumericDate] -> Encoding

Show NumericDate

Defined in Crypto.JWT

Methods

showsPrec :: Int -> NumericDate -> ShowS

show :: NumericDate -> String

showList :: [NumericDate] -> ShowS

Eq NumericDate

Defined in Crypto.JWT

Methods

(==) :: NumericDate -> NumericDate -> Bool

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

Ord NumericDate

Defined in Crypto.JWT

Methods

compare :: NumericDate -> NumericDate -> Ordering

(<) :: NumericDate -> NumericDate -> Bool

(<=) :: NumericDate -> NumericDate -> Bool

(>) :: NumericDate -> NumericDate -> Bool

(>=) :: NumericDate -> NumericDate -> Bool

max :: NumericDate -> NumericDate -> NumericDate

min :: NumericDate -> NumericDate -> NumericDate

module Crypto.JOSE

Orphan instances

HasJWTValidationSettings a => HasValidationSettings a

Methods

validationSettings :: Lens' a ValidationSettings

validationSettingsAlgorithms :: Lens' a (Set Alg)

validationSettingsValidationPolicy :: Lens' a ValidationPolicy