Use 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 com sistemas externos. Por exemplo, com conectores de API, você pode:

• Valide os dados de entrada do usuário. Valide contra dados de usuário malformados ou inválidos. Por exemplo, você pode validar dados fornecidos pelo usuário em relação aos dados existentes em um armazenamento de dados externo ou lista de valores permitidos. Se for inválido, você pode pedir a um usuário para fornecer 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.
• Integre 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 de contas.
• Aumente os tokens com atributos de fontes externas. Enriqueça 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.
• Sobrescrever atributos do utilizador. Reformatar ou atribuir um valor a um atributo coletado do usuário. Por exemplo, se um usuário inserir o primeiro nome em todas as letras minúsculas ou maiúsculas, você poderá formatar o nome apenas com a primeira letra em maiúsculas.
• Execute uma lógica de negócios personalizada. Você pode acionar 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 realizar a chamada ao ponto de extremidade da API, para definir a URL do ponto de extremidade HTTP e a autenticação necessária para a chamada de API. Depois de configurar um conector de API, você pode 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 da API é invocado e se materializa 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, solicitar que o usuário reinsira informações ou substituir atributos de usuário.

Onde você pode habilitar um conector de API em um fluxo de usuário

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

• Depois de estabelecer uma federação com um provedor de identidade durante a inscrição - aplica-se apenas a experiências de inscrições
• Antes de criar o usuário - aplica-se apenas a experiências de inscrições
• Antes de enviar o token (visualização) - aplica-se a registos e autenticações

Depois de federar com um provedor de identidade durante a inscrição

Um conector de API nesta etapa do processo de inscrição é invocado imediatamente após o usuário se autenticar com um provedor de identidade (como Google, Facebook e Microsoft Entra ID). Esta etapa precede a página de coleta de atributos, que é o formulário apresentado ao usuário para coletar atributos de usuário. Esta etapa não será invocada se um usuário estiver se registrando com uma conta local. A seguir estão exemplos de cenários de conector de API que você pode habilitar nesta etapa:

• Use o e-mail 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 disponibilize-as para retornar no token.
• Implemente uma lista de permissões ou bloqueios com base na identidade social.

Antes de criar o usuário

Um conector de API nesta etapa do processo de inscrição é invocado após a página de coleta de atributos, se uma estiver incluída. Esta etapa é sempre invocada antes da criação de uma conta de usuário. A seguir estão exemplos de cenários que você pode habilitar neste momento durante a inscrição:

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

Antes de enviar o token (pré-visualização)

Um conector de API nesta etapa do processo de inscrição ou entrada é invocado antes que um token seja emitido. A seguir estão exemplos de cenários que você pode habilitar nesta etapa:

• Enriquecimento do token com atributos sobre o utilizador de fontes distintas do diretório, incluindo sistemas de identidade legados, sistemas de RH, armazenamento de utilizadores externos e muito mais.
• Enriquecimento do token com atributos de grupo ou função que você armazena e gerencia em seu próprio sistema de permissões.
• Aplicando transformações ou manipulações aos valores de afirmações no diretório.

O Identity Experience Framework, subjacente ao Azure Ative Directory B2C (Azure AD B2C), pode integrar-se com APIs RESTful dentro de uma jornada do usuário. Este artigo mostra como criar uma jornada 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 uma jornada do usuário chamando seu próprio serviço RESTful. O Identity Experience Framework pode enviar e receber dados do 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 e-mail fornecido pelo usuário existe no banco de dados do cliente e, se não, apresentar um erro. Pode igualmente considerar os conectores de API como uma forma de dar suporte a webhooks de saída, porque a chamada é feita quando ocorre um evento, por exemplo, um registo.
• Processar reclamações. Se um usuário inserir seu primeiro nome em letras minúsculas ou maiúsculas, sua API REST poderá formatar o nome apenas com a primeira letra em maiúsculas e devolvê-lo ao Azure AD B2C. No entanto, ao usar uma política personalizada, ClaimsTransformations é preferido em vez de chamar uma API RESTful.
• Enriqueça dinamicamente os dados do usuário integrando-se ainda mais com aplicativos corporativos de linha de negócios. 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 para o Azure AD B2C. Em seguida, as declarações de retorno podem ser armazenadas na conta Microsoft Entra do usuário, avaliadas nas próximas etapas de orquestração ou incluídas no token de acesso.
• Execute uma 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ários, 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 de declaraçõ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 acontece 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 a jornada do usuário avance. Com o perfil técnico de validação, você pode:

  • Envie declarações para sua API REST.
  • Valide declarações e lance mensagens de erro personalizadas que são exibidas para o usuário.
  • Envie de volta as declarações da API REST para as próximas etapas de orquestração.

• Troca de reivindicações. Uma troca direta de declarações pode ser configurada chamando diretamente um perfil técnico da API REST numa etapa de orquestração de um percurso do utilizador. Esta definição limita-se a:

  • Envie declarações para sua API REST.
  • Valide declarações e lance mensagens de erro personalizadas que são retornadas para o aplicativo.
  • Envie de volta as declarações da API REST para as próximas etapas de orquestração.

Você pode adicionar uma chamada de API REST em qualquer etapa da jornada do usuário definida por uma política personalizada. Por exemplo, você pode chamar uma API REST:

• Durante o início de sessão, imediatamente antes de o Azure AD B2C validar as credenciais.
• Imediatamente após o início de sessão.
• Antes do Azure AD B2C cria uma nova conta no diretório.
• Depois que o Azure AD B2C cria uma nova conta no diretório.
• Antes do Azure AD B2C emite um token de acesso.

Envio de dados

No perfil técnico RESTful, o InputClaims elemento contém uma lista de declarações a serem enviadas ao seu 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 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.
• Formulário, enviado no corpo da solicitação HTTP POST em um formato de pares de chave-valor separados por '&'.
• Cabeçalho, enviado no cabeçalho do pedido HTTP GET.
• QueryString, enviado na cadeia de consulta da solicitação HTTP GET.

Quando a opção Body é configurada, o perfil técnico da API REST permite enviar uma carga JSON complexa para um ponto de extremidade. Para obter mais informações, consulte Enviar uma carga JSON.

Receção de 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 defina o atributo DefaultValue.

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

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

As declarações de saída devem se parecer com o 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 e-mail retorna o valor null:

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

Quando um elemento é nulo:

• Omita o par chave-valor do JSON.
• Retorna um valor que corresponde 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 integer dados, retorne um valor 0zero . Para um tipo de dateTime dados, retorne um valor 0001-01-01T00:00:00.0000000Zmínimo .

O exemplo a seguir demonstra como manipular um valor nulo. O e-mail é omitido do JSON:

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

Analisar um corpo JSON aninhado

Para analisar uma resposta de corpo JSON aninhado, configure os metadados ResolveJsonPathsInJsonTokens como true. Na declaração de saída, defina 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 assemelhar-se 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 CRM". Se ocorrer um erro, a API REST deve 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 a partir 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 após o envio da página.

Se referenciar um perfil técnico da API REST diretamente de um percurso do utilizador, o utilizador será redirecionado de volta para a aplicação de confiança 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
• Comece com as nossas amostras

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 Ative Directory B2C
• Proteja seus serviços de API REST
• Chamar uma API REST usando a política personalizada do Azure Ative Directory B2C