Share via

How to use custom claim for application's role

Quentin RODIC 40 Reputation points
2025-06-13T08:23:49.38+00:00

Hello,

I'm working with a third-party application that requires custom claims containing application roles as an array of strings. However, I'm encountering limitations with claims mapping policies in Entra ID.

Issue:

  • Need to include application roles in custom claims for a client credentials flow
  • The application source in claims mapping policies doesn't support retrieving application roles
  • Multi-valued properties like "tags" only emit a single value in claims mapping policies

Question:

What are the recommended approaches to include application role information in custom claims when using claims mapping policies? Are there alternative methods such as:

  • Extension attributes on application objects
  • Service principal properties that support role information
  • Other supported claim sources that can provide application role data

Context:

  • Using client credentials flow (no user context)
  • Third-party application expects roles as custom claims in JWT tokens
  • Standard "roles" claim in tokens doesn't meet the application's requirements

Any guidance on best practices for this scenario would be appreciated.

Thanks!

Microsoft Security | Microsoft Entra | Microsoft Entra ID
Accepted answer
  1. Rukmini 3,841 Reputation points Microsoft External Staff Moderator
    2025-06-18T08:05:20+00:00

    Hello Quentin RODIC,

    Microsoft Entra ID does not support emitting application roles in custom claims via claims mapping policies for client credentials flow.

    Hence as a workaround check the below:

    • Define appRoles in your API and assign them to the service principal of the calling app to use the standard roles claim.
    • Map a JSON string of roles to a custom claim (still as a string) and store it in a directory extension property.
    • By programmatically mapping roles and resolving the client app ID (azp), you can enhance roles inside your API.

    App-only tokens do not support dynamic app role assertions through policy. If you need array format, use backend enrichment.

    Hope this helps!

    If this answers your query, do click Accept Answer and Yes for was this answer helpful, which may help members with similar questions.

    User's image

    If you have any other questions or are still experiencing issues, feel free to ask in the "comments" section, and I'd be happy to help.

    1 person found this answer helpful.
    0 comments

1 additional answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. Eric Nguyen 1,025 Reputation points Independent Advisor
    2025-06-16T06:08:10.9066667+00:00

    Hi @Quentin RODIC ,

    Thank you for contacting Q&A Forum. I would like to provide my findings and proposed solution:

    Please note that the "app roles" are application permissions defined by an app and they are emitted in access tokens only if the permissions are called by a client app. For client credential flows, since no user context is involved, you can't select "user.assignedroles" as the custom claim. In this scenario, if you are not using any client apps to query the permissions exposed by the API app, I would suggest that you use the Graph API to directly retrieve the app roles defined by your app:

    https://learn.microsoft.com/en-us/graph/api/serviceprincipal-get?view=graph-rest-1.0&tabs=http#example-2-retrieve-the-specific-properties-of-a-service-principal

    Customizing the access token is not the recommended way to retrieve additional attributes as there are many limitations by designed.

    Kindly let me know if this work for you and please let me know if you have any further questions.

    If I have answered your question, please accept this answer as a token of appreciation and don't forget to give a thumbs up for "Was it helpful"!

    Best regards,
    Eric

Your answer

Answers can be marked as Accepted Answers by the question author, which helps users to know the answer solved the author's problem.