Edit

Share via

Claims customization using PowerShell and Claims Mapping Policy

  • Article

A claim is information that an identity provider states about a user inside the token they issue for that user. Claims customization is used by tenant admins to customize the claims emitted in tokens for a specific application in their tenant. You can use claims-mapping policies to:

  • select which claims are included in tokens.
  • create claim types that do not already exist.
  • choose or change the source of data emitted in specific claims.

Claims customization supports configuring claim-mapping policies for the SAML, OAuth, and OpenID Connect protocols.

Note

Claims Mapping Policy supersedes both Custom Claims policy and the claims customization offered through the Microsoft Entra admin center. Customizing claims for an application using the Claims Mapping Policy means that tokens issued for that application will ignore the configuration in Custom Claims Policy or the configuration in claims customization blade in the Microsoft Entra admin center.

Prerequisites

Get started

In the following examples, you create, update, link, and delete policies for service principals. Claims-mapping policies can only be assigned to service principal objects.

When creating a claims-mapping policy, you can also emit a claim from a directory extension attribute in tokens. Use ExtensionID for the extension attribute instead of ID in the ClaimsSchema element. For more info on extension attributes, see Using directory extension attributes.

Note

The Microsoft Graph PowerShell SDK is required to configure claims-mapping policies.

Open a terminal and run the following command to sign in to your Microsoft Entra admin account. Run this command each time you start a new session.

Import-Module Microsoft.Graph.Identity.SignIns

Connect-MgGraph -Scopes "Policy.ReadWrite.ApplicationConfiguration", "Policy.Read.All"

Now you can create a claims mapping policy and assign it to a service principal. Refer to the following examples for common scenarios:

After creating a claims mapping policy, configure your application to acknowledge that tokens will contain customized claims. For more information, read security considerations.

Omit the basic claims from tokens

In this example, you create a policy that removes the basic claim set from tokens issued to linked service principals.

  1. Create a claims-mapping policy. This policy, linked to specific service principals, removes the basic claim set from tokens.

  2. Using the terminal you have open, run the following command to create the policy:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"false"}}') -DisplayName "OmitBasicClaims"

  3. To see your new policy, and to get the policy ObjectId, run the following command:

    Get-MgPolicyClaimMappingPolicy

Definition                    DeletedDateTime Description DisplayName      Id
----------                    --------------- ----------- -----------      --
{"ClaimsMappingPolicy":{..}}                              OmitBasicClaims  36d1aa10-f9ac...

Include the EmployeeID and TenantCountry as claims in tokens

In this example, you create a policy that adds the EmployeeID and TenantCountry to tokens issued to linked service principals. The EmployeeID is emitted as the name claim type in both SAML tokens and JWTs. The TenantCountry is emitted as the country/region claim type in both SAML tokens and JWTs. In this example, we continue to include the basic claims set in the tokens.

  1. Create a claims-mapping policy. This policy, linked to specific service principals, adds the EmployeeID and TenantCountry claims to tokens.

  2. To create the policy, run the following command in your terminal:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"employeeid","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid","JwtClaimType":"employeeid"},{"Source":"company","ID":"tenantcountry","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country","JwtClaimType":"country"}]}}') -DisplayName "ExtraClaimsExample"

  3. To see your new policy, and to get the policy ObjectId, run the following command:

    Get-MgPolicyClaimMappingPolicy

Use a claims transformation in tokens

In this example, you create a policy that emits a custom claim "JoinedData" to JWTs issued to linked service principals. This claim contains a value created by joining the data stored in the extensionattribute1 attribute on the user object with "-ext". In this example, we exclude the basic claims set in the tokens.

  1. Create a claims-mapping policy. This policy, linked to specific service principals, emits a custom claim JoinedData to tokens.

  2. To create the policy, run the following command:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema":[{"Source":"user","ID":"extensionattribute1"},{"Source":"transformation","ID":"DataJoin","TransformationId":"JoinTheData","JwtClaimType":"JoinedData"}],"ClaimsTransformations":[{"ID":"JoinTheData","TransformationMethod":"Join","InputClaims":[{"ClaimTypeReferenceId":"extensionattribute1","TransformationClaimType":"string1"}], "InputParameters": [{"ID":"string2","Value":"ext"},{"ID":"separator","Value":"-"}],"OutputClaims":[{"ClaimTypeReferenceId":"DataJoin","TransformationClaimType":"outputClaim"}]}]}}') -DisplayName "TransformClaimsExample"

  3. To see your new policy, and to get the policy ObjectId, run the following command:

    Get-MgPolicyClaimMappingPolicy

Assign the claims mapping policy to your service principal

To assign the policy to the service principal you will need the ObjectId of your claims mapping policy and the objectId of the service principal to which the policy must be assigned.

  1. To see all your organization's service principals, you can query the Microsoft Graph API or, check them in Microsoft Graph Explorer.

  2. To see all the claims mapping policies in your tenant, and to get the policy ObjectId, run the following command:

    Get-MgPolicyClaimMappingPolicy

  3. When you have the ObjectId of your claims mapping policy and the service principal, run the following command:

    New-MgServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId <servicePrincipalId> -BodyParameter @{"@odata.id" = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/<claimsMappingPolicyId>"}

Related content