Customize your authentication flows with custom claims providers!

Howdy folks, 

I’m super excited to announce the public preview of custom claims providers for Azure Active Directory (Azure AD), now part of Microsoft Entra.  

A custom claims provider lets you call an API and map custom claims into the token during the authentication flow. The API call is made after the user has completed all their authentication challenges, and a token is about to be issued to the app.  

We heard from many of you that you need to return additional claims into the tokens sent to your apps so that they could function as intended. And these claims were being sourced from external systems, for a few reasons: 

• You needed to keep sensitive attributes on premises and use Active Directory Federation Services, or other federation services to pass through claims to Azure AD. 
• Regulatory requirements prevented you from being able to synchronize these attributes to Azure AD. 
• You have complex RBAC models which are stored in external databases. 
• You don’t own the app or cannot modify the app to fetch these attributes post authentication.

Now, with custom claims providers, you can source claims from external systems and issue them directly into the token. It allows interfacing with any data store, LDAP, SQL or anything else. A custom claims provider can be setup for your Open ID and SAML apps, and it works in scenarios to authenticate employees, and external identities. 

 
Let’s show you how you can set this up for Contoso’s HR app. In this scenario, Contoso are looking to decouple their HR app from Active Directory Federation Services, and authenticate directly with Azure AD. The HR app expects the user’s employee number to be returned in the token, which is stored in an on-premises Active Directory.  

Contoso can configure a custom claims provider to fetch this data and insert it into the token during authentication. Let’s begin setting it up for Contoso’s Azure AD.  
 
In the Enterprise applications menu, the Contoso Admin selects Custom authentication extensions, and then selects Create a custom extension. 

They then select TokenIssuanceEvent and select Next. 

The admin enters a Name, the API endpoint, and Description for Contoso’s API, and selects Next. The API endpoint would communicate with Active Directory using an LDAP search to fetch the user’s employee number. 

Next, the Contoso admin can configure how the custom extension will authenticate to their API. They will select Create new app registration, provide a Name, and select Next. We will use client credentials to authenticate to Contoso’s API.  Since Contoso hosts their API using an Azure Functions app, this app registration will be used to protect it automatically. 

Then, they configure the attribute name returned by the API to the custom extension. Contoso’s API will return the attribute employeeName. The admin enters employeeName under Claim name, and selects Next. 

Now let’s map in the claim for the HR App Registration using the custom claims provider. The Contoso admin navigates to the Enterprise Applications menu, selects their App, selects Single sign-on, and then selects Edit under Attributes and Claims. 

The Contoso admin then needs to create a claims mapping to source the employee number from the custom extension by configuring a custom claims provider. 

They expand the Advanced menu, and select Configure.  

The admin selects Custom claims provider and selects the custom extension that was created earlier, then selects Save. 

Finally, the admin selects Add new claim and enters a Name for the claim to be issued into the token. They will then select Attributes under Source, and select the Source Attribute, which will be in the format: customClaimsProvider.attributeName. Then select Save. 

Now that’s all done, when a user completes their sign in into the Contoso HR app, the custom extension will be triggered, and the custom claims provider will use the custom extension to add the employee number into the token. 

Here’s a diagram showing the flow. 

There is a more in-depth video tutorial you can find below: https://youtu.be/BYOMshjlwbc

Custom claims providers is just the first use of a custom extension. We’ll continue to release additional custom extension events, so you can customize your authentication flows even more. 

You can read more about custom extensions here and about custom claims providers here. Get started with setting up a custom claims provider here. 

As always, we'd love to hear your feedback, thoughts, and suggestions! Feel free to share with us on the Azure AD forum or leave comments below. We look forward to hearing from you. 

Best regards, 
Alex Simons (@Alex_A_Simons) 
Corporate VP of Program Management 
Microsoft Identity Division 

Learn more about Microsoft identity:  

• Related Articles:  
  • Authentication flows and application scenarios 
  • Custom Claims Overview 
• Return to the Azure Active Directory Identity blog home  
• Join the conversation on Twitter and LinkedIn  
• Share product suggestions on the Azure Feedback Forum