Attesto.AuthorizationRequest (Attesto v2.28.0)

Copy Markdown View Source

Authorization endpoint request validation (RFC 6749 §4.1.1, OIDC Core §3.1.2.1, RFC 7636 §4.3).

This module validates the protocol shape of an authorization request that the transport layer has already parsed out of the query string. It checks the response_type, the presence of client_id and redirect_uri, the requested scope (surfacing whether the OpenID Connect openid scope was requested), and the PKCE parameters (code_challenge + code_challenge_method). It carries state, nonce, claims, validated RFC 9396 authorization_details, and the optional prompt / max_age / acr_values parameters through to the normalized result.

It deliberately does NOT:

  • authenticate the resource owner or render consent (host policy, performed in the Phoenix layer);
  • decide whether the client_id exists, beyond requiring it to be present;
  • issue an authorization code (Attesto.AuthorizationCode.issue/3 does that, consuming the normalized request this module returns).

It DOES check redirect_uri against the registered set the caller passes in :registered_redirect_uris by exact string match (RFC 6749 §3.1.2.3, OIDC Core §3.1.2.1): the registered set is a fact the host supplies, not a policy decision this module makes. A caller running the RFC 8252 native-app profile may widen that comparison to the loopback-port exception (§7.3) with :redirect_uri_matching; see Attesto.RedirectURI.

Error disposition (OIDC Core §3.1.2.6, RFC 6749 §4.1.2.1)

RFC 6749 §4.1.2.1 and OIDC Core §3.1.2.6 split authorization errors into two classes by where the error may be reported:

  • {:error, {:direct, reason}} - the request client_id or redirect_uri is missing or invalid. The authorization server MUST NOT redirect back to the supplied URI (it is untrusted); the error is shown directly to the user agent. Reasons: :invalid_client_id, :missing_redirect_uri, :invalid_redirect_uri, :redirect_uri_not_registered.

  • {:error, {:redirect, error}} - the client_id/redirect_uri pair is trusted but some other parameter is invalid. The server redirects back to the validated redirect_uri with an error (and error_description) query parameter, echoing state when present. The error map carries: :error (the RFC 6749 §4.1.2.1 code), :error_description, :redirect_uri, and :state.

The Phoenix layer turns each class into the correct HTTP response; this core module only classifies.

Summary

Types

Why an authentication event does not satisfy a request's max_age.

The classification of a validation failure (OIDC Core §3.1.2.6).

A redirectable authorization error (RFC 6749 §4.1.2.1).

t()

A normalized, validated authorization request.

Functions

Check an authentication event against the request's max_age (OIDC Core §3.1.2.1).

Re-check the OIDC Core §3.1.2.1 nonce requirement against request's effective scope (for example after host scope policy applies defaults).

Check that prompt=login produced a new authentication (OIDC Core §3.1.2.1, §3.1.2.3). since is the Unix time the request arrived or was parked. Requests without login need no authentication timestamp.

Verify and resolve a JAR Request Object (RFC 9101 / OIDC Core §6.1 / FAPI 2.0 §5.3.1) for an authorization or PAR parameter map.

Check a host's choice of response modes: a non-empty list drawn from supported_response_modes/0, without repeats. Returns the list, or raises ArgumentError.

The response modes this authorization-code server accepts (OAuth 2.0 Response Modes / JARM §2.3): query and the JARM JWT modes. Exposed so the discovery document advertises exactly what validate/2 enforces.

Validate a parsed authorization request parameter map (RFC 6749 §4.1.1, OIDC Core §3.1.2.1, RFC 7636 §4.3).

Types

auth_time_error()

@type auth_time_error() ::
  :auth_time_required | :invalid_auth_time | :max_age_exceeded

Why an authentication event does not satisfy a request's max_age.

error()

@type error() ::
  {:direct,
   :invalid_client_id
   | :missing_redirect_uri
   | :invalid_redirect_uri
   | :redirect_uri_not_registered}
  | {:redirect, redirect_error()}

The classification of a validation failure (OIDC Core §3.1.2.6).

redirect_error()

@type redirect_error() :: %{
  :error => String.t(),
  :error_description => String.t(),
  :redirect_uri => String.t(),
  :state => String.t() | nil,
  optional(:response_mode) => String.t() | nil,
  optional(:client_id) => String.t()
}

A redirectable authorization error (RFC 6749 §4.1.2.1).

Errors raised once the client is trusted (from validate_redirectable/4) also carry :response_mode (the requested JARM mode, or nil) and :client_id, so the transport can return the error in the requested response mode (JARM §2.3); earlier errors omit them.

t()

@type t() :: %Attesto.AuthorizationRequest{
  acr_values: [String.t()],
  authorization_details: [map()],
  claims: map(),
  client_id: String.t(),
  code_challenge: String.t() | nil,
  code_challenge_method: String.t() | nil,
  dpop_jkt: String.t() | nil,
  id_token_hint: String.t() | nil,
  login_hint: String.t() | nil,
  max_age: non_neg_integer() | nil,
  nonce: String.t() | nil,
  openid?: boolean(),
  prompt: [String.t()],
  redirect_uri: String.t(),
  resource: [String.t()],
  response_mode: String.t() | nil,
  response_type: String.t(),
  scope: [String.t()],
  state: String.t() | nil
}

A normalized, validated authorization request.

The binding fields (client_id, redirect_uri, scope, code_challenge, code_challenge_method, nonce) line up with the attrs Attesto.AuthorizationCode.issue/3 consumes.

Functions

check_auth_time(request_or_max_age, auth_time, now, opts \\ [])

@spec check_auth_time(t() | non_neg_integer() | nil, term(), integer(), keyword()) ::
  :ok | {:error, auth_time_error()}

Check an authentication event against the request's max_age (OIDC Core §3.1.2.1).

auth_time is the Unix time the End-User was last actively authenticated, as the authorization server established it for this request, or nil when it has none. now is the current Unix time.

A request without max_age returns :ok whatever auth_time is. With max_age:

  • {:error, :auth_time_required} - there is no auth_time. OIDC Core §3.1.2.1: when max_age is used the ID Token MUST carry auth_time, so a response cannot be issued without one.
  • {:error, :invalid_auth_time} - auth_time is not a non-negative integer, or lies further in the future than :future_skew allows.
  • {:error, :max_age_exceeded} - more than max_age seconds have elapsed since auth_time, so the End-User must be actively re-authenticated.

Options:

  • :allowance - non-negative seconds added to max_age before an authentication counts as too old. Default 0. An authorization server that re-authenticated the End-User and then came back to finish the same request passes the time that round trip may take; a request that could not have involved a re-authentication (prompt=none) passes nothing.
  • :future_skew - seconds an auth_time may lie ahead of now. Default Attesto.NumericDate.default_clock_skew_seconds/0.

Also accepts a plain max_age (nil or non-negative integer) in place of %Attesto.AuthorizationRequest{} so relying parties and step-up checks apply the same freshness rule.

check_nonce(request, opts \\ [])

@spec check_nonce(
  t(),
  keyword()
) :: :ok | {:error, {:redirect, redirect_error()}}

Re-check the OIDC Core §3.1.2.1 nonce requirement against request's effective scope (for example after host scope policy applies defaults).

check_prompt_login(request, auth_time, since, opts \\ [])

@spec check_prompt_login(t(), term(), non_neg_integer(), keyword()) ::
  :ok
  | {:error,
     :auth_time_required | :invalid_auth_time | :reauthentication_required}

Check that prompt=login produced a new authentication (OIDC Core §3.1.2.1, §3.1.2.3). since is the Unix time the request arrived or was parked. Requests without login need no authentication timestamp.

:allowance permits that many seconds before since (default 0). :now defaults to since; pass the current Unix time for a resumed request. :future_skew defaults to Attesto.NumericDate.default_clock_skew_seconds/0. Missing or invalid timestamps return :auth_time_required or :invalid_auth_time; an older authentication returns :reauthentication_required. These timestamps establish freshness, not proof that a host displayed UI.

resolve_request_object(params, opts)

@spec resolve_request_object(
  map(),
  keyword()
) ::
  {:ok, map()}
  | {:error,
     :request_not_supported
     | :invalid_request_object
     | :duplicate_request
     | :request_object_required}

Verify and resolve a JAR Request Object (RFC 9101 / OIDC Core §6.1 / FAPI 2.0 §5.3.1) for an authorization or PAR parameter map.

Returns {:ok, resolved_params} or {:error, reason} where reason is one of :request_not_supported, :invalid_request_object, :duplicate_request, or :request_object_required.

response_modes!(modes)

@spec response_modes!(term()) :: [String.t()]

Check a host's choice of response modes: a non-empty list drawn from supported_response_modes/0, without repeats. Returns the list, or raises ArgumentError.

validate/2 applies it to :response_modes_supported. A layer that takes the same list as configuration calls it at boot, so a bad list fails there and not on the first request.

supported_response_modes()

@spec supported_response_modes() :: [String.t()]

The response modes this authorization-code server accepts (OAuth 2.0 Response Modes / JARM §2.3): query and the JARM JWT modes. Exposed so the discovery document advertises exactly what validate/2 enforces.

validate(params, opts)

@spec validate(
  map(),
  keyword()
) :: {:ok, t()} | {:error, error()}

Validate a parsed authorization request parameter map (RFC 6749 §4.1.1, OIDC Core §3.1.2.1, RFC 7636 §4.3).

params is a string-keyed map of the authorization request parameters. Present client_id, redirect_uri, response_type, scope, state, nonce, code_challenge, code_challenge_method, prompt, acr_values, response_mode, id_token_hint, login_hint, dpop_jkt, request, request_uri, and claims must be strings; other types (including nil) are malformed requests. Client and redirect URI errors remain direct; other type errors are redirectable once that pair is trusted. resource supports a list, max_age also supports an integer, and authorization_details also supports a decoded list from a Request Object.

Options

  • :registered_redirect_uris (required) - the list of redirect URIs registered for the client. The request redirect_uri MUST be an exact string match against one of these (RFC 6749 §3.1.2.3, OIDC Core §3.1.2.1). An empty list rejects every request with {:direct, :redirect_uri_not_registered}.

  • :redirect_uri_matching (optional, default :exact) - how the request redirect_uri is compared against :registered_redirect_uris, one of Attesto.RedirectURI.matching_modes/0. :exact is the RFC 6749 §3.1.2.3 simple string comparison. :exact_allow_loopback_port adds the RFC 8252 §7.3 exception for native apps, under which a loopback redirect URI (http://127.0.0.1/... or http://[::1]/..., never http://localhost/... - §8.3) matches on any port while scheme, host, path, and query still compare exactly; nothing else is relaxed. :exact_allow_loopback_port_including_localhost extends that same port flexibility to the bare localhost name, for native clients that register a portless localhost callback and bind an ephemeral port; the name stays a distinct host from the IP literals. Enabling either is a host decision, incompatible with profiles that mandate exact redirect-URI matching. An unrecognized value raises ArgumentError.

  • :require_nonce (optional, default false) - the host's OP nonce policy. When true, an OpenID Connect Authentication Request (one whose EFFECTIVE scope - after any signed request object is merged - carries openid) with no nonce is rejected with a redirectable invalid_request error (OIDC Core §3.1.2.1). The openid test runs on the merged request, so a scope=openid carried only inside a signed request object still triggers the requirement. A plain OAuth request (no openid scope) is never nonce-constrained (RFC 6749 keeps code at SHOULD). When false, nonce stays OPTIONAL and is carried through unenforced.

  • :require_pkce (optional, default true) - when true, a request with no code_challenge is rejected with a redirectable invalid_request error (RFC 7636 §4.3). When false, an absent code_challenge is permitted and the validated request carries none. The caller MUST pass false only for a confidential client: RFC 9700 §2.1.1 keeps PKCE a MUST for public clients. A code_challenge that IS present is fully enforced (S256, no plain) regardless of this flag - presence means the client opted into PKCE, so a downgrade is always rejected.

  • :response_modes_supported (optional, default supported_response_modes/0) - the response modes this authorization server accepts, a non-empty subset of supported_response_modes/0. A request for a mode outside the list is a redirectable invalid_request. A request with no response_mode asks for the default, query, so it is refused the same way when "query" is not listed. Anything other than a non-empty subset raises ArgumentError; see response_modes!/1.

  • :request_object_policy (optional, default %Attesto.RequestObject.Policy{})

  • :request_objects_supported (optional, default true) - whether this server supports the request parameter at all. With false, a request carrying a Request Object is answered request_not_supported (OIDC Core §3.1.2.6). With true, an object that cannot be verified, including one from a client with no usable keys, stays invalid_request_object.

A non-string request (including a list, map, or nil) is a redirectable invalid_request (RFC 6749 §3.1). An empty request counts as omitted, as that section requires.

Returns {:ok, %Attesto.AuthorizationRequest{}} or {:error, error()}, where error() is classified per the moduledoc.

The client_id / redirect_uri checks run first, because their failure is non-redirectable (OIDC Core §3.1.2.6): only once a trusted redirect_uri is established may any further error be reported by redirecting to it.