The JWT token emitted by the Azure AD (irrespective of whether it is an access token or an id token) does not contain much useful information except the email address and some other fields. Particularly when you are coming from an enterprise background where employeeid plays a crucial part in identifying a user in a lot of backend systems. Then we need more claims as a part of the JWT token apart from the default claims that are present in the JWT tokens. In this article, let’s look at the steps to include a custom claim, such as an employeeid as a part of the JWT token itself. So when the JWT token is passed around to the backend services, the backend services could identify a user based on employeeid and make necessary claims.
In my previous blog, I explained how to find out the actual name of the Azure AD attribute that needs to be a part of the JWT token. This article will focus on adding employeeid claim as a part of the JWT token. However, you can do the same to any other attribute in Azure AD that is synchronized from on-premises Active Directory Domain Services (AD DS).
We are going to be using the “Claims Mapping” feature of Azure AD that is currently in “public preview” at the time of this writing.
The documentation sometimes can be outdated, obsolete or sometimes just plain wrong. So in order to obtain the desired result, it is recommended to follow the exact steps described in the article.
The sample application that we would be using to test whether the employeeid is added as a part of JWT claims would be https://github.com/dream-365/OfficeDev-Samples. However, if there is an existing application already registered under Azure AD -> applications, then it should also work (provided that you have edited the manifest file and configured the appropriate “Application ID” settings).
Since claims mapping is a public preview feature, there is no GUI support in the Azure portal. Therefore, we need an Azure AD PowerShell module that supports claims mapping. As recommended in the MSDN documentation, this particular version of Azure AD Powershell works with the samples as described in the article. The future releases of Azure AD Preview or the newer releases work as well.
Claims Mapping Policy
A claims mapping policy is a policy that would be associated with a service principal object for an application in Azure AD. A service principal is an identity that is used to run an Application in Azure AD.
For example: Under services.msc in Windows, a service runs under an identity such as Local Service, or Network Service, or anything that is configured to run under. Similarly, every application that is registered in Azure AD, runs under its own service principal (synonymous to a service account in Windows / Linux)
In the screenshot below, the Application ID and Object ID is not the service principal. We need Get-AzureADServicePrincipal cmdlet from Azure AD PowerShell to query the service principal id of an application.
Step 1: Edit the Application’s manifest to process claims mapping
Set acceptMappedClaims to true
Step 2: Understanding a claims mapping policy and binding it to a service principal
This step is only to understand how claims mapping policy is created and how it is bound to a service principal object in Azure AD. Step 3 proposes a PowerShell script do all of this in one go.
So, creating a new Azure AD Policy to include employeeid is as below. Running this cmdlet would throw back an Object ID for the created policy.
Then with the created policy, we need to run the cmdlet below to associate it with a service principal. Service principal is obtained from the Get-AzureADServicePrincipal cmdlet.
And that’s it.
Step 3: Running the PowerShell script to create claims mapping policy and bind the policy to Application’s Service principal
The script below removes any existing policies bound to a Service Principal Object. You can modify the script if you don’t want that existing policy mappings are removed. But if you are creating claims mapping for the first time, then you can leave the script intact.
Replace the $appid with the Application ID value of the application.
Save the below script as AddEmployeeIDToJWTClaims.ps1.
Open PowerShell and run cmdlet Connect-AzureAD.
There you have it. That should have you get going with adding employeeid claims with Azure AD’s JWT token.
PowerShell script courtesy of http://www.redbaronofazure.com/?p=7566.
Step 4: Configuring a Proof of Concept Application to request a JWT token with employeeid claims
The steps below outline, what it takes to run the https://github.com/dream-365/OfficeDev-Samples as a proof of concept to visually see the employeeid added as a part of the JWT token.
Open the Office365DevQuickStart.sln file in Visual Studio and navigate to the project OAuth2-basic.
Replace the values of the OAuthBasic.cs file as appropriate. For our example, here’s how the file was modified.
Open AuthorizationCodeGrantFlow.cs and modify code as below. Change the value of the resource to any resource in your tenant. If the application has permission to access the resource, and the user has given consent to allow an application to access the resource, our Claims Mapping policy would get applied and we would get a JWT token with the employee id. If not, try requesting a JWT token for the application id itself.
Run the application, log in and follow the steps as below. We ran a fiddler trace as well to capture the HTTP traffic and see the raw JWT token.
And here’s a fiddler trace showing the token response and a base 64 decoded JWT content value with the employeeid claim.
Optionally we can have additional permissions defined for our application. This way, you can use JWT tokens (with employeeid) to be requested for those resources.