Solucionar problemas da sua extensão de autenticação personalizada

Artigo
04/10/2024

Eventos de autenticação e provedores de declarações personalizadas permitem personalizar a experiência de autenticação do Microsoft Entra integrando-se a sistemas externos. Por exemplo, você pode criar uma API de provedor de declarações personalizadas e configurar um aplicativo OpenID Connect ou um aplicativo SAML para receber tokens com declarações de um repositório externo.

Comportamento do erro

Quando uma chamada à API falha, o comportamento do erro é o seguinte:

Para aplicativos OpenId Connect – o Microsoft Entra ID redireciona o usuário de volta para o aplicativo cliente com um erro. Um token não é cunhado.
Para aplicativos SAML – o Microsoft Entra ID mostra ao usuário uma tela de erro na experiência de autenticação. O usuário não é redirecionado de volta para o aplicativo cliente.

O código de erro enviado de volta para o aplicativo ou o usuário é genérico. Para solucionar problemas, verifique os logs de credenciais para obter os códigos de erro.

Registro em log

Para solucionar problemas com o ponto de extremidade da API REST do provedor de declarações personalizadas, a API REST deve identificar o registro em log. Azure Functions e outras plataformas de desenvolvimento de API fornecem soluções de registro em log detalhadas. Use essas soluções para obter informações detalhadas sobre o comportamento das APIs e solucionar problemas da lógica da API.

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Você também pode usar logs de credenciais do Microsoft Entra, além de seus logs de API REST e soluções de diagnóstico de ambiente de hospedagem. Usando logs de credenciais do Microsoft Entra ID, você pode encontrar erros, o que pode afetar as credenciais dos usuários. Os logs de credenciais do Microsoft Entra ID fornecem informações sobre o status HTTP, o código de erro, a duração da execução e o número de repetições que ocorreram a API foi chamado pelo Microsoft Entra ID.

Logs de credenciais do Microsoft Entra também se integram com o Azure Monitor. Você pode configurar alertas e monitoramento, visualizar os dados e integrar-se às ferramentas de SIEM (gerenciamento de eventos e informações de segurança). Por exemplo, você poderá configurar notificações se o número de erros exceder um determinado limite escolhido.

Para acessar os logs de entrada do Microsoft Entra:

Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
Navegue até Identidade>Aplicativos>Aplicativos Empresariais.
Selecione Logs de entrada e, em seguida, selecione o log de entrada mais recente.
Para obter mais detalhes, selecione a guia Eventos de Autenticação. Informações relacionadas à chamada à API REST de extensão de autenticação personalizada são exibidas, incluindo quaisquer códigos de erro.

Referência de códigos de erro

Use a tabela a seguir para diagnosticar um código de erro.

Código do erro	Nome do erro	Descrição
1003000	EventHandlerUnexpectedError	Ocorreu um erro inesperado ao processar um manipulador de eventos.
1003001	CustomExtenstionUnexpectedError	Ocorreu um erro inesperado ao chamar uma API de extensão personalizada.
1003002	CustomExtensionInvalidHTTPStatus	A API de extensão personalizada retornou um código de status HTTP inválido. Verifique se a API retorna um código de status aceito definido para esse tipo de extensão personalizada.
1003003	CustomExtensionInvalidResponseBody	Houve um problema ao analisar o corpo da resposta da extensão personalizada. Verifique se o corpo da resposta da API está em um esquema aceitável para esse tipo de extensão personalizada.
1003004	CustomExtensionThrottlingError	Há muitas solicitações de extensão personalizada. Essa exceção é gerada para chamadas à API de extensão personalizada quando os limites de limitação são atingidos.
1003005	CustomExtensionTimedOut	A extensão personalizada não respondeu dentro do tempo limite permitido. Verifique se a API está respondendo dentro do tempo limite configurado para a extensão personalizada. Também pode indicar que o token de acesso é inválido. Siga as etapas para chamar sua API REST diretamente.
1003006	CustomExtensionInvalidResponseContentType	O tipo de conteúdo de resposta da extensão personalizada não é 'application/json'.
1003007	CustomExtensionNullClaimsResponse	A API de extensão personalizada respondeu com um recipiente de declarações nulas.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	A API de extensão personalizada não respondeu com a mesma apiSchemaVersion para a qual foi chamada.
1003009	CustomExtensionEmptyResponse	O corpo da resposta da API de extensão personalizada era nulo quando isso não era esperado.
1003010	CustomExtensionInvalidNumberOfActions	A resposta da API de extensão personalizada incluiu um número diferente de ações daquelas com suporte para esse tipo de extensão personalizada.
1003011	CustomExtensionNotFound	Não foi possível encontrar a extensão personalizada associada a um ouvinte de eventos.
1003012	CustomExtensionInvalidActionType	A extensão personalizada retornou um tipo de ação inválido definido para esse tipo de extensão personalizada.
1003014	CustomExtensionIncorrectResourceIdFormat	A propriedade identifierUris no manifesto do registro do aplicativo para a extensão personalizada deve estar no formato "api://{nome de domínio totalmente qualificado}/{appid}.
1003015	CustomExtensionDomainNameDoesNotMatch	O targetUrl e resourceId da extensão personalizada devem ter o mesmo nome de domínio totalmente qualificado.
1003016	CustomExtensionResourceServicePrincipalNotFound	A appId da extensão personalizada resourceId deve corresponder a uma entidade de serviço real no locatário.
1003017	CustomExtensionClientServicePrincipalNotFound	A entidade de serviço de recurso de extensão personalizada não foi encontrada no locatário.
1003018	CustomExtensionClientServiceDisabled	A entidade de serviço de recurso de extensão personalizada está desabilitada no locatário.
1003019	CustomExtensionResourceServicePrincipalDisabled	A entidade de serviço de recurso de extensão personalizada está desabilitada no locatário.
1003020	CustomExtensionIncorrectTargetUrlFormat	A URL de destino está em um formato inadequado. Deve ser uma URL válida que comece com https.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	A entidade de serviço não tem consentimento do administrador para a função de aplicativo CustomAuthenticationExtensions.Receive.Payload do Microsoft Graph (também conhecida como permissão de aplicativo), que é necessária para que o aplicativo receba solicitações HTTP de extensão de autenticação personalizadas.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	A entidade de serviço do MS Graph está desabilitada ou não foi encontrada neste locatário.
1003023	CustomExtensionBlocked	O ponto de extremidade usado para a extensão personalizada está bloqueado pelo serviço.
1003024	CustomExtensionResponseSizeExceeded	O tamanho da resposta da extensão personalizada excedeu o limite máximo.
1003025	CustomExtensionResponseClaimsSizeExceeded	O tamanho total de declarações na resposta da extensão personalizada excedeu o limite máximo.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	A API de extensão personalizada respondeu com declarações que contêm chave nula ou vazia'
1003027	CustomExtensionConnectionError	Erro ao se conectar à API de extensão personalizada.

Chamar sua API REST diretamente

Sua API REST é protegida pelo token de acesso do Microsoft Entra. Você pode testar a sua API;

Obtenção de um token de acesso com um registro de aplicativo associado às extensões de autenticação personalizadas
Teste sua API localmente usando uma ferramenta de teste de API.

Ferramentas de teste de API
Obter um token de acesso

Para fins de desenvolvimento e teste, abra local.settings.json e substitua o código pelo seguinte JSON:
```
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsSecretStorageType": "files",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation" : false
  }
}
```
Observação

Se você usou o pacote NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents certifique-se de definir "AuthenticationEvents__BypassTokenValidation" : true para fins de teste local.
Usando sua ferramenta de teste de API preferencial, crie uma nova solicitação HTTP e defina o método HTTP como POST.

Use o seguinte corpo JSON que imita a solicitação que o Microsoft Entra ID envia para sua API REST.

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
        "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
        "authenticationContext": {
            "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2023-08-16T00:00:00Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "Casey Jensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Dica

Se você estiver usando um token de acesso obtido do Microsoft Entra ID, selecione Autorização e, em seguida, selecione Token de portador e cole o token de acesso recebido do Microsoft Entra ID.

Selecione Enviar e você deverá receber uma resposta JSON semelhante à seguinte:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "customClaim1": "customClaimValue1",
                    "customClaim2": [
                        "customClaimString1",
                        "customClaimString2" 
                    ]
                }
            }

        ]
    }
}

Depois de adquirir um token de acesso, passe-o para o cabeçalho HTTP Authorization. Para obter um token de acesso, siga estas etapas:

Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
Navegue até Identidade>Inscrições>Registros de inscrições.
Selecione o registro de aplicativo de API de eventos de autenticação do Azure Functions, configurado anteriormente na configuração de um provedor de declaração personalizado para um evento de emissão de token.
Copie a ID do aplicativo.
Se você ainda não criou um segredo do aplicativo, siga estas etapas:
1. Selecione Certificados e segredos>Segredos do cliente>Novo segredo do cliente.
2. Adicione uma descrição para o segredo do cliente.
3. Selecione uma data de expiração para o segredo ou especifique um tempo de vida personalizado.
4. Selecione Adicionar.
5. Registre o valor do segredo para uso no código do aplicativo cliente. Esse valor secreto nunca será exibido novamente depois que você sair dessa página.
No menu, selecione Expor uma API e copie o valor do URI da ID do Aplicativo. Por exemplo, api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.
Abra sua ferramenta de teste de API preferida e crie uma nova consulta HTTP.
Altere o método HTTP para POST.
Insira a URL a seguir. Substitua o {tenantID} pela ID de locatário.
```
https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
```

Em Corpo, selecione form-data e adicione as seguintes chaves:

Chave	Valor
`grant_type`	`client_credentials`
`client_id`	A ID do Cliente do seu aplicativo.
`client_secret`	O Segredo do Cliente do seu aplicativo.
`scope`	O URI da ID do Aplicativo do seu aplicativo e, em seguida, adicione `.default`. Por exemplo, `api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default`

Execute a consulta HTTP e copie o access_token para o aplicativo Web https://jwt.ms.
Compare o iss com o nome do emissor configurado em sua API.
Compare o aud com a ID do cliente configurada em sua API.

Principais aprimoramentos de desempenho

Um dos problemas mais comuns é que a API do provedor de declarações personalizadas não responde dentro do tempo limite de dois segundos. Se a API REST não responder em novas tentativas subsequentes, a autenticação falhará. Para melhorar o desempenho da API REST, siga as sugestões abaixo:

Se a API acessar APIs downstream, armazene em cache o token de acesso usado para chamar essas APIs, para que um novo token não precise ser adquirido em cada execução.
Problemas de desempenho geralmente estão relacionados a serviços downstream. Adicione o registro em log, que registra o tempo de processo para chamar quaisquer serviços downstream.
Se você usar um provedor de nuvem para hospedar sua API, use um plano de hospedagem que mantenha a API sempre "quente". Para o Azure Functions, pode ser o plano Premium ou o Plano Dedicado.
Execute testes de integração automatizados para suas autenticações. Você também pode usar ferramentas de teste de API para testar apenas o desempenho da API.

Compartilhar via

Solucionar problemas da sua extensão de autenticação personalizada

Comportamento do erro

Registro em log

Referência de códigos de erro

Chamar sua API REST diretamente

Principais aprimoramentos de desempenho

Confira também

Comentários

Recursos adicionais

Compartilhar via

Solucionar problemas da sua extensão de autenticação personalizada

Comportamento do erro

Registro em log

Logs de entrada do Microsoft Entra

Referência de códigos de erro

Chamar sua API REST diretamente

Principais aprimoramentos de desempenho

Confira também

Comentários

Recursos adicionais