Why is preferred_username missing from ID token in Entra ID (Azure AD), even after adding it as an optional claim?

Question

Why is preferred_username missing from ID token in Entra ID (Azure AD), even after adding it as an optional claim?

Johannes T 20

Hi all,

We’re using Microsoft Entra ID (formerly Azure AD) for authentication via oidc 2.0 in a web application, and encountering an issue with missing token claims.

Specifically, the preferred_username claim is not present in the ID token, even though:

• The app is registered in Entra ID with openid profile email scopes.

• preferred_username has been explicitly added as an optional claim for the ID token under “Token Configuration” in the Azure Portal.

• We are using standard users from our tenant (not B2C).

• The token is being correctly issued (we receive upn, unique_name, and others — just not preferred_username).

• The issue persists even after forcing a new login session.

This is causing issues in our Spring Security backend, which expects preferred_username to be present by default when mapping user identity.

Has anyone encountered this before, or is there a documented reason why preferred_username may be omitted from the ID token in certain conditions? Are there workarounds besides manually mapping upn to preferred_username?

Thanks in advance for any insights!

Accepted answer

0 additional answers

Your answer

Answer 1

Kancharla Saiteja 3,250 Microsoft External Staff

Hi @Johannes T,

Based on your query, here is my understanding: you have added preferred_username as an optional claim which has not passed in token.

Preferred_username claim is mutable which cannot be used for any authorization decisions and is only available for the users when you use v2.0 token. This claim is availble for the application when you have scope as profile for your application.

In order to receive the token with preferred_username you may need to use this endpoint:

Well-known configuration document path: /.well-known/openid-configuration
Authority URL: https://login.microsoftonline.com/{tenant}/v2.0
v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

The profile scope: The profile scope can be used with the openid scope and any other scope. It gives the app access to a large amount of information about the user. The information it can access includes, but not limited to, the user's given name, surname, preferred username, and object ID.

Additional information:

ID tokens in the Microsoft identity platform

Scopes and permissions in the Microsoft identity platform

v1.0 and v2.0 optional claims set

I hope this information is helpful. Please feel free to reach out if you have any further questions.

If the answer is helpful, please click "Accept Answer" and kindly "upvote it". If you have extra questions about this answer, please click "Comment".

Johannes T 20 Reputation points

2025-03-24T11:26:07.65+00:00

Hi again,

Thanks for your previous response — it was very helpful. We've now confirmed that the preferred_username claim is indeed present in the ID token after switching to the v2.0 endpoint and including the appropriate openid profile scopes. That part is working as expected. ✅

However, we noticed that the preferred_username is not included in the response from the UserInfo endpoint (/userinfo). We'd like to understand: • Is it expected behavior that preferred_username is not included in the /userinfo response even if it's in the ID token? • Is there a way to configure Azure (e.g. via optional claims or API permissions) to include preferred_username in the UserInfo endpoint response?

Or alternatively, should we just extend our application's user identity model to rely only on the claims from the ID token (and not from /userinfo) if that's the only place preferred_username will appear? We're using Spring Security, which by default expects certain claims in the UserInfo response, so having this claim consistently available would simplify our setup. Thanks again for your help, and looking forward to your guidance!

Regards
Kancharla Saiteja 3,250 Reputation points Microsoft External Staff

2025-03-24T11:54:51.2066667+00:00

Hi @Johannes T,

Thanks for your response,

I am glad you are able to get the preferred_username claim in your token. But you can add or modify anything to the output provided by /userinfo endpoint. This is unique and cannot be modified which has been confirmed here. Instead, I would suggest you add the claims which are available in /userinfo endpoint to the application as optional claims which would help you to achieve your required information in the token. Here is the Microsoft document to configure optional claims: v1.0 and v2.0 optional claims set

If the answer is helpful, please click "Accept Answer" and kindly "upvote it". If you have extra questions about this answer, please click "Comment".
Kancharla Saiteja 3,250 Reputation points Microsoft External Staff

2025-03-25T03:43:11.4933333+00:00

Hi @Johannes T,

Following up to see if the above answer was helpful. If this answers your query, do click Accept Answer and Yes for was this answer helpful. And, if you have any further query do let us know.
Johannes T 20 Reputation points

2025-03-25T06:51:47.85+00:00

Hi,you mentioned "But you can add or modify anything to the output provided by /userinfo endpoint."... assuming that was a type and you meant that we can**'t** modify it? Is this the expected behavior even if we create an optional claim?

You also mentioned: "I would suggest you add the claims which are available in /userinfo endpoint to the application as optional claims which would help you"

How would that help us with the initial problem?

Thanks a lot!
Kancharla Saiteja 3,250 Reputation points Microsoft External Staff

2025-03-25T08:15:11.27+00:00

Hi @Johannes T,

Thanks for your response,

I apologies for the miscommunication here. Yes, I have to mention "But you cannot add or modify anything to the output provided by /userinfo endpoint" instead I mentioned "But you can add or modify anything to the output provided by /userinfo endpoint". You cannot modify the output provided by /userinfo endpoint. This is an expected behavior and confirmed here.

As you have mentioned that you need the claims that has been provided by /userinfo ("name""family_name""given_name" "picture" "email") in the token so I suggested that without that endpoint as well you can get these claims by adding them as optional claims. That is the point I mentioned the documents and information regarding optional claims.

Thanks,

Saiteja K.

Share via

Why is preferred_username missing from ID token in Entra ID (Azure AD), even after adding it as an optional claim?

0 additional answers

Your answer