feat(oauth): add MCP / RFC 8707 + RFC 8414 compatibility

- Add RFC 8707 Resource Indicators across authorization_code, device_code,
  refresh_token, and client_credentials grants
- Bind issued JWT aud to the requested resource and persist resource on
  auth codes and access/refresh token rows
- Enforce subset rule on refresh and token exchange per RFC 8707 §2.2
- Add /.well-known/oauth-authorization-server endpoint (RFC 8414) with
  curated OAuth-only metadata
- Apply CORS middleware to /.well-known/* for browser-based MCP clients
- Reject non-http(s) schemes and cap resource-list size in the validator
- Add docs/MCP.md integration guide

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: appleboy

docs/MCP.md

@@ -0,0 +1,169 @@
+# MCP Integration Guide
+
+AuthGate implements the OAuth 2.1 surface required by the
+[Model Context Protocol (MCP) authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization),
+so it can act as a drop-in authorization server for any MCP deployment.
+
+This guide covers what an MCP server (the resource server) advertises to
+clients, what AuthGate provides on each side of the trust boundary, and how
+to wire the two together.
+
+## Trust boundary
+
+| Component            | Owner                | Responsibility                                                       |
+| -------------------- | -------------------- | -------------------------------------------------------------------- |
+| MCP client           | The application      | Discovers the AS, performs PKCE, sends `resource=<MCP-URL>`          |
+| MCP server (RS)      | Your deployment      | Publishes [RFC 9728 Protected Resource Metadata][rfc9728] pointing at AuthGate; verifies token signature, `iss`, `aud` |
+| AuthGate (AS)        | This service         | Issues access/refresh tokens with audience bound to the MCP resource |
+
+AuthGate does **not** publish RFC 9728 Protected Resource Metadata; that
+belongs to each MCP server. The PRM document is what tells clients which
+AuthGate URL to use.
+
+[rfc9728]: https://datatracker.ietf.org/doc/html/rfc9728
+
+## What to advertise on your MCP server
+
+The MCP server's PRM document (`/.well-known/oauth-protected-resource`) must
+advertise the AuthGate base URL as its authorization server. Example:
+
+```json
+{
+  "resource": "https://mcp.example.com",
+  "authorization_servers": ["https://auth.example.com"],
+  "bearer_methods_supported": ["header"],
+  "scopes_supported": ["read", "write"]
+}
+```
+
+When an MCP client receives a 401 with `WWW-Authenticate: Bearer
+resource_metadata="..."`, it fetches the PRM, follows
+`authorization_servers[0]`, and asks AuthGate for metadata.
+
+## AuthGate AS metadata
+
+MCP clients try `/.well-known/oauth-authorization-server` (RFC 8414) first,
+then fall back to OIDC discovery. AuthGate publishes both:
+
+| URL                                                  | Use                                                   |
+| ---------------------------------------------------- | ----------------------------------------------------- |
+| `/.well-known/oauth-authorization-server`            | OAuth 2.0 AS metadata — curated, no OIDC-only fields  |
+| `/.well-known/openid-configuration`                  | OIDC Provider metadata — unchanged                    |
+| `/.well-known/jwks.json`                             | Public keys for `RS256`/`ES256` verification          |
+
+The OAuth metadata response includes:
+
+- `issuer`, `authorization_endpoint`, `token_endpoint`
+- `introspection_endpoint`, `revocation_endpoint`
+- `registration_endpoint` — only when `ENABLE_DYNAMIC_CLIENT_REGISTRATION=true`
+- `grant_types_supported` — `authorization_code`, `device_code`,
+  `refresh_token`, `client_credentials`
+- `code_challenge_methods_supported` — `["S256"]` (PKCE `plain` is rejected)
+- `token_endpoint_auth_methods_supported`,
+  `introspection_endpoint_auth_methods_supported`,
+  `revocation_endpoint_auth_methods_supported`
+
+Browser-based MCP clients need cross-origin access to these endpoints. The
+`/.well-known/*` group respects `CORS_ENABLED` / `CORS_ALLOWED_ORIGINS`
+exactly like `/oauth/*`.
+
+## PKCE requirement
+
+MCP requires `code_challenge_method=S256`. AuthGate's behaviour aligns:
+
+- Public clients (no client secret) **must** present an `S256` code challenge.
+- `plain` is rejected (returns `invalid_request`).
+- Confidential clients may also opt into PKCE; set `PKCE_REQUIRED=true` to
+  force it across all clients.
+
+## Dynamic Client Registration (RFC 7591)
+
+MCP recommends DCR so clients can self-register without admin intervention.
+AuthGate exposes `POST /oauth/register` when
+`ENABLE_DYNAMIC_CLIENT_REGISTRATION=true`. An MCP client posts:
+
+```http
+POST /oauth/register HTTP/1.1
+Content-Type: application/json
+
+{
+  "client_name": "Acme MCP CLI",
+  "redirect_uris": ["http://127.0.0.1:1729/callback"],
+  "grant_types": ["authorization_code", "refresh_token"],
+  "token_endpoint_auth_method": "none"
+}
+```
+
+The response contains `client_id` and (for confidential clients) a one-time
+`client_secret`. Restrict DCR with `DYNAMIC_CLIENT_REGISTRATION_TOKEN` to
+require a pre-shared bearer token for registration.
+
+## Audience binding via Resource Indicators (RFC 8707)
+
+MCP clients send `resource=<MCP-URL>` on both `/authorize` and `/token`. The
+issued JWT's `aud` claim is **bound to the requested resource**. AuthGate:
+
+- Validates each `resource` value against RFC 8707 §2.1 (absolute URI, no
+  fragment) and rejects malformed values with `error=invalid_target`.
+- Replaces the static `JWT_AUDIENCE` config for that token. When the caller
+  does not send `resource`, the existing `JWT_AUDIENCE` is used as before.
+- Persists the bound resource on the authorization code and on access/refresh
+  token rows.
+- Enforces RFC 8707 §2.2 on refresh: the caller may narrow the audience but
+  never widen it. Widening returns 400 `invalid_target`.
+- On `authorization_code` token exchange, validates that any token-time
+  `resource` is a subset of what was bound at `/authorize`.
+
+**Trust model:** the `aud` claim is server-attested. The MCP server must
+verify that `aud` matches its own resource identifier before accepting the
+token — token replay against a different MCP server with the same
+`iss`/signature must fail. Standard verification still applies: check JWT
+signature against JWKS, `iss` matches AuthGate, `exp` is in the future.
+
+## curl walkthrough
+
+```bash
+# 1. Fetch AS metadata (the MCP-required endpoint).
+curl -s http://localhost:8080/.well-known/oauth-authorization-server | jq '
+  {issuer, authorization_endpoint, token_endpoint,
+   introspection_endpoint, registration_endpoint,
+   code_challenge_methods_supported}'
+# Expect: code_challenge_methods_supported = ["S256"];
+# registration_endpoint present when ENABLE_DYNAMIC_CLIENT_REGISTRATION=true.
+
+# 2. Confirm CORS preflight on the metadata endpoint.
+curl -i -H "Origin: https://allowed.example.com" \
+  http://localhost:8080/.well-known/oauth-authorization-server \
+  | grep -i access-control-allow-origin
+# Expect: Access-Control-Allow-Origin: https://allowed.example.com
+
+# 3. Run the authorization-code flow with a resource indicator.
+#    (Perform interactive consent in a browser, then exchange the code.)
+curl -s -X POST http://localhost:8080/oauth/token \
+  -d grant_type=authorization_code -d "code=$CODE" -d "redirect_uri=$RURI" \
+  -d "client_id=$CID" -d "code_verifier=$CV" \
+  -d "resource=https://mcp.example.com"
+# Decode the access_token's payload; "aud" must equal "https://mcp.example.com".
+
+# 4. Refresh requesting a resource outside the original grant — must fail.
+curl -X POST http://localhost:8080/oauth/token \
+  -d grant_type=refresh_token -d "refresh_token=$RT" -d "client_id=$CID" \
+  -d "resource=https://forbidden.example.com"
+# Expect: 400 {"error":"invalid_target",...}
+```
+
+## Configuration checklist
+
+For an MCP-ready deployment:
+
+- `BASE_URL=https://auth.example.com` (your AuthGate's public URL)
+- `JWT_SIGNING_ALGORITHM=RS256` or `ES256` (asymmetric keys exposed via JWKS)
+- `CORS_ENABLED=true` and `CORS_ALLOWED_ORIGINS=<browser MCP client origins>`
+- `ENABLE_DYNAMIC_CLIENT_REGISTRATION=true` if you want self-service MCP clients
+- `ENABLE_REFRESH_TOKENS=true` (long-running MCP sessions)
+- `PKCE_REQUIRED=true` recommended; AuthGate already requires `S256` for public
+  clients and rejects `plain`.
+
+No new configuration keys are required to support MCP — Resource Indicators
+are always-on and backward-compatible: callers that don't send `resource`
+keep getting `aud` from `JWT_AUDIENCE`.

internal/bootstrap/router.go

@@ -215,9 +215,17 @@ func setupAllRoutes(
 	// OAuth routes (public)
 	setupOAuthRoutes(r, oauthProviders, h.oauth)
 
-	// OIDC Discovery and JWKS (public, no auth required)
-	r.GET("/.well-known/openid-configuration", h.oidc.Discovery)
-	r.GET("/.well-known/jwks.json", h.jwks.JWKS)
+	// OIDC Discovery, OAuth 2.0 AS metadata (RFC 8414), and JWKS (public,
+	// no auth required). Browser-based MCP clients need cross-origin access
+	// to these endpoints, so CORS is applied here when enabled — the same
+	// middleware as /oauth/* uses.
+	wellKnown := r.Group("/.well-known")
+	if cfg.CORSEnabled {
+		wellKnown.Use(middleware.CORSMiddleware(cfg))
+	}
+	wellKnown.GET("/openid-configuration", h.oidc.Discovery)
+	wellKnown.GET("/oauth-authorization-server", h.oidc.OAuthAuthorizationServerMetadata)
+	wellKnown.GET("/jwks.json", h.jwks.JWKS)
 
 	// OAuth API routes (public, called by CLI)
 	oauth := r.Group("/oauth")

internal/bootstrap/wellknown_cors_test.go

@@ -0,0 +1,101 @@
+package bootstrap
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/go-authgate/authgate/internal/config"
+	"github.com/go-authgate/authgate/internal/middleware"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// buildWellKnownRouter mirrors the router setup in setupAllRoutes for the
+// /.well-known/* group only, so CORS behaviour can be asserted in isolation
+// without booting the full bootstrap pipeline.
+func buildWellKnownRouter(cfg *config.Config) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	wellKnown := r.Group("/.well-known")
+	if cfg.CORSEnabled {
+		wellKnown.Use(middleware.CORSMiddleware(cfg))
+	}
+	stub := func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"ok": true}) }
+	wellKnown.GET("/openid-configuration", stub)
+	wellKnown.GET("/oauth-authorization-server", stub)
+	wellKnown.GET("/jwks.json", stub)
+	return r
+}
+
+func TestWellKnown_CORS_AllowsConfiguredOrigin(t *testing.T) {
+	cfg := &config.Config{
+		CORSEnabled:        true,
+		CORSAllowedOrigins: []string{"https://allowed.example.com"},
+		CORSAllowedMethods: []string{"GET", "OPTIONS"},
+		CORSAllowedHeaders: []string{"Origin", "Content-Type"},
+	}
+	r := buildWellKnownRouter(cfg)
+
+	req := httptest.NewRequest(
+		http.MethodGet,
+		"/.well-known/oauth-authorization-server",
+		nil,
+	)
+	req.Header.Set("Origin", "https://allowed.example.com")
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(
+		t,
+		"https://allowed.example.com",
+		w.Header().Get("Access-Control-Allow-Origin"),
+	)
+}
+
+func TestWellKnown_CORS_RejectsUnconfiguredOrigin(t *testing.T) {
+	cfg := &config.Config{
+		CORSEnabled:        true,
+		CORSAllowedOrigins: []string{"https://allowed.example.com"},
+		CORSAllowedMethods: []string{"GET", "OPTIONS"},
+		CORSAllowedHeaders: []string{"Origin", "Content-Type"},
+	}
+	r := buildWellKnownRouter(cfg)
+
+	req := httptest.NewRequest(
+		http.MethodGet,
+		"/.well-known/oauth-authorization-server",
+		nil,
+	)
+	req.Header.Set("Origin", "https://evil.example.com")
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	// gin-contrib/cors rejects un-allowed origins; ACAO must be empty so the
+	// browser refuses to expose the response to JS.
+	assert.Empty(t, w.Header().Get("Access-Control-Allow-Origin"))
+}
+
+func TestWellKnown_CORSDisabled_NoACAOHeader(t *testing.T) {
+	cfg := &config.Config{CORSEnabled: false}
+	r := buildWellKnownRouter(cfg)
+
+	req := httptest.NewRequest(
+		http.MethodGet,
+		"/.well-known/oauth-authorization-server",
+		nil,
+	)
+	req.Header.Set("Origin", "https://anything.example.com")
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+	assert.Empty(
+		t,
+		w.Header().Get("Access-Control-Allow-Origin"),
+		"CORS disabled must not emit Access-Control-Allow-Origin",
+	)
+}

internal/core/token.go

@@ -63,18 +63,25 @@ type TokenRefreshResult struct {
 // extraClaims (when non-empty) is merged into the generated JWT before standard
 // claims are set; standard claims (iss, sub, exp, iat, jti, aud, type, scope,
 // user_id, client_id) take precedence and cannot be overridden.
+//
+// audience (when non-empty) overrides the "aud" claim with the supplied values
+// (RFC 8707 Resource Indicators). When empty, the provider falls back to its
+// default audience configuration. Caller-supplied "aud" inside extraClaims is
+// always stripped — audience must be passed explicitly through this parameter.
 type TokenProvider interface {
 	GenerateToken(
 		ctx context.Context,
 		userID, clientID, scopes string,
 		ttl time.Duration,
 		extraClaims map[string]any,
+		audience []string,
 	) (*TokenResult, error)
 	GenerateRefreshToken(
 		ctx context.Context,
 		userID, clientID, scopes string,
 		ttl time.Duration,
 		extraClaims map[string]any,
+		audience []string,
 	) (*TokenResult, error)
 	// GenerateClientCredentialsToken generates a token for the client_credentials grant.
 	// May apply a different expiry or claim set than GenerateToken.
@@ -83,13 +90,15 @@ type TokenProvider interface {
 		userID, clientID, scopes string,
 		ttl time.Duration,
 		extraClaims map[string]any,
+		audience []string,
 	) (*TokenResult, error)
 	ValidateToken(ctx context.Context, tokenString string) (*TokenValidationResult, error)
 	RefreshAccessToken(
 		ctx context.Context,
 		refreshToken string,
 		accessTTL, refreshTTL time.Duration,
 		extraClaims map[string]any,
+		audience []string,
 	) (*TokenRefreshResult, error)
 	Name() string
 }