Specify optional requirements for your app - Microsoft Entra (2023)

You can use optional requirements to:

• Select requirements to include in the tokens for your application.
• Change the behavior of certain assertions that the Microsoft identity platform returns in tokens.
• Add and access custom requirements for your application.

For lists of standard requirements, seeaccess tokenAndid_tokendamage documentation.

While optional claims are supported in both v1.0 and v2.0 format tokens and SAML tokens, they provide most of their value in the v1.0 to v2.0 transition. Smaller token sizes are used in the Microsoft identity platform to ensure optimal client performance. As a result, several requirements previously contained in access and ID tokens are no longer present in v2.0 tokens and must be requested specifically by application.

v1.0 and v2.0 optional requirement set

The optional requirements available by default for applications are listed in the table below. You can use custom data in extension attributes and library extensions to add optional requirements to your application. If you add requirements to the access token, the requirements apply to the requested access tokensTothe application (a web API), no solicited claimsvonthe application. Regardless of how the client accesses your API, the correct data is contained in the access token used to authenticate against your API.

The following table shows the v1.0 and v2.0 optional requirement set.

v2.0 specific optional requirement set

These requirements are always included in v1.0 tokens, but not in v2.0 tokens unless requested. These requirements only apply to JWTs (ID tokens and access tokens).

v1.0 specific optional requirement set

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

additional propertiesof optional requirements

Some optional claims can be configured to change how the claim is returned. Thisadditional propertiesMainly used to support migration of on-premises applications with different data expectations. E.g.include_externally_authenticated_upn_without_hashhelps with clients that can't handle hash tags (#) i UPN.

additional propertiesExample

„optionalClaims“: { „idToken“: [ { „name“: „upn“, „essential“: false, „additionalProperties“: [ „include_externally_authenticated_upn“ ] } ]}

This oneoptional requirementsThe object causes the ID token returned to the client to contain aupnRequirements with the other apartment tenants and resource tenant information. TheupnThe claim only changes in the token if the user is a guest in the tenant (and uses a different IDP to authenticate).

Configure optional requirements

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

1. Go toAzure-Portal.
2. Search and selectAzure Active Directory.
3. Undercontrol, ChooseApp Registrations.
4. Select the application for which you want to configure optional requirements based on your scenario and desired outcome.
5. Undercontrol, Choosetoken configuration.
   • The UI settingtoken configurationBlade is not available for apps registered in an Azure AD B2C tenant. This can be configured by changing the application manifest. For more information, seeAdd requirements and customize user input using custom policies in Azure Active Directory B2C

Configure requirements using the manifest:

1. chooseAdd optional requirement.

2. Select the token type you want to configure.

3. Select the optional requirements to add.

4. chooseAdd to.

5. Undercontrol, ChooseManifest. A web-based manifest editor will open where you can edit the manifest. You can choose optionalPick upand edit the manifest locally and then use ituploadto reuse it in your application.

   The following application manifest entry addsauth_time,ipaddr, Andupnoptional requirements for ID, access, and SAML tokens.

   (Video) Introduction to Azure AD Custom claims providers (part one)

   „optionalClaims“: { „idToken“: [ { „name“: „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're done, selectSave. Now the specified optional requirements are included in the tokens for your application.

Theoptional requirementsThe object declares the optional requirements requested by an application. An application can configure optional claims that are returned in ID tokens, access tokens, and SAML 2 tokens. The application can configure a different set of optional claims to be returned in each token type.

If supported by a specific requirement, you can also change the behavior of the optional requirementadditional propertiesTo mark.

Configure optional library expansion requests

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

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

Format folder extension

When configuring optional address extension requests using the application manifest, use the full name of the extension (in the format:Extension___). Theis the stripped-down version of the appid (or clientid) of the application making the claim.

Within the JWT, these claims are issued with the following naming format:extn.. Within the SAML tokens, these claims are issued using the following URI format:http://schemas.microsoft.com/identity/claims/extn.

Configure groups of optional requirements

This section covers the configuration options under Optional Claims to change the group attributes used in group claims from the default group object ID to attributes synchronized from local Windows Active Directory. You can configure groups of optional requirements for your application through the Azure portal or the application manifest. Optional group claims are only issued in the JWT for user policies. Service principals are not included in optional group claims issued in JWT.

To configure groups of optional requirements using the Azure portal, complete the following steps:

1. login inAzure-Portal.
2. Once approved, choose your tenant by selecting them in the top right corner of the page.
3. Search and selectAzure Active Directory.
4. Undercontrol, ChooseApp Registrations.
5. From the list, select the program for which you want to configure optional requirements.
6. Undercontrol, Choosetoken configuration.
7. chooseAdd requirement groups.
8. Select the group types to return (security groups, ordirectory role,All groupsand orGroups assigned to the application):
   • TheGroups assigned to the applicationThe setting includes only groups assigned to the application. TheGroups assigned to the applicationThis option is recommended for large organizations due to the group count limitation in the token. To change the groups assigned to the application, disable the applicationbusiness applicationsList. chooseUsers and Groupsand thenAdd user/group. Select the group(s) you want to add to the applicationUsers and Groups.
   • TheAll groupsoption includedsecurity group,directory role, Anddistribution list, but notGroups assigned to the application.
9. Optional: Select the specific token type properties to change the group claim value to include local group attributes or to change the claim type to a role.
10. chooseSave.

To configure groups of optional requirements through the application manifest, complete the following steps:

1. login inAzure-Portal.

   (Video) How to Use Optional Parameters in Microsoft Access VBA

2. Once approved, choose your Azure AD tenant by selecting it in the top right corner of the page.

3. Search and selectAzure Active Directory.

4. From the list, select the program for which you want to configure optional requirements.

5. Undercontrol, ChooseManifest.

6. Using the manifest editor, add the following entry:

   The valid values ​​are:

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

   For example:

   "groupMembershipClaims": "Security Group"

   By default, group object IDs are emitted in the group claim value. To change the claim value to include local group attributes or to change the claim type to role, useoptional requirementsConfiguration as follows:

7. Set optional group name configuration requirements.

   If you want groups in the token to include the local group attributes in the optional claim section, specify which token type the optional claim should apply to. You also specify the name of the optional requirement and any other desired properties.

   Multiple token types can be specified:

   • idToken for the OIDC ID token
   • accessToken for OAuth accesstokenet
   • Saml2Token to SAML tokens.

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

   For each relevant token type, change the groups that claim usageoptional requirementssection of the manifest. Theoptional requirementsThe schedule is as follows:

   { „name“: „groups“, „source“: null, „essential“: false, „additionalProperties“: []}

   Optional application form	Wert
   Name	Must beThe group
   Those	Not in use. Omit it or enter null.
   important	Not in use. Omit it or set it to false.
   additional properties	List of additional properties. Valid options aresame_account_name,dns_domain_and_sam_account_name,netbios_domain_and_sam_account_name,Broadcast_as_rolesAndcloud_displayname.

   Iadditional propertiesjust one ofsame_account_name,dns_domain_and_sam_account_name,netbios_domain_and_sam_account_namenecessary. If there is more than one, the first one is used and all others are ignored. You can also addcloud_displaynameto transfer the display name of the cloud group. This option only works ifRequirements for Group Membershipis set toapplication group.

   (Video) Asp.Net Core Web Application Azure Active Directory (Azure AD) Authentication

   Some applications require group information about the user in the role request. To change the claim type from a group claim to a role claim, addBroadcast_as_rolesToadditional properties. The group values ​​are output in the role claim.

   IfBroadcast_as_rolesis used, any configured application roles assigned to the user are not included in the role request.

The following examples show the manifest configuration for group claims:

Pass groups as group names in OAuth access tokens idnsDomainName\sAMAccountNameFormat.

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

Pass group name to returnnetbiosDomæne\sAMAccountNameFormat claimed by the roles in SAML and OIDC identity tokens.

„optionalClaims“: { „saml2Token“: [ { „name“: „groups“, „additionalProperties“: [ „netbios_domain_and_sam_account_name“, „emit_as_roles“ ] } ], „idToken“: [ { „name“: „groups“, „ „additionalProperties“: [ „netbios_domain_and_sam_account_name“, „emit_as_roles“ ] } ]}

Send group names in the formatsame_account_namefor locally synced groups andcloud_displayCloud group name in SAML and OIDC ID tokens for the groups assigned to the application.

„groupMembershipClaims“: „ApplicationGroup“, „optionalClaims“: { „saml2Token“: [ { „name“: „groups“, „additionalProperties“: [ „sam_account_name“, „cloud_displayname“ ] } ], „idToken“: [ { „ name": "groups", "additionalProperties": [ "sam_account_name", "cloud_displayname" ] } ]}

Example of optional requirements

There are several options for updating an application's identity configuration properties to enable and configure optional requirements:

• You can use the Azure portal
• You can use the manifest.
• It is also possible to write an application that usesMicrosoft Graph-APIto update your application. TheOptional RequirementsWriting in the Microsoft Graph API Reference Guide can help you configure the optional requirements.

The following example uses the Azure portal and Azure Manifest to add optional requests for access, identity, and SAML tokens specific to your application. Various optional requirements are added for each token type that the application can receive:

• The ID tokens contain the federated user's UPN in its full form (_#EXT#@).
• Access tokens that other clients request for this application include:auth_timeClaim.
• The SAML tokens includedSkype IDLibrary schema extension (in this example, the app ID for this app).ab603c56068041afb2f6832e2a17e237). The SAML token exposes the Skype IDextension_ab603c56068041afb2f6832e2a17e237_skypeId.

Configure requests in the Azure portal:

1. login inAzure-Portal.
2. Once approved, choose your tenant by selecting them in the top right corner of the page.
3. Search and selectAzure Active Directory.
4. Undercontrol, ChooseApp Registrations.
5. From the list, locate and select the program for which you want to configure optional requirements.
6. Undercontrol, Choosetoken configuration.
7. chooseAdd optional requirement, chooseIDSelect token typeupnfrom the list of requirements, and then selectAdd to.
8. chooseAdd optional requirement, chooseAccessSelect token typeauth_timefrom the list of requirements, and then selectAdd to.
9. From the Token Configuration overview screen, select the pencil icon next to itupn, chooseApproved from outsidetoggle and then selectSave.
10. chooseAdd optional requirement, chooseSAMLSelect token typeextn.skypeIDfrom the list of requirements (relevant only if you have created an Azure AD user object named skypeID) and then selectAdd to.

Configure requirements in the manifest:

1. login inAzure-Portal.

2. Once approved, choose your tenant by selecting them in the top right corner of the page.

3. Search and selectAzure Active Directory.

4. From the list, locate and select the program for which you want to configure optional requirements.

   (Video) Azure AD Temporary Access Pass

5. Undercontrol, ChooseManifestto open the inline manifest editor.

6. With this editor you can edit the manifest directly. The manifest follows the timetable forapplication unitand automatically formats the manifest when saving. New items are addedoptional requirementsProperty.

   „optionalClaims“: { „idToken“: [ { „name“: „upn“, „essential“: false, „additionalProperties“: [ „include_externally_authenticated_upn“ ] } ], „accessToken“: [ { „name“: „auth_time“ , „essential“: false } ], „saml2Token“: [ { „name“: „extension_ab603c56068041afb2f6832e2a17e237_skypeId“, „source“: „bruger“, „essential“: true } ]}

7. After you finish updating the manifest, selectSaveto save the manifest.

See also

• application manifest
• ID-Token
• access token

Next Step

• learn more aboutTokens and Claimsin Microsoft's identity platform.