Claims customization using a policy
A policy object represents a set of rules enforced on individual applications or on all applications in an organization. Each type of policy has a unique structure, with a set of properties that are then applied to objects to which they're assigned.
Microsoft Entra ID supports two ways to customize claims using Microsoft Graph/PowerShell for your applications:
- Using Custom Claims Policy (Preview)
- Using Claims Mapping Policy
Custom claims policy and claims mapping policy are two different types of policy objects that modify the claims included in tokens.
Custom Claims Policy(Preview) allows admins to customize additional claims for their applications. It can be used interchangeably with the claims customization offered through the Microsoft Entra admin center allowing admins to manage claims either through the Microsoft Entra admin center or MS Graph/PowerShell. Both Custom Claims Policy and claims customization offered through Microsoft Entra admin center use the same underlying policy to configure additional claims for the service principals. However, admins can only configure one Custom Claims Policy(Preview) per service principal. The PUT
method allows admins to create or replace an existing a policy object with the values passed in the request body while PATCH
method allows admins to update the policy object with the values which are passed in the request body. Learn how to configure and manage additional claims using Custom Claims Policy here.
Claims Mapping Policy also allows admins to customize additional claims for their applications. Admins can configure one Claims Mapping Policy and assign it to multiple applications in their tenant. If an admin chooses to use Claims Mapping Policy to manage additional claims for their applications, they won't be able to edit or update the claims in the claims customization blade in Microsoft Entra admin center for those applications. Learn how to configure and manage additional claims using Claims Mapping Policy here.
Note
Claims Mapping Policy supersedes both Custom Claims policy and the claims customization offered through the Microsoft Entra admin center. Customizing claims for an application using the Claims Mapping Policy means that tokens issued for that application will ignore the configuration in Custom Claims Policy or the configuration in claims customization blade on Microsoft Entra admin center. For more information on claims customization, see Customize claims issued in the token for enterprise applications.
Claim sets
The following table lists the sets of claims that define how and when they're used in tokens.
Claim set | Description |
---|---|
Core claim set | Present in every token regardless of the policy. These claims are also considered restricted, and can't be modified. |
Basic claim set | Includes the claims that are included by default for tokens in addition to the core claim set. You can omit or modify basic claims by using the custom claims policies and claims mapping policies. |
Restricted claim set | Can't be modified using a policy. The data source can't be changed, and no transformation is applied when generating these claims. |
JSON Web Token (JWT) restricted claim set
The following claims are in the restricted claim set for a JWT.
.
_claim_names
_claim_sources
aai
access_token
account_type
acct
acr
acrs
actor
actortoken
ageGroup
aio
altsecid
amr
app_chain
app_displayname
app_res
appctx
appctxsender
appid
appidacr
assertion
at_hash
aud
auth_data
auth_time
authorization_code
azp
azpacr
bk_claim
bk_enclave
bk_pub
brk_client_id
brk_redirect_uri
c_hash
ca_enf
ca_policy_result
capolids
capolids_latebind
cc
cert_token_use
child_client_id
child_redirect_uri
client_id
client_ip
cloud_graph_host_name
cloud_instance_host_name
cloud_instance_name
CloudAssignedMdmId
cnf
code
controls
controls_auds
credential_keys
csr
csr_type
ctry
deviceid
dns_names
domain_dns_name
domain_netbios_name
e_exp
email
endpoint
enfpolids
exp
expires_on
extn. as prefix
fido_auth_data
fido_ver
fwd
fwd_appidacr
grant_type
graph
group_sids
groups
hasgroups
hash_alg
haswids
home_oid
home_puid
home_tid
iat
identityprovider
idp
idtyp
in_corp
instance
inviteTicket
ipaddr
isbrowserhostedapp
iss
isViral
jwk
key_id
key_type
login_hint
mam_compliance_url
mam_enrollment_url
mam_terms_of_use_url
mdm_compliance_url
mdm_enrollment_url
mdm_terms_of_use_url
msgraph_host
msproxy
nameid
nbf
netbios_name
nickname
nonce
oid
on_prem_id
onprem_sam_account_name
onprem_sid
openid2_id
origin_header
password
platf
polids
pop_jwk
preferred_username
previous_refresh_token
primary_sid
prov_data
puid
pwd_exp
pwd_url
rdp_bt
redirect_uri
refresh_token
refresh_token_issued_on
refreshtoken
request_nonce
resource
rh
role
roles
rp_id
rt_type
scope
scp
secaud
sid
sid
signature
signin_state
source_anchor
src1
src2
sub
target_deviceid
tbid
tbidv2
tenant_ctry
tenant_display_name
tenant_id
tenant_region_scope
tenant_region_sub_scope
thumbnail_photo
tid
tokenAutologonEnabled
trustedfordelegation
ttr
unique_name
upn
user_agent
user_setting_sync_url
username
uti
ver
verified_primary_email
verified_secondary_email
vnet
vsm_binding_key
wamcompat_client_info
wamcompat_id_token
wamcompat_scopes
wids
win_ver
x5c_ca
xcb2b_rclient
xcb2b_rcloud
xcb2b_rtenant
ztdid
Note
Any claim starting with xms_
is restricted.
SAML restricted claim set
The following table lists the SAML claims that are in the restricted claim set.
Restricted Claim type (URI):
http://schemas.microsoft.com/2012/01/devicecontext/claims/ismanaged
http://schemas.microsoft.com/2014/02/devicecontext/claims/isknown
http://schemas.microsoft.com/2014/03/psso
http://schemas.microsoft.com/2014/09/devicecontext/claims/iscompliant
http://schemas.microsoft.com/claims/authnmethodsreferences
http://schemas.microsoft.com/claims/groups.link
http://schemas.microsoft.com/identity/claims/accesstoken
http://schemas.microsoft.com/identity/claims/acct
http://schemas.microsoft.com/identity/claims/agegroup
http://schemas.microsoft.com/identity/claims/aio
http://schemas.microsoft.com/identity/claims/identityprovider
http://schemas.microsoft.com/identity/claims/objectidentifier
http://schemas.microsoft.com/identity/claims/openid2_id
http://schemas.microsoft.com/identity/claims/puid
http://schemas.microsoft.com/identity/claims/scope
http://schemas.microsoft.com/identity/claims/tenantid
http://schemas.microsoft.com/identity/claims/xms_et
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
http://schemas.microsoft.com/ws/2008/06/identity/claims/confirmationkey
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarygroupsid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarysid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlywindowsdevicegroup
http://schemas.microsoft.com/ws/2008/06/identity/claims/expiration
http://schemas.microsoft.com/ws/2008/06/identity/claims/expired
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid
http://schemas.microsoft.com/ws/2008/06/identity/claims/ispersistent
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
http://schemas.microsoft.com/ws/2008/06/identity/claims/samlissuername
http://schemas.microsoft.com/ws/2008/06/identity/claims/wids
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsdeviceclaim
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsdevicegroup
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsfqbnversion
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowssubauthority
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsuserclaim
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/authentication
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/authorizationdecision
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlysid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/spn
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
http://schemas.xmlsoap.org/ws/2009/09/identity/claims/actor
These claims are restricted by default, but aren't restricted if you have a custom signing key. Avoid setting acceptMappedClaims
in the app manifest.
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/sid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/x500distinguishedname
These claims are restricted by default, but aren't restricted if you have a custom signing key:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
Properties of the policy used for claims customization
To control the claims that are included and where the data comes from, use the properties of the policy for claims customization. Without a policy, the system issues tokens with the following claims:
- The core claim set.
- The basic claim set.
- Any optional claims that the application has chosen to receive.
Note
Claims in the core claim set are present in every token, regardless of what this property is set to.
String | Data type | Summary |
---|---|---|
IncludeBasicClaimSet | Boolean (True or False) | Determines whether the basic claim set is included in tokens affected by this policy. If set to True, all claims in the basic claim set are emitted in tokens affected by the policy. If set to False, claims in the basic claim set aren't in the tokens, unless they're individually added in the claims schema property of the same policy. |
ClaimsSchema | JSON blob with one or more claim schema entries | Defines which claims are present in the tokens affected by the policy, in addition to the basic claim set and the core claim set. For each claim schema entry defined in this property, certain information is required. Specify where the data is coming from (Value, Source/ID pair, or Source/ExtensionID pair), and Claim Type, which is emitted as (JWTClaimType or SamlClaimType). |
Claim schema entry elements
- Value - Defines a static value as the data to be emitted in the claim.
- SAMLNameForm - Defines the value for the NameFormat attribute for this claim. If present, the allowed values are:
urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
urn:oasis:names:tc:SAML:2.0:attrname-format:uri
urn:oasis:names:tc:SAML:2.0:attrname-format:basic
- Source/ID pair - Defines where the data in the claim is sourced from.
- Source/ExtensionID pair - Defines the directory extension attribute where the data in the claim is sourced from. For more information, see Using directory extension attributes in claims.
- Claim Type - The JwtClaimType and SamlClaimType elements define which claim this claim schema entry refers to.
- The JwtClaimType must contain the name of the claim to be emitted in JWTs.
- The SamlClaimType must contain the URI of the claim to be emitted in SAML tokens.
Set the Source element to one of the values in the following table.
Source value | Data in claim |
---|---|
user |
Property on the User object. |
application |
Property on the application (client) service principal. |
resource |
Property on the resource service principal. |
audience |
Property on the service principal that is the audience of the token (either the client or resource service principal). |
company |
Property on the resource tenant's Company object. |
transformation |
Claims transformation. When you use this claim, the TransformationID element must be included in the claim definition. The TransformationID element must match the ID element of the transformation entry in the ClaimsTransformation property that defines how the data for the claim is generated. |
The ID element identifies the property on the source that provides the value for the claim. The following table lists the values of the ID element for each value of Source.
Source | ID | Description |
---|---|---|
user |
surname |
The family name of the user. |
user |
givenname |
The given name of the user. |
user |
displayname |
The display name of the user. |
user |
objectid |
The object ID of the user. |
user |
mail |
The email address of the user. |
user |
userprincipalname |
The user principal name of the user. |
user |
department |
The department of the user. |
user |
onpremisessamaccountname |
The on-premises SAM account name of the user. |
user |
netbiosname |
The NetBios name of the user. |
user |
dnsdomainname |
The DNS domain name of the user. |
user |
onpremisesecurityidentifier |
The on-premises security identifier of the user. |
user |
companyname |
The organization name of the user. |
user |
streetaddress |
The street address of the user. |
user |
postalcode |
The postal code of the user. |
user |
preferredlanguage |
The preferred language of the user. |
user |
onpremisesuserprincipalname |
The on-premises UPN of the user. When you use an alternate ID, the on-premises attribute userPrincipalName is synchronized with the onPremisesUserPrincipalName attribute. This attribute is only available when Alternate ID is configured. |
user |
mailnickname |
The mail nickname of the user. |
user |
extensionattribute1 |
Extension attribute 1. |
user |
extensionattribute2 |
Extension attribute 2. |
user |
extensionattribute3 |
Extension attribute 3. |
user |
extensionattribute4 |
Extension attribute 4. |
user |
extensionattribute5 |
Extension attribute 5. |
user |
extensionattribute6 |
Extension attribute 6. |
user |
extensionattribute7 |
Extension attribute 7. |
user |
extensionattribute8 |
Extension attribute 8. |
user |
extensionattribute9 |
Extension attribute 9. |
user |
extensionattribute10 |
Extension attribute 10. |
user |
extensionattribute11 |
Extension attribute 11. |
user |
extensionattribute12 |
Extension attribute 12. |
user |
extensionattribute13 |
Extension attribute 13. |
user |
extensionattribute14 |
Extension attribute 14. |
user |
extensionattribute15 |
Extension attribute 15. |
user |
othermail |
The other mail of the user. |
user |
country |
The country/region of the user. |
user |
city |
The city of the user. |
user |
state |
The state of the user. |
user |
jobtitle |
The job title of the user. |
user |
employeeid |
The employee ID of the user. |
user |
facsimiletelephonenumber |
The facsimile telephone number of the user. |
user |
assignedroles |
The list of app roles assigned to the user. |
user |
accountEnabled |
Indicates whether the user account is enabled. |
user |
consentprovidedforminor |
Indicates whether consent was provided for a minor. |
user |
createddatetime |
The date and time that the user account was created. |
user |
creationtype |
Indicates how the user account was creation. |
user |
lastpasswordchangedatetime |
The last date and time that the password was changed. |
user |
mobilephone |
The mobile phone of the user. |
user |
officelocation |
The office location of the user. |
user |
onpremisesdomainname |
The on-premises domain name of the user. |
user |
onpremisesimmutableid |
The on-premises immutable ID of the user. |
user |
onpremisessyncenabled |
Indicates whether on-premises sync is enabled. |
user |
preferreddatalocation |
Defines the preferred data location of the user. |
user |
proxyaddresses |
The proxy addresses of the user. |
user |
usertype |
The type of user account. |
user |
telephonenumber |
The business or office phones of the user. |
application , resource , audience |
displayname |
The display name of the object. |
application , resource , audience |
objectid |
The ID of the object. |
application , resource , audience |
tags |
The service principal tag of the object. |
company |
tenantcountry |
The country/region of the tenant. |
The only available multi-valued claim sources on a user object are multi-valued extension attributes that have been synced from Active Directory Connect. Other properties, such as othermails
and tags
, are multi-valued but only one value is emitted when selected as a source.
Names and URIs of claims in the restricted claim set can't be used for the claim type elements.
Group Filter
- String - GroupFilter
- Data type: - JSON blob
- Summary - Use this property to apply a filter on the user’s groups to be included in the group claim. This property can be a useful means of reducing the token size.
- MatchOn: - Identifies the group attribute on which to apply the filter. Set the MatchOn property to one of the following values:
displayname
- The group display name.samaccountname
- The on-premises SAM account name.
- Type - Defines the type of filter applied to the attribute selected by the MatchOn property. Set the Type property to one of the following values:
prefix
- Include groups where the MatchOn property starts with the provided Value property.suffix
Include groups where the MatchOn property ends with the provided Value property.contains
- Include groups where the MatchOn property contains with the provided Value property.
Claims transformation
- String - ClaimsTransformation
- Data type - JSON blob, with one or more transformation entries
- Summary - Use this property to apply common transformations to source data to generate the output data for claims specified in the Claims Schema.
- ID - References the transformation entry in the TransformationID Claims Schema entry. This value must be unique for each transformation entry within this policy.
- TransformationMethod - Identifies the operation that's performed to generate the data for the claim.
Based on the method chosen, a set of inputs and outputs is expected. Define the inputs and outputs by using the InputClaims, InputParameters and OutputClaims elements.
TransformationMethod | Expected input | Expected output | Description |
---|---|---|---|
Join | string1, string2, separator | output claim | Joins input strings by using a separator in between. For example, string1:foo@bar.com , string2:sandbox , separator:. results in output claim:foo@bar.com.sandbox . |
ExtractMailPrefix | Email or UPN | extracted string | Extension attributes 1-15 or any other directory extensions, which store a UPN or email address value for the user. For example, johndoe@contoso.com . Extracts the local part of an email address. For example, mail:foo@bar.com results in output claim:foo . If no @ sign is present, then the original input string is returned. |
ToLowercase() | string | output string | Converts the characters of the selected attribute into lowercase characters. |
ToUppercase() | string | output string | Converts the characters of the selected attribute into uppercase characters. |
RegexReplace() | RegexReplace() transformation accepts as input parameters: - Parameter 1: a user attribute as regex input - An option to trust the source as multivalued - Regex pattern - Replacement pattern. The replacement pattern may contain static text format along with a reference that points to regex output groups and more input parameters. |
- InputClaims - Used to pass the data from a claim schema entry to a transformation. It has three attributes: ClaimTypeReferenceId, TransformationClaimType and TreatAsMultiValue.
- ClaimTypeReferenceId - Joined with the ID element of the claim schema entry to find the appropriate input claim.
- TransformationClaimType Gives a unique name to this input. This name must match one of the expected inputs for the transformation method.
- TreatAsMultiValue is a Boolean flag that indicates whether the transform should be applied to all values or just the first. By default, transformations are only applied to the first element in a multi-value claim. Setting this value to true ensures it's applied to all. ProxyAddresses and groups are two examples for input claims that you would likely want to treat as a multi-value claim.
- InputParameters - Passes a constant value to a transformation. It has two attributes: Value and ID.
- Value is the actual constant value to be passed.
- ID is used to give a unique name to the input. The name must match one of the expected inputs for the transformation method.
- OutputClaims - Holds the data generated by a transformation, and ties it to a claim schema entry. It has two attributes: ClaimTypeReferenceId and TransformationClaimType.
- ClaimTypeReferenceId is joined with the ID of the claim schema entry to find the appropriate output claim.
- TransformationClaimType is used to give a unique name to the output. The name must match one of the expected outputs for the transformation method.
Exceptions and restrictions
SAML NameID and UPN - The attributes from which you source the NameID and UPN values, and the claims transformations that are permitted, are limited.
Source | ID | Description |
---|---|---|
user |
mail |
The email address of the user. |
user |
userprincipalname |
The user principal name of the user. |
user |
onpremisessamaccountname |
On-premises Sam Account Name |
user |
employeeid |
The employee ID of the user. |
user |
telephonenumber |
The business or office phones of the user. |
user |
extensionattribute1 |
Extension attribute 1. |
user |
extensionattribute2 |
Extension attribute 2. |
user |
extensionattribute3 |
Extension attribute 3. |
user |
extensionattribute4 |
Extension attribute 4. |
user |
extensionattribute5 |
Extension attribute 5. |
user |
extensionattribute6 |
Extension attribute 6. |
user |
extensionattribute7 |
Extension attribute 7. |
user |
extensionattribute8 |
Extension attribute 8. |
user |
extensionattribute9 |
Extension Attribute 9. |
user |
extensionattribute10 |
Extension attribute 10. |
user |
extensionattribute11 |
Extension attribute 11. |
user |
extensionattribute12 |
Extension attribute 12. |
user |
extensionattribute13 |
Extension attribute 13. |
user |
extensionattribute14 |
Extension attribute 14. |
User |
extensionattribute15 |
Extension attribute 15. |
The transformation methods listed in the following table are allowed for SAML NameID.
TransformationMethod | Restrictions |
---|---|
ExtractMailPrefix | None |
Join | The suffix being joined must be a verified domain of the resource tenant. |
Issuer With Application ID
- String - issuerWithApplicationId
- Data type - Boolean (True or False)
- If set to
True
, the application ID is added to the issuer claim in tokens affected by the policy. - If set to
False
, the application ID isn't added to the issuer claim in tokens affected by the policy. (default)
- If set to
- Summary - Enables the application ID to be included in the issuer claim. Ensures that multiple instances of the same application have a unique claim value for each instance. This setting is ignored if a custom signing key isn't configured for the application.
Audience Override
- String - audienceOverride
- Data type - String
- Summary - Enables you to override the audience claim sent to the application. The value provided must be a valid absolute URI. This setting is ignored if no custom signing key is configured for the application.
Next steps
- To learn more about extension attributes, see Directory extension attributes in claims.
Pripomienky
https://aka.ms/ContentUserFeedback.
Pripravujeme: V priebehu roka 2024 postupne zrušíme službu Problémy v službe GitHub ako mechanizmus pripomienok týkajúcich sa obsahu a nahradíme ju novým systémom pripomienok. Ďalšie informácie nájdete na stránke:Odoslať a zobraziť pripomienky pre