在 Azure Active Directory B2C 自定义策略中定义 Azure Active Directory 技术配置文件Define an Azure Active Directory technical profile in an Azure Active Directory B2C custom policy

备注

在 Azure Active Directory B2C 中,custom policies 主要用于解决复杂方案。In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. 大多数情况下,建议使用内置的用户流For most scenarios, we recommend that you use built-in user flows.

Azure Active Directory B2C (Azure AD B2C) 为 Azure Active Directory 用户管理提供支持。Azure Active Directory B2C (Azure AD B2C) provides support for the Azure Active Directory user management. 本文介绍了与支持此标准化协议的声明提供程序进行交互的技术配置文件的详细信息。This article describes the specifics of a technical profile for interacting with a claims provider that supports this standardized protocol.

协议Protocol

“Protocol”元素的“Name”属性必须设置为 ProprietaryThe Name attribute of the Protocol element needs to be set to Proprietary. handler 属性必须包含协议处理程序程序集 Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null 的完全限定名称。The handler attribute must contain the fully qualified name of the protocol handler assembly Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

以下自定义策略初学者包 Azure AD 技术配置文件包含 AAD-Common 技术配置文件。Following custom policy starter pack Azure AD technical profiles include the AAD-Common technical profile. Azure AD 技术配置文件不会指定协议,因为协议在 AAD-Common 技术配置文件中进行配置:The Azure AD technical profiles don't specify the protocol because the protocol is configured in the AAD-Common technical profile:

  • AAD-UserReadUsingAlternativeSecurityIdAAD-UserReadUsingAlternativeSecurityId-NoError - 在目录中查找社交帐户。AAD-UserReadUsingAlternativeSecurityId and AAD-UserReadUsingAlternativeSecurityId-NoError - Look up a social account in the directory.
  • AAD-UserWriteUsingAlternativeSecurityId - 创建新的社交帐户。AAD-UserWriteUsingAlternativeSecurityId - Create a new social account.
  • AAD-UserReadUsingEmailAddress - 在目录中查找本地帐户。AAD-UserReadUsingEmailAddress - Look up a local account in the directory.
  • AAD-UserWriteUsingLogonEmail - 创建新的本地帐户。AAD-UserWriteUsingLogonEmail - Create a new local account.
  • AAD-UserWritePasswordUsingObjectId - 更新本地帐户的密码。AAD-UserWritePasswordUsingObjectId - Update a password of a local account.
  • AAD-UserWriteProfileUsingObjectId - 更新本地或社交帐户的用户配置文件。AAD-UserWriteProfileUsingObjectId - Update a user profile of a local or social account.
  • AAD-UserReadUsingObjectId - 读取本地或社交帐户的用户配置文件。AAD-UserReadUsingObjectId - Read a user profile of a local or social account.
  • AAD-UserWritePhoneNumberUsingObjectId - 写入本地或社交帐户的 MFA 电话号码AAD-UserWritePhoneNumberUsingObjectId - Write the MFA phone number of a local or social account

以下示例演示了 AAD-Common 技术配置文件:The following example shows the AAD-Common technical profile:

<TechnicalProfile Id="AAD-Common">
  <DisplayName>Azure Active Directory</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

  <CryptographicKeys>
    <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
  </CryptographicKeys>

  <!-- We need this here to suppress the SelfAsserted provider from invoking SSO on validation profiles. -->
  <IncludeInSso>false</IncludeInSso>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

InputClaimsInputClaims

InputClaims 元素包含一个声明,该声明用于在目录中查找帐户,或创建一个新帐户。The InputClaims element contains a claim, which is used to look up an account in the directory, or create a new one. 所有 Azure AD 技术配置文件的输入声明集合中必须有且只有一个 InputClaim 元素。There must be exactly one InputClaim element in the input claims collection for all Azure AD technical profiles. 可能需要将策略中定义的声明名称映射到 Azure Active Directory 中定义的名称。You may need to map the name of the claim defined in your policy to the name defined in Azure Active Directory.

若要读取、更新或删除现有用户帐户,输入声明是在 Azure AD 目录中唯一标识该帐户的键。To read, update, or delete an existing user account, the input claim is a key that uniquely identifies the account in Azure AD directory. 例如,objectIduserPrincipalNamesignInNames.emailAddresssignInNames.userNamealternativeSecurityIdFor example, objectId, userPrincipalName, signInNames.emailAddress, signInNames.userName, or alternativeSecurityId.

若要新建用户帐户,输入声明是唯一标识本地帐户或联合帐户的键。To create a new user account, the input claim is a key that uniquely identifies a local or federated account. 例如,对于本地帐户,为:signInNames.emailAddresssignInNames.userNameFor example, local account: signInNames.emailAddress, or signInNames.userName. 对于联合帐户,为:alternativeSecurityIdFor a federated account: the alternativeSecurityId.

InputClaimsTransformations 元素可以包含一组输入声明转换元素,这些元素用于修改输入声明或生成新的声明。The InputClaimsTransformations element may contain a collection of input claims transformation elements that are used to modify the input claim or generate new one.

OutputClaimsOutputClaims

OutputClaims 元素包含 Azure AD 技术配置文件返回的声明列表。The OutputClaims element contains a list of claims returned by the Azure AD technical profile. 可能需要将策略中定义的声明名称映射到 Azure Active Directory 中定义的名称。You may need to map the name of the claim defined in your policy to the name defined in Azure Active Directory. 如果设置了 DefaultValue 属性,则还可以包含 Azure Active Directory 不会返回的声明。You can also include claims that aren't returned by the Azure Active Directory, as long as you set the DefaultValue attribute.

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。The OutputClaimsTransformations element may contain a collection of OutputClaimsTransformation elements that are used to modify the output claims or generate new ones.

例如,AAD-UserWriteUsingLogonEmail 技术配置文件可创建本地帐户并返回以下声明:For example, the AAD-UserWriteUsingLogonEmail technical profile creates a local account and returns the following claims:

  • objectId:新帐户的标识符objectId, which is identifier of the new account
  • newUser:指示用户是否为新用户newUser, which indicates whether the user is new
  • authenticationSource:将身份验证设置为 localAccountAuthenticationauthenticationSource, which sets authentication to localAccountAuthentication
  • userPrincipalName:新帐户的用户主体名称userPrincipalName, which is the user principal name of the new account
  • signInNames.emailAddress:帐户登录名,类似于 email 输入声明signInNames.emailAddress, which is the account sign-in name, similar to the email input claim
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="objectId" />
  <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="localAccountAuthentication" />
  <OutputClaim ClaimTypeReferenceId="userPrincipalName" />
  <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
</OutputClaims>

PersistedClaimsPersistedClaims

PersistedClaims 元素包含 Azure AD 应持久保存的所有值,以及策略的 ClaimsSchema 节中已定义的声明类型与 Azure AD 属性名称之间可能的映射信息。The PersistedClaims element contains all of the values that should be persisted by Azure AD with possible mapping information between a claim type already defined in the ClaimsSchema section in the policy and the Azure AD attribute name.

AAD-UserWriteUsingLogonEmail 技术配置文件,它可以创建新本地帐户并保存以下声明:The AAD-UserWriteUsingLogonEmail technical profile, which creates new local account, persists following claims:

  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="email" PartnerClaimType="signInNames.emailAddress" />
    <PersistedClaim ClaimTypeReferenceId="newPassword" PartnerClaimType="password"/>
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="passwordPolicies" DefaultValue="DisablePasswordExpiration" />

    <!-- Optional claims. -->
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>

除非指定了包含 Azure AD 属性名称的 PartnerClaimType 属性,否则声明名称是 Azure AD 属性的名称。The name of the claim is the name of the Azure AD attribute unless the PartnerClaimType attribute is specified, which contains the Azure AD attribute name.

操作要求Requirements of an operation

  • 所有 Azure AD 技术配置文件的声明包中必须刚好有一个 InputClaim 元素。There must be exactly one InputClaim element in the claims bag for all Azure AD technical profiles.
  • “用户配置文件属性”一文介绍了可在输入声明、输出声明和持久化声明中使用的受支持 Azure AD B2C 用户配置文件属性。The user profile attributes article describes the supported Azure AD B2C user profile attributes you can use in the input claims, output claims, and persisted claims.
  • 如果操作为 WriteDeleteClaims,则 PersistedClaims 元素中也必须包含此操作。If the operation is Write or DeleteClaims, then it must also appear in a PersistedClaims element.
  • userPrincipalName 声明的值必须采用 user@tenant.partner.onmschina.cn 格式。The value of the userPrincipalName claim must be in the format of user@tenant.partner.onmschina.cn.
  • displayName 声明是必需的,不能为空字符串。The displayName claim is required and cannot be an empty string.

Azure AD 技术提供程序操作Azure AD technical provider operations

读取Read

Read 操作读取有关单个用户帐户的数据。The Read operation reads data about a single user account. 以下技术配置文件使用用户的 objectId 读取有关用户帐户的数据:The following technical profile reads data about a user account using the user's objectId:

<TechnicalProfile Id="AAD-UserReadUsingObjectId">
  <Metadata>
    <Item Key="Operation">Read</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalDoesNotExist">true</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims>

    <!-- Required claims -->
    <OutputClaim ClaimTypeReferenceId="strongAuthenticationPhoneNumber" />

    <!-- Optional claims -->
    <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
    <OutputClaim ClaimTypeReferenceId="displayName" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
    <OutputClaim ClaimTypeReferenceId="givenName" />
    <OutputClaim ClaimTypeReferenceId="surname" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

写入Write

Write 操作创建或更新单个用户帐户。The Write operation creates or updates a single user account. 以下技术配置文件创建新社交帐户:The following technical profile creates new social account:

<TechnicalProfile Id="AAD-UserWriteUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">Write</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalAlreadyExists">true</Item>
    <Item Key="UserMessageIfClaimsPrincipalAlreadyExists">You are already registered, please press the back button and sign in instead.</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="CreateOtherMailsFromEmail" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="AlternativeSecurityId" PartnerClaimType="alternativeSecurityId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <PersistedClaim ClaimTypeReferenceId="userPrincipalName" />
    <PersistedClaim ClaimTypeReferenceId="mailNickName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />

    <!-- Optional claims -->
    <PersistedClaim ClaimTypeReferenceId="otherMails" />
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

DeleteClaimsDeleteClaims

DeleteClaims 操作从提供的声明列表中清除信息。The DeleteClaims operation clears the information from a provided list of claims. 以下技术配置文件删除声明:The following technical profile deletes claims:

<TechnicalProfile Id="AAD-DeleteClaimsUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaims</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <PersistedClaim ClaimTypeReferenceId="objectId" />
    <PersistedClaim ClaimTypeReferenceId="Verified.strongAuthenticationPhoneNumber" PartnerClaimType="strongAuthenticationPhoneNumber" />
  </PersistedClaims>
  <OutputClaims />
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

DeleteClaimsPrincipalDeleteClaimsPrincipal

DeleteClaimsPrincipal 操作从目录中删除单个用户帐户。The DeleteClaimsPrincipal operation deletes a single user account from the directory. 以下技术配置文件使用用户主体名称从目录中删除用户帐户:The following technical profile deletes a user account from the directory using the user principal name:

<TechnicalProfile Id="AAD-DeleteUserUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

以下技术配置文件使用 alternativeSecurityId 删除社交用户帐户:The following technical profile deletes a social user account using alternativeSecurityId:

<TechnicalProfile Id="AAD-DeleteUserUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

元数据Metadata

AttributeAttribute 必选Required 说明Description
OperationOperation Yes 要执行的操作。The operation to be performed. 可能的值:ReadWriteDeleteClaimsDeleteClaimsPrincipalPossible values: Read, Write, DeleteClaims, or DeleteClaimsPrincipal.
RaiseErrorIfClaimsPrincipalDoesNotExistRaiseErrorIfClaimsPrincipalDoesNotExist No 如果目录中不存在该用户对象,则引发错误。Raise an error if the user object does not exist in the directory. 可能的值:truefalsePossible values: true or false.
RaiseErrorIfClaimsPrincipalAlreadyExistsRaiseErrorIfClaimsPrincipalAlreadyExists No 如果该用户对象已存在,则引发错误。Raise an error if the user object already exists. 可能的值:truefalsePossible values: true or false.
ApplicationObjectIdApplicationObjectId No 扩展属性的应用程序对象标识符。The application object identifier for extension attributes. 值:应用程序的 ObjectId。Value: ObjectId of an application.
ClientIdClientId No 作为第三方访问租户的客户端标识符。The client identifier for accessing the tenant as a third party.
IncludeClaimResolvingInClaimsHandlingIncludeClaimResolvingInClaimsHandling   No 对于输入和输出声明,指定声明解析是否包含在技术配置文件中。For input and output claims, specifies whether claims resolution is included in the technical profile. 可能的值:truefalse (默认值)。Possible values: true, or false (default). 若要使用技术配置文件中的声明解析程序,请将此项设为 trueIf you want to use a claims resolver in the technical profile, set this to true.

UI 元素UI elements

以下设置可用于配置失败时显示的错误消息。The following settings can be used to configure the error message displayed upon failure. 元数据应该在自断言技术配置文件中进行配置。The metadata should be configured in the self-asserted technical profile. 可以将错误消息本地化The error messages can be localized.

AttributeAttribute 必选Required 说明Description
UserMessageIfClaimsPrincipalAlreadyExistsUserMessageIfClaimsPrincipalAlreadyExists No 如果要引发错误(参阅 RaiseErrorIfClaimsPrincipalAlreadyExists 属性说明),则指定当用户对象已存在时要向用户显示的消息。If an error is to be raised (see RaiseErrorIfClaimsPrincipalAlreadyExists attribute description), specify the message to show to the user if user object already exists.
UserMessageIfClaimsPrincipalDoesNotExistUserMessageIfClaimsPrincipalDoesNotExist No 如果要引发错误(参阅 RaiseErrorIfClaimsPrincipalDoesNotExist 属性说明),则指定当用户对象不存在时要向用户显示的消息。If an error is to be raised (see the RaiseErrorIfClaimsPrincipalDoesNotExist attribute description), specify the message to show to the user if user object does not exist.