在 Azure Active Directory B2C 自定义策略中定义 RESTful 技术配置文件

Azure Active Directory B2C （Azure AD B2C） 支持集成自己的 RESTful 服务。 Azure AD B2C 将数据发送到输入声明集合中的 RESTful 服务，并在输出声明集合中接收数据。

协议

“Protocol”元素的“Name”属性必须设置为 。 处理程序属性必须包含 Azure AD B2C 使用的协议处理程序程序集的完全限定名称： Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

以下示例显示了 RESTful 技术配置文件：

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

输入声明

InputClaims 元素包含要发送到 REST API 的声明列表。 还可以将声明的名称映射到 REST API 中定义的名称。 以下示例显示了策略与 REST API 之间的映射。 givenName 声明作为 firstName 发送到 REST API，而姓氏作为 lastName 发送。 电子邮件声明按原样设置。

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

InputClaimsTransformations 元素可能包含 InputClaimsTransformation 元素的集合，这些元素用于在发送到 REST API 之前修改输入声明或生成新元素。

发送 JSON 有效负载

REST API 技术配置文件允许将复杂的 JSON 有效负载发送到终结点。

发送复杂的 JSON 有效负载：

1. 使用 GenerateJson 声明转换生成 JSON 有效负载。
2. 在 REST API 技术配置文件中：
   1. 添加具有对声明转换的引用的 GenerateJson 输入声明转换。
   2. 将 SendClaimsIn 元数据选项设置为 body
   3. 将 ClaimUsedForRequestPayload 元数据选项设置为包含 JSON 有效负载的声明的名称。
   4. 在输入声明中，添加对包含 JSON 有效负载的输入声明的引用。

以下示例 TechnicalProfile 使用第三方电子邮件服务（在本例中为 SendGrid）发送验证电子邮件。

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

输出声明

OutputClaims 元素包含 REST API 返回的声明列表。 可能需要将策略中定义的声明的名称映射到 REST API 中定义的名称。 还可以包含 REST API 不返回的声明，只要设置 DefaultValue 属性。

OutputClaimsTransformations 元素可能包含用于修改输出声明或生成新输出声明的 OutputClaimsTransformation 元素集合。

以下示例演示 REST API 返回的声明：

• 映射到 loyaltyNumber 声明名称的 MembershipId 声明。

技术配置文件还返回标识提供者未返回的声明：

• 将默认值设置为的 true 声明。

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

元数据

错误处理

以下元数据可用于配置 REST API 失败时显示的错误消息。 可以将错误消息本地化。

加密密钥

如果身份验证类型设置为 None，则不使用 CryptographicKeys 元素。

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.chinacloudsites.cn/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

如果身份验证类型设置为 Basic， 则 CryptographicKeys 元素包含以下属性：

以下示例显示了具有基本身份验证的技术配置文件：

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.chinacloudsites.cn/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

如果身份验证类型设置为 ClientCertificate， 则 CryptographicKeys 元素包含以下属性：

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.chinacloudsites.cn/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

如果身份验证类型设置为 Bearer， 则 CryptographicKeys 元素包含以下属性：

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.chinacloudsites.cn/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

如果身份验证类型设置为 ApiKeyHeader， 则 CryptographicKeys 元素包含以下属性：

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.chinacloudsites.cn/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

返回验证错误消息

REST API 可能需要返回错误消息，例如“在 CRM 系统中找不到用户”。 如果发生错误，REST API 应返回 HTTP 4xx 错误消息，例如 400（错误请求）或 409（冲突）响应状态代码。 响应正文包含 JSON 格式的错误消息：

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}

以下示例演示返回错误消息的 C# 类：

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}