通过

使用策略进行声明自定义

  • 项目

策略对象表示针对组织中的单个应用程序或所有应用程序强制实施的一组规则。 每种类型的策略都有一个唯一的结构，其中的一组属性将应用于它们所分配到的对象。

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。 如果没有为应用程序配置自定义签名密钥，则忽略此设置。

后续步骤