Attesto.JARM (Attesto v0.7.0)

Copy Markdown View Source

JWT Secured Authorization Response Mode (JARM).

Builds the signed JWT an authorization server returns to a client as the single response parameter when a JWT response mode (jwt, query.jwt, fragment.jwt, form_post.jwt) is requested, giving the authorization response non-repudiation and integrity (FAPI 2.0 Message Signing §5.4).

This is conn-free core: it turns the issuer/keystore on the Attesto.Config, the client identifier, and a map of authorization-response parameters (the code/state/iss of a success, or the error/error_description/state of a failure) into a compact JWS. The transport layer (the authorization endpoint) decides the response mode and how the resulting JWT is delivered (redirect query/fragment or auto-submitting form); nothing here touches HTTP.

JWT claims (JARM §2.1)

  • iss - REQUIRED, the authorization server's issuer identifier.
  • aud - REQUIRED, the client the response is addressed to (client_id).
  • exp - REQUIRED, expiration; the response is short-lived.
  • iat - the issuance time.
  • every supplied authorization-response parameter, verbatim, as a top-level claim (code, state, iss-echo for success; error, error_description, error_uri, state for failure).

Signing mirrors Attesto.IDToken: the keystore's current signing key and its algorithm (Attesto.SigningAlg.for_key/3), with the kid in the JOSE header, signed with that pinned algorithm (never none).

Summary

Functions

Build and sign the JARM response JWT for client_id, carrying params.

Types

opts()

@type opts() :: [now: integer() | DateTime.t(), lifetime: pos_integer()]

response_params()

@type response_params() :: %{optional(String.t()) => String.t() | nil}

Functions

response_jwt(config, client_id, params, opts \\ [])

@spec response_jwt(Attesto.Config.t(), String.t(), response_params(), opts()) ::
  {:ok, String.t()}

Build and sign the JARM response JWT for client_id, carrying params.

params is the authorization-response parameter map; nil values are dropped (an absent state/error_uri is not advertised). Returns {:ok, compact_jws}.

Options:

  • :now - the issuance time (integer Unix seconds or DateTime), for deterministic tests; defaults to the current time.
  • :lifetime - the JWT lifetime in seconds; may only shorten the 600-second default.