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.
Install
Section titled “Install”cargo add nest-rs --features oauth-resourceWire it in
Section titled “Wire it in”#[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.
NESTRS_OAUTH__RESOURCE__RESOURCE=https://api.example.comNESTRS_OAUTH__RESOURCE__AUTHORIZATION_SERVERS=https://auth.example.comThe 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.
What the document says
Section titled “What the document says”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 var | Document member | What it says |
|---|---|---|
<PREFIX>_OAUTH__RESOURCE__RESOURCE_NAME | resource_name | a human-readable name for this resource (§2 RECOMMENDs it) |
<PREFIX>_OAUTH__RESOURCE__RESOURCE_DOCUMENTATION | resource_documentation | where a developer reads about it |
<PREFIX>_OAUTH__RESOURCE__RESOURCE_POLICY_URI | resource_policy_uri | where a developer reads how this resource’s data may be used |
<PREFIX>_OAUTH__RESOURCE__RESOURCE_TOS_URI | resource_tos_uri | the terms of service |
<PREFIX>_OAUTH__RESOURCE__BEARER_METHODS_SUPPORTED | bearer_methods_supported | how 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
Section titled “The discovery walk”The discovery walk, from a client that knows only one URL:
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 ForbiddenWWW-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.
What a token is checked against
Section titled “What a token is checked against”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.
Going further
Section titled “Going further”- Split deployment — the issuer and the resource servers this document connects.
- OAuth scopes — the rules behind the
insufficient_scopechallenge. - JWT configuration — the issuer and audience the module binds the verifier to.