Criar uma extensão de autenticação personalizada para validação de declaração de recuperação de conta

Este artigo descreve como configurar uma extensão de autenticação personalizada que valida declarações de ID verificadas durante a recuperação de conta do Microsoft Entra. No fluxo de recuperação de conta, os ouvintes de eventos podem ser usados para estender o processo de validação de declaração:

• O evento OnVerifiedIdClaimValidation ocorre quando um usuário inicia a recuperação de conta e apresenta declarações de ID verificadas. Você pode adicionar ações como validar declarações em uma fonte de dados autoritativa (como um sistema de RH, um banco de dados de aplicativo ou qualquer sistema de registros de funcionários) e retornar uma decisão de aprovação ou falha.

Além de criar uma extensão de autenticação personalizada, você precisa criar uma API REST que defina as ações de fluxo de trabalho a serem executadas para o evento. Este artigo demonstra uma maneira rápida de começar a usar um C# Azure Function implantado a partir de um repositório de exemplo. Com Azure Functions, você executa seu código em um ambiente sem servidor sem precisar primeiro criar uma VM (máquina virtual) ou publicar um aplicativo Web.

Pré-requisitos

• Uma assinatura do Azure. Se você não tiver uma conta existente da Azure, inscreva-se em uma avaliação gratuita.
• Um locatário do Microsoft Entra ID com recuperação de conta habilitada.
• Pelo menos as funções administrador de aplicativos e administrador de autenticação .

Como funciona

Durante a recuperação da conta, um usuário que perdeu todos os métodos de autenticação deve restabelecer sua identidade. A extensão de autenticação personalizada adiciona uma etapa de validação de declaração a esse fluxo:

O OnVerifiedIdClaimValidation evento é o gancho de pré-validação no pipeline de recuperação. Ele permite que você conecte a lógica de validação personalizada – pesquisas de RH, verificações de banco de dados externos ou verificação de confiança do parceiro – antes que Microsoft Entra ID prossiga com a recuperação.

Etapa 1: Criar uma API REST de extensões de autenticação personalizada (aplicativo de funções Azure)

Nesta etapa, você implantará um aplicativo de funções Azure que serve como a API REST para sua extensão de autenticação personalizada. A função recebe declarações de ID verificadas de Microsoft Entra ID durante a recuperação da conta e as valida em uma fonte de dados autoritativa.

A função de amostra está disponível para implantação com um único clique. Ele implanta um aplicativo de funções Azure (.NET 10, modelo de trabalho isolado) no plano de consumo com o Application Insights e uma conta de armazenamento.

1.1 Implantar a função Azure

1. Selecione o botão Deploy para Azure:

   

2. Preencha os parâmetros de implantação:

   Parâmetro	Description
   Nome do aplicativo de funções	Um nome global exclusivo para o Aplicativo de Funções (por exemplo, contoso-recovery-claims).
   URL do repositório	Pré-preenchido com a URL do repositório GitHub.
   Branch	main
   Tipo de conta de armazenamento	Standard_LRS (padrão).
   Location	Selecione uma região Azure próxima dos usuários.

   Deixe os parâmetros opcionais em branco por enquanto – configure-os nas próximas etapas.

3. Selecione Examinar + criar, depois Criar.

4. Aguarde até que a implantação seja concluída (normalmente de 2 a 3 minutos).

1.2 Obter a URL da função

1. Depois de implantado, acesse o recurso Function App.
2. Selecione Functions>CustomClaimMatching>Obter URL da Função.
3. Copie a URL. Parece com: https://<your-function-app>.azurewebsites.net/api/CustomClaimMatching

1.3 Configurar a fonte de dados de teste

Para teste, a função dá suporte a um arquivo Excel hospedado em qualquer servidor Web com acesso de leitura como fonte de dados. Em produção, você pode alternar para o provedor de API de RH (consulte Alternar para produção: use o provedor de API de RH).

1. Baixe o arquivo de Excel de exemplo da pasta SampleData no repositório ou crie seu próprio com estas colunas:

   ID do Funcionário	UPN	firstName	lastName	fullName	dateOfBirth	tipoDeDocumento	documentId	data de validade do documento
   E001	user@contoso.com	John	Cerva	Júlio Pinto	1990-01-15	Passaporte	AB123456	15-01-2028

   Dica

   Para adicionar uma nova declaração, adicione uma coluna com o nome da declaração como o cabeçalho. A função compara dinamicamente as chaves de reivindicação da solicitação com os cabeçalhos de coluna — sem necessidade de alterações no código.

   Observação

   Por padrão, o aplicativo de funções valida apenas a declaração de número do documento (documentId). Para corresponder a declarações adicionais, como firstName, dateOfBirth ou employeeId, atualize a lógica de validação no código da função Azure.

2. Carregue o arquivo em um servidor Web, compartilhamento de arquivos ou serviço de armazenamento em nuvem (por exemplo, Armazenamento de Blobs do Azure, SharePoint ou qualquer local acessível por HTTP).

3. Obtenha uma URL de download direto para o arquivo. A URL deve estar acessível sem entrada interativa.

4. No portal do Azure, vá para o Aplicativo de Funções >Configurações>Variáveis de ambiente. O modelo de implantação cria previamente essas variáveis com valores padrão. Verifique e atualize o seguinte:

   Name	Ação	Value
   ClaimsValidator__Provider	Verificar (pré-criado como excel)	excel
   Excel__ShareUrl	Atualizar (pré-criado, mas vazio)	O URL de download direto do arquivo de Excel.
   Excel__SheetName	Verificar (pré-criado como Sheet1)	Sheet1 (ou o nome da planilha).

5. Selecione Aplicar, depois Confirmar.

Etapa 2: criar e registrar uma extensão de autenticação personalizada

Nesta etapa, você registrará uma extensão de autenticação personalizada que Microsoft Entra ID usa para chamar sua função Azure. A extensão de autenticação personalizada contém informações sobre o endpoint da sua API REST, a ação de validação de reivindicação que ela analisa a partir de sua API REST e como autenticar na sua API REST.

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
    "appId": "{authenticationeventsAPI_AppId}"
}

PATCH https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}
Content-type: application/json

{
    "identifierUris": [
        "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
    ],
    "api": {
        "requestedAccessTokenVersion": 2,
        "acceptMappedClaims": null,
        "knownClientApplications": [],
        "oauth2PermissionScopes": [],
        "preAuthorizedApplications": []
    },
    "requiredResourceAccess": [
        {
            "resourceAppId": "00000003-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "214e810f-fda8-4fd7-a475-29461495eb00",
                    "type": "Role"
                }
            ]
        }
    ]
}

2.1 Conceder consentimento do administrador

Depois que sua extensão de autenticação personalizada for criada, dê o consentimento ao aplicativo registrado, o que permitirá que a extensão de autenticação personalizada se autentique em sua API.

1. Navegue até Entra ID>Enterprise apps>Extensões de autenticação personalizada.
2. Selecione sua extensão de autenticação personalizada na lista.
3. Na guia Visão geral, selecione o botão Conceder permissão para dar consentimento do administrador ao aplicativo registrado. A extensão de autenticação personalizada usa client_credentials para autenticar no aplicativo de funções Azure usando a permissão Receive custom authentication extension HTTP requests. Selecione Aceitar.

Etapa 3: Adicionar a extensão de autenticação personalizada à política de recuperação de conta

Agora você associa a extensão de autenticação personalizada às configurações de validação de conta do perfil de verificação de identidade para que ela seja invocada durante o fluxo de recuperação.

Etapa 4: Testar a função (antes de adicionar a autenticação)

Antes de configurar a autenticação (Etapa 5), verifique se a lógica de correspondência de declarações da função funciona chamando-a diretamente. Neste ponto, a função não deve ter nenhuma autenticação configurada — nenhum provedor de identidade EasyAuth e as variáveis de ambiente EntraId__TenantId / EntraId__ClientId devem estar vazias.

4.1 Testar a função diretamente

1. Abra um terminal e execute:

   $body = @'
   {
       "type": "microsoft.graph.authenticationEvent.verifiedIdClaimValidation",
       "source": "/tenants/<tenant-guid>/applications/<app-id>",
       "data": {
           "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationCalloutData",
           "tenantId": "<tenant-guid>",
           "authenticationContext": {
               "correlationId": "00000000-0000-0000-0000-000000000001",
               "user": {
                   "userPrincipalName": "user@contoso.com"
               }
           },
           "verifiedIdClaimsContext": {
               "additionalInfo": {
                   "employeeId": "E001"
               },
               "claims": {
                   "firstName": "John",
                   "lastName": "Doe",
                   "dateOfBirth": "1990-01-15"
               }
           }
       }
   }
   '@
   
   (Invoke-WebRequest -Method Post `
     -Uri "https://<your-function-app>.azurewebsites.net/api/CustomClaimMatching" `
     -ContentType "application/json" `
     -Headers @{ Authorization = "Bearer test" } `
     -Body $body).Content
   

2. Verifique a resposta:

   Correspondência bem-sucedida:

   {
       "data": {
           "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.verifiedIdClaimValidation.pass"
               }
           ]
       }
   }
   

   Correspondência com falha (retorna quais declarações não corresponderam):

   {
       "data": {
           "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.verifiedIdClaimValidation.failed",
                   "failedClaims": ["dateOfBirth"]
               }
           ]
       }
   }
   

Etapa 5: Proteger sua função Azure

As extensões de autenticação personalizadas do Microsoft Entra utilizam o fluxo de servidor a servidor para obter um token de acesso que é enviado no cabeçalho HTTP Authorization para sua Azure Function. Ao publicar sua função em Azure, especialmente em um ambiente de produção, você precisa validar o token enviado no cabeçalho de autorização.

Para proteger sua Azure Function, siga estas etapas para integrar a autenticação do Microsoft Entra para validar os tokens de entrada com o registro do aplicativo da API de eventos de autenticação do Azure Functions.

5.1 Adicionar um provedor de identidade à função Azure

1. Entre no portal do Azure.
2. Navegue até e selecione o Aplicativo de Funções que você implantou anteriormente.
3. Selecione Autenticação no menu à esquerda.
4. Selecione Adicionar provedor de identidade.
5. Selecione Microsoft como provedor de identidade.
6. Em Escolher um locatário, selecione a configuração da Força de Trabalho (locatário atual).
7. Em App registration, selecione Escolha um registro de aplicativo existente neste diretório e selecione o registro de aplicativo da API de eventos de autenticação do Azure Functions criado na Etapa 2.
8. Na expiração do segredo do cliente, selecione um período de expiração.
9. Em tipos de conta com suporte, selecione Locatário atual – locatário único.
10. Em verificações adicionais:
    • Requisito de aplicativo cliente: Selecione Permitir solicitações de aplicativos clientes específicos e adicione 99045fe1-7639-4a75-9d4a-577b6ca3810f (este é o ID de aplicativo de primeira parte das extensões de autenticação personalizadas do Microsoft Entra).
    • Requisito de identidade: Selecione Permitir solicitações de qualquer identidade.
    • Requisito de locatário: Selecione Permitir solicitações de locatários específicos e insira sua ID de locatário da força de trabalho.
11. Em solicitações não autenticadas, selecione HTTP 401 Não autorizado: recomendado para APIs.
12. Para a URL Issuer, insira https://login.microsoftonline.com/{tenantId}/v2.0, em que {tenantId} é a ID do locatário do Microsoft Entra.
13. Desmarque a opção Repositório de tokens.
14. Selecione Add para adicionar autenticação à função Azure.

5.2 Usar o provedor de identidade do OpenID Connect

Se a função Azure estiver hospedada em um locatário diferente do locatário em que sua extensão de autenticação personalizada está registrada, siga estas etapas:

1. Entre no portal Azure e navegue até o Aplicativo de Funções.
2. Selecione Autenticação no menu à esquerda.
3. Selecione Adicionar provedor de identidade.
4. Selecione OpenID Connect como provedor de identidade.
5. Forneça um nome, como Contoso Microsoft Entra ID.
6. Na entrada Metadata, insira a seguinte URL na URL Document, substituindo {tenantId} pelo ID do inquilino do Microsoft Entra:

   https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
   

7. Em App registration, insira a ID do aplicativo (ID do cliente) da API de eventos de autenticação Azure Functions registro de aplicativo criado na Etapa 2.
8. No centro de administração do Microsoft Entra, acesse o registro de aplicativo da API de eventos de autenticação do Azure Functions, Certificados e segredos, Segredos do cliente, Novo segredo do cliente. Copie o valor do segredo.
9. De volta à função Azure, insira o segredo do Cliente.
10. Desmarque a opção Repositório de tokens.
11. Selecione Adicionar para adicionar o provedor de identidade do OpenID Connect.

Etapa 6: Testar o fluxo de recuperação de ponta a ponta

1. Entre no centro de administração do Microsoft Entra e confirme se a extensão de autenticação personalizada está ativa e atribuída ao perfil de verificação de identidade (Etapa 3).

2. Em uma janela privada do navegador, acesse https://myaccount.microsoft.com e inicie uma recuperação de conta.

3. Conclua as etapas de revisão de identidade (verificação facial, apresentação de ID verificada).

4. O evento OnVerifiedIdClaimValidation é acionado e chama sua função Azure. A função valida as declarações contra a fonte de dados e retorna aprovado ou reprovado.

5. Verifique nosLogs do > se a função foi chamada e se as declarações foram validadas:

   traces
   | where message has "claims" or message has "validation"
   | order by timestamp desc
   | take 20
   

Mudar para produção: use o provedor de API de RH

Para a produção, mude do provedor de Excel para o provedor de API de RH, que faz chamadas para o endpoint REST de RH da sua organização.

1. Nas variáveis de Ambiente do Aplicativo de Funções, atualize:

   Name	Value
   ClaimsValidator__Provider	hrapi
   HrApi__BaseUrl	Sua URL base da API de RH (por exemplo, https://hr.contoso.com/api).
   HrApi__AuthMode	apikey ou oauth.
   HrApi__ApiKey	Sua chave de API (se estiver usando apikey o modo de autenticação).
   HrApi__OAuthScope	Escopo do OAuth (se estiver usando oauth o modo de autenticação, por exemplo, api://hr-api-app-id/.default).

2. Ao usar o modo de autenticação oauth, a função utiliza a identidade gerenciada atribuída pelo sistema do Function App. Conceda à identidade gerenciada a função de aplicativo adequada no registro de aplicativo da API de RH.

3. Sua API de RH deve implementar este contrato:

   Solicitação:POST {BaseUrl}/validate

   {
       "upn": "user@contoso.com",
       "employeeId": "E001",
       "claims": {
           "firstName": "John",
           "lastName": "Doe",
           "dateOfBirth": "1990-01-15"
       }
   }
   

   Resposta (passagem):

   {
       "result": "pass"
   }
   

   Resposta (falha):

   {
       "result": "fail",
       "failedClaims": ["dateOfBirth"]
   }
   

Troubleshoot

Para obter mais diretrizes de solução de problemas, consulte Solucionar problemas da API de extensões de autenticação personalizadas.

Conteúdo relacionado

• Visão geral das extensões de autenticação personalizadas
• Visão geral da Recuperação de Conta do Microsoft Entra ID
• Habilitar a recuperação de conta para sua organização
• Código de exemplo: AccountRecoveryClaimsMatchingAPI