Customize claims using Microsoft Graph Custom Claims Policy (preview)

  • 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. Claims customization supports configuring claims for applications using SAML, OAuth, and OpenID Connect protocols. You can use claims customization to:

  • Select which claims are included in tokens.
  • Create claim types that don't already exist.
  • Choose or change the source of data emitted in specific claims.

In this how-to guide, we cover a few common scenarios that can help you understand how to use the Custom Claims policy.

Prerequisites

Claims customization in Microsoft Entra ID

Microsoft Entra ID supports two ways to customize claims using Microsoft Graph/PowerShell for your applications:

In the following examples, you create, update, and replace policies for service principals. Custom claims policies are always linked to service principal objects. Be sure that you've configured your Enterprise Application as part of the prerequisites before creating a Custom Claims policy for the application/service principal.

Open Microsoft Graph Explorer in your browser sign in to Microsoft Graph Explorer as at least an Application Administrator, choose one of the following scenarios.

After creating a Custom Claims policy, you should configure your application to acknowledge that the tokens contain the customized claims. For more information, refer to Security considerations.

Omit the basic claims from tokens

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

  1. In Microsoft Graph Explorer, identify the application you want to configure the custom claims policy for using the service principal API.

  2. Create the Custom Claims policy by running the following API. This policy, linked to a service principal, omits the basic claims from the tokens.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Request Body:

    {
    "includeBasicClaimSet": false
}

  3. To see your new policy, run the following command

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Response:

    HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222.",
    "includeBasicClaimSet": false,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": []
}

Include the EmployeeID and TenantCountry as claims in tokens

In this example, you create a customization to the claims that adds the EmployeeID and TenantCountry to tokens. In this example, we also include the basic claims set in the tokens.

  1. In Microsoft Graph Explorer, identify the application you want to configure the custom claims policy for using the service principal API.

  2. Create the Custom Claims policy by running the following API. This policy, linked to a service principal, adds the EmployeeID and TenantCountry claims to tokens.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Request Body:

    {
    "includeBasicClaimSet": true,
    "claims": [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "employeeId",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " employeeid",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        },
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "country",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " tenantcountry",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        }
    ]
}

  3. To see your new policy, run the following command:

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Response:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Use a claims transformation in tokens

In this example, you update a policy to emit 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. In Microsoft Graph Explorer, identify the application you want to configure the custom claims policy for using the service principal API.

  2. Create the custom claims policy by running the following API. This policy emits a custom claim JoinedData to tokens.

    PATCH https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Request Body:

    {
    "includeBasicClaimSet": true,
    "claims": 
    [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "JoinedData",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": 
            [
                {
                    "condition": null,
                    "attribute": null,
                    "transformations": 
                    [
                        {
                            "@odata.type": "#microsoft.graph.joinTransformation",
                            "separator": "-",
                            "input": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type": "#microsoft.graph.sourcedAttribute",
                                    "id": "extensionattribute1",
                                    "source": "user",
                                    "isExtensionAttribute": false
                                }
                            },
                            "input2": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type":"#microsoft.graph.valueBasedAttribute",
                                    "value": "ext"
                                 }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

    Note

    Custom Claims Policy is a strongly typed policy and each transformation uses a different @odata.type value.

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

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Response:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Related content