Skip to content

Protected resource metadata

OAuthResourceModule serves the RFC 9728 document and points every 401 at it, so a client learns which authorization server issues this API's tokens.

An OAuth client that has never met your API does not know which authorization server to ask. OAuthResourceModule answers that, the way RFC 9728 and the MCP authorization spec require: it serves /.well-known/oauth-protected-resource, and it stamps a pointer to that document onto every 401 the app emits.

Terminal window
cargo add nest-rs --features oauth-resource
apps/api/src/module.rs
#[module(imports = [
OAuthResourceModule,
])]
pub struct ApiModule;

It imports the token verifier it binds, AuthnModule, itself: the root names neither the verifier nor its key. A resource server with no key to verify with fails the boot as AuthnModule does, naming the <PREFIX>_AUTHN__* variables that give it one — never a server that accepts nothing, or anything.

Terminal window
NESTRS_OAUTH__RESOURCE__RESOURCE=https://api.example.com
NESTRS_OAUTH__RESOURCE__AUTHORIZATION_SERVERS=https://auth.example.com

The resource and each issuer are absolute https URIs naming a host, with no userinfo and no fragment; anything else fails the boot, naming the variable and never the value. Plain http is spared on localhost, 127.0.0.1 or [::1] in a declared development or test profile (<PREFIX>_ENV) alone, so a local loop runs without a certificate while staging and production speak https, loopback included.

Five more members of the RFC 9728 document round out the deployment’s description of itself. The four naming the resource are omitted from the served JSON when unset, as §3.2 requires, and bearer_methods_supported is served as ["header"]:

Env varDocument memberWhat it says
<PREFIX>_OAUTH__RESOURCE__RESOURCE_NAMEresource_namea human-readable name for this resource (§2 RECOMMENDs it)
<PREFIX>_OAUTH__RESOURCE__RESOURCE_DOCUMENTATIONresource_documentationwhere a developer reads about it
<PREFIX>_OAUTH__RESOURCE__RESOURCE_POLICY_URIresource_policy_uriwhere a developer reads how this resource’s data may be used
<PREFIX>_OAUTH__RESOURCE__RESOURCE_TOS_URIresource_tos_urithe terms of service
<PREFIX>_OAUTH__RESOURCE__BEARER_METHODS_SUPPORTEDbearer_methods_supportedhow a token may be presented. §2’s defined values are header, body and query; the framework reads a bearer token only from the Authorization header, so anything but header fails the boot rather than advertising a form this server refuses

The documentation, policy and terms URLs are published as they are set, so one carrying userinfo fails the boot as the resource does.

§2 defines fourteen members and the framework serves eight. The rest are not advertised, because nothing here implements them: nothing signs a response, so no jwks_uri; no cnf-claim handling, so no DPoP binding; a Strategy never sees the TLS handshake, so no mTLS binding. signed_metadata is not advertised either.

A token your issuer bound to a key anyway — one carrying cnf, DPoP’s jkt or a certificate’s x5t#S256 — is refused, 401 invalid_token, on the guard’s one warn with the reason sender_constrained: read as a bearer it would pass with no proof, and a stolen copy with it. RFC 9449 §7.2 requires that of a resource taking both schemes and expects a Bearer-only one to accept such a token; the framework refuses it all the same, so a binding your issuer asked for is never dropped in silence. Have the issuer mint this audience a plain bearer token.

The discovery walk, from a client that knows only one URL:

Terminal window
curl -si https://api.example.com/users | grep -i www-authenticate
# www-authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource", scope="users:read users:write"
curl -s https://api.example.com/.well-known/oauth-protected-resource
# {"resource":"https://api.example.com","authorization_servers":["https://auth.example.com"], …}

The metadata route is declared #[public], because a client cannot hold a token before it has read the document that says where to get one. Everything else stays closed.

When RESOURCE carries a path — https://api.example.com/mcp — the document is published at the path-aware URL RFC 9728 §3.1 defines, https://api.example.com/.well-known/oauth-protected-resource/mcp, and that is what the challenge advertises. The unsuffixed URL stays served for the bare-origin case and for clients that skip the challenge; a tail that is not this resource’s path answers 404 rather than claiming an identity the deployment does not have.

The second refusal: a token that is merely too narrow

Section titled “The second refusal: a token that is merely too narrow”

The 401 above is “you have no token”. Its counterpart is “your token verified, but it was not delegated enough” — a 403 carrying the RFC 6750 §3.1 challenge:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
resource_metadata="https://api.example.com/.well-known/oauth-protected-resource",
scope="users:write"

Both are written by the same unit-stage interceptor around every HTTP request, so a route, a WS upgrade and /mcp get them identically and neither can drift from the metadata document. What raises the 403 is a scope-gated authorization rule — see OAuth scopes. Hand the module the scopes your rules gate on, declared once — OAuthResourceModule::for_root(constants::ALL) — and the document and the challenge advertise them; a deployment setting SCOPES_SUPPORTED advertises its own list instead, which must hold every one, or you are telling clients to request something discovery never names.

The document is what a token is checked against. Under this module the verifier binds itself to the resource it advertises, as RFC 9068 §4 asks of a resource server: a token is accepted only when its aud is RESOURCE and its iss exactly matches one of AUTHORIZATION_SERVERS, so a token minted for another service, or signed by an issuer the document does not name, is refused — one carrying no aud or no iss too. Nothing is copied by hand: <PREFIX>_AUTHN__AUDIENCE may stay unset, and when set to something else — some authorization servers mint an opaque audience by policy — it is the one required, and the boot warns naming both variables. <PREFIX>_AUTHN__ISSUER narrows the accepted issuers to itself, and must be one of them: an issuer the document does not advertise would refuse every token, so the boot fails naming both variables. An app that also mints access tokens sets it, or sign and sign_for refuse naming it, since every access token names its issuer (RFC 9068 §2.2); its OAuth transaction cookie is checked against what it stamps, and needs nothing. ALLOW_ANY_AUDIENCE beside the module fails the boot, since an audience-agnostic verifier protects no resource.

  • Split deployment — the issuer and the resource servers this document connects.
  • OAuth scopes — the rules behind the insufficient_scope challenge.
  • JWT configuration — the issuer and audience the module binds the verifier to.