Compartilhar via

Visão geral das extensões de autenticação personalizadas

O pipeline de autenticação da ID do Microsoft Entra consiste em vários eventos de autenticação internos, como a validação de credenciais do usuário, políticas de acesso condicional, autenticação multifator, redefinição de senha de autoatendimento e muito mais.

As extensões de autenticação personalizada do Microsoft Entra permitem estender os fluxos de autenticação com sua própria lógica de negócios 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ê pode usar um provedor de declarações personalizadas para adicionar dados de usuário externos ao token de segurança antes que o token seja emitido. 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. Este artigo fornece uma visão geral técnica de alto nível das extensões de autenticação personalizada da ID do Microsoft Entra.

O vídeo Microsoft Entra Custom Authentication Extension Overview oferece um resumo abrangente dos principais recursos e funcionalidades das extensões de autenticação personalizadas.

Visão geral dos componentes

Há dois componentes que você precisa configurar: uma extensão de autenticação personalizada no Microsoft Entra 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.

Este vídeo fornece instruções detalhadas sobre como configurar extensões de autenticação personalizada do Microsoft Entra e oferece práticas recomendadas e dicas valiosas para a implementação ideal.

Fluxo de login

O diagrama a seguir ilustra o fluxo de login integrado a uma extensão de autenticação personalizada.

Diagrama que mostra um token sendo aprimorado com declarações de uma fonte externa.

  1. Um usuário tenta fazer login em um aplicativo e é redirecionado para a página de login do Microsoft Entra.
  2. Depois que um usuário conclui uma determinada etapa na autenticação, um ouvinte de evento é disparado.
  3. Sua extensão de autenticação personalizada envia uma solicitação HTTP para o ponto de extremidade da API REST. A solicitação contém informações sobre o evento, o perfil do usuário, os dados de sessão e outras informações de contexto.
  4. A API REST executa um fluxo de trabalho personalizado.
  5. A API REST retorna uma resposta HTTP para o Microsoft Entra ID.
  6. A extensão de autenticação personalizada do Microsoft Entra processa a resposta e personaliza a autenticação com base no tipo de evento e no conteúdo da resposta HTTP.
  7. Um token é retornado ao aplicativo.

Pontos de extremidade da API REST

Quando um evento é disparado, o Microsoft Entra ID invoca um ponto de extremidade da API REST de sua propriedade. A API REST deve ser publicamente acessível. Ele pode ser hospedado usando o Azure Functions, o Serviço de Aplicativo do Azure, os Aplicativos Lógicos do Azure ou outro ponto de extremidade de API disponível publicamente.

Você tem a flexibilidade de usar qualquer linguagem de programação, estrutura ou solução sem código baixo, como Aplicativos Lógicos do Azure para desenvolver e implantar sua API REST. Para obter uma maneira rápida de começar, considere empregar o Azure Function. Ele permite que você execute seu código em um ambiente sem servidor sem precisar primeiro criar uma VM (máquina virtual) ou publicar um aplicativo Web.

Sua API REST deve lidar com:

Assista a este vídeo para saber como criar um ponto de extremidade da API REST de extensões de autenticação com os Aplicativos Lógicos do Azure, sem escrever código. O Aplicativo Lógico do Azure capacita os usuários a criar fluxos de trabalho usando um designer visual. O vídeo aborda a personalização de emails de verificação e se aplica a todos os tipos de extensões de autenticação personalizadas, incluindo provedores de declarações personalizadas.

Conteúdo da solicitação

A solicitação à API REST inclui um conteúdo JSON contendo detalhes sobre o evento, o perfil do usuário, os dados da solicitação de autenticação e outras informações de contexto. Os atributos dentro do conteúdo JSON podem ser usados para executar a lógica por sua API.

Por exemplo, no evento de início da emissão de token , o conteúdo da solicitação pode incluir o identificador exclusivo do usuário, permitindo que você recupere o perfil de usuário do seu próprio banco de dados. Os dados de conteúdo da solicitação devem seguir o esquema, conforme especificado no documento de evento.

Retornar dados e tipo de ação

Depois que a API Web executar o fluxo de trabalho com sua lógica de negócios, ela deverá retornar um tipo de ação que orienta o Microsoft Entra sobre como proceder com o processo de autenticação.

Por exemplo, no caso do início da coleção de atributos e eventos de envio da coleção de atributos , o tipo de ação retornado pela API Web indica se a conta pode ser criada no diretório, mostrar um erro de validação ou bloquear completamente o fluxo de inscrição.

A resposta da API REST pode incluir dados. Por exemplo, o evento de início de emissão de token pode fornecer um conjunto de atributos que se pode mapear para o token de segurança.

Proteger sua API REST

Para garantir que as comunicações entre a extensão de autenticação personalizada e sua API REST sejam adequadamente seguras vários controles de segurança devem ser aplicados.

  1. Quando a extensão de autenticação personalizada chama sua API REST, ela envia um cabeçalho HTTP Authorization com um token de portador emitido pelo Microsoft Entra ID.
  2. O token de portador contém uma declaração appid ou azp. Valide se a respectiva declaração contém o valor 99045fe1-7639-4a75-9d4a-577b6ca3810f. Esse valor garante que o Microsoft Entra ID seja responsável por chamar a API REST.
    1. Para Aplicativos V1, valide a declaração appid.
    2. Para Aplicativos V2, valide a declaração azp.
  3. A declaração de audiência do token de portador aud contém a ID do registro de aplicativo associado. O ponto de extremidade da API REST precisa validar se o token de portador foi emitido para esse público específico.
  4. A declaração do emissor do token de portador iss contém a URL do emissor do Microsoft Entra. Dependendo da configuração do locatário, a URL do emissor será uma das seguintes:
    • Força de trabalho: https://login.microsoftonline.com/{tenantId}/v2.0.
    • Cliente: https://{domainName}.ciamlogin.com/{tenantId}/v2.0.

Tipos de evento de autenticação personalizada

Esta seção lista os eventos de extensões de autenticação personalizadas disponíveis para a força de trabalho e locatários externos no Microsoft Entra ID. Para obter informações detalhadas sobre os eventos, consulte a respectiva documentação.

Acontecimento Locatário da força de trabalho Locatário externo
Início da emissão de token
Início da coleção de atributos
Envio da coleção de atributos
Envio de senha única

Início da emissão de token

O evento de início de emissão de token, OnTokenIssuanceStart , é disparado quando um token está prestes a ser emitido para um aplicativo. É um tipo de evento configurado em um provedor de reivindicações personalizado. O provedor de declarações personalizadas é uma extensão de autenticação personalizada que chama uma API REST para buscar declarações de sistemas externos. Um provedor de declarações personalizado mapeia declarações de sistemas externos em tokens e pode ser atribuído a um ou muitos aplicativos em seu diretório.

Início da coleção de atributos

Os eventos de início da coleção de atributos podem ser usados com extensões de autenticação personalizadas para adicionar lógica antes que os atributos sejam coletados de um usuário. O evento OnAttributeCollectionStart ocorre no início da etapa de coleta de atributos, antes que a página da coleta de atributos seja renderizada. Ele permite adicionar ações como pré-preenchimento de valores e exibição de um erro de bloqueio.

Envio da coleção de atributos

Os eventos de envio da coleção de atributos podem ser usados com extensões de autenticação personalizadas para adicionar lógica depois que os atributos são coletados de um usuário. O evento OnAttributeCollectionSubmit dispara depois que o usuário insere e envia atributos, permitindo que você adicione ações como validar entradas ou modificar atributos.

Envio de senha única

O evento OnOtpSend é disparado quando um email com código de uso único é enviado. Ele permite que você chame uma API REST para usar seu próprio provedor de email. Esse evento pode ser usado para enviar emails personalizados para usuários que se inscrevem com o endereço de email, entrar com a senha única por email (Email OTP), redefinir a senha usando o Email OTP ou usar o Email OTP para autenticação multifator (MFA).

Quando o evento OnOtpSend é ativado, o Microsoft Entra envia uma senha única para a API REST especificada que você possui. Em seguida, a API REST usa seu provedor de email escolhido, como o Serviço de Comunicação do Azure ou o SendGrid, para enviar a senha única com seu modelo de email personalizado, de endereço e assunto de email, ao mesmo tempo em que dá suporte à localização.

Conteúdo relacionado

  • Last updated on