“preferred_username” and Email are present in token, but show null in claims .NET 4.8

Summary

The issue arises when claims like preferred_username and email are present in the JWT token but appear as null in the .NET 4.8 application’s claims collection. This occurs due to a mismatch between the claim type mappings in the token validation configuration and the actual claim types in the token.

Root Cause

• Claim type mismatch: The NameClaimType is set to "preferred_username", but the token uses "preferred_username" directly, which is not automatically mapped to ClaimsIdentity.Name.
• Missing claim type mapping: The TokenValidationParameters does not explicitly map "preferred_username" or "email" to their corresponding .NET claim types.

Why This Happens in Real Systems

• Assumption of default mappings: Developers often assume that common claim types like "preferred_username" or "email" are automatically mapped to ClaimsIdentity.Name or ClaimTypes.Email.
• Token issuer variations: Different identity providers (e.g., Azure AD) may use non-standard claim types, requiring explicit mapping.

Real-World Impact

• Authentication failures: Users cannot log in due to missing required claims.
• Debugging overhead: Time wasted verifying token contents and configuration.
• Security risks: Incorrect claim mappings can lead to unauthorized access if fallback mechanisms are misused.

Example or Code

public void ConfigureAzureJwtBearer(IAppBuilder app)
{
    var tenantId = ConfigurationManager.AppSettings["ida:TenantId"];
    var audience = ConfigurationManager.AppSettings["ida:Audience"];

    app.UseJwtBearerAuthentication(new JwtBearerAuthenticationOptions
    {
        AuthenticationMode = AuthenticationMode.Active,
        TokenValidationParameters = new TokenValidationParameters
        {
            ValidIssuers = new[] { 
                $"https://sts.windows.net/{tenantId}/", 
                $"https://login.microsoftonline.com/{tenantId}/v2.0" 
            },
            ValidAudience = audience,
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            NameClaimType = "preferred_username", // Incorrect assumption
            **TokenClaimTypeMappings = new Dictionary
            {
                { "preferred_username", ClaimTypes.Name },
                { "email", ClaimTypes.Email } // Explicit mapping
            }**
        }
    });
}

How Senior Engineers Fix It

• Explicitly map claim types: Use TokenClaimTypeMappings to map token claim types to .NET claim types.
• Verify token contents: Always inspect the raw token claims to ensure they match the expected types.
• Avoid hardcoded assumptions: Do not rely on default mappings for non-standard claim types.

Why Juniors Miss It

• Lack of understanding of claim mappings: Juniors often overlook the need to explicitly map token claims to .NET claim types.
• Overreliance on defaults: Assuming that common claim types like "preferred_username" are automatically mapped to ClaimsIdentity.Name.
• Insufficient token inspection: Not verifying the actual claims in the token before configuring validation parameters.