Custom Claims in JWT access token (ad nauseam)

Chris 20 Reputation points

It seems this question is asked over and over again but each is slightly different. We have a web app that we deploy for each of our clients. Each installation is different and may or may not require SSO. For Microsoft clients, we are integrating with Azure AD for the SSO portion. The web app requires a custom claim "entitlements" in the access token which has 1 or more values that specify the resource privileges of the user within the app, i.e. user, reports, admin.

I built the web app with the understanding that Azure AD supported custom claims which it sort of does and everything I have seen in documentation and even in the portal indicates that is possible, however in practice doesn't seem to work as advertised.

Here is what I need:

To register our app with Azure, assign some property to the members/users for the company using Azure that indicates their privileges within our app and that property is ultimately placed into the claims of the access JWT when it is requested by the web app. Assigning the user privileges should be like a property on the user account but protected so the administrator can only change or assign the value. However, it is unacceptable to subject the IT person for a company to use a script for every change that needs to be made for a user.

Here is what I found:

Most of the instructions for adding any sort of custom claim involves adding a preexisting optional claim that is considered an optional token and can be added using a minor tweak to the app manifest but the result is a static value or a name that is not what is specified. If the value is not static then it requires using Powershell or the graph API of some sort and not the portal. Documentation indicates that directory extensions can be used but they require a script as well. None of these options are visible in the portal.

Some of the instructions suggest using custom security attributes. They were extremely promising. It was all point click with logic that prevented multiple assignments values perfect for that was looking for. I created the definition, added them to the application and user, but ultimately, they didn't flow through to the JWT. The manifest doesn't allow adding them directly and if you do, it rejects them if you add them. Trying to add them using SSO / Attributes and Claims is fruitless. The attributes that appear there are only user.* based properties that are visible in the profile.

Alternative attempts:

The SSO / Attributes & Claims has the ability to add conditional claims that includes a reference to the group the user is associated with. So I created a special group and assigned a user to it. Then within the Add Claim, specified the condition that for that group, the claim would have one of the privileges. Nothing comes through.


I am pretty sure I missed something in my past attempts. For instance, the Add Claim surely must be able to pull values from AD beyond just user.* values. I just don't know enough about Azure or AD to figure out where it is that some permission is missing that needs to be turned on to enable it. Or if there is another setting that wasn't included when they were added.

If anyone has done what I am trying to set up, please let me know what I am doing wrong. If this is not even possible, please let me know that as well. Thanks for your help!


My app also supports the "roles" claim but it is restricted.

My steps in case you were wondering:

  1. Create a free Azure AD account and elevate it to P2 license level.
  2. Elevate my user account to create custom security attribute definitions.
  3. Create custom security attribute definition.
  4. Create a custom security attribute with 8 different possible values that can be selected.
  5. Under user, add a custom security attribute with at least one value selected.
  6. Back under the application registration, api permissions, add all permissions that allow access to all possible values that might be relevant.
  7. Under Manifest, changed accessTokenAcceptedVersion to 2
  8. Added the optionalClaims within the Manifest, added the custom security attribute named "entitlements" with source as "user"
  9. Tried to add Optional Claim "entitlements" but not present. Addition of entry typed into Manifest indicates it will not be added to JWT since it is not a valid claim.
  10. I went to enterprise application, single sign on, Manage Claims, clicked on Add a claim, and looked for entitlements but only user.* properties are there from the profile area of a user.
  11. Typing the source attribute for entitlement just makes a string appear with the text "entitlements"
Microsoft Entra ID
Microsoft Entra ID
A Microsoft Entra identity service that provides identity management and access control capabilities. Replaces Azure Active Directory.
19,867 questions
{count} votes

Accepted answer
  1. Akshay-MSFT 16,511 Reputation points Microsoft Employee

    @Chris Thank you for posting your query on Microsoft Q&A. From above description, I was able to conclude that you are looking to get "user roles" in access token claims when they access an application.

    Where Roles are permission / Privilege tag assigned to the application by you.

    The approach you tried above would not help as only permissions/roles of app w.r.t other app or user w.r.t current app could received in the token.

    The suggestion here would be to defined roles in each of the application and add the user groups to it. An app registration's app roles pane in the Azure portal

    An app registration's app roles create context pane in the Azure portal


    Akshay Kaushik

    0 comments No comments

1 additional answer

Sort by: Most helpful
  1. Limitless Technology 44,011 Reputation points

    Hello there, Try adding this claim as optional claim and see if that helps. As a workaround, you can add it as an optional claim through App registrations in the Azure portal. Open the application in App registrations, select Token configuration, and then select Add optional claim. Select the SAML token type, choose upn from the list, and then click Add to add the claim to the token. Hope this resolves your Query !! --If the reply is helpful, please Upvote and Accept it as an answer--

    0 comments No comments