Security  

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.

Membership not found