HEADER_MAPPING fails when userinfo claim is missing from JWT

[sanderaasmaa]

Problem

HEADER_MAPPING only reads from claims["userinfo"] in the JWT (proxy.go:96). When the OIDC userinfo doesn't survive fosite's authorization code exchange (the Extra field on the JWT session isn't preserved through handleToken), the userinfo claim is absent from the access token JWT, and no headers are mapped.

The user's email IS available as the top-level sub claim (set via OIDC_USER_ID_FIELD=/email), but HEADER_MAPPING doesn't read from top-level claims.

Steps to reproduce

1. Configure with Azure AD OIDC + HEADER_MAPPING=/email:X-User-Email
2. Authenticate via the OAuth flow (Claude Teams MCP client)
3. Make a tool call — the X-User-Email header is not set on the proxied request
4. Debug logging on the upstream server confirms no x-user-email in received headers

Expected behavior

HEADER_MAPPING=/email:X-User-Email should set X-User-Email to the user's email, reading from claims["userinfo"]["email"] OR falling back to claims["sub"] when userinfo is absent.

Suggested fix

In pkg/proxy/proxy.go, after the existing userinfo mapping block, add a fallback that reads from top-level JWT claims:

if len(p.headerMapping) > 0 {
    if claims, ok := token.Claims.(jwt.MapClaims); ok {
        // Try userinfo claim first (existing behavior)
        source := claims
        if userinfo, exists := claims["userinfo"]; exists {
            if ui, ok := userinfo.(map[string]any); ok {
                source = ui
            }
        }
        for pointer, headerName := range p.headerMapping {
            // ... existing mapping logic using source instead of userinfo
        }
    }
}

Or simpler: when a pointer like /email isn't found in userinfo, fall back to the top-level claim sub (or whatever matches).

Environment

• mcp-auth-proxy v2.8.1
• Azure AD OIDC (Microsoft Entra ID)
• Transparent proxy mode (HTTP target)
• OIDC_USER_ID_FIELD=/email

[hrntknr]

Thanks for the detailed report! I looked into this and you're right — HEADER_MAPPING was hardcoded to only read from the userinfo claim.

Rather than adding an implicit fallback, I went with a new HEADER_MAPPING_BASE option (env: HEADER_MAPPING_BASE) that lets you explicitly set where claims are read from. It defaults to /userinfo (existing behavior), but setting it to / will read from top-level JWT claims instead.

For your setup, this should work:

HEADER_MAPPING=/email:X-User-Email
HEADER_MAPPING_BASE=/

PR: #144

[sanderaasmaa]

Root cause confirmed

Added debug logging to the proxy. The JWT issued by /.idp/token contains:

JWT claim keys: [nbf scp aud exp iat iss jti], sub=<nil>, userinfo exists=false

sub is nil and userinfo is absent. The JWT is completely anonymous — no user identity survives the authorization code → access token exchange.

The issue is in handleToken (pkg/idp/idp.go:192):

session, err := NewJWTSessionWithKey("", "", a.privKey, nil)

This creates a blank session with empty subject and nil userinfo. Fosite's NewAccessRequest is supposed to hydrate the session from the stored authorization, but it appears the Extra claims and Subject are not being restored from the stored JWTClaims.

The fix likely needs to happen in fosite's session restoration, or handleToken needs to explicitly restore the subject/userinfo from the stored authorization session after NewAccessRequest returns.

[hrntknr]

Just pushed another fix in #146 — turns out the session data (including sub and userinfo) wasn't being persisted during the authorization code exchange at all. That's why even top-level claims were empty in your JWT.

With both #144 and #146, HEADER_MAPPING should work as expected. Could you give it a try when you get a chance?

For your Azure AD setup:

HEADER_MAPPING=/email:X-User-Email
HEADER_MAPPING_BASE=/userinfo

If userinfo still doesn't have what you need, try HEADER_MAPPING_BASE=/ to read from top-level claims instead.