type

Jwt

const class Jwt : Obj

Models a JSON Web Token (JWT) as specified by RFC7519

A JWT includes three sections:

  1. Javascript Object Signing and Encryption (JOSE) Header
  2. Claims
  3. Signature

11111111111.22222222222.33333333333

These sections are encoded as base64url strings and are separated by dot (.) characters.

The (alg) parameter must be set to a supported JWS algorithm.

The following JWS algorithms are supported:

  • HS256 - HMAC using SHA-256
  • HS384 - HMAC using SHA-384
  • HS512 - HMAC using SHA-512
  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256
  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384
  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512
  • ES256 - ECDSA using P-256 and SHA-256
  • ES384 - ECDSA using P-256 and SHA-384
  • ES512 - ECDSA using P-256 and SHA-512
  • none - No digital signature or MAC performed

constructors

decode

Decode a Jwt from an encoded Str

make

It-block constructor

fields

alg

Algorithm header

aud

Audience claim for this token (Str or Str[])

claims

JWT Claims

exp

Expiration claim for this token

header

JOSE Header

iat

Issued at claim for this token

iss

Issuer claim for this token

jti

JWT ID claim for this token

kid

Key ID header

nbf

Not before claim for this token

sub

Subject claim for this token

methods

encode

Provide a Key (PrivKey or SymKey) to sign and return the base64 encoded Jwt

toStr
verifyClaim

Convenience function to check the value of a claim

Slot Details

alg

const Str alg

Algorithm header

aud

const Obj? aud

Audience claim for this token (Str or Str[])

If value is a Str it will converted to a Str[] of size 1

claims

const Str:Obj claims := [Str:Obj][:]

JWT Claims

decode

static new decode(Str encoded, Obj key, Duration clockDrift := 1min)

Decode a Jwt from an encoded Str

The key parameter supports these types to verify the signature:

  • Key (PubKey or SymKey)
  • Jwk[] - An error is thrown if the Jwt kid header parameter
    is missing or no matching kid is found in the list

If the exp and/or nbf claims exist, those will be verified

jwk :=  [
          "kty": "EC",
          "use": "sig",
          "crv": "P-256",
          "kid": "abcd",
          "x": "I59TOAdnJ7uPgPOdIxj-BhWSQBXKS3lsRZJwj5eIYAo",
          "y": "8FJEvVIZDjVBnrBJPRUCwtgS86rHoFl1kBfbjX9rOng",
          "alg": "ES256",
        ]

ecJwk := Crypto.cur.loadJwk(jwk)

jwt   := Jwt.decode("1111.2222.3333", ecJwk.key)

jwks := Crypto.cur.loadJwksForUri(`https://example.com/jwks.json`)

jwt2  := Jwt.decodeJwks("4444.5555.6666", jwks)

encode

Str encode(Key? key)

Provide a Key (PrivKey or SymKey) to sign and return the base64 encoded Jwt

Null key will return an unsigned base64 encoded JWT

The alg field must be set to a supported JWS algorithm

The following JWS Algorithms are supported:

  • HS256 - HMAC using SHA-256
  • HS384 - HMAC using SHA-384
  • HS512 - HMAC using SHA-512
  • RS256 - RSASSA-PKCS1-v1_5 using SHA-256
  • RS384 - RSASSA-PKCS1-v1_5 using SHA-384
  • RS512 - RSASSA-PKCS1-v1_5 using SHA-512
  • ES256 - ECDSA using P-256 and SHA-256
  • ES384 - ECDSA using P-256 and SHA-384
  • ES512 - ECDSA using P-256 and SHA-512
  • none - No digital signature or MAC performed
pair   := Crypto.cur.genKeyPair("RSA", 2048)
priv   := pair.priv

jwtStr := Jwt {
             it.alg    = "RS256"
             it.claims = ["myClaim": "ClaimValue"]
             it.exp    = DateTime.nowUtc + 10min
             it.iss    = "https://fantom.accounts.dev"
          }.encode(priv)

exp

const DateTime? exp

Expiration claim for this token

When encoded, the value will be converted to TimeZone.utc, the epoch const will be subtracted from this value and it will be converted to seconds

When decoded, the value will be converted to TimeZone.utc

const Str:Obj header := [Str:Obj][:]

JOSE Header

iat

const DateTime? iat

Issued at claim for this token

When encoded, the value will be converted to TimeZone.utc, the epoch const will be subtracted from this value and it will be converted to seconds

When decoded, the value will be converted to TimeZone.utc

iss

const Str? iss

Issuer claim for this token

jti

const Str? jti

JWT ID claim for this token

kid

const Str? kid

Key ID header

When encoding this value will take precedent if the kid parameter is also set in the JOSE header

make

new make(|This| f)

It-block constructor

nbf

const DateTime? nbf

Not before claim for this token

When encoded, the value will be converted to TimeZone.utc, the epoch const will be subtracted from this value and it will be converted to seconds

When decoded, the value will be converted to TimeZone.utc

sub

const Str? sub

Subject claim for this token

toStr

virtual override Str toStr()

verifyClaim

This verifyClaim(Str claim, Obj? expectedValue := null)

Convenience function to check the value of a claim

If value of JWT claim is a List, this function checks that the expectedValue is contained in the List.

If expectedValue is null, just checks if the claim exists

Throws Err if claim does not exist or expectedValue does not match (or is not contained in the List)

jwt := Jwt.decode("1111.2222.3333", pubKey)
          .verifyClaim("iss", "https://fantom.accounts.dev")