Docs: shorter validate_token_resource guidance as a list; spell out test tokens

Author: maxisbey

docs/run/authorization.md

@@ -23,15 +23,18 @@ The SDK has no opinion about what a valid token looks like. You tell it, by impl
 ```
 
 * `TokenVerifier` is a protocol with one async method. `verify_token` gets the raw token from the `Authorization` header and returns an **`AccessToken`** if it's valid, `None` if it isn't. There is nothing else to implement.
-* This one looks the token up in a table that belongs to this server. A real one verifies a JWT signature or calls the authorization server's token-introspection endpoint, and puts the token's audience (`aud`) in `AccessToken.resource` so the SDK can check the token was issued for this server (see `validate_token_resource` below); if `aud` is a list, use the entry that equals your `resource_server_url`. That code is yours; the SDK only calls it.
+* This one looks the token up in a table. A real one verifies a JWT signature or calls the authorization server's token-introspection endpoint, and reports who the token was issued for (its `aud`) in `AccessToken.resource`. That code is yours; the SDK only calls it.
 * `token_verifier=` and `auth=` always travel together. Pass one without the other and `MCPServer(...)` raises a `ValueError` before it ever serves a request.
 
 `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.
 * `required_scopes`: every token must carry all of them.
-* `validate_token_resource`: refuse any token your verifier does not report as issued for `resource_server_url` (its `AccessToken.resource`, compared as a URL, a trailing slash aside). Turn it on when your authorization server binds tokens to the `resource` a client asks for, which is what MCP clients send, and keep `resource_server_url` the exact endpoint URL clients connect to: a client that skips the discovery document binds its token to that URL, and a parent such as the bare origin will not match. If your authorization server issues its own audience identifiers instead (an Auth0 API identifier, an Entra application ID), leave it off and check `aud` against that identifier in your verifier: a token you cannot tie to this server should come back as `None`.
+* `validate_token_resource`: refuse any token whose `AccessToken.resource` is not `resource_server_url`. Off by default.
+  * Turn it on when your authorization server binds tokens to the `resource` the client requested, which MCP clients always send. Keep `resource_server_url` the exact URL clients connect to.
+  * Leave it off when your authorization server uses its own audience identifiers (an Auth0 API identifier, an Entra application ID) and check `aud` in your verifier instead, returning `None` for a token that isn't for this server.
+  * If `aud` is a list, put the entry that equals `resource_server_url` in `resource`.
 
 !!! tip
     `examples/servers/simple-auth/` in the SDK repository has an `IntrospectionTokenVerifier` that calls

tests/interaction/auth/test_bearer.py

@@ -31,18 +31,24 @@
 _PAST = int(time.time()) - 3600
 
 
-def tok(name: str, *, scopes: list[str], expires_at: int, resource: str | None = RESOURCE) -> AccessToken:
-    return AccessToken(token=name, client_id="c", scopes=scopes, expires_at=expires_at, resource=resource)
-
-
 TOKENS = {
-    "tok-valid": tok("tok-valid", scopes=[REQUIRED_SCOPE], expires_at=_FUTURE),
-    "tok-expired": tok("tok-expired", scopes=[REQUIRED_SCOPE], expires_at=_PAST),
-    "tok-noscope": tok("tok-noscope", scopes=["other:thing"], expires_at=_FUTURE),
-    "tok-wrong-aud": tok(
-        "tok-wrong-aud", scopes=[REQUIRED_SCOPE], expires_at=_FUTURE, resource="https://other.example/mcp"
+    "tok-valid": AccessToken(
+        token="tok-valid", client_id="c", scopes=[REQUIRED_SCOPE], expires_at=_FUTURE, resource=RESOURCE
+    ),
+    "tok-expired": AccessToken(
+        token="tok-expired", client_id="c", scopes=[REQUIRED_SCOPE], expires_at=_PAST, resource=RESOURCE
+    ),
+    "tok-noscope": AccessToken(
+        token="tok-noscope", client_id="c", scopes=["other:thing"], expires_at=_FUTURE, resource=RESOURCE
+    ),
+    "tok-wrong-aud": AccessToken(
+        token="tok-wrong-aud",
+        client_id="c",
+        scopes=[REQUIRED_SCOPE],
+        expires_at=_FUTURE,
+        resource="https://other.example/mcp",
     ),
-    "tok-no-aud": tok("tok-no-aud", scopes=[REQUIRED_SCOPE], expires_at=_FUTURE, resource=None),
+    "tok-no-aud": AccessToken(token="tok-no-aud", client_id="c", scopes=[REQUIRED_SCOPE], expires_at=_FUTURE),
 }