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

Artigo
01/22/2024

Nota

No Azure Ative Directory B2C, as políticas personalizadas são projetadas principalmente para lidar com cenários complexos. Para a maioria dos cenários, recomendamos que você use fluxos de usuário internos. Se você não tiver feito isso, saiba mais sobre o pacote inicial de políticas personalizadas em Introdução às políticas personalizadas no Ative Directory B2C.

O Azure Ative Directory B2C (Azure AD B2C) fornece suporte para integrar seu próprio serviço RESTful. O Azure AD B2C envia dados para o serviço RESTful em uma coleção de declarações de entrada e recebe dados de volta em uma coleção de declarações de saída. Para obter mais informações, consulte 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 handler 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 da 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 o sobrenome é enviado como lastName. A declaração de e-mail está definida como está.

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

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

Enviar uma carga JSON

O perfil técnico da API REST permite enviar uma carga JSON complexa para um ponto de extremidade.

Para enviar uma carga JSON complexa:

Crie sua carga 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 GenerateJson declarações.
2. Defina a SendClaimsIn opção de metadados como body
3. Defina a opção de metadados como o nome da declaração que contém a ClaimUsedForRequestPayload carga JSON útil.
4. Na declaração de entrada, adicione uma referência à declaração de entrada que contém a carga JSON útil.

O exemplo TechnicalProfile a seguir envia um email de verificação usando um serviço de email de terceiros (neste caso, 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>

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 defina o DefaultValue atributo.

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

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

A declaração MembershipId que é 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	Description
ServiceUrl	Sim	A URL do ponto de extremidade da API REST.
Tipo de autenticação	Sim	O tipo de autenticação que está sendo executada pelo provedor de declarações RESTful. Valores possíveis: `None`, , , , `ClientCertificateBasicBearer`ou `ApiKeyHeader`. O `None` valor indica que a API REST é anônima. O `Basic` valor indica que a API REST está protegida com autenticação básica HTTP. Somente usuários verificados, incluindo o Azure AD B2C, podem acessar sua API. O `ClientCertificate` valor (recomendado) indica que a API REST restringe o acesso usando a autenticação de certificado de cliente. Somente os serviços que têm os certificados apropriados, por exemplo, o Azure AD B2C, podem acessar sua API. O valor indica que a API REST restringe o acesso usando o token OAuth2 `Bearer` Bearer do cliente. O `ApiKeyHeader` valor indica que a API REST está protegida com o cabeçalho HTTP da chave de API, como x-functions-key.
AllowInsecureAuthInProduction	Não	Indica se o `AuthenticationType` pode ser definido como no ambiente de produção (`DeploymentMode` do TrustFrameworkPolicy está definido como `none` `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 ao provedor de declarações RESTful. Valores possíveis: `Body` (padrão), `Form`, , `HeaderUrl` ou `QueryString`. O `Body` valor é a declaração de entrada que é enviada no corpo da solicitação no formato JSON. O `Form` valor é a declaração de entrada que é enviada no corpo da solicitação em um formato de valor de chave separado '&' e comercial. O `Header` valor é a declaração de entrada que é enviada no cabeçalho da solicitação. O `Url` valor é a declaração de entrada que é 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 `QueryString` valor é a declaração de entrada que é enviada na cadeia de caracteres de consulta de solicitação. Os verbos HTTP invocados por cada um são os seguintes: `Body`:PUBLICAR `Form`:PUBLICAR `Header`:OBTER `Url`:OBTER `QueryString`:OBTER
ClaimsFormat	Não	Não usado atualmente, pode ser ignorado.
ClaimUsedForRequestPayload	Não	Nome de uma declaração de cadeia de caracteres que contém a carga a ser enviada para a 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. Consulte a seção Retornando mensagem de erro.
IncludeClaimResolvingInClaimsHandling	Não	Para 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 isso 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 dados de um elemento JSON aninhado. Em um OutputClaim, defina o para o `PartnerClaimType` elemento de caminho JSON que você deseja produzir. Por exemplo: `firstName.localized`, ou `data[0].to[0].email`.
UseClaimAsBearerToken	Não	O nome da declaração que contém o token ao portador.

Processamento de erros

Os metadados a seguir podem ser usados para configurar as mensagens de erro exibidas após falha da API REST. As mensagens de erro podem ser localizadas.

Atributo	Obrigatório	Description
DefaultUserMessageIfRequestFailed	Não	Uma mensagem de erro personalizada padrão para todas as exceções da API REST.
UserMessageIfCircuitOpen	Não	Mensagem de erro quando a API REST não está acessível. Se não for especificado, o DefaultUserMessageIfRequestFailed será retornado.
UserMessageIfDnsResolutionFailed	Não	Mensagem de erro para a exceção de resolução DNS. Se não for especificado, o DefaultUserMessageIfRequestFailed será retornado.
UserMessageIfRequestTimeout	Não	Mensagem de erro quando a conexão atinge o tempo limite. Se não for especificado, o DefaultUserMessageIfRequestFailed será retornado.

Chaves criptográficas

Se o tipo de autenticação estiver 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 estiver definido como Basic, o elemento CryptographicKeys conterá os seguintes atributos:

Atributo	Obrigatório	Description
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 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 estiver definido como ClientCertificate, o elemento CryptographicKeys conterá o seguinte atributo:

Atributo	Obrigatório	Description
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 estiver definido como Bearer, o elemento CryptographicKeys conterá o seguinte atributo:

Atributo	Obrigatório	Description
BearerAuthenticationToken	Não	O token ao portador 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 estiver definido como ApiKeyHeader, o elemento CryptographicKeys conterá o seguinte atributo:

Atributo	Obrigatório	Description
O nome do cabeçalho HTTP, como `x-functions-key`, ou `x-api-key`.	Sim	A chave usada para autenticar.

Nota

No momento, o Azure AD B2C dá suporte a apenas um cabeçalho HTTP para autenticação. Se sua chamada RESTful exigir vários cabeçalhos, como um ID do cliente e um valor secreto do cliente, você precisará fazer proxy da solicitação de alguma maneira.

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

Retornando mensagem de erro de validação

Sua API REST pode precisar retornar uma mensagem de erro, como "O usuário não foi encontrado no sistema CRM". Se ocorrer um erro, a API REST deverá retornar uma mensagem de erro HTTP 4xx, como o código de status de resposta 400 (solicitação incorreta) ou 409 (conflito). O corpo da resposta contém 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	Description
versão	Sim	Sua versão da API REST. Por exemplo: 1.0.1
estado	Sim	Um número semelhante a códigos 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` habilitado.
userMensagem	Sim	Uma mensagem de erro que é mostrada ao usuário.
developerMessage	Não	A descrição detalhada do problema e como corrigi-lo, que é exibida quando `DebugMode` está habilitada.
maisInformações	Não	Um URI que aponta para informações adicionais, que são exibidas quando `DebugMode` estão habilitadas.

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óximos passos

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

Partilhar via