fix(oauth): support external URL override for TLS-terminating proxy d…

[michaelalinks]

When aks-mcp is deployed behind a TLS-terminating reverse proxy (e.g. Envoy Gateway, AGIC), r.TLS is always nil so OAuth metadata endpoints incorrectly return http:// URLs. This causes MCP clients to reject the metadata.

Add --oauth-external-url flag (and OAUTH_EXTERNAL_URL env var fallback) that, when set, is used as the base URL in both /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server responses instead of deriving the scheme from r.TLS. The existing request-derived logic is preserved as the fallback when the flag is not set.

Expose the option in the Helm chart as oauth.externalURL.

Please see also the related open issue (running a custom image of these code changes): #365

[michaelalinks]

@microsoft-github-policy-service agree

[michaelalinks]

Notes on the OAuth callback proxy fix

Adding these notes to document three decisions made in the changes to internal/auth/oauth/endpoints.go.

Why crypto/rand, encoding/base64, and related helpers were removed

The following functions formed a chain only used by the old callbackHandler:

• generateSessionToken — generated a random token using crypto/rand + encoding/base64
• writeCallbackSuccessResponse — called generateSessionToken and rendered an HTML token page
• writeCallbackErrorResponse — rendered an HTML error page
• exchangeCodeForToken — exchanged the authorization code with Azure AD server-side

None of these are called from anywhere else. Since the new callbackHandler only does a 302 redirect, the entire chain is dead code and has been removed along with the imports that only served it.

Why the removed exchangeCodeForToken was already broken

exchangeCodeForToken never passed a code_verifier to Azure AD, but PKCE is enforced on the /authorize endpoint — meaning every authorization code issued requires a verifier to exchange it. Azure AD
returns AADSTS9002313 without it, which is exactly the error reported in #365. The old server-side token exchange was never going to succeed for any client.

Why the proxy approach works for all MCP clients, not just one

The state → client redirect_uri mapping in pendingStates is fully client-agnostic. Whatever redirect_uri an MCP client sends to /authorize (VS Code Copilot, MCP Inspector, or any future OAuth 2.1
client) gets stored and forwarded back after Azure AD redirects to the server callback. The only operational requirement is that each client's redirect URI is added to the --oauth-redirects allowed list in
the Helm chart — no code changes needed to support new clients.