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_idexists, beyond requiring it to be present; - issue an authorization code (
Attesto.AuthorizationCode.issue/3does 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 requestclient_idorredirect_uriis 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}}- theclient_id/redirect_uripair is trusted but some other parameter is invalid. The server redirects back to the validatedredirect_uriwith anerror(anderror_description) query parameter, echoingstatewhen present. Theerrormap 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).
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
@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.
@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).
@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.
@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
@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 noauth_time. OIDC Core §3.1.2.1: whenmax_ageis used the ID Token MUST carryauth_time, so a response cannot be issued without one.{:error, :invalid_auth_time}-auth_timeis not a non-negative integer, or lies further in the future than:future_skewallows.{:error, :max_age_exceeded}- more thanmax_ageseconds have elapsed sinceauth_time, so the End-User must be actively re-authenticated.
Options:
:allowance- non-negative seconds added tomax_agebefore an authentication counts as too old. Default0. 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 anauth_timemay lie ahead ofnow. DefaultAttesto.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.
@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).
@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.
@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.
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.
@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 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 requestredirect_uriMUST 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 requestredirect_uriis compared against:registered_redirect_uris, one ofAttesto.RedirectURI.matching_modes/0.:exactis the RFC 6749 §3.1.2.3 simple string comparison.:exact_allow_loopback_portadds the RFC 8252 §7.3 exception for native apps, under which a loopback redirect URI (http://127.0.0.1/...orhttp://[::1]/..., neverhttp://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_localhostextends that same port flexibility to the barelocalhostname, for native clients that register a portlesslocalhostcallback 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 raisesArgumentError.:require_nonce(optional, defaultfalse) - the host's OP nonce policy. Whentrue, an OpenID Connect Authentication Request (one whose EFFECTIVE scope - after any signedrequestobject is merged - carriesopenid) with nononceis rejected with a redirectableinvalid_requesterror (OIDC Core §3.1.2.1). The openid test runs on the merged request, so ascope=openidcarried only inside a signed request object still triggers the requirement. A plain OAuth request (noopenidscope) is never nonce-constrained (RFC 6749 keepscodeat SHOULD). Whenfalse,noncestays OPTIONAL and is carried through unenforced.:require_pkce(optional, defaulttrue) - whentrue, a request with nocode_challengeis rejected with a redirectableinvalid_requesterror (RFC 7636 §4.3). Whenfalse, an absentcode_challengeis permitted and the validated request carries none. The caller MUST passfalseonly for a confidential client: RFC 9700 §2.1.1 keeps PKCE a MUST for public clients. Acode_challengethat IS present is fully enforced (S256, noplain) regardless of this flag - presence means the client opted into PKCE, so a downgrade is always rejected.:response_modes_supported(optional, defaultsupported_response_modes/0) - the response modes this authorization server accepts, a non-empty subset ofsupported_response_modes/0. A request for a mode outside the list is a redirectableinvalid_request. A request with noresponse_modeasks for the default,query, so it is refused the same way when"query"is not listed. Anything other than a non-empty subset raisesArgumentError; seeresponse_modes!/1.:request_object_policy(optional, default%Attesto.RequestObject.Policy{})- the JAR verification policy for a signed
requestobject (RFC 9101), threaded intoAttesto.RequestObject.verify/3. The default is the generic OpenID Connect §6.1 baseline (nbf/exp/typnot required). For FAPI 2.0 Message Signing §5.3.1 passAttesto.RequestObject.Policy.fapi_message_signing/0and set:request_object_audienceto the AS issuer. Has no effect unless arequestobject is present.
- the JAR verification policy for a signed
:request_objects_supported(optional, defaulttrue) - whether this server supports therequestparameter at all. Withfalse, a request carrying a Request Object is answeredrequest_not_supported(OIDC Core §3.1.2.6). Withtrue, an object that cannot be verified, including one from a client with no usable keys, staysinvalid_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.