Reject bearer tokens that carry no audience claim

When `AuthSettings.resource_server_url` is configured, `BearerAuthBackend`
previously ran the RFC 8707 audience comparison only for tokens whose
verifier populated `AccessToken.resource`: a token carrying no resource
indicator at all was accepted. The MCP authorization spec requires a
resource server to only accept tokens issued specifically for it, so the
gate now fails closed: a verified token with no `resource` is answered
`401 invalid_token` ("The access token carries no audience claim").
`resource_server_url=None` still means there is no audience to enforce.

For verifiers that validate the audience themselves and cannot surface
the claim (for example a JWT decoder configured with the expected
audience), the new `AuthSettings.verifier_validates_audience=True` opts
the gate out. The `AuthSettings.enforced_audience` property derives the
single value both server wirings pass to `BearerAuthBackend`, whose
signature is unchanged.

`RefreshToken` gains an optional `resource` field so an authorization
server provider can carry the original grant's audience binding through
`exchange_refresh_token`; without it every refreshed access token would
be audience-unbound and rejected by the hardened gate.

The docs tutorials and example servers now populate
`AccessToken.resource` (and the client-credentials demo token endpoint
honors the RFC 8707 `resource` parameter) so they pass the check they
teach. The migration guide entry for audience validation is rewritten
for the fail-closed behavior.

Author: maxisbey

docs/advanced/authorization.md

@@ -16,7 +16,7 @@ That's the whole triangle. Everything on this page is the middle bullet.
 
 The SDK has no opinion about what a valid token looks like. You tell it, by implementing **`TokenVerifier`**:
 
-```python title="server.py" hl_lines="12-14 19-24"
+```python title="server.py" hl_lines="14-16 21-26"
 --8<-- "docs_src/authorization/tutorial001.py"
 ```
 
@@ -27,7 +27,7 @@ The SDK has no opinion about what a valid token looks like. You tell it, by impl
 `AuthSettings` is the public face of your resource server:
 
 * `issuer_url`: the authorization server that issues your tokens.
-* `resource_server_url`: the public URL of this MCP endpoint. It names *which* resource a token is for, and it's where the discovery document lives. When your verifier returns an `AccessToken.resource`, the SDK rejects the token unless it matches this URL, so a token issued for a different resource never reaches a tool.
+* `resource_server_url`: the public URL of this MCP endpoint. It names *which* resource a token is for, and it's where the discovery document lives. The SDK rejects any token whose `AccessToken.resource` does not match this URL, including one whose verifier left `resource` unset, so a token issued for a different resource (or for no resource) never reaches a tool. If your verifier validates the audience itself and cannot surface the claim, set `verifier_validates_audience=True`.
 * `required_scopes`: every token must carry all of them.
 
 !!! tip
@@ -83,7 +83,7 @@ This document is how a client that has never heard of your server finds its way
 
 Inside any handler, **`get_access_token()`** is the `AccessToken` your verifier returned for the current request:
 
-```python title="server.py" hl_lines="4 32-35"
+```python title="server.py" hl_lines="4 34-37"
 --8<-- "docs_src/authorization/tutorial002.py"
 ```
 

docs/migration.md

@@ -1401,9 +1401,18 @@ issuer inconsistent with what clients compare against under RFC 8414 / RFC 9207.
 already-built `AnyHttpUrl` object still normalizes at construction; pass a string to get the
 preserved form.
 
-### Bearer tokens with a mismatched audience are rejected
+### Bearer tokens are rejected unless their audience names this server
 
-`BearerAuthBackend` now compares `AccessToken.resource` against `AuthSettings.resource_server_url` and answers a token whose RFC 8707 resource indicator does not name this server with `401 invalid_token`. The check is canonical-URI equality, so a token issued for `https://host/` is not accepted by a server at `https://host/mcp`. It is skipped when either side is `None` — populate `AccessToken.resource` only when your verifier surfaces the underlying audience claim. `BearerAuthBackend.__init__` gains a keyword-only `resource_server_url: AnyHttpUrl | None = None`, wired automatically from `AuthSettings`; pass it only if you construct the backend directly.
+`BearerAuthBackend` now compares `AccessToken.resource` against `AuthSettings.resource_server_url` and answers any token whose RFC 8707 resource indicator does not name this server — **including a token that carries no resource indicator at all** — with `401 invalid_token`. The comparison is canonical-URI equality, so a token issued for `https://host/` is not accepted by a server at `https://host/mcp`.
+
+To migrate, do exactly one of:
+
+- **Populate `AccessToken.resource`** from the token's `aud` claim (an introspection response's `aud`, or the decoded JWT's `aud`) in your `TokenVerifier`. This is the recommended path and what the SDK's examples now show.
+- **Set `AuthSettings(verifier_validates_audience=True)`** if your verifier already validates the audience itself and cannot surface it — for example a JWT library configured with `audience=` that fails decoding on a mismatch. This tells the bearer gate not to repeat a check your verifier already performed. Do not set it just to make the `401` go away: with it set, the SDK performs no audience validation of its own at all.
+
+Leaving `resource_server_url=None` continues to disable the check entirely (there is no audience to compare against), but a protected server should configure it: it is also the value published as RFC 9728 Protected Resource Metadata. If your authorization server does not support RFC 8707 resource indicators, your tokens will not carry an audience — audit that before opting out, because accepting audience-unbound tokens is what the MCP specification's audience-validation MUST exists to prevent.
+
+`RefreshToken` gains an optional `resource` field so an `OAuthAuthorizationServerProvider` can propagate the original grant's audience binding through `exchange_refresh_token`; without it a refreshed access token would carry no audience and be rejected. `BearerAuthBackend.__init__` gains a keyword-only `resource_server_url: AnyHttpUrl | None = None`, wired automatically from `AuthSettings.enforced_audience`; `None` (the default, and what the SDK passes when `verifier_validates_audience` is set) means no audience is enforced.
 
 ### Lowlevel `Server`: `subscribe` capability now correctly reported
 

docs_src/authorization/tutorial001.py

@@ -5,7 +5,9 @@
 from mcp.server.auth.settings import AuthSettings
 
 KNOWN_TOKENS = {
-    "alice-token": AccessToken(token="alice-token", client_id="alice", scopes=["notes:read"]),
+    "alice-token": AccessToken(
+        token="alice-token", client_id="alice", scopes=["notes:read"], resource="http://127.0.0.1:8000/mcp"
+    ),
 }
 
 

docs_src/authorization/tutorial002.py

@@ -6,7 +6,9 @@
 from mcp.server.auth.settings import AuthSettings
 
 KNOWN_TOKENS = {
-    "alice-token": AccessToken(token="alice-token", client_id="alice", scopes=["notes:read"]),
+    "alice-token": AccessToken(
+        token="alice-token", client_id="alice", scopes=["notes:read"], resource="http://127.0.0.1:8000/mcp"
+    ),
 }
 
 

examples/stories/bearer_auth/server.py

@@ -28,6 +28,7 @@ async def verify_token(self, token: str) -> AccessToken | None:
             client_id="demo-client",
             scopes=[REQUIRED_SCOPE],
             expires_at=int(time.time()) + 3600,
+            resource=RESOURCE_URL,
             subject="demo-user",
         )
 

examples/stories/oauth_client_credentials/server.py

@@ -13,7 +13,7 @@
 from mcp.server.mcpserver import MCPServer
 from mcp.shared.auth import OAuthMetadata, OAuthToken
 from stories._hosting import NO_DNS_REBIND, run_app_from_args
-from stories._shared.auth import BASE_URL, auth_settings
+from stories._shared.auth import BASE_URL, MCP_URL, auth_settings
 
 # DEMO ONLY — never hard-code real credentials.
 DEMO_CLIENT_ID = "demo-m2m-client"
@@ -65,8 +65,17 @@ async def token_endpoint(request: Request) -> JSONResponse:
         creds = base64.b64decode(request.headers.get("authorization", "").removeprefix("Basic ")).decode()
         if creds != f"{DEMO_CLIENT_ID}:{DEMO_CLIENT_SECRET}":
             return JSONResponse({"error": "invalid_client"}, status_code=401)
+        # RFC 8707 §2.2: this AS protects exactly one resource. Anything else (or a missing
+        # indicator) is answered with `invalid_target`, and the issued token is audience-bound
+        # to that one resource so the bearer gate accepts it. Never mint whatever audience the
+        # client names: a multi-resource AS that does so hands out tokens for resources the
+        # client was never granted.
+        if form.get("resource") != MCP_URL:
+            return JSONResponse({"error": "invalid_target"}, status_code=400)
         access = f"access_{secrets.token_hex(16)}"
-        issued[access] = AccessToken(token=access, client_id=DEMO_CLIENT_ID, scopes=[DEMO_SCOPE], expires_at=None)
+        issued[access] = AccessToken(
+            token=access, client_id=DEMO_CLIENT_ID, scopes=[DEMO_SCOPE], expires_at=None, resource=MCP_URL
+        )
         body = OAuthToken(access_token=access, token_type="Bearer", expires_in=3600, scope=DEMO_SCOPE)
         return JSONResponse(body.model_dump(exclude_none=True), headers={"cache-control": "no-store"})
 

examples/stories/oauth_client_credentials/server_lowlevel.py

@@ -18,7 +18,7 @@
 from mcp.server.lowlevel import Server
 from mcp.shared.auth import OAuthMetadata, OAuthToken
 from stories._hosting import NO_DNS_REBIND, run_app_from_args
-from stories._shared.auth import BASE_URL, auth_settings
+from stories._shared.auth import BASE_URL, MCP_URL, auth_settings
 
 from .server import DEMO_CLIENT_ID, DEMO_CLIENT_SECRET, DEMO_SCOPE
 
@@ -62,8 +62,17 @@ async def token_endpoint(request: Request) -> JSONResponse:
         creds = base64.b64decode(request.headers.get("authorization", "").removeprefix("Basic ")).decode()
         if creds != f"{DEMO_CLIENT_ID}:{DEMO_CLIENT_SECRET}":
             return JSONResponse({"error": "invalid_client"}, status_code=401)
+        # RFC 8707 §2.2: this AS protects exactly one resource. Anything else (or a missing
+        # indicator) is answered with `invalid_target`, and the issued token is audience-bound
+        # to that one resource so the bearer gate accepts it. Never mint whatever audience the
+        # client names: a multi-resource AS that does so hands out tokens for resources the
+        # client was never granted.
+        if form.get("resource") != MCP_URL:
+            return JSONResponse({"error": "invalid_target"}, status_code=400)
         access = f"access_{secrets.token_hex(16)}"
-        issued[access] = AccessToken(token=access, client_id=DEMO_CLIENT_ID, scopes=[DEMO_SCOPE], expires_at=None)
+        issued[access] = AccessToken(
+            token=access, client_id=DEMO_CLIENT_ID, scopes=[DEMO_SCOPE], expires_at=None, resource=MCP_URL
+        )
         body = OAuthToken(access_token=access, token_type="Bearer", expires_in=3600, scope=DEMO_SCOPE)
         return JSONResponse(body.model_dump(exclude_none=True), headers={"cache-control": "no-store"})
 

src/mcp/server/auth/middleware/bearer_auth.py

@@ -69,6 +69,12 @@ class BearerAuthBackend(AuthenticationBackend):
     """Authentication backend that validates Bearer tokens using a TokenVerifier."""
 
     def __init__(self, token_verifier: TokenVerifier, *, resource_server_url: AnyHttpUrl | None = None) -> None:
+        """Validate bearer tokens with `token_verifier` and, when `resource_server_url` is set,
+        enforce that every token's RFC 8707 audience names exactly that resource.
+
+        `resource_server_url=None` means there is no audience to enforce; verification stops at
+        the verifier's answer and the expiry check.
+        """
         self.token_verifier = token_verifier
         self.resource_server_url = resource_server_url
 
@@ -86,12 +92,11 @@ async def authenticate(self, conn: HTTPConnection) -> tuple[AuthCredentials, Bas
             return AuthCredentials(), InvalidTokenUser("The access token is malformed or unknown")
         if auth_info.expires_at is not None and auth_info.expires_at < int(time.time()):
             return AuthCredentials(), InvalidTokenUser("The access token has expired")
-        if (
-            self.resource_server_url is not None
-            and auth_info.resource is not None
-            and not check_token_audience(auth_info.resource, self.resource_server_url)
-        ):
-            return AuthCredentials(), InvalidTokenUser("The access token was issued for a different resource")
+        if self.resource_server_url is not None:
+            if auth_info.resource is None:
+                return AuthCredentials(), InvalidTokenUser("The access token carries no audience claim")
+            if not check_token_audience(auth_info.resource, self.resource_server_url):
+                return AuthCredentials(), InvalidTokenUser("The access token was issued for a different resource")
 
         return AuthCredentials(auth_info.scopes), AuthenticatedUser(auth_info)
 

src/mcp/server/auth/provider.py

@@ -33,6 +33,7 @@ class RefreshToken(BaseModel):
     client_id: str
     scopes: list[str]
     expires_at: int | None = None
+    resource: str | None = None  # RFC 8707 resource indicator; propagate to refreshed AccessTokens
     subject: str | None = None  # resource owner; propagate to refreshed AccessTokens
 
 

src/mcp/server/auth/settings.py

@@ -34,3 +34,23 @@ class AuthSettings(BaseModel):
         description="The URL of the MCP server to be used as the resource identifier "
         "and base route to look up OAuth Protected Resource Metadata.",
     )
+
+    verifier_validates_audience: bool = Field(
+        default=False,
+        description="Set when your TokenVerifier validates the token's audience itself and "
+        "therefore never populates AccessToken.resource (for example a JWT decoder configured "
+        "with the expected audience). The bearer gate then skips its own audience check. "
+        "Leave False to have the SDK reject any token whose resource indicator is absent or "
+        "names a different server.",
+    )
+
+    @property
+    def enforced_audience(self) -> AnyHttpUrl | None:
+        """The resource identifier the bearer gate compares each token's audience against.
+
+        `None` when no `resource_server_url` is configured, or when
+        `verifier_validates_audience` declares that the verifier already did the check -- in
+        both cases the gate has nothing of its own to enforce. Both server wirings read this,
+        so it is the single source of the should-the-gate-audience-check decision.
+        """
+        return None if self.verifier_validates_audience else self.resource_server_url