AttestoClient.IDToken (AttestoClient v0.6.0)

Copy Markdown View Source

Verify OpenID Connect ID Tokens issued by an authorization server.

This is the client-side mirror of Attesto.IDToken.mint/4. A relying party receives an ID Token from the server, fetches (or supplies) the server JWKS, and verifies the signed JWT plus the OIDC claims that bind it to the client and the authorization response.

Checks

  • signature verifies against the issuer JWKS, selected by kid, with Attesto's supported asymmetric algorithms.
  • JOSE typ, when present, must be "JWT"; an access-token type such as "at+jwt" is rejected.
  • iss equals :issuer.
  • aud equals, or is an all-string array containing, :client_id.
  • azp equals :client_id whenever present, and is required when aud contains multiple audiences.
  • sub, exp, and iat are present and well-typed; exp must be in the future and iat must not be meaningfully in the future.
  • a supplied :nonce must match the token's nonce claim.
  • auth_time, when present, must not be meaningfully in the future; a supplied :max_age requires auth_time and enforces the age.
  • supplied :access_token, :code, and :state are checked against at_hash, c_hash, and s_hash respectively using the ID Token signing algorithm's left-half hash construction.

:jwks may be supplied directly. Otherwise the verifier can fetch through AttestoClient.Discovery: pass :metadata, :jwks_uri, or just :issuer with optional :req_options / :well_known.

Summary

Types

error()
verify_opt()

Functions

verify(id_token, opts)

Verify id_token, returning {:ok, claims} or {:error, reason}.

Types

error()

@type error() ::
  :missing_issuer
  | :missing_client_id
  | :invalid_jwks
  | :invalid_metadata
  | :issuer_mismatch
  | :unsupported_alg
  | :invalid_token
  | :invalid_signature
  | :unsupported_critical_header
  | :unexpected_typ
  | :invalid_issuer
  | :invalid_audience
  | :missing_azp
  | :invalid_azp
  | :invalid_claims
  | :missing_exp
  | :expired
  | :invalid_iat
  | :not_yet_valid
  | :nonce_required
  | :nonce_mismatch
  | :invalid_max_age
  | :auth_time_required
  | :invalid_auth_time
  | :max_age_exceeded
  | :missing_at_hash
  | :invalid_at_hash
  | :missing_c_hash
  | :invalid_c_hash
  | :missing_s_hash
  | :invalid_s_hash
  | AttestoClient.Discovery.error()

verify_opt()

@type verify_opt() ::
  {:issuer, String.t()}
  | {:client_id, String.t()}
  | {:jwks, AttestoClient.Verifier.jwks()}
  | {:metadata, map()}
  | {:jwks_uri, String.t()}
  | {:nonce, String.t()}
  | {:max_age, non_neg_integer()}
  | {:access_token, String.t()}
  | {:code, String.t()}
  | {:state, String.t()}
  | {:accepted_algs, [Attesto.SigningAlg.alg()]}
  | {:now, integer() | DateTime.t()}
  | {:req_options, keyword()}
  | {:well_known, AttestoClient.Discovery.well_known()}

Functions

verify(id_token, opts)

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

Verify id_token, returning {:ok, claims} or {:error, reason}.

Required options:

  • :issuer - expected OpenID Provider issuer.
  • :client_id - this relying party's client id.

JWKS options:

  • :jwks - a JWKS map/list supplied by the caller.
  • :metadata - discovery metadata containing matching issuer and jwks_uri.
  • :jwks_uri - fetch only the JWKS.
  • no JWKS option - fetch discovery from :issuer, then fetch its JWKS.