[Proposal] Replace AuthContext map[string]string with Typed Struct in Policy SDK

[renuka-fernando]

Summary

• Replace AuthContext map[string]string in the policy SDK's SharedContext with a typed AuthContext struct containing named fields for common auth data
• Add a Properties map[string]string escape hatch on the struct for custom/policy-specific metadata that does not fit the typed fields
• Update all auth policy writers (jwt, oauth2, apikey, basic-auth) to set struct fields instead of magic string keys
• Update all auth context readers (analytics system policy, rate limiting) to read typed fields instead of map lookups

Motivation

• Auth policies currently write to AuthContext using magic string keys like "x-wso2-user-id" with no compile-time safety. A typo in a key name silently produces missing data rather than a build error.
• Downstream policies (analytics, rate limiting) must know the exact key strings to read, with no IDE discoverability or documentation of what keys are available or what auth types populate them.
• There is no way for a policy author to discover what auth information is available without reading the source code of every auth policy.

Proposal

• Define a new AuthContext struct in sdk/gateway/policy/v1alpha/context.go with typed fields for the most common auth attributes
• Use plain value types (not pointers) for all fields, consistent with the rest of SharedContext
• Keep a Properties map[string]string field as an escape hatch for custom data
• Use a flat struct (no nested sub-structs for token-specific fields) for simplicity

The proposed struct:

// AuthContext holds authentication data produced by auth policies (jwt, oauth2, apikey, basic-auth)
// and consumed by downstream policies (analytics, rate limiting, etc.).
type AuthContext struct {
    // Authenticated indicates whether the request passed authentication.
    Authenticated bool

    // AuthType identifies the mechanism that authenticated the request.
    // Values: "jwt", "oauth2", "apikey", "basic", or empty if unauthenticated.
    AuthType string

    // Subject is the authenticated principal identifier.
    // JWT "sub" claim, basic-auth username, API key owner/app ID, etc.
    Subject string

    // Issuer is the token issuer (JWT "iss" claim, IdP URL).
    // Empty for non-token auth types.
    Issuer string

    // Audience is the intended audience (JWT "aud" claim).
    // Empty for non-token auth types.
    Audience string

    // Scopes contains granted OAuth2/JWT scopes as a set for O(1) lookup.
    // Nil for non-token auth types.
    Scopes map[string]bool

    // AppID is the application identifier associated with the authenticated request.
    // For API key auth, this is the application that owns the key.
    // For OAuth2, this may be the client_id. Empty if not applicable.
    AppID string

    // Properties holds additional auth-related key-value data for
    // inter-policy communication that does not fit the typed fields above.
    // Examples: email, custom JWT claims, API key tier.
    Properties map[string]string
}

Examples

Before (auth policy writing to AuthContext):

func (p *JWTPolicy) OnRequest(ctx *policy.RequestContext, params map[string]interface{}) policy.RequestAction {
    // ... validate token ...
    ctx.SharedContext.AuthContext["x-wso2-user-id"] = claims.Subject
    // No way to know what other keys exist or matter
    return policy.NewRequestAllow()
}

After (auth policy writing to AuthContext):

func (p *JWTPolicy) OnRequest(ctx *policy.RequestContext, params map[string]interface{}) policy.RequestAction {
    // ... validate token ...
    ctx.SharedContext.AuthContext.Authenticated = true
    ctx.SharedContext.AuthContext.AuthType = "jwt"
    ctx.SharedContext.AuthContext.Subject = claims.Subject
    ctx.SharedContext.AuthContext.Issuer = claims.Issuer
    ctx.SharedContext.AuthContext.Audience = claims.Audience
    ctx.SharedContext.AuthContext.Scopes = toScopeSet(claims.Scopes)
    // Custom claims go in Properties
    ctx.SharedContext.AuthContext.Properties["email"] = claims.Email
    return policy.NewRequestAllow()
}

Before (downstream policy reading AuthContext):

// analytics.go - must know exact magic key string
if ctx.SharedContext.AuthContext != nil {
    if userID, ok := ctx.SharedContext.AuthContext["x-wso2-user-id"]; ok && userID != "" {
        analyticsMetadata["x-wso2-user-id"] = userID
    }
}

After (downstream policy reading AuthContext):

// analytics.go - typed field access, IDE autocomplete, compile-time checked
if ctx.SharedContext.AuthContext.Authenticated {
    analyticsMetadata["x-wso2-user-id"] = ctx.SharedContext.AuthContext.Subject
}

References

• SDK context definition - Current AuthContext map[string]string definition
• Kernel execution context - Where AuthContext is initialized as make(map[string]string)
• Analytics system policy - Primary consumer of AuthContext["x-wso2-user-id"]

[O-sura]

@renuka-fernando But let's say a user want to use a different claim rather than the default sub claim as the user ID. In that case, we still have to use the property bag inside the auth context and still the downstream policies need to know the exact key strings to read, isn't it?

[renuka-fernando]

Let's then include another field userId inside the AuthContext struct.
cc @malinthaprasan