Easy Auth Header Decoding – Quick Reference Guide
This guide provides a concise overview of how to inspect and leverage authentication data passed from the Easy Auth (Authentication/Authorization) container in Azure App Service. It covers how to extract key values—such as identity claims and ID tokens—from headers to support end-to-end authentication workflows.
If any of the following information becomes outdated, please refer to the original documentation, which is also referenced throughout this guide.
This guide explains how to extract identity details passed via request headers:
Work with user identities in Azure App Service authentication
This tutorial demonstrates how to use the token from Easy Auth to secure backend APIs:
Tutorial: Authenticate and authorize users end-to-end in Azure App Service
The Code
This example is built using a Windows Web App running .NET 9.0. Most of the logic is inside DebugAuthController.cs and can be triggered via the /debugauth endpoint.
using Microsoft.AspNetCore.Mvc;
using System.Linq;
namespace AuthHeaderDecoding.Controllers
{
[ApiController]
[Route("[controller]")]
public class DebugAuthController : Controller
{
[HttpGet]
public IActionResult Get()
{
var principal = ClaimsPrincipalParser.Parse(Request);
var identity = principal?.Identity;
var response = new
{
IdentityInfo = identity != null ? new
{
identity.Name,
identity.AuthenticationType,
identity.IsAuthenticated
} : null,
Claims = principal?.Claims?.Select(c => new
{
ClaimType = c.Type,
ClaimValue = c.Value
}),
AzureAppServiceAuthHeaders = new
{
X_MS_CLIENT_PRINCIPAL = new
{
Header = "x-ms-client-principal",
Value = Request.Headers["x-ms-client-principal"].ToString()
},
X_MS_CLIENT_PRINCIPAL_ID = new
{
Header = "x-ms-client-principal-id",
Value = Request.Headers["x-ms-client-principal-id"].ToString()
},
X_MS_CLIENT_PRINCIPAL_NAME = new
{
Header = "x-ms-client-principal-name",
Value = Request.Headers["x-ms-client-principal-name"].ToString()
},
X_MS_CLIENT_PRINCIPAL_IDP = new
{
Header = "x-ms-client-principal-idp",
Value = Request.Headers["x-ms-client-principal-idp"].ToString()
}
}
};
return Ok(response);
}
}
}The Authentication (Easy Auth) Container
It’s important to understand that Azure’s Easy Auth runs in a separate container, acting as a reverse proxy that processes requests before they reach your application code. This design means your app doesn’t have direct access to authentication data like tokens or user identities.
Instead, the Easy Auth container forwards this data via HTTP headers. By inspecting these headers, you can access a wide range of identity and claims information without implementing custom auth logic.
Testing
You can test the output by visiting the /debugauth route of your deployed app:
Here’s a sanitized sample of the response for illustration. The actual values are redacted or simplified for clarity:
{
"identityInfo": {
"name": "First Last",
"authenticationType": "aad",
"isAuthenticated": true
},
"claims": [
{"claimType": "aud", "claimValue": "APP_CLIENT_ID_REDACTED"},
{"claimType": "iss", "claimValue": "https://login.microsoftonline.com/TENANT_ID_REDACTED/v2.0"},
{"claimType": "iat", "claimValue": "TIMESTAMP"},
{"claimType": "nbf", "claimValue": "TIMESTAMP"},
{"claimType": "exp", "claimValue": "TIMESTAMP"},
{"claimType": "aio", "claimValue": "AIO_TOKEN_REDACTED"},
{"claimType": "c_hash", "claimValue": "HASH_REDACTED"},
{"claimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "claimValue": "FirstLast@example.com"},
{"claimType": "http://schemas.microsoft.com/identity/claims/identityprovider", "claimValue": "https://sts.windows.net/IDENTITY_PROVIDER_ID_REDACTED/"},
{"claimType": "name", "claimValue": "First Last"},
{"claimType": "nonce", "claimValue": "NONCE_REDACTED"},
{"claimType": "http://schemas.microsoft.com/identity/claims/objectidentifier", "claimValue": "USER_OBJECT_ID_REDACTED"},
{"claimType": "preferred_username", "claimValue": "FirstLast@example.com"},
{"claimType": "rh", "claimValue": "RH_TOKEN_REDACTED"},
{"claimType": "sid", "claimValue": "SESSION_ID_REDACTED"},
{"claimType": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", "claimValue": "NAME_IDENTIFIER_REDACTED"},
{"claimType": "http://schemas.microsoft.com/identity/claims/tenantid", "claimValue": "TENANT_ID_REDACTED"},
{"claimType": "uti", "claimValue": "UTI_REDACTED"},
{"claimType": "ver", "claimValue": "2.0"}
],
"azureAppServiceAuthHeaders": {
"x_MS_CLIENT_PRINCIPAL": {
"header": "x-ms-client-principal",
"value": "BASE64_ENCODED_JWT_REDACTED"
},
"x_MS_CLIENT_PRINCIPAL_ID": {
"header": "x-ms-client-principal-id",
"value": "USER_OBJECT_ID_REDACTED"
},
"x_MS_CLIENT_PRINCIPAL_NAME": {
"header": "x-ms-client-principal-name",
"value": "FirstLast@example.com"
},
"x_MS_CLIENT_PRINCIPAL_IDP": {
"header": "x-ms-client-principal-idp",
"value": "aad"
}
}
}
Additional Notes
If you’ve enabled the token store feature in Azure App Service Authentication, you can access the current authentication context via the built-in /.auth/me endpoint.
Example response from /.auth/me:
[
{
"access_token": "ACCESS_TOKEN_REDACTED",
"expires_on": "2025-05-15T22:11:10Z",
"id_token": "ID_TOKEN_REDACTED",
"provider_name": "aad",
"user_claims": [
{ "typ": "aud", "val": "APP_CLIENT_ID_REDACTED" },
{ "typ": "iss", "val": "https://login.microsoftonline.com/TENANT_ID_REDACTED/v2.0" },
{ "typ": "iat", "val": "TIMESTAMP" },
{ "typ": "nbf", "val": "TIMESTAMP" },
{ "typ": "exp", "val": "TIMESTAMP" },
{ "typ": "aio", "val": "AIO_CLAIM_REDACTED" },
{ "typ": "c_hash", "val": "HASH_REDACTED" },
{ "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "val": "FirstLast@example.com" },
{ "typ": "http://schemas.microsoft.com/identity/claims/identityprovider", "val": "https://sts.windows.net/IDENTITY_PROVIDER_REDACTED/" },
{ "typ": "name", "val": "First Last" },
{ "typ": "nonce", "val": "NONCE_REDACTED" },
{ "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier", "val": "USER_OBJECT_ID_REDACTED" },
{ "typ": "preferred_username", "val": "FirstLast@example.com" },
{ "typ": "rh", "val": "RH_TOKEN_REDACTED" },
{ "typ": "sid", "val": "SESSION_ID_REDACTED" },
{ "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", "val": "NAME_IDENTIFIER_REDACTED" },
{ "typ": "http://schemas.microsoft.com/identity/claims/tenantid", "val": "TENANT_ID_REDACTED" },
{ "typ": "uti", "val": "UTI_REDACTED" },
{ "typ": "ver", "val": "2.0" }
],
"user_id": "FirstLast@example.com"
}
]
There is also a /.auth/refresh endpoint. By default, this is disabled. However, enabling offline access in your identity provider (such as Azure AD) can allow you to manually refresh tokens from the frontend.
Refresh auth tokens
About Author
