Share via

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

  • Artigo

A ID Externa do Microsoft Entra foi projetada para flexibilidade. Além dos eventos de autenticação internos em um fluxo de usuário de inscrição e entrada, você 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 em que você definiu uma ação de fluxo de trabalho. Por exemplo, você pode 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ê pode usar um provedor de declarações personalizado para adicionar dados de usuário externos ao token antes que ele 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.

Diagrama mostrando pontos de extensibilidade no fluxo de autenticação.

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ê definiu. 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. Seu ponto de extremidade da API REST é responsável pela interface com bancos de dados downstream, APIs existentes, diretórios LDAP ou quaisquer outros repositórios que contenham os atributos que você gostaria de adicionar à configuração do token.

    A API REST retorna uma resposta HTTP para o Microsoft Entra ID que contém os atributos. Os atributos retornados pela API REST 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 que qualquer atributo seja incluído no token.

Para obter detalhes, confira:

Confira também