How can I include an email claim in an Open ID token for the managed account in Entra ID?

Tony Mee 20

I registered a multi-tenant application in my own tenant of Microsoft Entra ID. I configured email and openid as API Permissions. I tried the device code grant flow with this application.

I specified email and openid as scope in the v2.0/devicecode endpoint and obtained a user code, device code, and verification URL. I accessed the verified URL in a browser, entered the user code, signed in with my Outlook.com personal account, and consented to 'View your email address' and 'Sign you in'.

I then passed the device code to the v2.0/token endpoint and obtained an access token and id token as expected. I decoded the id token as JWT and confirmed that the payload contained an email claim.

Next, I tried the same thing with a managed account, that is, a user in the tenant where the application was registered. It was the same as with a personal account, up until the point where I entered the user code in the verification URL and logged in to the managed account. However, something strange happened here.

I was expecting to be asked for consent to 'View your email address' and 'Sign you in', just like with a personal account, but in fact I was asked for consent to 'View your basic profile' and 'Maintain access to data you have given it access to'. The scope I requested was email and openid as same as before. I was curious about the difference from the personal account, but I went ahead with the steps anyway.

When I passed the device code to the v2.0/token endpoint and decoded the id token obtained, there was no email claim this time. The email property of the signed-in managed account is set to the correct address. In fact, I can obtain this address as email by accessing the userinfo endpoint.

According to Microsoft's document, specifying the email scope allows the email claim to be included in the id token as long as the user is associated with an email address. I also tried specifying email as an optional claim in the token configuration, but the result was the same.

Is there any other setting required for managed accounts to include the email claim in the id token? Or are there other settings for the tenant, user, and application that prevent the email claim from being included in the id token for managed accounts?

Robina 25 Reputation points

2024-11-22T14:22:04.49+00:00
Why the Behavior Differs Between Personal and Managed Accounts

Consent Behavior Differences:

Personal Accounts: Consent is at the user level. When you request openid and email scopes, the system interprets these as "View your email address" and "Sign you in," which directly maps to the claims in the token.

Managed Accounts: Consent for organizational accounts may be governed by admin policies, and the resource (your app) may require additional admin approval. Additionally, the claims surfaced might vary based on the organization's configuration.

Relevant Documentation:

Microsoft identity platform scopes, permissions, and consent

2. Default Claims in ID Tokens:

The email claim is only included in the ID token if the email is available and certain conditions are met. For managed accounts:

If the email is not explicitly set for the user (e.g., a guest user with no email property in Entra ID), it will not appear in the token.

Even if the email exists, tenant or application policies may affect whether it’s included in the ID token.

Relevant Documentation:

ID token claims in the Microsoft identity platform

3.Scope Interpretation:

While you request openid and email scopes, the consent experience and claims may differ based on the audience and resource policy.

Managed accounts often map these scopes to more generic claims (like "View your basic profile") unless explicitly configured.

Troubleshooting and Solutions

Check Tenant-Level Policies

Admin Consent Settings: Verify if your tenant requires admin consent for specific scopes (even email) or for external applications.

Conditional Access Policies: Ensure there are no restrictions affecting token issuance or claim inclusion.

Relevant Documentation:

Troubleshooting Azure Active Directory issues

Token Configuration in the Application Registration

Navigate to Azure Portal > Entra ID > App registrations > Your App.

Under Token Configuration, ensure the email claim is added as an optional claim for ID tokens. If it already exists and the claim isn’t appearing:

Remove and re-add the optional claim.

Test again with the updated configuration. Relevant Documentation: https://learn.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims

Use the userinfo Endpoint

As you mentioned, the userinfo endpoint correctly provides the email claim. If this behavior is acceptable for your application, consider retrieving the email address from there instead of relying on the ID token.

Relevant Documentation:

Get additional claims using the UserInfo endpoint

Explicitly Request Email in the Scopes

Instead of relying on openid and email alone, try adding profile to the scope. This sometimes results in additional claims being included in the token.

Example:
scope=email openid profile

5. Debugging Tools

Use tools like JWT.ms to analyze the tokens you receive. Compare tokens between personal and managed accounts to identify missing claims or differences.

Relevant Documentation:

Analyze and debug tokens using Microsoft identity platform Recommendations

The behavior is expected due to differences in claim handling between personal and managed accounts.

Use Token Configuration to explicitly request the email claim for ID tokens.

Alternatively, rely on the userinfo endpoint to ensure you get the email address when needed.
Tony Mee 20 Reputation points

2024-11-25T05:50:13.1533333+00:00
Thank you for your detailed explanation and troubleshooting steps. As advised, I tried the following, but unfortunately it did not resolve the issue.

Admin consent for email permission: I did not originally configure my tenant and application to require admin consent for email permission, but I did pre-configure the application to grant admin consent for email and openid.

Conditional Access Policies: I verified that my tenant and application did not have any conditional access policies applied.

Token configuration (optional claims): I removed and re-added the optional email claim. I also edited 'optionalClaims' in the application's manifest to set 'true' to 'essential' for the email claim.

As I mentioned before, none of the above worked. It seems better to reference the userinfo endpoint than to try to include the email claim in the id token.

However, during these investigations, I discovered one thing.

As I explained in my original question, I registered my application as a multi-tenant application, but I discovered that registering my application as a single-tenant application allowed me to successfully include the email claim in the ID token for managed accounts. In this case, no admin consent or token configuration for optional claims was required.

Apparently, Microsoft applies more limited controls to multi-tenant applications compared to single-tenant applications.

Accepted answer

Navya 13,380 Reputation points Microsoft Vendor

2024-11-27T17:27:18.2366667+00:00
Hi @Tony Mee

I'm glad that you were able to resolve your issue and thank you for posting your solution so that others experiencing the same thing can easily reference this! Since the Microsoft Q&A community has a policy that "The question author cannot accept their own answer. They can only accept answers by others ", I'll repost your solution in case you'd like to "Accept " the answer.

Issue:

How can I include an email claim in an Open ID token for the managed account in Entra ID?

Solution:

Resolved by @Tony Mee

Cause for this issue:
According to the document https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization?source=recommendations, mutable claims such as email in tokens can be insecure if they are mistakenly used as a unique identifier for an account. To avoid unexpected security incidents, Microsoft has changed the default to not include such claims in tokens as of June 2023. With this change, email claims are no longer included in ID tokens unless they are verified by the domain owner.

An email is considered domain owner verified if:

The domain belongs to the tenant where the user account resides and the tenant administrator has verified the domain

The email is from a Microsoft account (MSA)

The email is from a Google account

The email was used to authenticate using the one-time passcode (OTP) flow

As previously reported, the email address of an Outlook.com personal account was included in the ID token. I believe this is because the Outlook.com address is from a Microsoft account.

The document also states that the above change in default behavior only applies to multi-tenant applications, which proves that I did not encounter the issue of missing email claim in a single-tenant application.

The solution is detailed in the following documentation:

https://learn.microsoft.com/en-us/graph/applications-authenticationbehaviors

You can change the default behavior so that the email claim is included in the ID token even if it is not considered domain owner verified by updating the authenticationBehaviors property of your application and setting removeUnverifiedEmailClaim to false.

This completely solved my problem. Now I can include the email of my managed account in the ID token. Of course, this solution is not desirable from a security perspective, so anyone should be very careful when implementing it.

Note: Of course, this solution is not desirable from a security perspective, so anyone should be very careful when implementing it.

If I missed anything please let me know and I'd be happy to add it to my answer, or feel free to comment below with any additional information. Thank you again for your time and patience throughout this issue.

Thanks,

Navya.

Please remember to "Accept Answer" if any answer/reply helped, so that others in the community facing similar issues can easily find the solution.
Please sign in to rate this answer.

1 person found this answer helpful.

0 comments No comments
Sign in to comment

Use comments to ask for clarification, additional information, or improvements to the question.

2 additional answers

Navya 13,380 Reputation points Microsoft Vendor

2024-11-25T20:36:58.7166667+00:00

Hi @Tony Mee

Thank you for posting this in Microsoft Q&A.

I understand that you have included email and OpenID as API permissions and scopes while making a request to the device code flow endpoint.

When using a personal account, it asks for consent to 'View your email address' and 'Sign you in.' However, when using managed accounts, it requests consent to 'View your basic profile' and 'Maintain access to data you have given it access to.'

The OpenID scope appears on the work account consent page as the 'Sign you in' permission. This permission gives the app access to the UserInfo endpoint. Therefore, when using managed accounts, it requests consent for 'View your basic profile' and 'Maintain access to data you have given it access to.'

How can I include an email claim in an OpenID token for the managed account in Entra ID?

By default, guest accounts that have an email address. In the first scenario, since you are using Outlook, you are receiving the email in the token. You can also get the email claim for managed accounts. To obtain the email claim in the token for managed accounts, the email attribute must be associated with the user account in the user properties. Otherwise, no email claim will exist in the token.

Could you please cross-check whether the managed account has the email attribute associated with it?

For your reference: https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc#:~:text=The%20openid%20scope,in%20the%20token.

https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference

Hope this helps. Do let us know if you any further queries.

Thanks,

Navya.

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.
Please sign in to rate this answer.
Tony Mee 20 Reputation points

2024-11-27T12:45:08.7233333+00:00

Hi, Navya

Thanks for your comment.

First the bad news. I checked the managed accounts and confirmed that they have the proper email address in the email property. In my case, the missing email property is not the root cause of the issue.

The good news. I found the true cause and solution for the situation in another Microsoft document.

https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization?source=recommendations

According to the document, mutable claims such as email in tokens can be insecure if they are mistakenly used as a unique identifier for an account. To avoid unexpected security incidents, Microsoft has changed the default to not include such claims in tokens as of June 2023. With this change, email claims are no longer included in ID tokens unless they are verified by the domain owner.

An email is considered domain owner verified if:

The domain belongs to the tenant where the user account resides and the tenant administrator has verified the domain

The email is from a Microsoft account (MSA)

The email is from a Google account

The email was used to authenticate using the one-time passcode (OTP) flow

As previously reported, the email address of an Outlook.com personal account was included in the ID token. I believe this is because the Outlook.com address is from a Microsoft account.

The document also states that the above change in default behavior only applies to multi-tenant applications, which proves that I did not encounter the issue of missing email claim in a single-tenant application.

The solution is detailed in the following documentation:

https://learn.microsoft.com/en-us/graph/applications-authenticationbehaviors

You can change the default behavior so that the email claim is included in the ID token even if it is not considered domain owner verified by updating the authenticationBehaviors property of your application and setting removeUnverifiedEmailClaim to false.

This completely solved my problem. Now I can include the email of my managed account in the ID token. Of course, this solution is not desirable from a security perspective, so anyone should be very careful when implementing it.
Sign in to comment

Use comments to ask for clarification, additional information, or improvements to the question.
Deleted

This answer has been deleted due to a violation of our Code of Conduct. The answer was manually reported or identified through automated detection before action was taken. Please refer to our Code of Conduct for more information.

Comments have been turned off. Learn more

Your answer