使用策略进行声明自定义
策略对象表示针对组织中的单个应用程序或所有应用程序强制实施的一组规则。 每种类型的策略都有一个唯一的结构,其中的一组属性将应用于它们所分配到的对象。
Microsoft Entra ID 支持通过两种方式使用 Microsoft Graph/PowerShell 为应用程序自定义声明:
- 使用自定义声明策略(预览版)
- 使用声明映射策略
自定义声明策略和声明映射策略是修改令牌中包含的声明的两种不同类型的策略对象。
自定义声明策略(预览版)允许管理员为其应用程序自定义其他声明。 它可与 Microsoft Entra 管理中心提供的声明自定义功能互换使用,使管理员可以通过 Microsoft Entra 管理中心或 MS Graph/PowerShell 管理声明。 通过 Microsoft Entra 管理中心提供的自定义声明策略和声明自定义都使用相同的基础策略来配置服务主体的其他声明。 但是,管理员只能为每个服务主体配置一个自定义声明策略(预览版)。 PUT
方法允许管理员创建策略对象或使用请求正文中传递的值替换现有策略对象,而 PATCH
方法允许管理员使用请求正文中传递的值更新策略对象。 在此处了解如何使用自定义声明策略配置和管理其他声明。
自定义映射策略(预览版)还允许管理员为其应用程序自定义其他声明。 管理员可以配置一个声明映射策略,并将其分配给其租户中的多个应用程序。 如果管理员选择使用声明映射策略为其应用程序管理其他声明,他们将无法在 Microsoft Entra 管理中心的声明自定义边栏选项卡为这些应用程序编辑或更新声明。 在此处了解如何使用声明映射策略配置和管理其他声明。
注意
声明映射策略取代了自定义声明策略以及通过 Microsoft Entra 管理中心提供的声明自定义。 使用声明映射策略自定义应用程序的声明意味着为该应用程序颁发的令牌将忽略自定义声明策略中的配置,或忽略 Microsoft Entra 管理中心的声明自定义边栏选项卡中的配置。 要详细了解声明自定义,请参阅自定义企业应用程序令牌颁发的声明。
声明集
下表列出了声明集,后者定义了它们在令牌中的使用方式和时间。
声明集 | 说明 |
---|---|
核心声明集 | 存在于每个令牌中,与策略无关。 这些声明也被视为受限制的,无法修改。 |
基本声明集 | 除了核心声明集之外,还包括令牌默认包含的声明。 你可以使用自定义声明策略和声明映射策略来省略或修改基本声明。 |
受限声明集 | 无法使用策略进行修改。 无法更改数据源,并且在生成这些声明时不应用任何转换。 |
JSON Web 令牌 (JWT) 受限制声明集
以下声明位于 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
注意
以 xms_
开头的任何声明都受到限制。
SAML 受限制声明集
下表列出了受限声明集中的 SAML 声明。
受限声明类型 (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
默认情况下,这些声明是受限的,但如果具有自定义签名密钥,则不受限制。 避免在应用清单中设置 acceptMappedClaims
。
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
默认情况下,这些声明是受限制的,但如果你有自定义签名密钥,则不受限制:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
用于声明自定义的策略的属性
要控制包含的声明和数据的来源,请使用声明自定义策略的属性。 如果没有策略,则系统会使用以下声明颁发令牌:
- 核心声明集。
- 基本声明集。
- 应用程序已选择接收的任何可选声明。
注意
核心声明集中的声明存在于每个令牌中(与此属性的设置无关)。
字符串 | 数据类型 | 总结 |
---|---|---|
IncludeBasicClaimSet | 布尔值(True 或 False) | 确定是否在受此策略影响的令牌中包含基本声明集。 如果设置为 True,则会在受策略影响的令牌中发出基本声明集中的所有声明。 如果设置为 False,基本声明集中的声明不包含在令牌中,除非在相同策略的声明架构属性中单独添加它们。 |
ClaimsSchema | 具有一个或多个声明架构条目的 JSON Blob | 定义除了基本声明集与核心声明集之外,在受此策略影响的令牌中存在的声明。 对于此属性中定义的每个声明架构条目,都需要特定信息。 指定数据的来源(Value、Source/ID 对或 Source/ExtensionID 对)以及发出的声明类型(JWTClaimType 或 SamlClaimType)。 |
声明架构条目元素
- Value - 将静态值定义为要在声明中发出的数据。
- SAMLNameForm - 定义此声明的 NameFormat 属性的值。 如果存在,那么允许的值为:
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 对 - 定义声明中数据的源位置。
- Source/ExtensionID 对 - 定义声明中的数据源自的目录扩展属性。 有关详细信息,请参阅在声明中使用目录扩展属性。
- 声明类型 - JwtClaimType 和 SamlClaimType 元素定义此声明架构条目引用的声明。
- JwtClaimType 必须包含要在 JWT 中发出的声明的名称。
- SamlClaimType 必须包含要在 SAML 令牌中发出的声明的 URI。
将 Source 元素设置为下表中的值之一。
源值 | 声明中的数据 |
---|---|
user |
User 对象的属性。 |
application |
应用程序(客户端)服务主体的属性。 |
resource |
资源服务主体的属性。 |
audience |
作为令牌受众的服务主体(客户端或资源服务主体)的属性。 |
company |
资源租户的 Company 对象的属性。 |
transformation |
声明转换。 使用此声明时,TransformationID 元素必须包含在声明定义中。 TransformationID 元素必须与 ClaimsTransformation 属性(定义如何生成此声明的数据)中的转换条目的 ID 元素匹配。 |
ID 元素标识为声明提供值的源的属性。 下表列出了每个 Source 值的 ID 元素的值。
源 | ID | 说明 |
---|---|---|
user |
surname |
用户的姓氏。 |
user |
givenname |
用户的给定名称。 |
user |
displayname |
用户的显示名称。 |
user |
objectid |
用户的对象 ID。 |
user |
mail |
用户的电子邮件地址。 |
user |
userprincipalname |
用户的用户主体名称。 |
user |
department |
用户所在的部门。 |
user |
onpremisessamaccountname |
用户的本地 SAM 帐户名称。 |
user |
netbiosname |
用户的 NetBios 名称。 |
user |
dnsdomainname |
用户的 DNS 域名。 |
user |
onpremisesecurityidentifier |
用户的本地安全标识符。 |
user |
companyname |
用户所在组织的名称。 |
user |
streetaddress |
用户的街道地址。 |
user |
postalcode |
用户的邮政编码。 |
user |
preferredlanguage |
用户的首选语言。 |
user |
onpremisesuserprincipalname |
用户的本地 UPN。 使用备用 ID 时,本地属性 userPrincipalName 会与 onPremisesUserPrincipalName 属性同步。 仅当配置备用 ID 时,此属性才可用。 |
user |
mailnickname |
用户的邮件别名。 |
user |
extensionattribute1 |
扩展属性 1。 |
user |
extensionattribute2 |
扩展属性 2。 |
user |
extensionattribute3 |
扩展属性 3。 |
user |
extensionattribute4 |
扩展属性 4。 |
user |
extensionattribute5 |
扩展属性 5。 |
user |
extensionattribute6 |
扩展属性 6。 |
user |
extensionattribute7 |
扩展属性 7。 |
user |
extensionattribute8 |
扩展属性 8。 |
user |
extensionattribute9 |
扩展属性 9。 |
user |
extensionattribute10 |
扩展属性 10。 |
user |
extensionattribute11 |
扩展属性 11。 |
user |
extensionattribute12 |
扩展属性 12。 |
user |
extensionattribute13 |
扩展属性 13。 |
user |
extensionattribute14 |
扩展属性 14。 |
user |
extensionattribute15 |
扩展属性 15。 |
user |
othermail |
用户的其他邮箱。 |
user |
country |
用户所在的国家/地区。 |
user |
city |
用户所在的城市。 |
user |
state |
用户所在的省/自治区/直辖市。 |
user |
jobtitle |
用户的职务。 |
user |
employeeid |
用户的员工 ID。 |
user |
facsimiletelephonenumber |
用户的传真电话号码。 |
user |
assignedroles |
分配给用户的应用角色列表。 |
user |
accountEnabled |
指示用户帐户是否已启用。 |
user |
consentprovidedforminor |
指示是否已为未成年人提供同意。 |
user |
createddatetime |
创建用户帐户的日期和时间。 |
user |
creationtype |
指示用户帐户是如何创建的。 |
user |
lastpasswordchangedatetime |
上次更改密码的日期和时间。 |
user |
mobilephone |
用户的移动电话。 |
user |
officelocation |
用户的办公地点。 |
user |
onpremisesdomainname |
用户的本地域名。 |
user |
onpremisesimmutableid |
用户的本地不可变 ID。 |
user |
onpremisessyncenabled |
指示是否已启用本地同步。 |
user |
preferreddatalocation |
定义用户的首选数据位置。 |
user |
proxyaddresses |
用户的代理地址。 |
user |
usertype |
用户帐户的类型。 |
user |
telephonenumber |
用户的商务或办公电话。 |
application 、resource 、audience |
displayname |
对象的显示名称。 |
application 、resource 、audience |
objectid |
对象的 ID。 |
application 、resource 、audience |
tags |
对象的服务主体标记。 |
company |
tenantcountry |
租户所在的国家/地区。 |
用户对象上唯一可用的多值声明源是已从 Active Directory Connect 同步的多值扩展属性。 othermails
和 tags
等其他属性是多值属性,但选择作为源时仅发出一个值。
受限制声明集中的声明的名称和 URI 不能用于声明类型元素。
组筛选器
- 字符串 - GroupFilter
- 数据类型 - JSON blob
- 摘要 - 使用此属性对要包含在组声明中的用户组应用筛选器。 这属性可以是减小令牌大小的有用方法。
- MatchOn - 标识要应用筛选器的组特性。 将 MatchOn 属性设置为以下值之一:
displayname
- 组显示名称。samaccountname
- 本地 SAM 帐户名。
- 类型 - 定义应用于由 MatchOn 属性选择的属性的筛选器类型。 将 Type 属性设置为以下值之一:
prefix
- 包括 MatchOn 属性以提供的 Value 属性开头的组。suffix
- 包括 MatchOn 属性以提供的 Value 属性结尾的组。contains
- 包括 MatchOn 属性含有提供的 Value 属性的组。
声明转换
- 字符串 - ClaimsTransformation
- 数据类型 - 具有一个或多个转换条目的 JSON blob
- 摘要 - 使用此属性可将常见转换应用于源数据,以便为声明架构中指定的声明生成输出数据。
- ID - 在 TransformationID 声明架构条目中引用转换条目。 就此策略中的每个转换条目来说,该值必须唯一。
- TransformationMethod - 标识为生成声明数据而执行的操作。
根据选择的方法,需要一组输入和输出。 使用 InputClaims、InputParameters 和OutputClaims 元素定义输入和输出。
TransformationMethod | 预期输入 | 预期输出 | 说明 |
---|---|---|---|
Join | string1、string2、分隔符 | 输出声明 | 联接输入字符串(之间使用分隔符)。 例如,string1:foo@bar.com ,string2:sandbox ,分隔符:. ,输出声明中的结果:foo@bar.com.sandbox 。 |
ExtractMailPrefix | 电子邮件或 UPN | 提取的字符串 | 扩展属性 1-15 或为用户存储 UPN 或电子邮件地址值的任何其他目录扩展。 例如,johndoe@contoso.com 。 提取电子邮件地址的本地部分。 例如,邮件:foo@bar.com ,输出声明中的结果:foo 。 如果未提供 @ 符号,则会返回原始输入字符串。 |
ToLowercase() | string | 输出字符串 | 将所选属性的字符转换为小写字符。 |
ToUppercase() | string | 输出字符串 | 将所选属性的字符转换为大写字符。 |
RegexReplace() | RegexReplace() 转换接受以下内容作为输入参数: - 参数 1:用户属性作为正则表达式输入 - 信任源作为多值的选项 - 正则表达式模式 - 替换模式。 替换模式可能包含静态文本格式,以及指向正则表达式输出组和其他输入参数的引用。 |
- InputClaims - 用于将数据从声明架构条目传递给转换。 它具有三个属性:ClaimTypeReferenceId、TransformationClaimType 和 TreatAsMultiValue。
- ClaimTypeReferenceId - 与声明架构条目的 ID 元素联接在一起可查找相应的输入声明。
- TransformationClaimType - 向此输入提供唯一名称。 此名称必须与转换方法的预期输入之一匹配。
- TreatAsMultiValue 是一个布尔型标志,用于指示转换是应用于所有值还是只应用于第一个值。 默认情况下,转换仅应用于多值声明中的第一个元素。 将此值设置为 true 可确保将其应用于所有元素。 ProxyAddresses 和 groups 是你可能想要视为多值声明的输入声明的两个示例。
- InputParameters - 将常量值传递给转换。 它具有两个属性:Value 和 ID。
- Value 是要传递的实际常数值。
- ID 用于为输入提供唯一名称。 此名称必须与转换方法的预期输入之一匹配。
- OutputClaims - 保存转换生成的数据,并将它绑定到声明架构条目。 它具有两个属性:ClaimTypeReferenceId 和 TransformationClaimType。
- ClaimTypeReferenceId 与声明架构条目的 ID 联接在一起可查找相应的输出声明。
- TransformationClaimType 用于为输出提供唯一名称。 此名称必须与转换方法的预期输出之一匹配。
例外和限制
SAML NameID 和 UPN - NameID 和 UPN 值所源自的属性以及允许使用的声明转换会受到限制。
源 | ID | 说明 |
---|---|---|
user |
mail |
用户的电子邮件地址。 |
user |
userprincipalname |
用户的用户主体名称。 |
user |
onpremisessamaccountname |
本地 Sam 帐户名称 |
user |
employeeid |
用户的员工 ID。 |
user |
telephonenumber |
用户的商务或办公电话。 |
user |
extensionattribute1 |
扩展属性 1。 |
user |
extensionattribute2 |
扩展属性 2。 |
user |
extensionattribute3 |
扩展属性 3。 |
user |
extensionattribute4 |
扩展属性 4。 |
user |
extensionattribute5 |
扩展属性 5。 |
user |
extensionattribute6 |
扩展属性 6。 |
user |
extensionattribute7 |
扩展属性 7。 |
user |
extensionattribute8 |
扩展属性 8。 |
user |
extensionattribute9 |
扩展属性 9。 |
user |
extensionattribute10 |
扩展属性 10。 |
user |
extensionattribute11 |
扩展属性 11。 |
user |
extensionattribute12 |
扩展属性 12。 |
user |
extensionattribute13 |
扩展属性 13。 |
user |
extensionattribute14 |
扩展属性 14。 |
User |
extensionattribute15 |
扩展属性 15。 |
允许将下表中列出的转换方法用于 SAML NameID。
TransformationMethod | 限制 |
---|---|
ExtractMailPrefix | 无 |
Join | 要联接的后缀必须是资源租户的已验证域。 |
具有应用程序 ID 的颁发者
- 字符串 - issuerWithApplicationId
- 数据类型 - 布尔(True 或 False)
- 如果设置为
True
,则应用程序 ID 将添加到受策略影响的令牌中的颁发者声明。 - 如果设置为
False
,则应用程序 ID 将不会添加到受策略影响的令牌中的颁发者声明。 (默认值)
- 如果设置为
- 摘要 - 允许应用程序 ID 包含在颁发者声明中。 确保同一应用程序的多个实例对每个实例具有唯一的声明值。 如果没有为应用程序配置自定义签名密钥,则忽略此设置。
受众替代
- 字符串 - audienceOverride
- 数据类型 - 字符串
- 摘要 - 允许替代发送到应用程序的受众声明。 提供的值必须为有效的绝对 URI。 如果没有为应用程序配置自定义签名密钥,则忽略此设置。
后续步骤
- 若要详细了解扩展属性,请参阅声明中的目录扩展属性。