AI Engineering from Scratch（英文原版）

Given an MCP server config and an IdP capability set, emit the auth surface and refusal rules that constitute a production MCP authorization layer.

Inputs:

• mcp_resource_url — canonical resource URL (most-specific identifier; keep a path only when it distinguishes co-hosted servers), used as aud and as the protected-resource metadata resource value.
• idp_metadata_url — the IdP's /.well-known/oauth-authorization-server (or OpenID Connect Discovery) URL.
• idp_capabilities: observed values for issuer, code_challenge_methods_supported, grant_types_supported, client_id_metadata_document_supported, deprecated registration_endpoint, response_types_supported, and authorization_response_iss_parameter_supported.
• pre_registered_client_ids: optional issuer-to-client-ID map provisioned by authorization-server operators. Prefer this issuer-scoped identity before CIMD, then use deprecated DCR only as the final compatibility path.
• application_type: native or web, required when deprecated DCR compatibility is selected.
• credential_store: client IDs and registration credentials keyed by authorization-server issuer, with access tokens keyed by (issuer, mcp_resource_url).
• tools: the MCP tool list with the scope each requires.

Produce:

1. Refusal gate. Refuse to wire and stop if any hard condition fails:

   • S256 is missing from code_challenge_methods_supported (PKCE has no degraded mode).
   • authorization_code is missing from grant_types_supported.
   • response_types_supported is anything other than exactly ["code"].
   • No enrollment path exists: none of a pre-registered client_id, client_id_metadata_document_supported: true, or a deprecated DCR compatibility endpoint is available.
   • CIMD is selected but its client_id is not the absolute HTTPS document URL with a path, does not match the document URL, or the document lacks a non-empty client_name or redirect_uris array. application_type is optional for CIMD.
   • A returned RFC 9207 iss differs from the issuer recorded before redirect, or is omitted when the server advertised it as supported.
   • Deprecated DCR lacks application_type, or its redirect URI policy conflicts with native or web.

2. Protected-resource metadata document (RFC 9728) for the MCP server. For a resource with a path, insert the well-known segment before that path: https://host/team/mcp maps to https://host/.well-known/oauth-protected-resource/team/mcp. Include resource, authorization_servers (the issuer allow-list), scopes_supported, and bearer_methods_supported: ["header"].

3. HTTP endpoints.

   • GET /.well-known/oauth-protected-resource — returns the document from (2).
   • POST /mcp (the stateless MCP transport): validates the bearer token for this request before any tool dispatches.
   • DCR compatibility only: POST /register, with an application-type check and a rate-limit check ahead of it.

4. Background job + routines.

   • A scheduled JWKS refresh that re-fetches jwks_uri into the cache \{keys, fetched_at\}. Idempotent; never mints keys. The AS rotates; the resource server only refreshes. Default 0 */6 * * *; tighten to */15 * * * * for high-rotation IdPs.
   • A validate routine — checks iss allow-list, signature against cached JWKS, aud == mcp_resource_url, exp, required scope.
   • A step-up issuance path — only if the tool list contains operations gated behind a scope the user does not initially grant.

5. Cache plan. One entry per accepted issuer keyed by issuer, holding \{keys, fetched_at\}. Document the read pattern: the validator reads the cache and falls back to a single synchronous refresh on kid miss (re-fetch, not rotate — re-fetch is idempotent and cannot be turned into a key-creation DoS).

6. Scope mapping. Map every tool to the scope it requires. Output a table: | tool | required_scope | rationale |. Group destructive tools under their own scope; never reuse a read scope for a write tool.

7. Refusal rules at runtime (the validator must encode these):

   • Reject when aud != mcp_resource_url → 401 Bearer error="invalid_token", error_description="audience mismatch", resource_metadata="<prm_url>".
   • Reject when iss not in authorization_servers.
   • Reject when kid not in cached JWKS after a single re-fetch fall-back.
   • Reject when required scope is absent → 403 Bearer error="insufficient_scope", scope="<required>", resource_metadata="<prm_url>".
   • Reject any authorization request without an S256 code_challenge, and reject any token request whose code_verifier, client, redirect URI, or resource does not match the one-time authorization-code record.
   • Reject any credential or token whose issuer does not match its credential-store key. Issuer change requires new enrollment.

Hard rejects (never wire any of these — refuse the request and document why):

• Storing client_secret in plaintext. Public clients use token_endpoint_auth_method: none; confidential clients use private_key_jwt. No plaintext shared secrets at rest or in the registration response logs.
• Skipping the aud check on the validator. Audience binding (access-token privilege restriction) is the entire reason for RFC 8707 + RFC 9728.
• Wiring the JWKS cache-miss fall-back to a rotate-and-mint instead of a re-fetch. It never produces the missing kid and lets attacker-controlled kid values force unbounded key creation. The fall-back must be the idempotent refresh.
• Allowing PKCE-less authorization code requests. OAuth 2.1 forbids it; the validator must reject any /token exchange whose stored authorization-code record lacks a code_challenge.
• Caching JWKS without a refresh job. Either the scheduled refresh ships, or the auth surface does not deploy.
• Trusting the iss claim without an allow-list. Any validator that accepts a token from any iss lets an attacker stand up their own IdP and forge tokens.
• Forwarding the inbound MCP token to an upstream API (token passthrough). If the MCP server calls upstream APIs it MUST obtain its own separate token; passthrough creates the confused-deputy problem.
• Storing registration_access_token in plaintext. Hash-at-rest; require cleartext on every update.
• Treating MCP request metadata or a removed protocol session as authorization state. The 2026-07-28 transport is stateless; authenticate and authorize every request.

Output: a one-page plan with the protected-resource document, issuer-keyed enrollment layout, issuer-and-resource token layout, chosen enrollment path, HTTP endpoints, JWKS refresh job, scope mapping, and runtime refusal rules. End with the first unmet deployment gate found in the authorization server's actual metadata.