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

O Azure AD B2C (Azure Active Directory B2C) oferece 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 de 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 da 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 à API REST como firstName, enquanto o sobrenome é enviado como lastName. A declaração de email 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 um conteúdo JSON

O perfil técnico da API REST permite que você envie uma carga JSON complexa para um ponto de extremidade.

Para enviar uma carga JSON complexa:

1. Crie seu conteúdo 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 à GenerateJson transformação de declarações.
   2. Definir a opção SendClaimsIn de metadados como body
   3. Defina a opção ClaimUsedForRequestPayload de metadados 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 o conteúdo JSON.

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

Tratamento de erros

Os metadados a seguir podem ser usados para configurar as mensagens de erro exibidas após a falha da API REST. A mensagem de erro pode ser localizada.

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:

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:

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

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

<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 400 (solicitação incorreta) ou 409 (conflito) código de status de resposta. O corpo da resposta contém uma 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"
}

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

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

• Integrar as trocas de declarações da API REST em sua política personalizada do Azure AD B2C
• Passo a passo: adicionar um conector de API a um fluxo de usuário de inscrição
• Passo a passo: adicionar trocas de declarações da API REST a políticas personalizadas no Azure Active Directory B2C
• Proteger seus serviços de API REST