Attesto.Plug.RequireScopes (Attesto v0.13.0)

Copy Markdown View Source

Authorize a request against the scopes on the verified token.

Runs after Attesto.Plug.Authenticate (which assigns the verified claims): it reads the scope claim, splits it, and checks that the granted set covers every required scope via Attesto.Scope. On success the conn passes through; otherwise it answers 403 insufficient_scope (RFC 6750 §3.1).

plug Attesto.Plug.RequireScopes, ["documents.read"]

Options. The first argument may be a bare list of required scopes, or a keyword list with:

  • :scopes (required) - the list of required concrete scopes.
  • :claims_key - the conn.assigns key the claims were put under (default :attesto_claims, matching Attesto.Plug.Authenticate).
  • :resource_metadata - the URL of this resource's protected-resource metadata (RFC 9728), advertised as a resource_metadata auth-param on the 403 insufficient_scope (and the 401 invalid_token for an unauthenticated request) WWW-Authenticate challenge (RFC 9728 §5.1).
  • :send_error, :www_authenticate, :no_store - the transport hooks Attesto.Plug.OAuthError honors, threaded onto BOTH the 403 and the 401 this plug renders so a host can override the response envelope and inject a per-conn challenge (e.g. a request-derived resource_metadata pointer) on the scope-rejection path, not just the authentication-rejection path.

A request that reaches this plug without verified claims (the authentication plug did not run or did not assign them) is treated as unauthenticated and answered 401.

Part of the optional Attesto.Plug layer; compiles only with Plug.