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

Este artigo fornece uma visão geral técnica de alto nível das extensões de autenticação personalizadas para o Microsoft Entra ID. As extensões de autenticação personalizadas permitem personalizar a experiência de autenticação do Microsoft Entra integrando-se a sistemas externos.

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

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.

Ponto de extremidade da API REST de extensão de autenticação personalizadas

Quando um evento é acionado, o Microsoft Entra ID chama um ponto de extremidade da API REST que você possui. 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.

Você pode usar qualquer linguagem de programação, estrutura e ambiente de hospedagem para criar e hospedar sua API REST de extensões de autenticação personalizadas. Para começar de maneira rápida, use uma Azure Function em C#. O Azure Functions lhe permite executar seu código em um ambiente sem servidor sem que seja preciso primeiro criar uma VM (máquina virtual) ou publicar um aplicativo Web.

Sua API REST deve lidar com:

• Validação de tokens para proteger as chamadas à API REST.
• Lógica de negócios
• Validação de entrada e saída de esquemas de solicitação e resposta HTTP.
• Auditoria e logs.
• Controles de disponibilidade, desempenho e segurança.

Para desenvolvedores que executam a API REST no Azure Functions, considere usar a biblioteca NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents, que ajuda na implementação da validação de token usando as funcionalidades de autenticação internas do Microsoft Azure. Ela fornece um modelo de dados para diferentes tipos de eventos e inicia o processamento de solicitação e resposta de entrada e saída, para que seja possível concentrar-se mais na lógica de negócios.

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.

Provedor de declarações personalizadas

Um provedor de declarações personalizado é um tipo de 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 para tokens e pode ser atribuído a um ou muitos aplicativos em seu diretório.

Saiba mais sobre provedores de declarações personalizados.

Iniciar e enviar eventos da coleção de atributos

Os eventos de início e envio da coleção de atributos podem ser usados com extensões de autenticação personalizadas para adicionar lógica antes e depois que os atributos são coletados de um usuário. Por exemplo, você pode adicionar um fluxo de trabalho para validar os atributos que um usuário insere durante a inscrição. 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. Ele permite adicionar ações como pré-preenchimento de valores e exibição de um erro de bloqueio. 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.

Confira também

• Saiba como criar extensões de autenticação personalizadas para iniciar e enviar eventos de coleção de atributos com um aplicativo OpenID Connect de exemplo.