Attesto.Plug.ResourceAuthenticate (Attesto v2.28.0)

Copy Markdown View Source

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

dpop_target_uri(conn, opts)

@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"