OCaml Library Collection

JSON Web Token (JWT) - RFC 7519

This module implements JSON Web Tokens as specified in RFC 7519.

JWTs are compact, URL-safe means of representing claims to be transferred between two parties. The claims are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC).

References

RFC 7519 - JSON Web Token (JWT)
RFC 7515 - JSON Web Signature (JWS)
RFC 7517 - JSON Web Key (JWK)
RFC 7518 - JSON Web Algorithms (JWA)

Error Handling

type error =

| Invalid_json of string
(*
JSON parsing failed
*)
| Invalid_base64url of string
(*
Base64url decoding failed
*)
| Invalid_structure of string
(*
Wrong number of parts or malformed structure
*)
| Invalid_header of string
(*
Header validation failed
*)
| Invalid_claims of string
(*
Claims validation failed
*)
| Invalid_uri of string
(*
StringOrURI validation failed per RFC 7519 Section 2
*)
| Duplicate_claim of string
(*
Duplicate claim name found in strict mode per RFC 7519 Section 4
*)
| Unsupported_algorithm of string
(*
Unknown algorithm identifier
*)
| Algorithm_not_allowed of string
(*
Algorithm rejected by allowed_algs policy
*)
| Signature_mismatch
(*
Signature verification failed
*)
| Token_expired
(*
exp claim validation failed per RFC 7519 Section 4.1.4
*)
| Token_not_yet_valid
(*
nbf claim validation failed per RFC 7519 Section 4.1.5
*)
| Invalid_issuer
(*
iss claim mismatch per RFC 7519 Section 4.1.1
*)
| Invalid_audience
(*
aud claim mismatch per RFC 7519 Section 4.1.3
*)
| Key_type_mismatch of string
(*
Key doesn't match algorithm
*)
| Unsecured_not_allowed
(*
alg:none used without explicit opt-in per RFC 7519 Section 6
*)
| Nesting_too_deep
(*
Nested JWT exceeds max_depth
*)

val pp_error : Format.formatter -> error -> unit

Pretty-print an error.

val error_to_string : error -> string

Convert error to human-readable string.

Algorithms

Signature and MAC algorithms for JWT. See RFC 7518 Section 3.

module Algorithm : sig ... end

JSON Web Key

Key representation for JWT signature verification. See RFC 7517.

module Jwk : sig ... end

JOSE Header

The JOSE (JSON Object Signing and Encryption) Header. See RFC 7519 Section 5.

module Header : sig ... end

Claims

JWT Claims Set. See RFC 7519 Section 4.

module Claims : sig ... end

JWT Token

type t = {

header : Header.t;
(*
JOSE header
*)
claims : Claims.t;
(*
Claims set
*)
signature : string;
(*
Raw signature bytes
*)
raw : string;
(*
Original compact serialization
*)

}

A parsed JWT token.

Parsing

See RFC 7519 Section 7.2.

val parse : ?strict:bool -> string -> (t, error) result

parse ?strict token_string parses a JWT from its compact serialization.

This parses the token structure but does NOT verify the signature. Use verify to validate the signature after parsing.

parameter strict
If true (default), reject duplicate claim names.

val parse_unsafe : string -> (t, error) result

parse_unsafe token_string parses a JWT without strict validation. Equivalent to parse ~strict:false.

Nested JWTs

See RFC 7519 Section 7.2 step 8 and Appendix A.2.

val parse_nested : 
  ?strict:bool ->
  ?max_depth:int ->
  string ->
  (t list, error) result

parse_nested ?strict ?max_depth token parses a potentially nested JWT. Returns a list of JWTs from outermost to innermost.

parameter max_depth
Maximum nesting depth (default 5).

val is_nested : t -> bool

is_nested t returns true if the JWT has cty: "JWT" header, indicating it contains a nested JWT.

Accessors

val header : t -> Header.t

header t returns the JOSE header.

val claims : t -> Claims.t

claims t returns the claims set.

val signature : t -> string

signature t returns the raw signature bytes.

val raw : t -> string

raw t returns the original token string.

Verification

See RFC 7519 Section 7.2.

val verify : 
  key:Jwk.t ->
  ?allow_none:bool ->
  ?allowed_algs:Algorithm.t list ->
  t ->
  (unit, error) result

verify ~key ?allow_none ?allowed_algs t verifies the JWT signature.

parameter key
The key to verify with (must match algorithm)

parameter allow_none
If true, accept alg:"none". Default: false. Per RFC 7519 Section 6, unsecured JWTs should only be used when security is provided by other means.

parameter allowed_algs
List of acceptable algorithms. Default: all except none. Note: "none" is only allowed if BOTH in this list AND allow_none=true.

val validate : 
  now:Ptime.t ->
  ?iss:string ->
  ?aud:string ->
  ?leeway:Ptime.Span.t ->
  t ->
  (unit, error) result

validate ~now ?iss ?aud ?leeway t validates JWT claims.

parameter now
Current time (required, no implicit clock)

parameter iss
Expected issuer (if provided, must match exactly)

parameter aud
Expected audience (if provided, must be in audience list)

parameter leeway
Clock skew tolerance for exp/nbf checks (default 0s)

val verify_and_validate : 
  key:Jwk.t ->
  now:Ptime.t ->
  ?allow_none:bool ->
  ?allowed_algs:Algorithm.t list ->
  ?iss:string ->
  ?aud:string ->
  ?leeway:Ptime.Span.t ->
  t ->
  (unit, error) result

verify_and_validate ~key ~now ... verifies signature and validates claims.

Creation

See RFC 7519 Section 7.1.

val create : 
  header:Header.t ->
  claims:Claims.t ->
  key:Jwk.t ->
  (t, error) result

create ~header ~claims ~key creates and signs a new JWT.

The key must be appropriate for the algorithm specified in header. For alg:none, pass any key (it will be ignored).

val encode : t -> string

encode t returns the compact serialization of the JWT.

Utilities

val is_expired : now:Ptime.t -> ?leeway:Ptime.Span.t -> t -> bool

is_expired ~now ?leeway t checks if the token has expired. Returns false if no exp claim present.

val time_to_expiry : now:Ptime.t -> t -> Ptime.Span.t option

time_to_expiry ~now t returns time until expiration, or None if no expiration claim or already expired.

Base64url Utilities

Exposed for testing with RFC test vectors.

val base64url_encode : string -> string

Base64url encode without padding per RFC 7515 Appendix C.

val base64url_decode : string -> (string, error) result

Base64url decode, handling missing padding.

CBOR Web Token (CWT)

See RFC 8392.

module Cwt : sig ... end

CBOR Web Token (CWT) - RFC 8392