Akamai: forward /.well-known/* to origin for MCP OAuth discovery (+ validation)

[jung-thomas]

Summary

Follow-up to #2075 (.well-known MCP discovery surface). The CAP origin now serves the full discovery set, but on developers.sap.com Akamai returns 403 for /.well-known/* at the edge (all except security.txt), so MCP clients can't auto-discover the OAuth endpoints. This tracks (a) the Akamai edge-forward change and (b) the post-deploy validation.

In-repo runbook: docs/developers/operations/akamai-well-known-forward.md

---

Jira ticket (for the Akamai/edge team) — ready to paste

Title: Forward /.well-known/* to origin for developers.sap.com (MCP OAuth discovery)

Problem: Akamai returns 403 at the edge for every /.well-known/* path except security.txt (confirmed: Server: AkamaiGHost on the 403). Requests never reach origin, so the MCP OAuth discovery documents the origin now serves are unreachable in PROD.

Request: On the developers.sap.com property, forward these origin paths to the approuter origin as pass-through (no edge auth; honor origin Cache-Control):

• /.well-known/oauth-authorization-server
• /.well-known/oauth-protected-resource
• /.well-known/openid-configuration
• /.well-known/mcp.json
• /.well-known/security.txt (keep working)

Simplest rule: forward the entire /.well-known/* prefix to origin.

Scope: Edge config only — no origin/code change needed (merged in #2075).

---

Validation tests

On DEV first (no Akamai — validates the origin)

Replace <dev-approuter> with the current DEV approuter route.

• curl -s -o /dev/null -w '%{http_code}\n' https://<dev-approuter>/.well-known/oauth-authorization-server → 200
• curl -s https://<dev-approuter>/.well-known/oauth-protected-resource | jq . → resource, authorization_servers, scopes_supported: ["…Tutorial.MCP"]
• curl -s https://<dev-approuter>/.well-known/openid-configuration | jq .issuer → XSUAA issuer (RFC 8414 body)
• curl -s https://<dev-approuter>/.well-known/mcp.json | jq '.servers[].name' → search, homepage, graph, developer
• curl -s https://<dev-approuter>/.well-known/security.txt → 200, Contact:/Expires:
• curl -s -D - -o /dev/null https://<dev-approuter>/mcp-auth/api | grep -i www-authenticate → Bearer resource_metadata="…/.well-known/oauth-protected-resource", scope="…Tutorial.MCP"
• End-to-end: mcp-remote https://<dev-approuter>/mcp-auth/api --static-oauth-client-info '{"client_id":"sb-tutorials!t676072"}' completes OAuth discovery + PKCE

On PROD after the edge rule lands (developers.sap.com)

• Same six curl checks return 200/correct bodies (not 403)
• /mcp-auth/api 401 carries the resource_metadata pointer
• Hybrid suite green against PROD: SMOKE_BASE_URL=https://developers.sap.com npx vitest run --project hybrid test/hybrid/oauth-discovery.test.js

---

Refs

• PR: feat(approuter): complete .well-known MCP discovery surface (openid-config, mcp.json, WWW-Authenticate pointer) #2075 (implementation), docs: register akamai-well-known-forward in sidebar (fix docs:build) #2076 (docs sidebar fix)
• Spec: docs/superpowers/specs/2026-08-28-well-known-oauth-discovery-design.md