如何:为租户中的特定应用自定义在令牌中发出的声明(预览版)How to: Customize claims emitted in tokens for a specific app in a tenant (Preview)

备注

此功能替换并取代了当前通过门户提供的声明自定义。This feature replaces and supersedes the claims customization offered through the portal today. 在同一应用程序中,如果使用门户以及本文档中详细介绍的 Graph/PowerShell 方法自定义声明,则为该应用程序颁发的令牌会忽略门户中的配置。On the same application, if you customize claims using the portal in addition to the Graph/PowerShell method detailed in this document, tokens issued for that application will ignore the configuration in the portal. 通过本文档中详细介绍的方法进行的配置不会在门户中进行反映。Configurations made through the methods detailed in this document will not be reflected in the portal.

此功能由租户管理员用来自定义以令牌形式针对其租户中的特定应用程序发出的声明。This feature is used by tenant admins to customize the claims emitted in tokens for a specific application in their tenant. 可以使用声明映射策略执行以下操作:You can use claims-mapping policies to:

  • 选择在令牌中包含的声明。Select which claims are included in tokens.
  • 创建尚未存在的声明类型。Create claim types that do not already exist.
  • 选择或更改在特定声明中发出的数据的源。Choose or change the source of data emitted in specific claims.

备注

此功能目前以公共预览版提供。This capability currently is in public preview. 应准备好还原或删除所做的任何更改。Be prepared to revert or remove any changes. 在公共预览版推出期间,可在任何 Azure Active Directory (Azure AD) 订阅中使用此功能。The feature is available in any Azure Active Directory (Azure AD) subscription during public preview. 但是,在正式版推出后,某些功能可能需要使用 Azure AD Premium 订阅。However, when the feature becomes generally available, some aspects of the feature might require an Azure AD premium subscription. 此功能支持配置适用于 WS-Fed、SAML、OAuth 和 OpenID Connect 协议的声明映射策略。This feature supports configuring claim mapping policies for WS-Fed, SAML, OAuth, and OpenID Connect protocols.

声明映射策略类型Claims mapping policy type

在 Azure AD 中,策略 对象表示针对组织中的单个应用程序或所有应用程序强制实施的一组规则。In Azure AD, 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 are assigned.

声明映射策略是某种类型的 策略 对象,它修改为特定应用程序颁发的令牌中发出的声明。A claims mapping policy is a type of Policy object that modifies the claims emitted in tokens issued for specific applications.

声明集Claim sets

有一些可定义如何以及何时在令牌中使用它们的特定声明集。There are certain sets of claims that define how and when they're used in tokens.

声明集Claim set 说明Description
核心声明集Core claim set 存在于每个令牌中,与策略无关。Are 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 emitted by default for tokens (in addition to the core claim set). 可以省略或通过使用声明映射策略来修改基本声明。You can omit or modify basic claims by using the claims mapping policies.
受限声明集Restricted claim set 无法使用策略进行修改。Can't be modified using policy. 无法更改数据源,并且在生成这些声明时不应用任何转换。The data source cannot be changed, and no transformation is applied when generating these claims.

表 1:JSON Web 令牌 (JWT) 受限制声明集Table 1: JSON Web Token (JWT) restricted claim set

声明类型(名称)Claim type (name)
_claim_names_claim_names
_claim_sources_claim_sources
access_tokenaccess_token
account_typeaccount_type
acracr
actoractor
actortokenactortoken
aioaio
altsecidaltsecid
amramr
app_chainapp_chain
app_displaynameapp_displayname
app_resapp_res
appctxappctx
appctxsenderappctxsender
appidappid
appidacrappidacr
assertionassertion
at_hashat_hash
audaud
auth_dataauth_data
auth_timeauth_time
authorization_codeauthorization_code
azpazp
azpacrazpacr
c_hashc_hash
ca_enfca_enf
cccc
cert_token_usecert_token_use
client_idclient_id
cloud_graph_host_namecloud_graph_host_name
cloud_instance_namecloud_instance_name
cnfcnf
codecode
controlscontrols
credential_keyscredential_keys
csrcsr
csr_typecsr_type
deviceiddeviceid
dns_namesdns_names
domain_dns_namedomain_dns_name
domain_netbios_namedomain_netbios_name
e_expe_exp
电子邮件email
endpointendpoint
enfpolidsenfpolids
expexp
expires_onexpires_on
grant_typegrant_type
graphgraph
group_sidsgroup_sids
groupsgroups
hasgroupshasgroups
hash_alghash_alg
home_oidhome_oid
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/expiration
http://schemas.microsoft.com/ws/2008/06/identity/claims/expired
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
iatiat
identityprovideridentityprovider
idpidp
in_corpin_corp
instanceinstance
ipaddripaddr
isbrowserhostedappisbrowserhostedapp
ississ
jwkjwk
key_idkey_id
key_typekey_type
mam_compliance_urlmam_compliance_url
mam_enrollment_urlmam_enrollment_url
mam_terms_of_use_urlmam_terms_of_use_url
mdm_compliance_urlmdm_compliance_url
mdm_enrollment_urlmdm_enrollment_url
mdm_terms_of_use_urlmdm_terms_of_use_url
nameidnameid
nbfnbf
netbios_namenetbios_name
noncenonce
oidoid
on_prem_idon_prem_id
onprem_sam_account_nameonprem_sam_account_name
onprem_sidonprem_sid
openid2_idopenid2_id
passwordpassword
polidspolids
pop_jwkpop_jwk
preferred_usernamepreferred_username
previous_refresh_tokenprevious_refresh_token
primary_sidprimary_sid
puidpuid
pwd_exppwd_exp
pwd_urlpwd_url
redirect_uriredirect_uri
refresh_tokenrefresh_token
refreshtokenrefreshtoken
request_noncerequest_nonce
resourceresource
rolerole
角色roles
scopescope
scpscp
sidsid
signaturesignature
signin_statesignin_state
src1src1
src2src2
subsub
tbidtbid
tenant_display_nametenant_display_name
tenant_region_scopetenant_region_scope
thumbnail_photothumbnail_photo
tidtid
tokenAutologonEnabledtokenAutologonEnabled
trustedfordelegationtrustedfordelegation
unique_nameunique_name
upnupn
user_setting_sync_urluser_setting_sync_url
usernameusername
utiuti
verver
verified_primary_emailverified_primary_email
verified_secondary_emailverified_secondary_email
widswids
win_verwin_ver

表 2:SAML 受限制声明集Table 2: SAML restricted claim set

声明类型 (URI)Claim type (URI)
http://schemas.microsoft.com/ws/2008/06/identity/claims/expiration
http://schemas.microsoft.com/ws/2008/06/identity/claims/expired
http://schemas.microsoft.com/identity/claims/accesstoken
http://schemas.microsoft.com/identity/claims/openid2_id
http://schemas.microsoft.com/identity/claims/identityprovider
http://schemas.microsoft.com/identity/claims/objectidentifier
http://schemas.microsoft.com/identity/claims/puid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier [MR1]
http://schemas.microsoft.com/identity/claims/tenantid
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
http://schemas.microsoft.com/accesscontrolservice/2010/07/claims/identityprovider
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
http://schemas.microsoft.com/claims/groups.link
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
http://schemas.microsoft.com/ws/2008/06/identity/claims/wids
http://schemas.microsoft.com/2014/09/devicecontext/claims/iscompliant
http://schemas.microsoft.com/2014/02/devicecontext/claims/isknown
http://schemas.microsoft.com/2012/01/devicecontext/claims/ismanaged
http://schemas.microsoft.com/2014/03/psso
http://schemas.microsoft.com/claims/authnmethodsreferences
http://schemas.xmlsoap.org/ws/2009/09/identity/claims/actor
http://schemas.microsoft.com/ws/2008/06/identity/claims/samlissuername
http://schemas.microsoft.com/ws/2008/06/identity/claims/confirmationkey
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/authorizationdecision
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/authentication
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/sid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarygroupsid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarysid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlysid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlywindowsdevicegroup
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/x500distinguishedname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/spn
http://schemas.microsoft.com/ws/2008/06/identity/claims/ispersistent
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
http://schemas.microsoft.com/identity/claims/scope

声明映射策略属性Claims mapping policy properties

若要控制要发出的声明以及数据的来源,请使用声明映射策略的属性。To control what claims are emitted and where the data comes from, use the properties of a claims mapping policy. 如果未设置策略,则系统将颁发包括核心声明集、基本声明集以及应用程序已选择接收的任何可选声明的令牌。If a policy is not set, the system issues tokens that include the core claim set, the basic claim set, and any optional claims that the application has chosen to receive.

包括基本声明集Include basic claim set

字符串: IncludeBasicClaimSetString: IncludeBasicClaimSet

数据类型: 布尔值(True 或 False)Data type: Boolean (True or False)

摘要: 此属性确定是否在受此策略影响的令牌中包含基本声明集。Summary: This property determines whether the basic claim set is included in tokens affected by this policy.

  • 如果设置为 True,则会在受策略影响的令牌中发出基本声明集中的所有声明。If set to True, all claims in the basic claim set are emitted in tokens affected by the policy.
  • 如果设置为 False,基本声明集中的声明不包含在令牌中,除非在相同策略的声明架构属性中单独添加它们。If set to False, claims in the basic claim set are not in the tokens, unless they are individually added in the claims schema property of the same policy.

备注

核心声明集中的声明存在于每个令牌中(与此属性的设置无关)。Claims in the core claim set are present in every token, regardless of what this property is set to.

声明架构Claims schema

字符串: ClaimsSchemaString: ClaimsSchema

数据类型: 具有一个或多个声明架构条目的 JSON BlobData type: JSON blob with one or more claim schema entries

摘要: 此属性定义除了基本声明集与核心声明集之外,在受此策略影响的令牌中存在的声明。Summary: This property 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. 指定数据来源(“Value”、“Source/ID 对”或“Source/ExtensionID 对”)以及数据作为哪种声明发出(声明类型)。Specify where the data is coming from (Value, Source/ID pair, or Source/ExtensionID pair), and which claim the data is emitted as (Claim Type).

声明架构条目元素Claim schema entry elements

Value: Value 元素将静态值定义为要在声明中发出的数据。Value: The Value element defines a static value as the data to be emitted in the claim.

Source/ID 对: Source 和 ID 元素定义声明中的数据的来源。Source/ID pair: The Source and ID elements define where the data in the claim is sourced from.

Source/ExtensionID 对: Source 元素和 ExtensionID 元素定义声明中的数据源自的目录架构扩展属性。Source/ExtensionID pair: The Source and ExtensionID elements define the directory schema extension attribute where the data in the claim is sourced from. 有关详细信息,请参阅在声明中使用目录架构扩展属性For more information, see Using directory schema extension attributes in claims.

将 Source 元素设置为下列值之一:Set the Source element to one of the following values:

  • "user":声明中的数据是 User 对象的属性。"user": The data in the claim is a property on the User object.
  • "application":声明中的数据是应用程序(客户端)服务主体的属性。"application": The data in the claim is a property on the application (client) service principal.
  • "resource":声明中的数据是资源服务主体的属性。"resource": The data in the claim is a property on the resource service principal.
  • "audience":声明中的数据是作为令牌受众的服务主体(客户端或资源服务主体)的属性。"audience": The data in the claim is a property on the service principal that is the audience of the token (either the client or resource service principal).
  • "company":声明中的数据是资源租户的 Company 对象的属性。"company": The data in the claim is a property on the resource tenant's Company object.
  • "transformation":声明中的数据来自声明转换(请参阅本文后面的“声明转换”部分)。"transformation": The data in the claim is from claims transformation (see the "Claims transformation" section later in this article).

如果 Source 是 transformation,则 TransformationID 元素也必须包含在此声明定义中。If the source is transformation, the TransformationID element must be included in this claim definition as well.

ID 元素标识源中用于为声明提供值的属性。The ID element identifies which property on the source provides the value for the claim. 下表列出对 Source 的每个值有效的 ID 值。The following table lists the values of ID valid for each value of Source.

表 3:每个 Source 的有效 ID 值Table 3: Valid ID values per source

Source IDID 说明Description
用户User surnamesurname 家族名称Family Name
用户User givennamegivenname Given Name
用户User displaynamedisplayname 显示名称Display Name
用户User objectidobjectid ObjectIDObjectID
用户User mailmail 电子邮件地址Email Address
用户User userprincipalnameuserprincipalname 用户主体名称User Principal Name
用户User departmentdepartment 部门Department
用户User onpremisessamaccountnameonpremisessamaccountname 本地 SAM 帐户名称On-premises SAM Account Name
用户User netbiosnamenetbiosname NetBios 名称NetBios Name
用户User dnsdomainnamednsdomainname DNS 域名DNS Domain Name
用户User onpremisesecurityidentifieronpremisesecurityidentifier 本地安全标识符On-premises Security Identifier
用户User companynamecompanyname 组织名称Organization Name
用户User streetaddressstreetaddress 街道地址Street Address
用户User postalcodepostalcode 邮政编码Postal Code
用户User preferredlanguagepreferredlanguage 首选语言Preferred Language
用户User onpremisesuserprincipalnameonpremisesuserprincipalname 本地 UPNOn-premises UPN *
用户User mailNicknamemailnickname 邮件别名Mail Nickname
用户User extensionattribute1extensionattribute1 扩展属性 1Extension Attribute 1
用户User extensionattribute2extensionattribute2 扩展属性 2Extension Attribute 2
用户User extensionattribute3extensionattribute3 扩展属性 3Extension Attribute 3
用户User extensionattribute4extensionattribute4 扩展属性 4Extension Attribute 4
用户User extensionattribute5extensionattribute5 扩展属性 5Extension Attribute 5
用户User extensionattribute6extensionattribute6 扩展属性 6Extension Attribute 6
用户User extensionattribute7extensionattribute7 扩展属性 7Extension Attribute 7
用户User extensionattribute8extensionattribute8 扩展属性 8Extension Attribute 8
用户User extensionattribute9extensionattribute9 扩展属性 9Extension Attribute 9
用户User extensionattribute10extensionattribute10 扩展属性 10Extension Attribute 10
用户User extensionattribute11extensionattribute11 扩展属性 11Extension Attribute 11
用户User extensionattribute12extensionattribute12 扩展属性 12Extension Attribute 12
用户User extensionattribute13extensionattribute13 扩展属性 13Extension Attribute 13
用户User extensionattribute14extensionattribute14 扩展属性 14Extension Attribute 14
用户User extensionattribute15extensionattribute15 扩展属性 15Extension Attribute 15
用户User othermailothermail 其他邮件Other Mail
用户User countrycountry 国家/地区Country/Region
用户User citycity 城市City
用户User statestate 状态State
用户User jobtitlejobtitle 职务Job Title
用户User employeeidemployeeid 员工 IDEmployee ID
用户User facsimiletelephonenumberfacsimiletelephonenumber 传真电话号码Facsimile Telephone Number
UserUser assignedrolesassignedroles 分配给用户的应用角色列表list of App roles assigned to user
application、resource、audienceapplication, resource, audience displaynamedisplayname 显示名称Display Name
application、resource、audienceapplication, resource, audience objectidobjectid ObjectIDObjectID
application、resource、audienceapplication, resource, audience 标记tags 服务主体标记Service Principal Tag
CompanyCompany tenantcountrytenantcountry 租户的国家/地区Tenant's country/region

TransformationID: 仅当 Source 元素设置为“transformation”时,才必须提供 TransformationID 元素。TransformationID: The TransformationID element must be provided only if the Source element is set to "transformation".

  • 此元素必须与 ClaimsTransformation 属性(定义如何生成此声明的数据)中的转换条目的 ID 元素匹配。This element must match the ID element of the transformation entry in the ClaimsTransformation property that defines how the data for this claim is generated.

声明类型: JwtClaimTypeSamlClaimType 元素定义此声明架构条目引用的声明。Claim Type: The JwtClaimType and SamlClaimType elements define which claim this claim schema entry refers to.

  • JwtClaimType 必须包含要在 JWT 中发出的声明的名称。The JwtClaimType must contain the name of the claim to be emitted in JWTs.
  • SamlClaimType 必须包含要在 SAML 令牌中发出的声明的 URI。The SamlClaimType must contain the URI of the claim to be emitted in SAML tokens.
  • onPremisesUserPrincipalName attribute: 使用替代 ID 时,本地属性 userPrincipalName 将与 Azure AD 属性 onPremisesUserPrincipalName 同步。onPremisesUserPrincipalName attribute: When using an Alternate ID, the on-premises attribute userPrincipalName is synchronized with the Azure AD attribute onPremisesUserPrincipalName. 此属性仅在以下情况下可用:备用 ID 已配置,但也可通过 MS Graph Beta (https://microsoftgraph.chinacloudapi.cn/beta/me/ ) 获取。This attribute is only available when Alternate ID is configured but is also available through MS Graph Beta: https://microsoftgraph.chinacloudapi.cn/beta/me/.

备注

受限声明集中的声明的 Name 和 URI 不能用于声明类型元素。Names and URIs of claims in the restricted claim set cannot be used for the claim type elements. 有关详细信息,请参阅本文后面的“例外和限制”部分。For more information, see the "Exceptions and restrictions" section later in this article.

声明转换Claims transformation

字符串: ClaimsTransformationString: ClaimsTransformation

数据类型: 具有一个或多个转换条目的 JSON BlobData 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: 使用 ID 元素可在 TransformationID 声明架构条目中引用此转换条目。ID: Use the ID element to reference this transformation entry in the TransformationID Claims Schema entry. 就此策略中的每个转换条目来说,该值必须唯一。This value must be unique for each transformation entry within this policy.

TransformationMethod: TransformationMethod 元素用于标识为生成声明的数据而执行的操作。TransformationMethod: The TransformationMethod element identifies which operation is performed to generate the data for the claim.

根据选择的方法,需要一组输入和输出。Based on the method chosen, a set of inputs and outputs is expected. 使用 InputClaimsInputParametersOutputClaims 元素定义输入和输出。Define the inputs and outputs by using the InputClaims, InputParameters and OutputClaims elements.

表 4:转换方法以及预期输入和输出Table 4: Transformation methods and expected inputs and outputs

TransformationMethodTransformationMethod 预期输入Expected input 预期输出Expected output 说明Description
联接Join string1、string2、分隔符string1, string2, separator outputClaimoutputClaim 联接输入字符串(之间使用分隔符)。Joins input strings by using a separator in between. 例如:string1:“foo@bar.com”、string2:“sandbox”、separator:“.”会生成 outputClaim:“foo@bar.com.sandbox”For example: string1:"foo@bar.com" , string2:"sandbox" , separator:"." results in outputClaim:"foo@bar.com.sandbox"
ExtractMailPrefixExtractMailPrefix 电子邮件或 UPNEmail or UPN 提取的字符串extracted string ExtensionAttributes 1-15 或为用户(例如 johndoe@contoso.com)存储 UPN 或电子邮件地址值的任何其他架构扩展。ExtensionAttributes 1-15 or any other Schema Extensions which are storing a UPN or email address value for the user e.g. johndoe@contoso.com. 提取电子邮件地址的本地部分。Extracts the local part of an email address. 例如:mail:“foo@bar.com”会生成 outputClaim:“foo”。For example: mail:"foo@bar.com" results in outputClaim:"foo". 如果未提供 @ 符号,则按原样返回原始输入字符串。If no @ sign is present, then the original input string is returned as is.

InputClaims: 使用 InputClaims 元素可将数据从声明架构条目传递给转换。InputClaims: Use an InputClaims element to pass the data from a claim schema entry to a transformation. 它具有两个属性:ClaimTypeReferenceIdTransformationClaimTypeIt has two attributes: ClaimTypeReferenceId and TransformationClaimType.

  • ClaimTypeReferenceId 与声明架构条目的 ID 元素联接在一起可查找相应的输入声明。ClaimTypeReferenceId is joined with ID element of the claim schema entry to find the appropriate input claim.
  • TransformationClaimType 用于向此输入提供唯一名称。TransformationClaimType is used to give a unique name to this input. 此名称必须与转换方法的预期输入之一匹配。This name must match one of the expected inputs for the transformation method.

InputParameters: 使用 InputParameters 元素可将常数值传递给转换。InputParameters: Use an InputParameters element to pass a constant value to a transformation. 它具有两个属性:ValueIDIt has two attributes: Value and ID.

  • Value 是要传递的实际常数值。Value is the actual constant value to be passed.
  • ID 用于为输入提供唯一名称。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: 使用 OutputClaims 元素可保存转换生成的数据,并将它绑定到声明架构条目。OutputClaims: Use an OutputClaims element to hold the data generated by a transformation, and tie it to a claim schema entry. 它具有两个属性:ClaimTypeReferenceIdTransformationClaimTypeIt has two attributes: ClaimTypeReferenceId and TransformationClaimType.

  • ClaimTypeReferenceId 与声明架构条目的 ID 联接在一起可查找相应的输出声明。ClaimTypeReferenceId is joined with the ID of the claim schema entry to find the appropriate output claim.
  • TransformationClaimType 用于为输出提供唯一名称。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 和 UPN: NameID 和 UPN 值所源自的属性以及允许使用的声明转换会受到限制。SAML NameID and UPN: The attributes from which you source the NameID and UPN values, and the claims transformations that are permitted, are limited. 请参阅表 5 和表 6 来查看允许的值。See table 5 and table 6 to see the permitted values.

表 5:允许作为 SAML NameID 数据源的属性Table 5: Attributes allowed as a data source for SAML NameID

Source IDID 说明Description
用户User mailmail 电子邮件地址Email Address
用户User userprincipalnameuserprincipalname 用户主体名称User Principal Name
用户User onpremisessamaccountnameonpremisessamaccountname 本地 Sam 帐户名称On Premises Sam Account Name
用户User employeeidemployeeid 员工 IDEmployee ID
用户User extensionattribute1extensionattribute1 扩展属性 1Extension Attribute 1
用户User extensionattribute2extensionattribute2 扩展属性 2Extension Attribute 2
用户User extensionattribute3extensionattribute3 扩展属性 3Extension Attribute 3
用户User extensionattribute4extensionattribute4 扩展属性 4Extension Attribute 4
用户User extensionattribute5extensionattribute5 扩展属性 5Extension Attribute 5
用户User extensionattribute6extensionattribute6 扩展属性 6Extension Attribute 6
用户User extensionattribute7extensionattribute7 扩展属性 7Extension Attribute 7
用户User extensionattribute8extensionattribute8 扩展属性 8Extension Attribute 8
用户User extensionattribute9extensionattribute9 扩展属性 9Extension Attribute 9
用户User extensionattribute10extensionattribute10 扩展属性 10Extension Attribute 10
用户User extensionattribute11extensionattribute11 扩展属性 11Extension Attribute 11
用户User extensionattribute12extensionattribute12 扩展属性 12Extension Attribute 12
用户User extensionattribute13extensionattribute13 扩展属性 13Extension Attribute 13
用户User extensionattribute14extensionattribute14 扩展属性 14Extension Attribute 14
用户User extensionattribute15extensionattribute15 扩展属性 15Extension Attribute 15

表 6:允许用于 SAML NameID 的转换方法Table 6: Transformation methods allowed for SAML NameID

TransformationMethodTransformationMethod 限制Restrictions
ExtractMailPrefixExtractMailPrefix None
联接Join 要联接的后缀必须是资源租户的已验证域。The suffix being joined must be a verified domain of the resource tenant.

自定义签名密钥Custom signing key

必须为服务主体对象分配自定义签名密钥,否则声明映射策略无法生效。A custom signing key must be assigned to the service principal object for a claims mapping policy to take effect. 这可以确保确认令牌是由声明映射策略的创建者修改的,并防止应用程序被恶意参与者创建的声明映射策略破坏。This ensures acknowledgment that tokens have been modified by the creator of the claims mapping policy and protects applications from claims mapping policies created by malicious actors. 若要添加自定义签名密钥,可以使用 Azure PowerShell cmdlet New-AzureADApplicationKeyCredential 为应用程序对象创建证书密钥凭据。In order to add a custom signing key, you can use the Azure PowerShell cmdlet New-AzureADApplicationKeyCredential to create a certificate key credential for your Application object.

启用了声明映射的应用必须通过将 appid={client_id} 追加到其 OpenID Connect 元数据请求来验证令牌签名密钥。Apps that have claims mapping enabled must validate their token signing keys by appending appid={client_id} to their OpenID Connect metadata requests. 下面是你应该使用的 OpenID 连接元数据文档的格式:Below is the format of the OpenID Connect metadata document you should use:

https://login.partner.microsoftonline.cn/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

跨租户方案Cross-tenant scenarios

声明映射策略不适用于来宾用户。Claims mapping policies do not apply to guest users. 如果来宾用户尝试访问向其服务主体分配了声明映射策略的应用程序,则会颁发默认令牌(策略不会生效)。If a guest user tries to access an application with a claims mapping policy assigned to its service principal, the default token is issued (the policy has no effect).

声明映射策略分配Claims mapping policy assignment

声明映射策略只能分配给服务主体对象。Claims mapping policies can only be assigned to service principal objects.

声明映射策略示例Example claims mapping policies

在 Azure AD 中,在可以为特定服务主体自定义令牌中发出的声明时,可以实现许多方案。In Azure AD, many scenarios are possible when you can customize claims emitted in tokens for specific service principals. 在此部分中,我们会演练几个常见方案,它们可帮助你理解如何使用声明映射策略类型。In this section, we walk through a few common scenarios that can help you grasp how to use the claims mapping policy type.

备注

创建声明映射策略时,还可以根据令牌中的目录架构扩展属性发出声明。When creating a claims mapping policy, you can also emit a claim from a directory schema extension attribute in tokens. 使用与扩展属性对应的 ExtensionID,而不是 ClaimsSchema 元素中的 ID。Use ExtensionID for the extension attribute instead of ID in the ClaimsSchema element. 有关扩展属性的更多信息,请参阅使用目录架构扩展属性For more info on extension attributes, see Using directory schema extension attributes.

先决条件Prerequisites

以下示例将创建、更新、链接和删除服务主体的策略。In the following examples, you create, update, link, and delete policies for service principals. 如果你是 Azure AD 新手,我们建议在继续学习这些示例之前,先了解如何获取 Azure AD 租户If you are new to Azure AD, we recommend that you learn about how to get an Azure AD tenant before you proceed with these examples.

若要开始,请执行以下步骤:To get started, do the following steps:

  1. 首先请下载最新的 Azure AD PowerShell 模块公共预览版Download the latest Azure AD PowerShell Module public preview release.

  2. 运行 Connect 命令,登录到 Azure AD 管理员帐户。Run the Connect command to sign in to your Azure AD admin account. 每次启动新会话都需要运行此命令。Run this command each time you start a new session.

    Connect-AzureAD -AzureEnvironmentName AzureChinaCloud -Confirm
    
  3. 若要查看组织中创建的所有策略,请运行以下命令。To see all policies that have been created in your organization, run the following command. 在以下方案中,建议在大多数操作之后运行此命令,以检查是否按预期创建策略。We recommend that you run this command after most operations in the following scenarios, to check that your policies are being created as expected.

    Get-AzureADPolicy
    

示例:创建并分配一个策略,以从颁发给服务主体的令牌中省略基本声明Example: Create and assign a policy to omit the basic claims from tokens issued to a service principal

在此示例中创建一个策略,它会从颁发给链接的服务主体的令牌中删除基本声明集。In this example, you create a policy that removes the basic claim set from tokens issued to linked service principals.

  1. 创建声明映射策略。Create a claims mapping policy. 此策略(链接到特定服务主体)会从令牌中删除基本声明集。This policy, linked to specific service principals, removes the basic claim set from tokens.
    1. 若要创建该策略,请运行以下命令:To create the policy, run this command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"false"}}') -DisplayName "OmitBasicClaims" -Type "ClaimsMappingPolicy"
      
    2. 若要查看新策略并获取其 ObjectId,请运行以下命令:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. 将策略分配到服务主体。Assign the policy to your service principal. 还需要获取服务主体的 ObjectId。You also need to get the ObjectId of your service principal.
    1. 若要查看组织的所有服务主体,可以查询 Microsoft Graph APITo see all your organization's service principals, you can query the Microsoft Graph API. 或者,在 Microsoft Graph Explorer 中登录到你的 Azure AD 帐户。Or, in Microsoft Graph Explorer, sign in to your Azure AD account.

    2. 获取服务主体的 ObjectId 后,运行以下命令:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

示例:创建并分配一个策略,以将 EmployeeID 和 TenantCountry 作为声明包含在颁发给服务主体的令牌中Example: Create and assign a policy to include the EmployeeID and TenantCountry as claims in tokens issued to a service principal

在此示例中创建一个策略,它会向颁发给链接的服务主体的令牌添加 EmployeeID 和 TenantCountry。In this example, you create a policy that adds the EmployeeID and TenantCountry to tokens issued to linked service principals. EmployeeID 在 SAML 令牌和 JWT 中都作为名称声明类型发出。The EmployeeID is emitted as the name claim type in both SAML tokens and JWTs. TenantCountry 在 SAML 令牌和 JWT 中都作为国家/地区声明类型发出。The TenantCountry is emitted as the country/region claim type in both SAML tokens and JWTs. 在此示例中,我们继续在令牌中包含基本声明集。In this example, we continue to include the basic claims set in the tokens.

  1. 创建声明映射策略。Create a claims mapping policy. 此策略(链接到特定服务主体)向令牌添加 EmployeeID 和 TenantCountry 声明。This policy, linked to specific service principals, adds the EmployeeID and TenantCountry claims to tokens.
    1. 若要创建该策略,请运行以下命令:To create the policy, run the following command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"employeeid","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid","JwtClaimType":"name"},{"Source":"company","ID":"tenantcountry","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country","JwtClaimType":"country"}]}}') -DisplayName "ExtraClaimsExample" -Type "ClaimsMappingPolicy"
      
    2. 若要查看新策略并获取其 ObjectId,请运行以下命令:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. 将策略分配到服务主体。Assign the policy to your service principal. 还需要获取服务主体的 ObjectId。You also need to get the ObjectId of your service principal.
    1. 若要查看组织的所有服务主体,可以查询 Microsoft Graph APITo see all your organization's service principals, you can query the Microsoft Graph API. 或者,在 Microsoft Graph Explorer 中登录到你的 Azure AD 帐户。Or, in Microsoft Graph Explorer, sign in to your Azure AD account.

    2. 获取服务主体的 ObjectId 后,运行以下命令:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

示例:创建并分配一个策略,以在颁发给服务主体的令牌中使用声明转换Example: Create and assign a policy that uses a claims transformation in tokens issued to a service principal

在此示例中创建一个策略,它会向颁发给链接的服务主体的 JWT 发出自定义声明“JoinedData”。In this example, you create a policy that emits a custom claim "JoinedData" to JWTs issued to linked service principals. 此声明包含通过将用户对象的 extensionattribute1 属性中存储的数据与“.sandbox”联接所创建的值。This claim contains a value created by joining the data stored in the extensionattribute1 attribute on the user object with ".sandbox". 在此示例中,我们在令牌中排除基本声明集。In this example, we exclude the basic claims set in the tokens.

  1. 创建声明映射策略。Create a claims mapping policy. 此策略(链接到特定服务主体)向令牌添加 EmployeeID 和 TenantCountry 声明。This policy, linked to specific service principals, adds the EmployeeID and TenantCountry claims to tokens.
    1. 若要创建该策略,请运行以下命令:To create the policy, run the following command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema":[{"Source":"user","ID":"extensionattribute1"},{"Source":"transformation","ID":"DataJoin","TransformationId":"JoinTheData","JwtClaimType":"JoinedData"}],"ClaimsTransformations":[{"ID":"JoinTheData","TransformationMethod":"Join","InputClaims":[{"ClaimTypeReferenceId":"extensionattribute1","TransformationClaimType":"string1"}], "InputParameters": [{"ID":"string2","Value":"sandbox"},{"ID":"separator","Value":"."}],"OutputClaims":[{"ClaimTypeReferenceId":"DataJoin","TransformationClaimType":"outputClaim"}]}]}}') -DisplayName "TransformClaimsExample" -Type "ClaimsMappingPolicy"
      
    2. 若要查看新策略并获取其 ObjectId,请运行以下命令:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. 将策略分配到服务主体。Assign the policy to your service principal. 还需要获取服务主体的 ObjectId。You also need to get the ObjectId of your service principal.
    1. 若要查看组织的所有服务主体,可以查询 Microsoft Graph APITo see all your organization's service principals, you can query the Microsoft Graph API. 或者,在 Microsoft Graph Explorer 中登录到你的 Azure AD 帐户。Or, in Microsoft Graph Explorer, sign in to your Azure AD account.

    2. 获取服务主体的 ObjectId 后,运行以下命令:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

另请参阅See also