Adding User Optional and Mapped Claims in the Azure AD Authentication Token

Developer Support

Premier Dev Consultant Erick Ramirez Martinez explores the use of User Optional and Mapped Claims with Azure AD Authentication.

When we are using Azure Active Directory, we need to add extra information related to the user in the token that we received once that we get an authenticated user in our app. By Default, in our token we only see some user’s information like preferred username, email, name, roles assigned to this user and the unique name.

What about if we need to add extra information like the country or any additional data related with the user, in the case of the country we can add it as an optional claim modifying the App Registration manifest in the Azure AD like in the following code snippet:

"optionalClaims": {
        "idToken":[
            {
                "name":"tenant_ctry",
                "source":null,
                "essential":false,
                "additionalProperties":[]
            },
            {
                "name":"upn",
                "source":null,
                "essential":false,
                "additionalProperties":["include_externally_authenticated_upn"]
            },
            {
                "name":"ctry",
                "source":null,
                "essential":false,
                "additionalProperties":[]
            }
        ]
    },

As you can see you can add the country and the tenant country in the manifest as optional claims, all the optional claims available are described in the Microsoft Documentation:

But what if we need to get the office or any other data that we are able to register in the new user form, directly in the Azure Active Directory Portal? That is not feasible adding an optional Claim!

The alternative is to add claims as mapped claims in the service principal in the Azure Active Directory Tenant.

To achieve this, we need to enable the AcceptMappedClaims to true in the App Registration Manifest as we can see in the following image:

Then we need to execute a series of commands in PowerShell to apply our claim mapped policy to our service principal and we can see the office claim in our token.

First, we need to enable the AzureADPreview PowerShell module with the following command:

Then we get connected to the Azure AD tenant with the “Connect-AzureAD” Command:

With our App Id we need to identify the service principal related with our App Registration, to do that we need to execute the following commands:

$appID = "4b1f35bb-xxxxxx"
Get-AzureADServicePrincipal -Filter "servicePrincipalNames/any(n: n eq '$appID')"

Getting the service principal as the object id as is shown in the image:

Now we procced to create an Azure AD policy where we will add 2 mapped claims (the user office and the country) and we specify a name (in this case we will name it UseClaimsExample3) with the following command:

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

Then to get the Policy’s object Id we execute “Get-AzureADPolicy” command:

Once that we have the new policy and the service principal, we need to associate them with the following command:

Add-AzureADServicePrincipalPolicy -Id '737bcfd8-xxxx-xxxx-xxxx-xxxxxxxxxxxx' -RefObjectId '755a3d64- xxxx-xxxx-xxxx-xxxxxxxxxxxx'

It’s important to mention that we only can have one policy per Service principal, but in that policy, we can specify multiple claim.

And that’s it! We will get the claims in our code; we can see that we are ready to consume the information directly from the claims.

Developer Support App Dev Customer Success Account Manager, Microsoft Developer Support

Follow