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

  • Artigo

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:

  1. Crie sua carga JSON com a transformação de declarações GenerateJson .
  2. 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, , , , ClientCertificateBasicBearerou 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 noneProduction, 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: