Usar conectores de API para personalizar e estender fluxos de inscrição de usuário e politicas personalizadas em fontes de dados de identidade externas

  • Artigo

Antes de começar, use o seletor Escolher um tipo de política para escolher o tipo de política que você está configurando. O Azure Active Directory B2C oferece dois métodos para definir como os usuários interagem com seus aplicativos: por meio de fluxos dos usuários predefinidos ou de políticas personalizadas totalmente configuráveis. As etapas necessárias neste artigo são diferentes para cada método.

Visão geral

Como desenvolvedor ou administrador de TI, você pode usar conectores de API para integrar seus fluxos de inscrição de usuários com APIs REST de maneira a personalizar a experiência de inscrição e fazer integração com sistemas externos. Por exemplo, com conectores de API, você pode:

  • Validar os dados de entrada do usuário. Verificar a existência de dados de usuário malformados ou inválidos. Por exemplo, você pode validar dados fornecidos pelo usuário em relação a dados existentes em um armazenamento de dados externo ou lista de valores permitidos. Se forem inválidos, você poderá solicitar que um usuário forneça dados válidos ou impedir que o usuário continue o fluxo de inscrição.
  • Verifique a identidade do usuário. Use um serviço de verificação de identidade ou fontes de dados de identidade externas para adicionar um nível extra de segurança às decisões de criação de conta.
  • Fazer integração com um fluxo de trabalho de aprovação personalizado. Conecte-se a um sistema de aprovação personalizado para gerenciar e limitar a criação da conta.
  • Aumente os tokens com atributos de fontes externas. Melhorar os tokens com atributos sobre o usuário de fontes que são externas para o Azure AD B2C como sistemas de nuvem, repositórios de usuários personalizados, sistemas de permissões personalizados, serviços de identidade herdados e muito mais.
  • Substituir atributos de usuário. Reformate ou atribua um valor a um atributo coletado do usuário. Por exemplo, se um usuário inserir o nome com todas as letras maiúsculas ou minúsculas, você poderá formatar o nome usando somente a primeira letra maiúscula.
  • Executar a lógica de negócios personalizada. Você pode disparar eventos downstream em seus sistemas de nuvem para enviar notificações por push, atualizar bancos de dados corporativos, gerenciar permissões, auditar bancos de dados e executar outras ações personalizadas.

Um conector de API fornece ao Azure AD B2C as informações necessárias para chamar o ponto de extremidade de API definindo a URL de ponto de extremidade HTTP e a autenticação para a chamada à API. Depois de configurar um conector de API, você poderá habilitá-lo para uma etapa específica em um fluxo de usuário. Quando um usuário atinge essa etapa no fluxo de inscrição, o conector de API é invocado e materializado como uma solicitação HTTP POST para sua API, enviando informações do usuário ("declarações") como pares chave-valor em um corpo JSON. A resposta da API pode afetar a execução do fluxo do usuário. Por exemplo, a resposta da API pode impedir que um usuário se inscreva, pedir que o usuário insira novamente as informações ou que substitua atributos de usuário.

Como habilitar um conector de API em um fluxo de usuário

Há três modos de habilitar um conector de API no fluxo de usuário:

  • Após a federação com um provedor de identidade durante a inscrição - aplica-se somente a experiências de inscrição
  • Antes de criar o usuário - aplica-se somente a experiências de inscrição
  • Antes de enviar o token (versão prévia) -aplica-se a inscrições e entradas

Após a federação com um provedor de identidade durante a inscrição

Nesta etapa do processo de inscrição, um conector de API é invocado imediatamente depois que o usuário se autentica com um provedor de identidade (como o Google, o Facebook e o Microsoft Entra ID). Essa etapa precede a página de coleta de atributos, que é o formulário apresentado ao usuário para coletar os atributos de usuário. Essa etapa não será invocada se um usuário estiver se registrando com uma conta local. Veja os seguintes exemplos de cenários de conector de API que você pode habilitar nessa etapa:

  • Use o email ou a identidade federada que o usuário forneceu para pesquisar declarações em um sistema existente. Retorne essas declarações do sistema existente, preencha previamente a página de coleta de atributos e torne-as disponíveis para retornar no token.
  • Implemente uma lista de permissões ou de bloqueio com base na identidade social.

Antes de criar o usuário

Nesta etapa no processo de inscrição, um conector de API é invocado após a página de coleção de atributos, se incluída. Essa etapa é sempre invocada antes da criação de uma conta de usuário. Veja os seguintes exemplos de cenários que você pode habilitar neste ponto durante a inscrição:

  • Validar os dados de entrada de usuário e pedir a um usuário para reenviar os dados.
  • Bloquear uma inscrição de usuário com base nos dados inseridos pelo usuário.
  • Verifique a identidade do usuário.
  • Consultar sistemas externos para obter dados existentes sobre o usuário para retorná-los no token do aplicativo ou armazená-los no Microsoft Entra ID.

Antes de enviar o token (versão preliminar)

Observação

Esse recurso está em uma versão prévia.

Um conector de API nesta etapa no processo de inscrição ou de entrada, é invocado antes de um token ser emitido. Veja os seguintes exemplos de cenários que você pode habilitar nessa etapa:

  • Enriquecer o token com atributos sobre o usuário de origens diferentes do diretório, incluindo sistemas de identidade herdados, sistemas de RH, repositórios de usuários externos e muito mais.
  • Enriquecendo o token com os atributos de grupo ou função que você armazena e gerencia em seu próprio sistema de permissões.
  • Aplicar transformações de declarações ou manipulações a valores de declarações no diretório.

A Identity Experience Framework subjacente ao Azure AD B2C (Azure Active Directory B2C), pode se integrar a APIs RESTful em um percurso do usuário. Este artigo mostra como criar um percurso do usuário que interage com um serviço RESTful usando um perfil técnico RESTful.

Usando o Azure AD B2C, é possível adicionar sua própria lógica de negócios a um percurso do usuário chamando o seu próprio serviço RESTful. A Identity Experience Framework pode enviar e receber dados de seu serviço RESTful para trocar declarações. Por exemplo, você pode:

  • Use a fonte de dados de identidade externa para validar dados de entrada do usuário. Por exemplo, você pode verificar se o endereço de email fornecido pelo usuário existe no banco de dados do cliente e, se não tiver, apresente um erro. Você também pode pensar em conectores de API como uma maneira de dar suporte a webhooks de saída porque a chamada é feita quando ocorre um evento, por exemplo, uma inscrição.
  • Processar declarações. Se um usuário inserir o nome com todas as letras maiúsculas ou minúsculas, sua API REST poderá formatar o nome usando somente a primeira letra maiúscula e retorná-la ao Azure AD B2C. No entanto, é preferível usar ClaimsTransformations como política personalizada, em vez de chamar uma API RESTful.
  • Aprimorar dinamicamente os dados do usuário com a integração adicional a aplicativos de linha de negócios corporativos. Seu serviço RESTful pode receber o endereço de email do usuário, consultar o banco de dados do cliente e retornar o número de fidelidade do usuário ao Azure AD B2C. As declarações retornadas podem ser armazenadas na conta do Microsoft Entra do usuário, avaliadas nas próximas etapas de orquestração ou incluídas no token de acesso.
  • Executar a lógica de negócios personalizada. Você pode enviar notificações por push, atualizar bancos de dados corporativos, executar um processo de migração de usuário, gerenciar permissões, auditar bancos de dados e realizar qualquer outro fluxo de trabalho.

Diagrama de uma troca de declarações do serviço RESTful

Observação

Se houver lentidão ou se não houver resposta do serviço RESTful para o Azure AD B2C, o tempo limite será de 30 segundos e a contagem de repetições será duas vezes (o que significa que há 3 tentativas no total). Atualmente, você não pode definir as configurações de contagem de tempo limite e repetição.

Chamando um serviço RESTful

A interação inclui uma troca de declarações de informações entre as declarações da API REST e o Azure AD B2C. É possível criar a integração com os serviços RESTful das seguintes maneiras:

  • Perfil técnico de validação. A chamada para o serviço RESTful ocorre dentro de um perfil técnico de validação do perfil técnico autodeclarado especificado ou um controle de exibição de verificação de um controle de exibição. O perfil técnico de validação valida os dados fornecido pelo usuário para que o percurso do usuário possa avançar. Com o perfil técnico de validação, é possível:

    • Enviar declarações para sua API REST.
    • Validar as declarações e gerar mensagens de erro personalizadas que são exibidas para o usuário.
    • Enviar declarações de retorno da API REST para as próximas etapas de orquestração.

  • Troca de declarações. Uma troca de declarações direta pode ser configurada chamando um perfil técnico da API REST diretamente de uma etapa de orquestração de um percurso do usuário. Essa definição é limitada a:

    • Enviar declarações para sua API REST.
    • Validar as declarações e gerar mensagens de erro personalizadas que são retornadas para o aplicativo.
    • Enviar declarações de retorno da API REST para as próximas etapas de orquestração.

Você pode adicionar uma chamada à API REST em qualquer etapa no percurso do usuário definido por uma política personalizada. Por exemplo, você pode chamar uma API REST:

  • Durante a entrada, logo antes de o Azure AD B2C validar as credenciais.
  • Imediatamente após a entrada.
  • Antes que o Azure AD B2C crie uma conta no diretório.
  • Depois que o Azure AD B2C criar uma conta no diretório.
  • Antes que o Azure AD B2C emita um token de acesso.

Coleção do perfil técnico de validação

Enviar dados

No perfil técnico RESTful, o elemento InputClaims contém uma lista de declarações a serem enviadas ao serviço RESTful. Você pode mapear o nome da sua declaração para o nome definido no serviço RESTful, definir um valor padrão e usar resolvedores de declarações.

Você pode configurar como as declarações de entrada são enviadas para o provedor de declarações RESTful usando o atributo SendClaimsIn. Os valores possíveis são:

  • Body, enviado no corpo da solicitação HTTP POST no formato JSON.
  • Formulário, enviado no corpo da solicitação HTTP POST em um formato de valor de chave separado por '&'.
  • Header, enviado no cabeçalho de solicitação HTTP GET.
  • QueryString, enviado na cadeia de caracteres de consulta de solicitação HTTP GET.

Quando a opção Body estiver configurada, o perfil técnico da API REST permitirá que você envie um payload JSON complexo para um ponto de extremidade. Para obter mais informações, confira Enviar um payload JSON.

Recebendo dados

O elemento OutputClaims do perfil técnico RESTful 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 pelo provedor de identidade de API REST, desde que defina o atributo DefaultValue.

As declarações de saída analisadas pelo provedor de declarações RESTful sempre esperam analisar uma resposta de corpo JSON simples, como:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

As declarações de saída devem ser semelhantes ao seguinte trecho xml:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Manipulando valores nulos

Um valor nulo em um banco de dados é usado quando o valor em uma coluna é desconhecido ou está ausente. Não inclua chaves JSON com um valor null. No exemplo a seguir, o email retorna o valor null:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Quando um elemento é nulo, você pode:

  • Omitir o par chave-valor do JSON.
  • Retornar um valor que corresponda ao tipo de dados de declaração do Azure AD B2C. Por exemplo, para um tipo de dados string, retorne uma cadeia de caracteres vazia "". Para um tipo de dados integer, retorne um valor zero 0. Para um tipo de dados dateTime, retorne um valor mínimo de 1970-00-00T00:00:00.0000000Z.

O exemplo a seguir demonstra como processar um valor nulo. O email é omitido do JSON:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Analisar um corpo JSON aninhado

Para analisar uma resposta de corpo JSON aninhada, defina os metadados de ResolveJsonPathsInJsonTokens como true. Na declaração de saída, defina PartnerClaimType como o elemento de caminho JSON que você deseja gerar.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

As declarações de saída devem ser similares ao seguinte trecho xml:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Localizar a API REST

Em um perfil técnico RESTful, talvez você queira enviar o idioma/localidade da sessão atual e, se necessário, gerar uma mensagem de erro localizada. Usando o resolvedor de declarações, você pode enviar uma declaração contextual, como o idioma do usuário. O exemplo a seguir mostra um perfil técnico RESTful demonstrando esse cenário.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</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.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Tratamento de mensagens de erro

Sua API REST pode precisar retornar uma mensagem de erro, como "O usuário não foi encontrado no sistema de CRM". Se ocorrer um erro, a API REST deve retornar uma mensagem de erro HTTP 409 (código de status de resposta em conflito). Para saber mais, confira Perfil técnico RESTful.

Esse comportamento só pode ser obtido com a chamada de um perfil técnico da API REST de um perfil técnico de validação. Permite que o usuário corrija os dados na página e execute a validação novamente no envio da página.

Se você fizer referência a um perfil técnico da API REST diretamente de um percurso do usuário, o usuário será redirecionado de volta para o aplicativo de terceiros confiável com a mensagem de erro relevante.

Desenvolvimento da API REST

Sua API REST pode ser desenvolvido em qualquer plataforma e escrita em qualquer linguagem de programação, desde que seja segura e possa enviar e receber declarações em formato JSON.

A solicitação para seu serviço de API REST vem de servidores do Azure AD B2C. O serviço de API REST deve ser publicado em um ponto de extremidade HTTPS publicamente acessível. As chamadas à API REST chegarão de um endereço IP do datacenter do Azure.

Você pode usar funções de nuvem sem servidor, como gatilhos HTTP no Azure Functions para facilitar o desenvolvimento.

Você deve projetar seu serviço de API REST e seus componentes subjacentes (como o banco de dados e o sistema de arquivos) para serem altamente disponíveis.

Importante

Seus pontos de extremidade devem estar em conformidade com os requisitos de segurança do Azure AD B2C. As versões e as criptografias de TLS mais antigas foram preterida. Para obter mais informações, consulte TLS do Azure AD B2C e requisitos do conjunto de criptografias.

Próximas etapas

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