Introducing a powerful new capability for native apps: custom claims—available as Public Preview in Microsoft Entra External ID. This enhancement allows an application to dynamically add custom claims into an authentication token, via a custom claims provider, when a user signs up or signs in. This allows you to tailor your app’s behavior based on specific user data. For example, the application may block or grant access to certain features based on a claim in the token. This is particularly useful when integrating with third-party or proprietary data stores that can’t be synced to the directory due to data residency, regulations, or other constraints.

How to get started with Native Authentication

If you have not yet explored how to create pixel-perfect mobile apps using Native Authentication, click the link below:

If you have already created a mobile app using Native Authentication, visit our docs to learn how to configure a custom claims provider.

What are custom claims?

Custom claims are pieces of key user data, often stored on and fetched from external systems, that can be added into authentication tokens. For example, secondary email addresses, billing tier information, or other sensitive information.

Custom claims providers

A custom claims provider is made up of a custom authentication extension that calls an external REST API to fetch claims from an external system. A custom claims provider can be assigned to one or many applications in your directory.

Custom authentication extensions use event listeners, like the token issuance start event listener. An event is triggered when a token is about to be issued to your application. An event listener is a procedure that waits for an event to occur. When an event is triggered, the custom authentication extension REST API is called to fetch attributes from external systems.

Setting up a custom claims provider

To set up a custom claims provider, you’ll need to create a REST API with a token issuance start event, then configure a custom claim provider for a token issuance event.

The screenshot below shows an example of an ID Token with custom claims ‘dateOfBirth’ and ‘customRoles’.

Accessing custom claims via the Native Authentication SDK

The Native Authentication SDK makes using custom claims seamless. Additional claims can be added to both the ID Token and Access Token using a custom claims provider. Custom claims from the ID Token are available in the accountResult object post sign-in on both Android and iOS SDK.

• Claims added to the ID Token are consumed by the client application (e.g. a native mobile application) for authentication purposes.

• Claims added to the Access Token should be consumed by a resource application (e.g. an API that is called by a client application) for authentication and authorization.

val dateOfBirth = accountResult.getClaims()?.get("dateOfBirth") 

val roles = accountResult.getClaims()?.get("customRoles") as JSONArray 

binding.resultIdToken.text = "User's date of birth: ${dateOfBirth}, User's role: ${roles.first()}" 

You can then use these claims to personalize an application experience dynamically—for instance, displaying a unique UI on an app for users with certain roles or loyalty tiers. Users with custom claim ‘loyaltyTier’ with value Platinum could enjoy a different color scheme, or exclusive menu options available only to platinum customers, etc.

Let’s recap

In this blog post, we have explored the powerful new custom claims capability for Native Authentication. We discussed how custom claims can be fetched from external systems using REST APIs and added into authentication tokens, enabling you to build more dynamic applications. By leveraging the Native Authentication SDK, you can access and use custom claims to tailor the user experience across mobile platforms.

To learn more or test out features in the Microsoft Entra portfolio, visit our developer center. Make sure you subscribe to the Identity developer blog for more insights and to keep up with the latest on all things Identity. And, follow us on YouTube for video overviews, tutorials, and deep dives.