Attesto.ClientAssertion (Attesto v2.6.1)

private_key_jwt client authentication verification (RFC 7523 / OIDC Core).

The host owns client registration and key storage. This module only verifies a compact client assertion against trusted client JWKs supplied by the host and checks the standard claims:

iss and sub equal the OAuth client_id
aud contains the expected token endpoint/audience
exp is in the future
iat, when present, is not meaningfully in the future
nbf, when present, has been reached within the permitted clock skew
exp is not earlier than a present iat or nbf
jti is present, non-empty, and at most 256 bytes for replay tracking by the caller

The JOSE algorithm is resolved from the trusted JWK's alg member when present, otherwise from the key shape. It is never accepted just because the presented JWT header names it.

Summary

Types

verify_error()

verify_opts()

Functions

assertion_type()

The required client_assertion_type value for private_key_jwt.

peek_client_id(assertion)

Peek iss from an assertion without trusting it.

verify(assertion, client_id, expected_audience, trusted_jwks, opts \\ [])

Verify a client assertion against the client's trusted JWK Set.

Types

verify_error()

@type verify_error() ::
  :invalid_assertion
  | :invalid_signature
  | :invalid_client_id
  | :invalid_audience
  | :expired
  | :not_yet_valid
  | :missing_jti
  | :unsupported_critical_header

verify_opts()

@type verify_opts() :: [
  now: DateTime.t() | non_neg_integer(),
  max_lifetime: pos_integer() | :unbounded,
  accepted_algs: [Attesto.SigningAlg.alg()],
  enforce_fapi_alg_policy: boolean()
]

Functions

assertion_type()

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

The required client_assertion_type value for private_key_jwt.

peek_client_id(assertion)

@spec peek_client_id(String.t()) :: {:ok, String.t()} | {:error, :invalid_assertion}

Peek iss from an assertion without trusting it.

verify(assertion, client_id, expected_audience, trusted_jwks, opts \\ [])

@spec verify(
  String.t(),
  String.t(),
  String.t() | [String.t()],
  map() | [map()] | map(),
  verify_opts()
) ::
  {:ok, map()} | {:error, verify_error()}

Verify a client assertion against the client's trusted JWK Set.

trusted_jwks may be an RFC 7517 JWK Set (%{"keys" => [...]}), a single public JWK map, or a list of public JWK maps.

Opts:

:max_lifetime - maximum remaining assertion lifetime in seconds, measured from verification time to exp. Defaults to 300. Set :unbounded only when the deployment deliberately applies its own assertion-lifetime policy.
:accepted_algs - the JOSE algorithms a candidate trusted key may use. Defaults to SigningAlg.fapi_algs/0 (PS256, ES256, EdDSA over Ed25519, and explicit Ed25519). An empty list always denies all algorithms.
:enforce_fapi_alg_policy - enforce the FAPI RSA modulus and Edwards curve restrictions in addition to :accepted_algs. Defaults to true for every algorithm allowlist. Only explicit false relaxes these gates.