Defina um perfil técnico RESTful em uma política personalizada do Azure Active Directory B2C

Artigo
01/22/2024

Observação

No Azure Active Directory B2C, as políticas personalizadas são projetadas principalmente para tratar de cenários complexos. Para a maioria dos cenários, recomendamos que você use fluxos de usuários predefinidos. Se você ainda não fez isso, saiba mais sobre o pacote de início de política personalizado em Introdução às políticas personalizadas no Active Directory B2C.

O Azure AD B2C (Azure Active Directory B2C) fornece suporte para integrar seu serviço RESTful. O Azure AD B2C envia dados para o serviço RESTful na entrada de uma coleção de declarações e recebe dados de volta em uma coleção de declarações de saída. Para obter mais informações, confira como Integrar trocas de declarações da API REST em sua política personalizada do Azure AD B2C.

Protocolo

O atributo Name do elemento Protocol precisa ser definido como Proprietary. O atributo manipulador deve conter o nome totalmente qualificado do assembly do manipulador de protocolo usado pelo Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

O exemplo a seguir mostra um perfil técnico 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" />
  ...

Declarações de entrada

O elemento InputClaims contém uma lista de declarações a serem enviadas para a API REST. Você também pode mapear o nome de sua declaração para o nome definido na API REST. O exemplo a seguir mostra o mapeamento entre sua política e a API REST. A declaração givenName é enviada para a API REST como firstName, enquanto surname é enviado como lastName. O A declaração de email é definida como está.

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

O elemento InputClaimsTransformations elemento pode conter uma coleção de elementos InputClaimsTransformation elementos usados para modificar as declarações de entrada ou gerar novas antes do envio à API REST.

Enviar um conteúdo JSON

O perfil técnico da API REST permite enviar um conteúdo JSON complexo a um ponto de extremidade.

Para enviar um conteúdo JSON complexo:

Crie seu conteúdo JSON com a transformação de declarações GenerateJson.
No perfil técnico da API REST:
1. Adicione uma transformação de declarações de entrada com uma referência à transformação de declarações GenerateJson.
2. Definir a opção de metadados SendClaimsIn como body
3. Defina a opção de metadados ClaimUsedForRequestPayload como o nome da declaração que contém o conteúdo JSON.
4. Na declaração de entrada, adicione uma referência à declaração de entrada que contém um conteúdo JSON.

No exemplo a seguir, o TechnicalProfile envia um email de verificação usando um serviço de email de terceiros (o SendGrid, neste caso).

<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>

Declarações de saída

O elemento OutputClaims contém uma lista de declarações retornadas pela API REST. Talvez seja necessário mapear o nome da declaração definida em sua política para o nome definido na API REST. Você também pode incluir declarações que não são retornadas pela API REST, desde que você defina o atributo DefaultValue.

O elemento OutputClaimsTransformations pode conter uma coleção de elementos OutputClaimsTransformation usados para modificar as declarações de saída ou gerar novas declarações.

O exemplo a seguir mostra a declaração retornada pela API REST:

A declaração MembershipId mapeada para o nome da declaração loyaltyNumber.

O perfil técnico também retorna declarações que não são retornadas pelo provedor de identidade:

A declaração loyaltyNumberIsNew que tem um valor padrão definido como true.

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

Metadados

Atributo	Obrigatório	Descrição
ServiceUrl	Sim	A URL do ponto de extremidade da API REST.
AuthenticationType	Sim	O tipo de autenticação que está sendo executada pelo provedor de declarações RESTful. Valores possíveis: `None`, `Basic`, `Bearer`, `ClientCertificate`, ou `ApiKeyHeader`. O valor `None` indica que a API REST é anônima. O valor `Basic` indica que a API REST está protegida com a autenticação Básica HTTP. Somente usuários verificados, incluindo Azure AD B2C, podem acessar a API. O valor `ClientCertificate` (recomendado) indica que a API REST restringe o acesso usando uma autenticação de certificado do cliente. Somente os serviços com certificados apropriados, como o Azure AD B2C, podem acessar sua API. O valor `Bearer` indica que a API REST restringe o acesso usando o Token de Portador do OAuth 2.0 do cliente. O valor `ApiKeyHeader` indica que a API REST está protegida com um cabeçalho HTTP da chave de API, como x-functions-key.
AllowInsecureAuthInProduction	Não	Indica se o `AuthenticationType` pode ser definido como `none` no ambiente de produção (o `DeploymentMode` do TrustFrameworkPolicy é definido como `Production` ou não é especificado). Valores possíveis: true ou false (padrão).
SendClaimsIn	Não	Especifica como as declarações de entrada são enviadas para o provedor de declarações RESTful. Valores possíveis: `Body` (padrão), `Form`, `Header`, `Url` ou `QueryString`. O valor `Body` é a declaração de entrada enviada no corpo da solicitação no formato JSON. O valor `Form` é a declaração de entrada enviada no corpo da solicitação em um formato de valor de chave separado de e comercial '&'. O valor `Header` é a declaração de entrada enviada no cabeçalho da solicitação. O valor `Url` é a declaração de entrada enviada na URL, por exemplo, `https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}`. A parte do nome do host da URL não pode conter declarações. O valor `QueryString` é a declaração de entrada enviada na cadeia de caracteres de consulta da solicitação. Os verbos HTTP invocados por eles são os seguintes: `Body`: POST `Form`: POST `Header`: GET `Url`: GET `QueryString`: GET
ClaimsFormat	Não	Não usado no momento, pode ser ignorado.
ClaimUsedForRequestPayload	Não	Nome de uma declaração de cadeia de caracteres que contém o conteúdo a ser enviado à API REST.
DebugMode	Não	Executa o perfil técnico no modo de depuração. Valores possíveis: `true` ou `false` (padrão). No modo de depuração, a API REST pode retornar mais informações. Confira a seção Como retornar mensagem de erro.
IncludeClaimResolvingInClaimsHandling	Não	Em declarações de entrada e saída, especifica se a resolução de declarações está incluída no perfil técnico. Valores possíveis: `true` ou `false` (padrão). Se você quiser usar um resolvedor de declarações no perfil técnico, defina como `true`.
ResolveJsonPathsInJsonTokens	Não	Indica se o perfil técnico resolve caminhos JSON. Valores possíveis: `true` ou `false` (padrão). Use esses metadados para ler os dados de um elemento JSON aninhado. Em OutputClaim, defina o `PartnerClaimType` como o elemento do caminho JSON que você deseja gerar. Por exemplo: `firstName.localized` ou `data[0].to[0].email`.
UseClaimAsBearerToken	Não	O nome da declaração que contém o token de portador.

Tratamento de erros

Os metadados a seguir poderão ser usados para configurar mensagens de erro exibidas quando houver falha na API REST. A mensagem de erro pode ser localizada.

Atributo	Obrigatório	Descrição
DefaultUserMessageIfRequestFailed	Não	Um tipo de mensagem de erro padrão personalizada usada em todas as exceções da API REST.
UserMessageIfCircuitOpen	Não	Um tipo de mensagem de erro exibida quando a API REST não está acessível. Caso não seja especificado, o DefaultUserMessageIfRequestFailed será retornado.
UserMessageIfDnsResolutionFailed	Não	Um tipo de mensagem de erro usada para mostrar uma exceção de resolução DNS. Caso não seja especificado, o DefaultUserMessageIfRequestFailed será retornado.
UserMessageIfRequestTimeout	Não	Um tipo de mensagem de erro exibida após a conexão atingir o tempo limite. Caso não seja especificado, o DefaultUserMessageIfRequestFailed será retornado.

Chaves criptográficas

Se o tipo de autenticação for definido como None, o elemento CryptographicKeys não será usado.

<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>

Se o tipo de autenticação for definido como Basic, o elemento CryptographicKeys conterá os seguintes atributos:

Atributo	Obrigatório	Descrição
BasicAuthenticationUsername	Sim	O nome de usuário usado para autenticar.
BasicAuthenticationPassword	Sim	A senha usada para autenticar.

O exemplo a seguir mostra um perfil técnico com a autenticação Básica:

<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>

Se o tipo de autenticação for definido como ClientCertificate, o elemento CryptographicKeys conterá o seguinte atributo:

Atributo	Obrigatório	Descrição
ClientCertificate	Sim	O certificado X509 (conjunto de chaves RSA) a ser usado para autenticar.

<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>

Se o tipo de autenticação for definido como Bearer, o elemento CryptographicKeys conterá o seguinte atributo:

Atributo	Obrigatório	Descrição
BearerAuthenticationToken	Não	O Token de Portador do 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>

Se o tipo de autenticação for definido como ApiKeyHeader, o elemento CryptographicKeys conterá o seguinte atributo:

Atributo	Obrigatório	Descrição
O nome do cabeçalho HTTP, como `x-functions-key` ou `x-api-key`.	Sim	A senha usada para executar uma autenticação.

Observação

No momento, o Azure AD B2C é compatível somente com um cabeçalho HTTP usado para executar uma autenticação. Caso sua chamada à RESTful exija obter vários cabeçalhos, como uma ID do cliente e um valor de segredo do cliente, será preciso usar de algum modo um proxy na solicitação.

<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>

Como retornar um tipo de mensagem de erro de validação

A API REST talvez precise retornar uma mensagem de erro, como "O usuário não foi encontrado no sistema CRM". Caso ocorra um erro, a API REST deverá retornar um tipo de mensagem de erro HTTP 4xx, como o código de status de resposta 400 (solicitação inadequada) ou 409 (conflito). O corpo da resposta contém a mensagem de erro formatada em 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"
}

Atributo	Obrigatório	Descrição
version	Sim	A versão da API REST. Por exemplo: 1.0.1
status	Sim	Um número semelhante a um código de status de resposta HTTP e deve ser 409. Seu serviço REST pode retornar um código de status HTTP 4XX, mas o `status` valor do arquivado no corpo de resposta formatado em JSON deve ser `409`.
code	Não	Um código de erro do provedor de ponto de extremidade RESTful, que é exibido quando `DebugMode` está habilitado.
requestId	Não	Um identificador de solicitação do provedor de ponto de extremidade RESTful, que é exibido quando `DebugMode` está habilitado.
userMessage	Sim	Uma mensagem de erro que é mostrada ao usuário.
developerMessage	Não	A descrição detalhada do problema e como corrigi-lo, o que é exibido quando `DebugMode` está habilitado.
moreInfo	Não	Um URI que aponta para informações adicionais, que são exibidas quando `DebugMode` está habilitado.

O exemplo a seguir mostra uma classe C# que retorna uma mensagem de erro:

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; }
}

Próximas etapas

Confira os seguintes artigos para obter exemplos de como usar um perfil técnico RESTful: