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

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 personalizada e configurar um aplicativo OpenID Connect para receber tokens com declarações de um repositório externo.

Error behavior

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. To troubleshoot, check the sign-in logs for the error codes.

Logging

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.

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.

Microsoft Entra sign-in logs also integrate with 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 um Administrador de Aplicativos na Nuvem.
Browse to Entra ID>Enterprise apps.
Select Sign-in logs, and then select the latest sign-in log.
For more details, select the Authentication Events tab. Information related to the custom authentication extension REST API call is displayed, including any error codes.

Referência de códigos de erro

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

Error code	Error name	Description
1003000	EventHandlerUnexpectedError	Ocorreu um erro inesperado ao processar um manipulador de eventos.
1003001	CustomExtensionUnexpectedError	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 a 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	The identifierUris property in the manifest for the application registration for the custom extension, should be in the format of "api://{fully qualified domain name}/{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;

Obtaining an access token with an application registration associated with the custom authentication extensions
Teste sua API localmente usando uma ferramenta de teste de API.

Ferramentas de teste de API
Obter um token de acesso

For local development and testing purposes, open local.settings.json and replace the code with the following JSON:
```
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsSecretStorageType": "files",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation" : false
  }
}
```
Note

If you used the Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet package, be sure to set "AuthenticationEvents__BypassTokenValidation" : true for local testing purposes.
Using your preferred API testing tool, create a new HTTP request and set the HTTP method to POST.

Use o corpo JSON a seguir 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"
            }
        }
    }
}

Tip

If you're using an access token obtained from Microsoft Entra ID, select Authorization and then select Bearer token, then paste the access token you received from Microsoft Entra ID.

Select Send, and you should receive a JSON response similar to the following:

{
    "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 um Administrador de Aplicativos na Nuvem.
Browse to Entra ID>App registrations.
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.
Copy the application ID.
Se você ainda não criou um segredo do aplicativo, siga estas etapas:
1. Selecione Certificados & segredosSegredos do clienteNovo 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. Select Add.
5. Record the secret's value for use in your client application code. 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/aaaabbbb-0000-cccc-1111-dddd2222eeee.
Abra sua ferramenta de teste de API preferida e crie uma nova consulta HTTP.
Change the HTTP method to POST.
Insira a URL a seguir. Substitua o {tenantID} pela ID de locatário.
```
https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
```

Under the Body, select form-data and add the following keys:

Key	Value
`grant_type`	`client_credentials`
`client_id`	The Client ID of your application.
`client_secret`	The Client Secret of your application.
`scope`	O URI da ID do Aplicativo do seu aplicativo e, em seguida, adicione `.default`. Por exemplo, `api://contoso.azurewebsites.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/.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 o ID do cliente que você configurou na 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.

Comentários

Esta página foi útil?

Last updated on 2025-07-24

Compartilhar via