Estendendo os fluxos de autenticação com sua própria lógica de negócios

Aplica-se a:Locatários da força detrabalho Locatários externos (saiba mais)

Os fluxos de usuário do Microsoft Entra External ID são projetados para flexibilidade. Dentro de um fluxo de usuário de inscrição e entrada, há eventos de autenticação internos. Você também pode adicionar extensões de autenticação personalizadas em pontos específicos dentro do fluxo de autenticação. Uma extensão de autenticação personalizada é essencialmente um ouvinte de eventos que, quando ativado, faz uma chamada HTTP para um ponto de extremidade da API REST onde você define uma ação de fluxo de trabalho. Por exemplo, você pode adicionar um fluxo de trabalho de coleta de atributos para validar os atributos que um usuário insere durante a inscrição ou pode usar um provedor de declarações personalizado para adicionar dados de usuário externos ao token antes que o token seja emitido.

Há dois componentes que você precisa configurar: uma extensão de autenticação personalizada e uma API REST. A extensão de autenticação personalizada especifica seu ponto de extremidade da API REST, quando a API REST deve ser chamada e as credenciais para chamar a API REST. Você pode criar extensões de autenticação personalizadas nos seguintes pontos do fluxo de autenticação:

• Durante a inscrição, antes ou depois da coleta de atributos:
  • O evento OnAttributeCollectionStart ocorre no início da etapa de coleta de atributos, antes da renderização da página de coleção de atributos.
  • O evento OnAttributeCollectionSubmit ocorre depois que o usuário insere e envia atributos.
• Após a emissão do token usando o evento OnTokenIssuanceStart , que é acionado imediatamente antes de um token ser emitido para o aplicativo.

Se você tiver uma extensão de autenticação personalizada configurada em um desses pontos, o ID do Microsoft Entra fará uma chamada para a API REST que você definir. A solicitação para a API REST contém informações sobre o evento, o perfil de usuário, dados de solicitação de autenticação e outras informações de contexto. Por sua vez, a API REST executa as ações do fluxo de trabalho.

Este artigo fornece uma visão geral das extensões de autenticação personalizadas no Microsoft Entra External ID.

Iniciar e enviar eventos da coleção de atributos

Você pode usar extensões de autenticação personalizadas para adicionar fluxos de trabalho à coleção de atributos em seus fluxos de usuário de inscrição de autoatendimento. Por exemplo, você pode pré-preencher campos de atributo com valores personalizados, validar entradas de um usuário, modificar atributos e exibir erros. Dois eventos estão habilitados:

• OnAttributeCollectionStart - O evento OnAttributeCollectionStart ocorre no início do processo de coleta de atributos antes da renderização da página de coleta de atributos. Esse evento pode ser usado para cenários como impedir que o usuário se inscreva com base em seu domínio ou adicionar atributos a serem coletados. Os cenários a seguir são configuráveis para o evento OnAttributeCollectionStart:

  • continueWithDefaultBehavior - Renderize a página de coleção de atributos como de costume.
  • setPreFillValues - Atributos de pré-preenchimento no formulário de inscrição.
  • showBlockPage - Mostrar uma mensagem de erro e bloquear o usuário de se inscrever.

• OnAttributeCollectionSubmit - O evento OnAttributeCollectionSubmit ocorre depois que o usuário insere e envia atributos. Esse evento pode ser usado para cenários como validar ou modificar as informações fornecidas pelo usuário. Por exemplo, você pode validar um código de convite ou número de parceiro, modificar um formato de endereço ou retornar um erro.

  • continueWithDefaultBehavior - Continue com o fluxo de inscrição.
  • modifyAttributeValues - Substitua os valores enviados pelo usuário no formulário de inscrição.
  • showValidationError - Retorna um erro com base nos valores enviados.
  • showBlockPage - Mostrar uma mensagem de erro e bloquear o usuário de se inscrever.

Para configurar os eventos de início e envio da coleção de atributos, crie uma API REST de extensão de autenticação personalizada. Quando um evento é acionado, o Microsoft Entra ID envia uma solicitação HTTP para o ponto de extremidade da API REST. A API REST pode ser uma Função do Azure, um Aplicativo Lógico do Azure ou outro ponto de extremidade de API disponível publicamente. Seu ponto de extremidade da API REST é responsável por definir as ações de fluxo de trabalho a serem executadas.

Para obter detalhes, consulte Adicionar extensões personalizadas de coleção de atributos ao seu fluxo de usuário.

Evento de início de emissão de token

O evento de início de emissão de token é acionado quando um usuário conclui todos os seus desafios de autenticação e um token de segurança está prestes a ser emitido.

Quando os usuários se autenticam em seu aplicativo com o Microsoft Entra ID, um token de segurança é retornado ao seu aplicativo. O token de segurança contém declarações que são instruções sobre o usuário, como nome, identificador exclusivo ou funções de aplicativo. Além do conjunto padrão de declarações contidas no token de segurança, você pode definir suas próprias declarações personalizadas de sistemas externos usando uma API REST desenvolvida.

Em alguns casos, os principais dados podem ser armazenados em sistemas externos ao Microsoft Entra, como um email secundário, uma camada de cobrança ou informações confidenciais. Nem sempre é viável que as informações no sistema externo sejam armazenadas no diretório Microsoft Entra. Para esses cenários, você pode usar uma extensão de autenticação personalizada e um provedor de declarações personalizado para adicionar esses dados externos em tokens retornados ao seu aplicativo.

Uma extensão de evento de emissão de token envolve os seguintes componentes:

• Provedor de declarações personalizadas. Um provedor de declarações personalizado é um tipo de extensão de autenticação personalizada que busca dados de sistemas externos. O provedor de declarações personalizado especifica os atributos a serem adicionados ao token de segurança que é retornado ao seu aplicativo. Vários provedores de declarações podem compartilhar a mesma extensão personalizada, portanto, um conjunto diferente de atributos pode ser adicionado ao token de segurança para cada aplicativo.

• Ponto de extremidade da API REST. Quando um evento é acionado, o Microsoft Entra ID envia uma solicitação HTTP para o ponto de extremidade da API REST. A API REST pode ser uma Função do Azure, um Aplicativo Lógico do Azure ou algum outro ponto de extremidade de API disponível publicamente. Seu ponto de extremidade da API REST faz interface com vários armazenamentos de dados, incluindo bancos de dados downstream, APIs existentes, diretórios LDAP (Lightweight Directory Access Protocol) ou outros repositórios que contêm os atributos que você deseja adicionar à configuração do token.

  A API REST retorna uma resposta HTTP, ou ação, de volta para o ID do Microsoft Entra que contém os atributos. Esses atributos não são adicionados automaticamente a um token. Em vez disso, a política de mapeamento de declarações de um aplicativo deve ser configurada para qualquer atributo a ser incluído no token.

Para obter mais detalhes, veja:

• Sobre extensões de autenticação personalizadas.
• Configure um provedor de declarações personalizado para um evento de emissão de token usando um provedor de declarações personalizado.

Consulte também

• Para saber mais sobre como as extensões personalizadas funcionam, consulte Extensões de autenticação personalizadas.
• Crie uma API REST com um evento de início de emissão de token.
• Configure um provedor de declarações personalizado para um evento de emissão de token.
• Configure extensões de autenticação personalizadas para iniciar e enviar eventos de coleta de atributos com um aplicativo OpenID Connect de exemplo.
• Consulte o Microsoft Entra External ID Developer Center para obter o conteúdo e os recursos mais recentes do desenvolvedor.