Partilhar via

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

O pipeline de autenticação do Microsoft Entra ID consiste em vários eventos de autenticação internos, como a validação de credenciais de 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 da API REST onde você define uma ação de fluxo de trabalho.

Por exemplo, você pode usar um provedor de declarações personalizado para adicionar dados de usuário externo ao token de segurança antes que o token seja emitido. Você pode adicionar um fluxo de trabalho de coleta de atributos para validar os atributos inseridos por um usuário durante a inscrição. Este artigo fornece uma visão geral técnica de alto nível das extensões de autenticação personalizada do Microsoft Entra ID.

O vídeo Visão geral da extensão de autenticação personalizada do Microsoft Entra fornece uma descrição abrangente dos principais recursos e capacidades das extensões de autenticação personalizadas.

Descriçã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 seu 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 as extensões de autenticação personalizada do Microsoft Entra e oferece práticas recomendadas e dicas valiosas para uma implementação ideal.

Fluxo de entrada

O diagrama a seguir mostra o fluxo de entrada integrado a uma extensão de autenticação personalizada.

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

  1. Um utilizador tenta iniciar sessão numa aplicação e é redirecionado para a página de início de sessão do Microsoft Entra.
  2. Quando um usuário conclui uma determinada etapa na autenticação, um ouvinte de eventos é acionado.
  3. Sua extensão de autenticação personalizada envia uma solicitação HTTP para seu ponto de extremidade da API REST. A solicitação contém informações sobre o evento, o perfil de usuário, dados da 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 na carga útil da resposta HTTP.
  7. Um token é retornado ao aplicativo.

Pontos de extremidade da API REST

Quando um evento é acionado, o Microsoft Entra ID invoca um ponto de extremidade da API REST de sua propriedade. A API REST deve ser acessível publicamente. 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 low-code-no-code, 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 ter que primeiro criar uma máquina virtual (VM) ou publicar um aplicativo Web.

Sua API REST deve lidar:

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 permite que os usuários criem fluxos de trabalho usando um designer visual. O vídeo aborda a personalização de e-mails de verificação e se aplica a todos os tipos de extensões de autenticação personalizadas, incluindo provedores de declarações personalizadas.

Solicitar carga útil

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

Por exemplo, no evento de início de emissão de token , a carga útil 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 carga útil da solicitação devem seguir o esquema conforme especificado no documento do evento.

Dados de retorno e tipo de ação

Depois que sua API da Web executa o fluxo de trabalho com sua lógica de negócios, ela deve retornar um tipo de ação que direcione o Microsoft Entra sobre como prosseguir com o processo de autenticação.

Por exemplo, no caso dos eventos de início de coleção de atributos e envio de coleção de atributos , o tipo de ação retornado pela API da 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 on token issuance start pode fornecer um conjunto de atributos que podem ser mapeados para o token de segurança.

Proteja sua API REST

Para garantir que as comunicações entre a extensão de autenticação personalizada e sua API REST sejam protegidas adequadamente, 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 appid ou azp declaração. Valide se a respetiva declaração contém o 99045fe1-7639-4a75-9d4a-577b6ca3810f valor. Esse valor garante que a ID do Microsoft Entra seja aquela que chama a API REST.
    1. Para Aplicações V1 , valide a appid declaração.
    2. Para Aplicações V2, valide a azp declaração.
  3. A declaração de audiência do token aud portador contém a ID do registro do aplicativo associado. Seu endpoint 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 iss ao portador contém a URL do emissor do Microsoft Entra. Dependendo da configuração do seu locatário, a URL do emissor é uma das seguintes;
    • Mão de obra: https://login.microsoftonline.com/{tenantId}/v2.0.
    • Cliente: https://{domainName}.ciamlogin.com/{tenantId}/v2.0.

Tipos de eventos de autenticação personalizados

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

Evento Entidade integrante da força de trabalho Inquilino externo
Início da emissão de tokens
Início da coleção de atributos
Envio da coleção de atributos
Envio único de código de acesso

Início da emissão de tokens

O evento de início de emissão de token, OnTokenIssuanceStart é acionado quando um token está prestes a ser emitido para um aplicativo. É um tipo de evento configurado dentro de um provedor de declaraçõ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 vários 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 da renderização da página de coleção de atributos. Ele permite que você adicione 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 é acionado depois que o usuário insere e envia atributos, permitindo que você adicione ações como validar entradas ou modificar atributos.

Envio único de código de acesso

O evento OnOtpSend é acionado quando um e-mail contendo uma senha única é enviado. Ele permite que você chame uma API REST para usar seu próprio provedor de e-mail. Esse evento pode ser usado para enviar e-mails personalizados para usuários que se inscrevem com endereço de e-mail, entram com senha única de e-mail (OTP de e-mail), redefinem sua senha usando OTP de e-mail ou usam OTP de e-mail 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, além de oferecer suporte à localização.

Conteúdo relacionado

  • Last updated on