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

Статья
01/22/2024

Примечание.

В Azure Active Directory B2C пользовательские политики преимущественно предназначены для выполнения сложных сценариев. В большинстве случаев рекомендуется использовать встроенные потоки пользователей. Ознакомьтесь со статьей Начало работы с настраиваемыми политиками в Azure Active Directory B2C, чтобы узнать о базовом пакете настраиваемых политик, если еще не сделали этого.

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

Протокол

Атрибуту Name элемента Protocol необходимо присвоить значение Proprietary. Атрибут handler должен содержать полное имя сборки обработчика протокола, которое используется 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, а surname — с именем lastName. Утверждение email сохраняется неизменным.

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

Элемент InputClaimsTransformations может содержать коллекцию элементов InputClaimsTransformation, которые используются для изменения входных утверждений или создания новых перед отправкой их в REST API.

Отправка полезных данных JSON

Технический профиль REST API позволяет отправлять в конечную точку сложные полезные данные JSON.

Для отправки сложных полезных данных JSON выполните следующие действия.

Создайте полезные данные JSON путем преобразования утверждений GenerateJson.
В техническом профиле 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, которое сопоставляется с именем утверждения loyaltyNumber.

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

Утверждение LoyaltyNumberIsNew, для которого установлено значение по умолчанию true.

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

Метаданные

Атрибут	Обязательное поле	Описание
ServiceUrl	Да	URL-адрес конечной точки REST API.
authenticationType	Да	Тип аутентификации, выполняемый поставщиком утверждений RESTful. Возможные значения: `None`, `Basic`, `Bearer`, `ClientCertificate` или `ApiKeyHeader`. Значение `None` указывает, что REST API анонимен. Значение `Basic` указывает, что REST API защищен помощью базовой проверки подлинности HTTP. Доступ к API могут получить только проверенные пользователи, включая Azure AD B2C. Значение `ClientCertificate` (рекомендуется) указывает, что REST API ограничивает доступ с помощью проверки подлинности на основе сертификата клиента. Доступ к вашему API могут получить только службы, у которых есть соответствующие сертификаты, например Azure AD B2C. Значение `Bearer` указывает, что REST API ограничивает доступ с помощью маркера носителя OAuth2 клиента. Значение `ApiKeyHeader` указывает, что REST API защищен с помощью HTTP-заголовка ключа API, такого как x-functions-key.
AllowInsecureAuthInProduction	No	Указывает, можно ли задать для параметра `AuthenticationType` значение `none` в рабочей среде (параметр `DeploymentMode` свойства TrustFrameworkPolicy имеет значение `Production` или не указано). Возможные значения: true или false (по умолчанию).
SendClaimsIn	No	Указывает, как отправляются входящие утверждения поставщику утверждений RESTful. Возможные значения: `Body` (по умолчанию), `Form`, `Header`, `Url` или `QueryString`. Значение `Body` обозначает входящее утверждение, которое отправляется в тексте запроса в формате JSON. Значение `Form` обозначает входящее утверждение, которое отправляется в тексте запроса в формате пар "ключ-значение", разделенных символом амперсанда (&). Значение `Header` обозначает входящее утверждение, которое отправляется в заголовке запроса. Значение `Url` указывает входящее утверждение, которое отправляется в URL-адресе, например `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`. Часть имени узла в URL-адресе не может содержать утверждения. Значение `QueryString` обозначает входящее утверждение, которое отправляется в строке запроса. HTTP-команды, вызываемые каждым из них, имеют следующий вид. `Body`: POST `Form`: POST `Header`: GET `Url`: GET `QueryString`: GET
ClaimsFormat	No	В настоящее время не используется, можно игнорировать.
ClaimUsedForRequestPayload	No	Имя строкового утверждения, содержащего полезные данные, для отправки в REST API.
DebugMode	No	Выполняет технический профиль в режиме отладки. Возможные значения: `true` или `false` (по умолчанию). В режиме отладки REST API может возвращать больше информации. См. раздел Возвращаемое сообщение об ошибке.
IncludeClaimResolvingInClaimsHandling	No	Для входящих и исходящих утверждений указывает, включено ли разрешение утверждений в технический профиль. Возможные значения: `true` или `false` (по умолчанию). Если вы хотите использовать сопоставитель утверждений в техническом профиле, задайте для этого параметра значение `true`.
ResolveJsonPathsInJsonTokens	No	Указывает, сопоставляет ли технический профиль пути JSON. Возможные значения: `true` или `false` (по умолчанию). Используйте эти метаданные для чтения данных из вложенного элемента JSON. В разделе OutputClaim установите параметр `PartnerClaimType` на значение элемента пути JSON, который хотите вывести. Например, `firstName.localized` или `data[0].to[0].email`.
UseClaimAsBearerToken	No	Имя утверждения, содержащего маркер носителя.

Обработка ошибок

Следующие метаданные можно использовать для настройки сообщений об ошибках, отображаемых при сбое REST API. Сообщения об ошибках можно локализовать.

Атрибут	Обязательное поле	Описание
DefaultUserMessageIfRequestFailed	No	Сообщение об ошибке, заданное по умолчанию для всех исключений REST API.
UserMessageIfCircuitOpen	No	Сообщение об ошибке, если REST API недоступен. Если не задано, возвращается DefaultUserMessageIfRequestFailed.
UserMessageIfDnsResolutionFailed	No	Сообщение об ошибке для исключения разрешения DNS. Если не задано, возвращается DefaultUserMessageIfRequestFailed.
UserMessageIfRequestTimeout	No	Сообщение об ошибке при истечении времени ожидания подключения. Если не задано, возвращается DefaultUserMessageIfRequestFailed.

Криптографические ключи

Если тип аутентификации имеет значение 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 содержит следующие атрибуты:

Атрибут	Обязательное поле	Описание
BasicAuthenticationUsername	Да	Имя пользователя, которое используется для аутентификации.
BasicAuthenticationPassword	Да	Пароль, который используется для аутентификации.

Следующий пример демонстрирует технический профиль с базовой проверкой подлинности:

<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 содержит следующий атрибут:

Атрибут	Обязательное поле	Описание
ClientCertificate	Да	Сертификат X509 (набор ключей RSA), используемый для аутентификации.

<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 содержит следующий атрибут:

Атрибут	Обязательное поле	Описание
BearerAuthenticationToken	No	Маркер носителя OAuth 2.0.

<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 содержит следующий атрибут:

Атрибут	Обязательное поле	Описание
Имя заголовка HTTP, например `x-functions-key` или `x-api-key`.	Да	Ключ, используемый для проверки подлинности.

Примечание.

В настоящее время Azure AD B2C поддерживает только один заголовок HTTP для проверки подлинности. Если для вызова RESTful требуется несколько заголовков, например идентификатор клиента и секрет клиента, необходимо выполнить запрос через прокси-сервер.

<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 может возвращать сообщения об ошибках, например The user was not found in the CRM system (Пользователь не найден в системе 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"
}

Атрибут	Обязательное поле	Описание
версия	Да	Ваша версия REST API. Например: 1.0.1.
статус	Да	Коды состояния HTTP-ответа, например число, и должно иметь значение 409. Служба REST может возвращать код состояния HTTP 4XX, но значение `status` , поданное в текст ответа в формате JSON, должно быть `409`.
кодом	No	Код ошибки, полученный от поставщика конечной точки RESTful, который отображается при включении `DebugMode`.
requestId	No	Идентификатор запроса, полученный от поставщика конечной точки RESTful, который отображается при включении `DebugMode`.
userMessage	Да	Сообщение об ошибке, которое отображается для пользователя.
developerMessage	No	Подробное описание проблемы и методов ее исправления, которое отображается при включении `DebugMode`.
moreInfo	No	URI, который указывает на дополнительную информацию, которая отображается при включении `DebugMode`.

Следующий пример демонстрирует класс 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 см. в следующих статьях: