Enable optional claims in your app - Microsoft Enter (2023)

  • Article

You can use optional requests to:

  • Select the token inclusion requirements for your application.
  • Change the behavior of certain requests that Microsoft Identity Platform returns in tokens.
  • Add and access custom requests for your application.

For lists of standard requirements, seetoken de accesoiid_tokenrequirements documentation.

Although optional claims are compatible with v1.0 and v2.0 format tokens and SAML tokens, they provide most of their value when moving from v1.0 to v2.0. The Microsoft identity platform uses smaller token sizes to ensure optimal client performance. As a result, several requirements that were previously included in access and identification tokens are no longer present in v2.0 tokens and must be requested separately for each application.

Account typesheet v1.0ficha v2.0
A personal Microsoft accountN / Asupported
Azure AD accountsupportedsupported

v1.0 and v2.0 additional set of requirements

The set of optional requirements that are available by default for applications are listed in the following table. You can use custom data in extension attributes and directory extensions to add optional requirements for your application. When you add claims to an access token, the claims refer to the requested access tokensforapplication (web API), not requestsafterapplication. No matter how a client accesses your API, the actual data is present in the access token used to authenticate to your API.


Most of these claims can be included in the JWT for v1.0 and v2.0 tokens, but not for SAML tokens, unless specified in the Token Type column. Consumer accounts support a subset of these requirements, listed in the Customer Type column. Many of the above statements do not apply to consumers (they do not have a tenant, sotenant_tryIt does not have value).

The following table lists the optional set of v1.0 and v2.0 requirements.

DoDescriptionType tokenType of usergrades
accountUser account status in the tenantJWT, SAMLIf the user is a tenant member, the value is0. If you are a guest, the value is1.
authorization_timeThe time of the last authentication of the user.JWT
proofUser country/regionJWTThis assertion is returned if it is present and the field value is a standard two-letter country/region code, such as FR, JP, SZ, etc.
emailEmail address registered for this userJWT, SAMLMSA, Azure ADThis value is included if the user is a guest in the tenant. For managed users (users within a tenant), this must be requested via this optional request or, in version 2.0 only, with an OpenID scope. This value is not guaranteed to be correct and changes over time; never use it to authorize or save data for a user. For more information, seeSecure applications and APIs through request validation. If you need an email address in your app, request that information directly from the user, using this statement as a hint or pre-populate your user experience.
forwardIP adressJWTAdds the source IPv4 address of the requesting client (when inside the virtual network).
groupsOptional format for group claimsJWT, SAMLHegroupsthe claim is used with the GroupMembershipClaims setting in theapplication manifest, which must also be configured.
ID TypeType tokenJWT access tokensSpecial: Only on App Only Access Tokensthe value isapplicationwhen the token is an app-only token. This assertion is the most accurate way for the API to determine if a token is an app token or an app+user token.
login_hintApplication TipsJWTMSA, Azure ADAn opaque and trusted login hint that is base64 encoded. Do not change this value. This statement is the best value to use forlogin_hintOAuth parameter on all flows to get SSO. It can also be passed between applications to help them with silent SSO: application A can log the user in, readlogin_hintrequest, and then send the request and current tenant context to App B in a query string or fragment when the user selects a link that leads to App B. To avoid race conditions and reliability issues,login_hintclaimIt does not workincludes the user's current tenant and uses the user's primary tenant by default. In the guest scenario where the user is from another tenant, the tenant ID must be provided in the login request. and forward the same to apps you partner with. This application is designed to be used with your existing SDKlogin_hintthe functionality, however, is exposed.
sidSession ID, used to log out users per sessionJWTPersonal and Azure AD accounts.
tenant_tryRegion/country of the resource tenantJWTLikeproofexcept that the administrator sets them at the tenant level. It must also be a standard two-letter value.
extension_of_tenant_regionResource Tenant RegionJWT
sangreUserPrincipalNameJWT, SAMLAn identifier for a user that can be used withUsernameparameter. It is not a permanent identifier for a user and should not be used to authorize or uniquely identify user information (for example, as a database key). Use the user object id instead (oid) as the database key. For more information, seeSecure applications and APIs through request validation. Users who log in withAlternate login IDit should not display your User Principal Name (UPN). Instead, use the following ID token requests to display login status to the user:preferred usernameounique namewaste tokens v1 ipreferred usernamefor v2 tokens. Although this request is included automatically, you can specify it as an optional request to attach other properties to modify guest behavior. you should uselogin_hintApplicationlogin_hintUsage: Human-readable identifiers, such as UPNs, are not trusted.
main_mail_verifiedOriginally from the user's primary authorized emailJWT
verified_secondary_mailOriginally from the user's secondary emailJWT
zealousVNET specifier information.JWT
xms_ccclient optionsJWTAzure ADIndicates whether the client application that acquired the token is capable of processing the challenge request. Utility applications (resource servers) can use this assertion to authorize access to protected resources. This assertion is typically used in continuous access and conditional access testing scenarios. The service application issuing the token controls the presence of requests on it. This optional requirement must be configured as part of the service application registration. For more information, seeClaim Challenges, Claim Requirements, and Client Opportunities.
xms_pdldesired data locationJWTFor Multi-Geo tenants, the preferred data location is a three-letter code that indicates the geographic region in which the user is located. For more information, seeAzure AD Connect documentation on preferred data location.
xms_plLanguage desired by the userJWTUser's preferred language, if set. Provided by the occupants of your home, in guest access scenarios. Formatted as LL-CC ("en-us").
xms_tplTenant preferred languageJWTThe preferred language of the resource's tenant, if set. Formatted as LL ("in").
ztdidContactless Deployment IDJWTThe identity of the device used toWindows Autopilot.


never useemailosangrerequested values ​​to store or determine if the user in the access token should have access to the data. Variable prompt values ​​like these can change over time, making them insecure and unreliable for authorization.

Set of optional requirements specific to v2.0

These claims are always included in v1.0 tokens, but are not included in v2.0 tokens unless requested. These statements only apply to JWTs (ID Tokens and Access Tokens).

(Video) How to set up authenticator on a new phone | Azure Active Directory

JWT RequestDoDescriptiongrades
ipaddrIP adressThe IP address from which the client logged in.
onprem_sidlocal security identifier
pwd_expPassword expiration timeNumber of seconds after the time uMe inthe request where the password expires. This assertion is only included when the password is about to expire (as defined by "days notice" in the password policy).
pwd_urlchange password urlThe URL that the user can visit to change their password. This assertion is only included when the password is about to expire (as defined by "days notice" in the password policy).
in_corpWithin the corporate networkIndicates whether the client is logging in from the corporate network. If they are not, the claim is not included.based ontrusted IP addressesconfiguration in MFA.
last nameLast nameProvides the user's last name, last name, or last name as defined in the user object. For example,"family_name": "Molinero".Compatible with MSA and Azure AD. requiresprofilerange.
First nameDoReturns the given or "given" name of the user, as set in the user object. For example,"given_name": "Franco".Compatible with MSA and Azure AD. requiresprofilerange.
sangrePrimary UsernameAn identifier for a user that can be used withUsernameparameter. It is not a permanent identifier for a user and should not be used to authorize or uniquely identify user information (for example, as a database key). For more information, seeSecure applications and APIs through request validation. Use the user object id instead (oid) as the database key. Users who log in withAlternate login IDit should not display your User Principal Name (UPN). Use the following insteadpreferred usernamea request to display the state of the application to the user.requireprofilerange.

Set of optional requirements specific to v1.0

Some of the enhancements to the v2 token format are available for applications that use the v1 token format because they help improve security and reliability. These enhancements only apply to JWTs, not SAML tokens.

JWT RequestDoDescriptiongrades
audAudienceAlways present in JWTs, but in v1 access tokens it can be issued in several ways: any App ID URI, with or without a trailing slash, and the client ID of the resource. This randomization can be hard to code when doing token validation. Wearadditional propertiesfor this assertion to ensure that it is always set to the client ID of the resource in access tokens v1.v1 only JWT access tokens
preferred usernamepreferred usernameAllows you to search for the desired username within the v1 token. This assertion makes it easy for apps to provide username suggestions and display human-readable display names, regardless of their token type. It is recommended that you use this optional declaration instead of using,sangreounique name.v1 ID tokens and access tokens

additional propertiesoptional requirements

Some optional requests can be configured to change the way the request is returned. theseadditional propertiesthey are primarily used to help migrate on-premises applications with different expected data. For example,include_externally_authenticated_upn_without_hashhelp with clients that cannot handle hash tags (#) at UPN.

property namebonus propertyDoDescription
sangreIt can be used for SAML and JWT responses, and for v1.0 and v2.0 tokens.
include_externally_authenticated_upnIncludes the guest's UPN stored in the resource tenant. For example,foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hashSame as above, except hash tags (#) are replaced by underscores (_), For examplefoo_hometenant.com_EXT_@resourcetenant.com.
audIn access tokens v1, this request is used to change the formataudsay. This assertion has no effect on v2 tokens or ID tokens of any version, where it isaudthe request is always the client ID. Use this setting to ensure that your API can more easily perform audience validation. Like all optional requests that affect an access token, the request resource must set this optional request, since the resource owns the access token.
use_guidReturns the resource's client ID (API) in GUID format asaudalways prompt instead of relying on the runtime. For example, if a resource sets this tag and its client ID isbb0a297b-6a42-4a55-ac40-09a501456577, any application that requires an access token for that resource receives an access token saud:bb0a297b-6a42-4a55-ac40-09a501456577. Without this set of requirements, the API could get tokens withaudApplicationapi://MiApi.com,api://MiApi.com/,api://myapi.com/AdditionalRegisteredFieldor any other value set as the URI of the application ID for that API and the ID of the resource client.

additional propertiesexample

"opciones": { "idToken": [ { "nombre": "upn", "essential": false, "additionalProperties": [ "include_externally_authenticated_upn" ] } ]}

Thisoptional claimsobject causes the ID token returned to the client to include asangreapplication with other tenants of the house and information about the tenants of the resource. Hesangrethe request is only changed in the token if the user is a guest in the tenant (using a different IDP for authentication).

Configure optional requirements


Access tokens areconstantlygenerated using the resource's manifest, not the client. on request...ámbito=https://graph.microsoft.com/user.read..., the resource is the Microsoft Graph API. The access token is created by the Microsoft Graph API manifest, not the client manifest. Changing your app's manifest will never make your Microsoft Graph API tokens look different. To confirm that it is yourstoken de accesochanges are in effect, request a token for your app, not another app.

You can configure optional requirements for your app through the Azure portal or the app manifest.

  1. to live inportal azure.
  2. search and chooseAzure Active Directory.
  3. under, undergovern, Chooseapplication logs.
  4. Select the application for which you want to configure optional requirements based on your scenario and desired outcome.
  5. under, undergovern, ChooseTab Settings.
    • user interface optionTab Settingsblade is not available for applications registered in the Azure AD B2C tenant, which can be configured by modifying the application manifest. For more information, seeAdd requirements and customize user input using custom rules in Azure Active Directory B2C

Configure the requirements using the manifest:

  1. chooseAdd an optional request.

  2. Select the type of token you want to set up.

  3. Select the optional declarations you want to add.

  4. chooseTo add.

  5. under, undergovern, ChooseManifest. The web manifest editor opens, allowing you to edit the manifest. If you want, you can choosedownload filesand edit the manifest locally and then useload it upto reapply it to your app.

    The following application manifest entry addsauthorization_time,ipaddr, isangreoptional SAML ID, access, and token claims.

    (Video) Custom Claims in Azure Active Directory | Claims Mapping Policy

    "opcionalClaims": { "idToken": [ { "nombre": "auth_time", "essential": false } ], "accessToken": [ { "name": "ipaddr", "essential": false } ], " saml2Token": [ { "name": "upn", "essential": false }, { "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId", "source": "user", "essential": false } ]}
  6. When you are done, selectSave. Now the specified optional requirements are included in the tokens for your application.

Heoriginal claimsThe object declares optional requirements required by the application. The application can configure optional requests that are returned in ID tokens, access tokens, and SAML 2 tokens. An application can configure a different set of optional requests that are returned in each type of token.

idtokenCollectionOptional requests returned in the JWT ID token.
token de accesoCollectionOptional requests returned in JWT access token.
saml2tokenCollectionOptional claims returned in the SAML token.

If it supports a specific request, you can also modify the behavior of an optional request by usingadditional propertiescampo.

DoEdm.CadenaThe name of the optional request.
fuenteEdm.CadenaThe source (directory object) of the request. There are predefined requirements and user-defined requirements of the extension properties. If the original value is zero, the prompt is a predefined optional prompt. If the original value is user, the value of the name property is the extension property of the user object.
importantEdm.BooleanoIf the value is true, the client-specified assertion is required to ensure a smooth authorization experience for the specific task required by the end user. The default is false.
additional propertiesZbirka (Edm.String)Other properties of the application. If the property exists in this collection, it modifies the behavior of the optional prompt specified in the name property.

Configuring optional directory extension claims

In addition to the standard optional set of requirements, you can also configure tokens to include Microsoft Graph extensions. For more information, seeAdd custom data to resources using extensions.

Optional requests support directory extension and extension attributes. This feature is useful for attaching more user data that your app can use. For example, other important identifiers or configuration options set by the user. If your app's manifest requires a custom extension and an MSA user signs in to your app, those extensions will not be returned.

Format directory extensions

When configuring optional directory extension claims via the application manifest, use the full name of the extension (in the format:extension__). Heis the simplified version of the appId (or client ID) of the requesting application.

Within a JWT, these assertions are issued in the following name format:ext.. Within the SAML token, these assertions are issued in the following URI format:http://schemas.microsoft.com/identity/claims/extn.

Configure groups according to your requirements

This section covers configuration options in optional requests to change the group attributes used in group requests from the default group object ID to attributes synchronized from the local Windows Active Directory. You can configure optional bulk requests for your app through the Azure portal or the app manifest. Group subscription requests are only issued in the JWT for user principals. Service principals are not included in group election requests transmitted in the JWT.


The number of groups issued in a token is limited to 150 for SAML assertions and 200 for JWT, including nested groups. For more information about group restrictions and important caveats for local attribute group requests, seeSet up bulk claims for apps with Azure AD.

Complete the following steps to configure optional group requests using the Azure portal:

  1. register atportal azure.
  2. Once you've authenticated, select your tenant by selecting in the top right corner of the page.
  3. search and chooseAzure Active Directory.
  4. under, undergovern, Chooseapplication logs.
  5. From the list, select the app for which you want to set optional notifications.
  6. under, undergovern, ChooseTab Settings.
  7. chooseAdd a group request.
  8. Select the types of groups you want to restore (security groups, osubstantive roles,All the groups, IGroups assigned to the application):
    • HeGroups assigned to the applicationThe option only includes groups assigned to the application. HeGroups assigned to the applicationThis option is recommended for large organizations due to the limit on the number of groups in the token. To change the groups assigned to an application, select an application frombusiness applicationsa list. chooseUsers and groupsand thenAdd user/group. Select the groups you want to add to the appUsers and groups.
    • HeAll the groupsoption includessecurity group,Directory Role, iDistribution list, but notGroups assigned to the application.
  9. Optional: Select specific token type properties to change the value of a group request to contain group attributes on-premises or to change the request type to a role.
  10. chooseSave.

Complete the following steps to configure optional group requests through the application manifest:

  1. register atportal azure.

    (Video) How to fix "This sign-in option is disabled" on windows 10/11

  2. Once you've authenticated, select your Azure AD tenant by selecting it in the top right corner of the page.

  3. search and chooseAzure Active Directory.

  4. From the list, select the app for which you want to set optional notifications.

  5. under, undergovern, ChooseManifest.

  6. Add the following entry using the manifest editor:

    Valid values ​​are:

    • "Everyone" (this option includes SecurityGroup, DirectoryRole, and DistributionList)
    • "Security Group"
    • "directory role"
    • "ApplicationGroup" (this option only includes groups assigned to the application)

    For example:

    "groupMembershipClaims": "Sigurnosna grupa"

    By default, group object IDs are emitted in the group request value. To change the prompt value to contain local group attributes or to change the prompt type to a role, useoptional claimsconfiguration as follows:

  7. Optional group name configuration claims.

    If you want the groups in the token to contain local group attributes in the optional section of the request, specify which type of token the optional request should apply to. It also specifies the name of the required optional prompt and any other desired properties.

    Several types of tokens can be specified:

    • idToken for OIDC ID token
    • accessToken for the OAuth access token
    • Saml2Token is a token SAML.

    The Saml2Token type applies to SAML1.1 and SAML2.0 format tokens.

    For each relevant token type, modify the usage pool requirementsoptional claimssection in the manifest. Heoptional claimsthe scheme is as follows:

    { "name": "groups", "source": null, "essential": false, "additional properties": []}
    Optional application schemeValor
    Domust begroups
    fuenteIt has not been used. Omit or specify null.
    importantIt has not been used. Omit or specify false.
    additional propertiesList of other properties. Valid options aresam_account_name,dns_domain_and_sam_account_name,netbios_domain_and_sam_account_name,broadcast_as_rolesicloud_displayname.

    tuadditional propertiesjust one ofsam_account_name,dns_domain_and_sam_account_name,netbios_domain_and_sam_account_nameAre needed. If there is more than one, the first one is used and the others are ignored. You can also addcloud_displaynameto pass the display name of the cloud group. This option only works whenGroup MembershipClaimsis set toapplication group.

    (Video) Azure Portal App registration improvements

    Some apps require group information about the user in the feature request. To change the request type from a group request to a feature request, addbroadcast_as_rolesdoadditional properties. Group values ​​are passed in the role request.

    Ibroadcast_as_rolesuses, all configured application roles assigned to the user are not in the role request.

The following examples show the manifest configuration for group claims:

Issue groups as group names in OAuth access tokensdnsDomainName\sAMAaccountNameFormat.

"opcionalClaims": { "accessToken": [ { "name": "groups", "additionalProperties": [ "dns_domain_and_sam_account_name" ] } ]}

Emits the names of the return groups.netbiosDomena\sAMAcuentaNombreformat as required by roles in SAML and OIDC ID tokens.

"optionals": { "saml2Token": [ { "name": "groups", "additional properties": [ "netbios_domain_and_sam_account_name", "emit_as_roles" ] } ], "idToken": [ { "name": "groups", " extraProperties": [ "netbios_domain_and_sam_account_name", "emit_as_roles" ] } ]}

Outputs group names in the format ofsam_account_namefor synchronized groups on site icloud_viewname for cloud groups in SAML and OIDC ID tokens for groups assigned to the application.

"groupMembershipClaims": "ApplicationGroup","OptionalClaims": { "saml2Token": [ { "name": "groups", "additionalProperties": [ "sam_account_name", "cloud_displayname" ] } ], "idToken": [ { " nombre": "grupos", "propiedades adicionales": [ "sam_account_name", "cloud_displayname" ] } ]}

optional example statement

There are several options available to update the application's identity configuration properties to enable and configure optional notifications:

  • You can use the Azure portal
  • You can use the manifest.
  • It is also possible to write an application that usesMicrosoft Graphics APIto update your app. Heoptional claimstype The Microsoft Graph API Reference Guide can help you configure optional requests.

In the following example, the Azure portal and manifest are used to add optional access requests, SAML identifiers, and tokens for your application. Different optional requirements are added to each type of token an application can receive:

  • ID tokens contain the UPN for federated users in full (_#EXT#@).
  • Access tokens that other clients request for this application includeauthorization_timeclaim.
  • SAML tokens containskype iddirectory schema extension (in this example, the application ID for this application isab603c56068041afb2f6832e2a17e237). The SAML token exposes the Skype ID asextension_ab603c56068041afb2f6832e2a17e237_skypeId.

Configure the requests in the Azure portal:

  1. register atportal azure.
  2. Once you've authenticated, select your tenant by selecting in the top right corner of the page.
  3. search and chooseAzure Active Directory.
  4. under, undergovern, Chooseapplication logs.
  5. In the list, find the app you want to set optional notifications for, and select it.
  6. under, undergovern, ChooseTab Settings.
  7. chooseAdd an optional request, selectID cardtab type, selectsangrefrom the request list, then selectTo add.
  8. chooseAdd an optional request, selectaccesstab type, selectauthorization_timefrom the request list, then selectTo add.
  9. On the token configuration preview screen, select the pencil icon next to itsangre, selectexternal certificationchange, then selectSave.
  10. chooseAdd an optional request, selectSAMLtab type, selectextn.skypeIDfrom the request list (applicable only if you have created an Azure AD user object called skypeID), then selectTo add.

Configure the requirements in the manifest:

  1. register atportal azure.

  2. Once you've authenticated, select your tenant by selecting in the top right corner of the page.

  3. search and chooseAzure Active Directory.

  4. In the list, find the app you want to set optional notifications for, and select it.

    (Video) Your Account Has Been Disabled, Please See Your System Administrator In Windows 10 FIX [Tutorial]

  5. under, undergovern, ChooseManifestto open the built-in manifest editor.

  6. You can directly edit the manifest using this editor. The manifesto follows the outline ofapplication entityand automatically formats the manifest after saving. New elements have been added.optional claimsproperty.

    "options": { "idToken": [ { "name": "upn", "essential": false, "additionalProperties": [ "include_externally_authenticated_upn" ] } ], "accessToken": [ { "name": "auth_time" , "essential": false } ], "saml2Token": [ { "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId", "source": "user", "essential": true } ]}
  7. When you're done updating the manifest, selectSaveto save the manifest.

See also

  • application manifest
  • Stock ID
  • access tokens

Next steps

  • learn more abouttokens and claimson the Microsoft identity platform.


1. Fix Windows 11 Login Problems : This Sign-in Option is Disabled Because of Failed Sign-in Attempts
2. Copilot AI updates across the Power Platform | Automate, apps, pages & virtual agents
(Microsoft Mechanics)
3. How to use Windows Sandbox - a lightweight virtual machine
(Kevin Stratvert)
4. Using Personal Access Tokens with GIT and GitHub
(Ed Goad)
5. How to open the BIOS on your HP computer | @HPSupport #shorts
(HP Support)
6. Word: Track Changes and Comments


Top Articles
Latest Posts
Article information

Author: Maia Crooks Jr

Last Updated: 12/07/2023

Views: 5605

Rating: 4.2 / 5 (43 voted)

Reviews: 90% of readers found this page helpful

Author information

Name: Maia Crooks Jr

Birthday: 1997-09-21

Address: 93119 Joseph Street, Peggyfurt, NC 11582

Phone: +2983088926881

Job: Principal Design Liaison

Hobby: Web surfing, Skiing, role-playing games, Sketching, Polo, Sewing, Genealogy

Introduction: My name is Maia Crooks Jr, I am a homely, joyous, shiny, successful, hilarious, thoughtful, joyous person who loves writing and wants to share my knowledge and understanding with you.