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

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

Os fluxos de usuário da ID Externa do Microsoft Entra foram projetados para flexibilidade. Dentro de um fluxo de usuário de inscrição e login, existem eventos de autenticação integrados. 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 de API REST no qual você define uma ação de fluxo de trabalho. Por exemplo, você poderia adicionar um fluxo de trabalho de coleção de atributos para validar os atributos que um usuário insere durante a inscrição, ou você poderia 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 o 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 no fluxo de autenticação:

• Durante a inscrição, antes ou depois da coleção de atributos:
  • O evento OnAttributeCollectionStart ocorre no início da etapa de coleção de atributos, antes que a página da coleção de atributos seja renderizada.
  • O evento OnAttributeCollectionSubmit ocorre depois que o usuário insere e envia atributos.
• Após a emissão de token usando o evento OnTokenIssuanceStart, que é disparado pouco 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 Microsoft Entra ID 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 do usuário, os dados de solicitação de autenticação e outras informações contextuais. Por sua vez, a API REST executa as ações de fluxo de trabalho.

Esse artigo fornece uma visão geral das extensões de autenticação personalizadas na ID externa do Microsoft Entra.

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é-armazenar campos de atributo com valores personalizados, validar entradas de um usuário e modificar atributos e exibir erros. Dois eventos estão habilitados:

• OnAttributeCollectionStart – O evento OnAttributeCollectionStart ocorre no início do processo de coleção de atributos antes da renderização da página da coleção 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 seguintes cenários são configuráveis para o evento OnAttributeCollectionStart:

  • continueWithDefaultBehavior – Renderiza a página de coleção de atributos como de costume.
  • setPreFillValues – Preenche previamente atributos no formulário de inscrição.
  • showBlockPage – Mostra uma mensagem de erro e impedir que o usuário se inscreva.

• 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 – Retornar um erro com base nos valores enviados.
  • showBlockPage – Mostra uma mensagem de erro e impedir que o usuário se inscreva.

Para configurar a coleção de atributos iniciar e enviar eventos, 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. O 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 da coleção de atributos ao fluxo do usuário.

Evento de início de emissão de token

O evento de início de emissão de token é disparado quando um usuário conclui todos os 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 declarações personalizadas de sistemas externos usando uma API REST que você desenvolve.

Em alguns casos, os dados principais podem ser armazenados em sistemas externos a 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 do Microsoft Entra. Para esses cenários, você pode usar uma extensão de autenticação personalizada e um provedor de declarações personalizadas para adicionar esses dados externos a 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 personalizadas é um tipo de extensão de autenticação personalizada que busca dados de sistemas externos. O provedor de declarações personalizadas 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, de modo que 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. Suas interfaces de ponto de extremidade de API REST com vários armazenamentos de dados, incluindo bancos de dados downstream, APIs existentes, diretórios de Lightweight Directory Access Protocol (LDAP) ou outros repositórios que contenham os atributos que você quer adicionar à configuração do token.

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

Para obter detalhes, confira:

• 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.

Confira também

• Para saber mais sobre como as extensões personalizadas funcionam, confira Extensões de autenticação personalizadas.
• Crie uma API REST com um evento de início de emissão de token.
• Configurar 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 coleção de atributos com uma amostra de aplicativo OpenID Connect.
• Consulte a Central de Desenvolvedores da ID externa do Microsoft Entra para obter o conteúdo e os recursos mais recentes para desenvolvedores.