const class crypto::Jwt

sys::Obj
  crypto::Jwt

Source

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

alg

const Str alg

Source

Algorithm header

aud

const Obj? aud

Source

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][:]

Source

JWT Claims

decode

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

Source

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)

Source

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

Source

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

header

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

Source

JOSE Header

iat

const DateTime? iat

Source

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

Source

Issuer claim for this token

jti

const Str? jti

Source

JWT ID claim for this token

kid

const Str? kid

Source

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)

Source

It-block constructor

nbf

const DateTime? nbf

Source

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

Source

Subject claim for this token

toStr

virtual override Str toStr()

Source

verifyClaim

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

Source

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")