Application developers can use optional claims in their Azure AD applications to specify which claims they want in tokens sent to their application. While optional claims are supported in both v1. One of the goals of the v2.
As a result, several claims formerly included in the access and ID tokens are no longer present in v2. The set of optional claims available by default for applications to use are listed below. To add custom optional claims for your application, see Directory Extensionsbelow.
When adding claims to the access tokenthe claims apply to access tokens requested for the application a web APInot claims requested by the application.
No matter how the client accesses your API, the right data is present in the access token that is used to authenticate against your API. The majority of these claims can be included in JWTs for v1. Consumer accounts support a subset of these claims, marked in the "User Type" column. These claims are always included in v1. Some optional claims can be configured to change the way the claim is returned.
This OptionalClaims object causes the ID token returned to the client to include a upn claim with the additional home tenant and resource tenant information. The upn claim is only changed in the token if the user is a guest in the tenant that uses a different IDP for authentication. Access tokens are always generated using the manifest of the resource, not the client.
So in the request Changing the manifest for your application will never cause tokens for the Microsoft Graph API to look different. In order to validate that your accessToken changes are in effect, request a token for your application, not another app.
From the Manage section, select Manifest. A web-based manifest editor opens, allowing you to edit the manifest. Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application. For more information on the application manifest, see the Understanding the Azure AD application manifest article. When finished, click Save.
Now the specified optional claims will be included in the tokens for your application. Declares the optional claims requested by an application. An application can configure optional claims to be returned in each of three types of tokens ID token, access token, SAML 2 token it can receive from the security token service. The application can configure a different set of optional claims to be returned in each token type. Contains an optional claim associated with an application or a service principal.
If supported by a specific claim, you can also modify the behavior of the OptionalClaim using the AdditionalProperties field. In addition to the standard optional claims set, you can also configure tokens to include extensions. For more info, see the Microsoft Graph extensionProperty documentation - note that schema and open extensions are not supported by optional claims, only the AAD-Graph style directory extensions.
This feature is useful for attaching additional user information that your app can use — for example, an additional identifier or important configuration option that the user has set. See the bottom of this page for an example.Azure Active Directory - Microsoft Azure Tutorial for Beginners - Azure 70-533 Training - Edureka
Within the JWT, these claims will be emitted with the following name format: extn. This section covers the configuration options under optional claims for changing the group attributes used in group claims from the default group objectID to attributes synced from on-premises Windows Active Directory.Apps are often said to be claims-aware, or claims-based, and often not much more explanation is given.
But what does this mean? The short answer is that claims are in most cases the same as an attribute or property of the user object. For instance the user Bob could have a claim with the name "email" and the value "bob contoso. The way the claim is a part of the user object depends on the type of solution you are working on. If you are creating a line of business app which will run in an on-prem environment in close proximity to a farm of domain controllers maybe you don't use claims as part of the login process.
Maybe you perform authentication to authorize the user, but whenever you need to know something about the user you make a direct query against Active Directory. If you were to sign in to your mobile operator's end-user portal however you probably would not be in their Active Directory, and the phone number is possibly stored in the token you receive upon signing in. You should restrict yourself to key pieces of info needed directly in the app, or attributes commonly used for enabling other lookups.
An example of using claims for looking up other info would be the example of the mobile operator login. You as a user consider the phone number to be the identifier, but the mobile operator might not use that as an identifier because there are multiple levels in the hierarchy that you don't see.
This could be how a phone number might have one user as the end-user, whereas a different entity user or company might be the legal owner of the subscription. And a subscription might have more than one phone number in case you have a separate sim card for data traffic on a tablet. This means that there could very well be a chance they are using an id that means nothing to you, but would be very relevant for the web app to have knowledge of.
So behind the scenes that id is stored in a claim. Note that this identifier is not something kept secret from you, there's just no intrinsic value for you to be aware of it. Or take a video streaming app that works in multiple countries. When you sign up your country is returned in a claim, so that when you initiate streaming the app contacts servers specific for that country. This is a hypothetical use case; this is not how a global streaming company would do it - Content Delivery Networks are more likely to be involved to solve this in a good manner.
In an enterprise setup were everything is running in the same datacenter, and everything is behind the same firewall, and controlled by the same people one could argue that it's not as important.
The developer might be able to solve the use case with or without the use of claims. When you start developing apps that work across multiple tenants, and possible federating with other identity providers, things get more complicated. Let's say you have a web app that offers login through Facebook. It's perfectly valid to not implement a user management system of your own, and rely on third-parties, but it would still be required to know something about the user.
For instance the web app could use johndoe facebook. Facebook would certainly have both your given name and surname stored in their records. But they wouldn't allow other apps than their own to tap directly into that database. This is solved by adding claims to your token when logging in. The web app can then use these properties without ever having access to your entire Facebook profile.When using Azure Active Directory for managing your users, it is a common requirement to add additional attributes to your Users like SkypeId, employee code, EmployeeId and similar.
Even though this happens to be a common need, getting this done is not that straightforward. This post describes how you can get additional properties on User objects in Azure AD.
Recently when I had to do this at a client, we had users in Azure AD, the additional property, employeeCode for the user was available in an internal application which had the users Azure email-address mapped to it. We needed these to be synced across to the user Azure AD and make it available as part of claims for a Web site that uses Azure AD authentication.
Azure AD user has a set of default propertiesmanageable through the Azure Portal. Any additional property to User gets added as an extension to the current user Schema. To add a new property we first need to register an extension.
Adding a new extension can be done using the GraphExplorer website. You need to specify the appropriate directory name e. Azure AD supports a similar type of extension, known as directory schema extensions, on a few directory object resources.
Although you have to use the Azure AD Graph API to create and manage the definitions of directory schema extensions, you can use the Microsoft Graph API to add, get, update and delete data in the properties of these extensions.
AAD from A to Z
The response gives back the fully-qualified extension property name, which is used to write values to the property. If you have multiple environments like Dev, Test, UAT, Prod all pointing to the same Active Directory, it is a good idea to append the environment name to the extension property.
It avoids any bad data issues between environments as all these properties get written to the same User object. You can automate the above step using any scripting language of your choice if required. Now that we have the extension property created on the AD application, we can set the property on the User object. If you want to set this manually, you can use the GraphExplorer website again to do this.
In our case it was not a one-off case of updating the User object, so better wanted this to be automated. Employee codes were available from a database with the associated Azure AD email address. So we created a windows service job that would sync these codes to Azure AD. Add a reference to the Microsoft Graph NuGet packageand you are all set to go. For the Graph API to authenticate, use a different Azure AD app separate to the one that you registered the extension property on, which the web app uses to authenticatejust because it needs additional permissions as well and it is a good idea to isolate that.
Looping through all the employee codes, you can update all of them into Azure AD at regular intervals. To verify that the attributes are updated correctly, you can either use the Graph API client to read the extension property or use the Graph Explorer Website.
With the Azure AD updated with the employee code for each user, we can now set up the AD application to return the additional property as part of the claims, when the web application authenticates with it. The application manifest of the Azure AD application needs to be modified to return the extension property as part of the claims. By default optionalClaims property is set to null and you can update it with the below values.
I updated the idToken property as the.And then, the application validates and uses the token to log the user in instead of prompting for a username and password. These SAML tokens contain pieces of information about the user known as claims. A claim is information that an identity provider states about a user inside the token they issue for that user. To view or edit the claims issued in the SAML token to the application, open the application in Azure portal.
Select the attribute or transformation you want to apply to the attribute. Optionally, you can specify the format you want the NameID claim to have. If no format is specified Azure AD will use the default source format associated with the claim source selected.
From the Choose name identifier format dropdown, you can select one of the following options. Transient NameID is also supported, but is not available in the dropdown and cannot be configured on Azure's side.
You can select from the following options. For more info, see Table 3: Valid ID values per source. You can also assign any constant static value to any claims which you define in Azure AD.
Please follow the below steps to assign a constant value:. Enter the constant value without quotes in the Source attribute as per your organization and click Save. In Manage claimselect Transformation as the claim source to open the Manage transformation page. Select the function from the transformation dropdown. Depending on the function selected, you will have to provide parameters and a constant value to evaluate in the transformation. Refer to the table below for more information about the available functions.
To apply multiple transformation, click on Add transformation. You can apply a maximum of two transformation to a claim. For example, you could first extract the email prefix of the user.
Then, make the string upper case. If you need additional transformations, submit your idea in the feedback forum in Azure AD under the SaaS application category. You can specify the source of a claim based on user type and the group to which the user belongs. One scenario where this is helpful is when the source of a claim is different for a guest and an employee accessing an application. You may want to specify that if the user is an employee the NameID is sourced from user. The order in which you add the conditions are important.
Azure AD evaluates the conditions from top to bottom to decide which value to emit in the claim. For example, Brita Simon is a guest user in the Contoso tenant.
She belongs to another organization that also uses Azure AD. Given the below configuration for the Fabrikam application, when Brita tries to sign in to Fabrikam, Azure AD will evaluate the conditions as follow.
Since, this is true then Azure AD assigns the source for the claim to user. Finally, the claim is emitted with value user. You may also leave feedback directly on GitHub.
Skip to main content. Exit focus mode. There are two possible reasons why you might need to edit the claims issued in the SAML token: The application requires the NameIdentifier or NameID claim to be something other than the username or user principal name stored in Azure AD.
The application has been written to require a different set of claim URIs or claim values. Click on the required claim which you want to modify. The constant value will be displayed as below.When we are using Azure Active Directory, we need to add extra information related to the user in the token that we received once that we get an authenticated user in our app. What about if we need to add extra information like the country or any additional data related with the user, in the case of the country we can add it as an optional claim modifying the App Registration manifest in the Azure AD like in the following code snippet:.
As you can see you can add the country and the tenant country in the manifest as optional claims, all the optional claims available are described in the Microsoft Documentation :. But what if we need to get the office or any other data that we are able to register in the new user form, directly in the Azure Active Directory Portal? That is not feasible adding an optional Claim!
The alternative is to add claims as mapped claims in the service principal in the Azure Active Directory Tenant. To achieve this, we need to enable the AcceptMappedClaims to true in the App Registration Manifest as we can see in the following image:.
Then we need to execute a series of commands in PowerShell to apply our claim mapped policy to our service principal and we can see the office claim in our token. With our App Id we need to identify the service principal related with our App Registration, to do that we need to execute the following commands:. Now we procced to create an Azure AD policy where we will add 2 mapped claims the user office and the country and we specify a name in this case we will name it UseClaimsExample3 with the following command:.
Once that we have the new policy and the service principal, we need to associate them with the following command:. We will get the claims in our code; we can see that we are ready to consume the information directly from the claims. Log in to join the discussion. Thanks for the post, it was helpful.
Subscribe to RSS
Learn more. June 9th, Premier Support for Developers Follow. Read next DevOps and Your Definition of Done DevOps, among other things, is about collaboration, and a shared responsibility for delivering features into production.
Your Definition of Done should reflect this. Learn why and how you should explicitly define Done to improve collaboration and quality. Premier Developer June 10, Premier Developer June 11, Designed for a single domain or multiple domains. If any of the information is wrong, it will affect user login.
Just make sure that the Azure AD relying party trust is already in place. It will automatically update the claim rules for you based on your tenant information. However, if you are not using it to manage your trust, proceed below to generate the same set of claims as AAD Connect. Click here to learn more about Azure AD Connect with federation. If you only have one federated Azure AD domain for example contoso.
If the claim rules are not updated prior to making the domain change, all users will be unable to sign-in. In order to generate the right set of claims for your organization, we will need to ask you a few questions about your AAD Connect configuration. Select how users should be uniquely identified with Azure AD. The Immutable ID attribute is defined as an attribute that is immutable during the lifetime of an object.
It uniquely identifies an object as being the same object on-premises and in Azure AD, and is the primary key linking on-premises users with users in Azure AD. Click here to learn more about Immutable ID attributes. Select the attribute that users will use to sign into Azure AD. This will be what users type in for their username during login. However, the administrator may have selected an Alternate ID such as email. Enter in the configuration used with AAD Connect.
Issuer Id Claim RegEx. For federating multiple domain, this is the regex that can be used to set correct IssuerId claim. The regex was developed using the domain information you provided. The script will also make a backup of the current claim rules for safe keeping. In order to create the right set of claims, we need more information about your Azure AD domains.
You can upload the information in a CSV file recommendedor provide the information yourself. To get the domain information directly from your Azure AD tenant, perform the following steps:. Copy and run the following code snippet. This will generate the CSV file based on your tenant information. Manually enter in any Azure AD information below.
Learn more. AD FS Help.
Previous Next. Yes No. Previous Next Generate Claims.Azure Active Directory can provide a users group membership information in tokens for use within applications.
Two main patterns are supported:. Many applications configured to authenticate with AD FS rely on group membership information in the form of Windows AD group attributes. An app that has been moved from AD FS needs claims in the same format.
They aren't available on groups created in Azure Active Directory or Office Applications configured in Azure Active Directory to get synced on-premises group attributes get them for synced groups only. Applications can call the MS Graph groups endpoint to obtain group information for the authenticated user. This call ensures that all the groups a user is a member of are available even when there are a large number of groups involved.
Group enumeration is then independent of token size limitations. However, if an existing application expects to consume group information via claims, Azure Active Directory can be configured with a number of different claims formats. Consider the following options:.
How to: customize claims issued in the SAML token for enterprise applications
Group membership claims can be emitted in tokens for any group if you use the ObjectId format. Synchronize group names from Active Directory Before Azure Active Directory can emit the group names or on premises group SID in group or role claims, the required attributes need to be synchronized from Active Directory. You must be running Azure AD Connect version 1. Earlier versions of Azure AD Connect than 1. Upgrade to the current version.
Configure the application registration in Azure Active Directory to include group claims in tokens Group claims can be configured in the Enterprise Applications section of the portal, or using the Application Manifest in the Application Registrations section. Only groups synchronized from Active Directory will be included in the claims.
To emit only groups assigned to the application, select Groups Assigned to the application. Groups assigned to the application will be included in the token. Other groups the user is a member of will be omitted. With this option nested groups are not included and the user must be a direct member of the group assigned to the application. See the document Assign a user or group to an enterprise app for details of managing group assignment to applications.
Customize the name of the group claim: If selected, a different claim type can be specified for group claims. Enter the claim type in the Name field and the optional namespace for the claim in the namespace field.
Some applications require the group membership information to appear in the 'role' claim.