Authenticate one OAuth protected resource using Attesto.Plug.Authenticate.
Requires an explicit :resource_audience or :trusted_audiences policy.
With resource_audience: :resource, use :resource_path and a pinned
:base_url or :origin. Never derive an audience from an unchecked Host.
A DPoP mount requires a pin or an explicit :htu callback at initialization;
:allow_dynamic_origin also supports a non-empty :allowed_hosts allowlist.
HTTP pins require allow_http: true and loopback.
:base_url / :origin accepts a URL, one-arity callback or MFA tuple.
:resource_audience also accepts a literal identifier, callback or MFA.
:resource_metadata_url overrides the derived RFC 9728 challenge pointer;
:www_authenticate overrides challenge rendering entirely.
:principal receives verified claims and sender context and returns
{:ok, principal} or {:error, reason}. The exact error result
{:error, {:temporarily_unavailable, reason}} answers 503
temporarily_unavailable, without a challenge or Retry-After. The reason
is discarded. Every other result answers 401 invalid_token. An exception
the callback raises is not caught, as with the verifier: it reaches the
host's error handling, which typically answers 500. MFA extras follow call
arguments.
Assign keys are configurable with :claims_key (default :attesto_claims),
:scopes_key (:attesto_scopes), :sender_key (:attesto_sender),
:principal_key (:attesto_principal) and :context_key (:attesto_context).
The context contains subject, client_id, scope, claims, cnf and principal.
:policy_rejection_send_error optionally supplies a separate error renderer
for principal refusals; otherwise :send_error handles them too.
:principal_unavailable_send_error similarly overrides :send_error for
principal outages. Both hooks receive (conn, status, body).
Outcome hooks distinguish :policy_rejected (401 principal refusal),
:principal_unavailable (503 principal outage), and :verifier_unavailable
(503 verifier outage through :send_error). A status/body alone cannot
distinguish the two outage outcomes.
All other Attesto.Plug.Authenticate options pass through, including
:config, :verify, :replay_check, :nonce_check, :nonce_issue,
:cert_der, :htu, :credential_from_conn, :bearer_methods, :step_up,
:send_error, :www_authenticate, :no_store and verification options.
With no explicit :bearer_methods, the base plug's defaults apply.
Use Attesto.Plug.ProtectResource to add per-route scope authorization.
Summary
Functions
Returns the DPoP target URI (htu) a proof must sign for conn when the
plug is configured with opts and no :htu: the origin resolved by
Attesto.ResourceMetadata.resolve_origin/2 followed by conn.request_path.
Functions
@spec dpop_target_uri( Plug.Conn.t(), keyword() ) :: String.t()
Returns the DPoP target URI (htu) a proof must sign for conn when the
plug is configured with opts and no :htu: the origin resolved by
Attesto.ResourceMetadata.resolve_origin/2 followed by conn.request_path.
With a pinned :base_url or :origin, the request's scheme, Host header,
and port do not affect the result. A pinned value carrying a path prefix is
joined with conn.request_path, which matches a proxy that strips that
prefix before the request reaches the application. Without a pin, the
resolved origin is the request's own.
iex> conn = Plug.Test.conn(:post, "http://10.0.0.5:4000/mcp")
iex> Attesto.Plug.ResourceAuthenticate.dpop_target_uri(conn, base_url: "https://mcp.example.com")
"https://mcp.example.com/mcp"