Working with Claims Mapping Policies in Microsoft Entra ID

Introduction

Microsoft Entra ID token customization is one of the most powerful capabilities for enterprise identity integrations. Many modern applications require additional user attributes in the token beyond the default claims provided by Microsoft Entra ID. These additional claims help applications personalize the user experience, implement authorization logic, or integrate with external systems.

One common requirement is to include user profile attributes such as:

First Name
Last Name
Employee ID
Department
Extension Attributes

While Microsoft Entra ID already issues a default set of claims, applications sometimes need additional optional claims that are not included by default in the token. This is where Claims Mapping Policies become useful.

Understanding Claims Mapping Policies

A Claims Mapping Policy in Microsoft Entra ID allows administrators to customize the claims emitted in:

OAuth 2.0 access tokens
OpenID Connect ID tokens
SAML tokens

The policy enables you to:

Add custom claims
Transform claims
Rename claims
Include additional user attributes

Claims Mapping Policies are assigned to a Service Principal (Enterprise Application) and not directly to the App Registration.

Common Scenario

Consider an internal enterprise application that requires the following user information after authentication:

{
  "given_name": "John",
  "family_name": "Doe"
}

By default, the application may only receive standard claims such as:

{
  "aud": "api://application-id",
  "iss": "https://login.microsoftonline.com/",
  "sub": "xxxxxxxx",
  "oid": "xxxxxxxx",
  "tid": "xxxxxxxx"
}

The application team now wants:

First Name (given_name)
Last Name (family_name)

to be included in the token automatically.

This requirement can be fulfilled using a Claims Mapping Policy.

The Claims Mapping Policy is attached to the Service Principal associated with the application.

Create the Claims Mapping Policy

The following PowerShell command creates a Claims Mapping Policy that adds:

given_name
family_name

to the token.

Connect-MgGraph -Scopes "Policy.ReadWrite.ApplicationConfiguration"

$policyDefinition = @{
    ClaimsMappingPolicy = @{
        Version             = 1
        IncludeBasicClaimSet = "true"
        ClaimsSchema        = @(
            @{
                Source        = "user"
                ID            = "givenname"
                JwtClaimType  = "given_name"
                SamlClaimType = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
            },
            @{
                Source        = "user"
                ID            = "surname"
                JwtClaimType  = "family_name"
                SamlClaimType = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
            }
        )
    }
} | ConvertTo-Json -Depth 10 -Compress

$body = @{
    definition            = @($policyDefinition)
    displayName           = "TenantWide-FirstLastName"
    isOrganizationDefault = $true
}

$response = Invoke-MgGraphRequest -Method POST `
    -Uri "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies" `
    -Body ($body | ConvertTo-Json -Depth 10) `
    -ContentType "application/json"

Write-Host "Policy created with ID: $($response.id)"

The above PowerShell script will create Claim Mapping Policies with the displayName TenantWide-FirstLastName

Let us understand the important properties used in the policy.

"IncludeBasicClaimSet": "true"

This ensures that Microsoft Entra ID still emits the default standard claims along with the custom claims.

ClaimsSchema

This section defines the additional claims to include.

Given Name

{
    "Source": "user",
    "ID": "givenname",
    "JwtClaimType": "given_name"
}

Family Name

{
    "Source": "user",
    "ID": "surname",
    "JwtClaimType": "family_name"
}

Locate the Service Principal

Claims Mapping Policies are assigned to the Service Principal.

Retrieve the Service Principal:

Get-MgServicePrincipal -Filter "displayName eq 'MyApplication'"

Copy the:

Id - This is the Service Principal Object ID.

Assign the Claims Mapping Policy

Assign the policy to the Service Principal:

New-MgServicePrincipalClaimMappingPolicyByRef `
    -ServicePrincipalId "<SERVICE_PRINCIPAL_OBJECT_ID>" `
    -BodyParameter @{
        "@odata.id" = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/$($policy.Id)"
    }

Once assigned, Microsoft Entra ID will begin issuing tokens with the additional claims.

Note- Claims Mapping Policies Are Assigned to Service Principals

This is one of the most important concepts to understand.

Claims Mapping Policies are attached to: Service Principals not App Registrations

No Organization-Level Assignment

Currently, Microsoft Entra ID does not support applying a Claims Mapping Policy globally across the tenant.

This means:

New applications do not automatically inherit the policy
Policies must be assigned individually
Automation is recommended for large environments

Summary

Claims Mapping Policies in Microsoft Entra ID provide a flexible mechanism for customizing authentication tokens with additional user attributes and custom claims. Understanding the distinction between App Registrations and Service Principals is essential when working with Claims Mapping Policies because the policy is always applied to the Service Principal responsible for token issuance.