Usar conectores de API para personalizar e estender fluxos de usuário de inscrição e políticas personalizadas com fontes de dados de identidade externas

Visão geral

Como desenvolvedor ou administrador de TI, você pode usar conectores de API para integrar seus fluxos de usuário de inscrição com APIs REST para personalizar a experiência de inscrição e integrar-se a 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 da conta.
• Integre-se a 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. Enriquecer tokens com atributos de usuário de fontes externas ao Azure AD B2C, como sistemas de nuvem, repositórios de usuários personalizados, sistemas de permissão 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 da API definindo a URL do 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 à API pode impedir um usuário de se inscrever, pedir ao usuário para reentradar informações ou substituir atributos de usuário.

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

Há três locais em um fluxo de usuário em que você pode habilitar um conector de API:

• 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 ao registro e ao login

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

Um conector de API nesta etapa no processo de inscrição é invocado imediatamente após o usuário se autenticar com um provedor de identidade (como Google, Facebook e ID do Microsoft Entra). 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 a página de coleção de atributos e disponibilize-as para retorno 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 prévia)

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

• Enriquecendo o token com atributos sobre o usuário de fontes 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 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.

O Identity Experience Framework, que está por trás do Azure AD B2C (Azure Active Directory B2C), pode se integrar às 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, você pode adicionar sua própria lógica de negócios a um percurso do usuário chamando seu próprio serviço RESTful. O 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 os 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, caso contrário, apresentar um erro. Você também pode pensar nos conectores de API como uma forma 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 seu nome em todas as letras minúsculas ou maiúsculas, sua API REST poderá formatar o nome com apenas a primeira letra maiúscula e devolvê-la ao Azure AD B2C. No entanto, é preferível usar ClaimsTransformations como política personalizada, em vez de chamar uma API RESTful.
• Enriqueça dinamicamente os dados do usuário integrando-se ainda mais com 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. Em seguida, as declarações de retorno 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 executar quaisquer outros fluxos de trabalho.

Chamando um serviço RESTful

A interação inclui uma troca de informações entre as declarações da API REST e o Azure AD B2C. Você pode projetar 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 fornecidos pelo usuário antes que o percurso do usuário avance. Com o perfil técnico de validação, você pode:

  • Envie declarações para sua API REST.
  • Valide as declarações e gere 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 direta de declarações 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:

  • Envie declarações para sua API REST.
  • Valide as declarações e gere mensagens de erro personalizadas que são retornadas ao 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, pouco antes do Azure AD B2C validar as credenciais.
• Imediatamente após o login.
• Antes de o Azure AD B2C criar uma nova conta no diretório.
• Depois que o Azure AD B2C cria uma nova conta no diretório.
• Antes que o Azure AD B2C emita um token de acesso.

Enviar dados

No perfil técnico RESTful, o InputClaims elemento contém uma lista de declarações a serem enviadas ao serviço RESTful. Você pode mapear o nome da 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 ao provedor de declarações RESTful usando o atributo SendClaimsIn. Os valores possíveis são:

• Corpo, enviado no corpo da solicitação HTTP POST no formato JSON.
• Form, enviado no corpo da solicitação HTTP POST em um formato de valor de chave separado de e comercial “&”.
• 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 Corpo está configurada, o perfil técnico da API REST permite que você envie uma carga JSON complexa para um ponto de extremidade. Para obter mais informações, consulte Enviar uma carga JSON.

Recebendo dados

O OutputClaims elemento 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 da API REST, desde que você 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 ausente. Não inclua chaves JSON com um null valor. No exemplo a seguir, o email retorna o valor: null

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

Quando um elemento é nulo, ou:

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

O exemplo a seguir demonstra como lidar com 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 o PartnerClaimType como o elemento de caminho JSON que você deseja produzir.

"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, convém 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>

Processar mensagens de erro

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 409 (código de status de resposta de conflito). Para obter mais informações, consulte o perfil técnico RESTful.

Esse comportamento só pode ser alcançado chamando um perfil técnico da API REST de um perfil técnico de validação. Permitir 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 terceira parte confiável com a mensagem de erro relevante.

• Saiba como adicionar um conector de API para modificar experiências de inscrição
• Saiba como adicionar um conector de API para enriquecer tokens com declarações externas
• Saiba como proteger seu Conector de API
• Introdução aos nossos exemplos

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

• 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
• Chamar uma API REST usando a política personalizada do Azure Active Directory B2C