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

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)

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.

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.

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.

• 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 às nossas amostras

Confira 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
• Referência: Perfil técnico RESTful