Определение технического профиля RESTful в пользовательской политике Azure Active Directory B2C

Azure Active Directory B2C (Azure AD B2C) обеспечивает поддержку интеграции собственной службы RESTful. Azure AD B2C отправляет данные в службу RESTful в коллекции входных утверждений и получает данные обратно в коллекции выходных утверждений. Дополнительные сведения см. в статье Интеграция обмена утверждениями REST API в настраиваемой политике Azure AD B2C.

Протокол

Атрибуту Name элемента Protocol необходимо присвоить значение Proprietary. Атрибут обработчика должен содержать полное имя сборки обработчика протокола, которая используется 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 отправляется в REST API как firstName, а фамилия отправляется как 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. Создайте полезные данные JSON с помощью преобразования утверждений GenerateJson .
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:

• Утверждение MembershipId, сопоставленного с именем утверждения лояльностиNumber.

Технический профиль также возвращает утверждения, которые не возвращаются поставщиком удостоверений:

• Утверждение loyaltyNumberIsNew с заданным значением 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.azurewebsites.NET/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.azurewebsites.NET/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.azurewebsites.NET/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.azurewebsites.NET/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.azurewebsites.NET/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; }
}

Дальнейшие шаги

Примеры использования технического профиля RESTful см. в следующих статьях:

• Интеграция обмена утверждениями REST API в настраиваемой политике Azure AD B2C
• Пошаговое руководство: добавление соединителя API в поток регистрации пользователей
• Пошаговое руководство. Добавление обмена утверждениями REST API в пользовательские политики в Azure Active Directory B2C
• Защита служб REST API