AttestoClient.ClientAssertion (AttestoClient v2.2.0)

Build private_key_jwt client-authentication assertions (RFC 7523 §2.2 / OpenID Connect Core §9), signed with the client's own private key.

This is the client-side mirror of Attesto.ClientAssertion.verify/5: the authorization server verifies the assertion at its token / PAR / introspection endpoints; the client builds one to authenticate. The assertion is a JWT whose iss and sub are the client_id and whose aud is the authorization server (its issuer identifier or the concrete endpoint URL, per the server's policy - RFC 7523 §3 / FAPI 2.0 prefers the issuer).

Claims (RFC 7523 §3)

iss = sub = the client_id.
aud = the authorization server identifier the assertion is presented to.
jti = a unique identifier (the server rejects replays).
iat, exp = issuance and a short expiry.

Signing uses the client key directly (a JOSE.JWK or a JWK map); the algorithm defaults to the key's natural algorithm (Attesto.SigningAlg.infer/1: RS256 for RSA, the curve-matched ES algorithm for EC, or legacy EdDSA for Edwards keys) and may be overridden with :alg. A FAPI client using RSA must therefore select alg: "PS256" explicitly; FAPI does not permit the inferred RS256 default. An explicit algorithm is validated against the key before signing; in particular, Ed25519 and Ed448 require their matching OKP curves.

Summary

Types

build_opt()

error()

jwk()

Functions

assertion_type()

The RFC 7523 §2.2 client_assertion_type value a client submits alongside the assertion.

build(jwk, opts)

Build a signed private_key_jwt assertion, returning {:ok, compact_jws} or {:error, reason}.

Types

build_opt()

@type build_opt() ::
  {:client_id, String.t()}
  | {:audience, String.t()}
  | {:alg, String.t()}
  | {:kid, String.t()}
  | {:lifetime, pos_integer()}
  | {:now, integer()}
  | {:jti, String.t()}

error()

@type error() ::
  :invalid_key
  | :invalid_client_id
  | :invalid_audience
  | :invalid_lifetime
  | :invalid_jti
  | :unsupported_alg
  | :unsupported_key
  | {:signing_failed, String.t()}

jwk()

@type jwk() :: JOSE.JWK.t() | map()

Functions

assertion_type()

@spec assertion_type() :: String.t()

The RFC 7523 §2.2 client_assertion_type value a client submits alongside the assertion.

build(jwk, opts)

@spec build(jwk(), [build_opt()]) :: {:ok, String.t()} | {:error, error()}

Build a signed private_key_jwt assertion, returning {:ok, compact_jws} or {:error, reason}.

Fails fast on invalid input rather than signing it: an empty :client_id or :audience, a non-positive :lifetime, an empty :jti, or an unsupported :alg (including "none") returns {:error, :unsupported_alg}. A supported algorithm that is incompatible with the key returns the existing {:error, {:signing_failed, message}} tuple before signing.

jwk is the client's private key (a JOSE.JWK or a JWK map).

Required options:

:client_id - the client identifier (becomes iss and sub).
:audience - the authorization server the assertion is addressed to (aud).

Optional:

:alg - the JWS algorithm; defaults to the key's natural algorithm. Set "PS256" explicitly for an RSA client under FAPI.
:kid - the JOSE kid header; defaults to the key's own kid when the JWK carries one, otherwise omitted.
:lifetime - seconds until exp; defaults to 60.
:now - issuance time (Unix seconds), for deterministic tests.
:jti - the assertion identifier; defaults to a fresh random value.