Solucionar problemas da API do provedor de declarações personalizado
Eventos de autenticação e provedores de declarações personalizados permitem que você personalize a experiência de autenticação do Microsoft Entra integrando-se com sistemas externos. Por exemplo, você pode criar uma API de provedor de declarações personalizada e configurar um aplicativo OpenID Connect ou um aplicativo SAML para receber tokens com declarações de um repositório externo.
Comportamento de erro
Quando uma chamada de API falha, o comportamento de erro é o seguinte:
- Para aplicativos OpenId Connect - Microsoft Entra ID redireciona o usuário de volta para o aplicativo cliente com um erro. Um token não é cunhado.
- Para aplicativos SAML - 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 entrada para os códigos de erro.
Registo
Para solucionar problemas com o ponto de extremidade da API REST do provedor de declarações personalizadas, a API REST deve lidar com o registro em log. O Azure Functions e outras plataformas de desenvolvimento de API fornecem soluções de registo detalhadas. Use essas soluções para obter informações detalhadas sobre o comportamento de suas APIs e solucionar problemas de sua lógica de API.
Registos de início de sessão do Microsoft Entra
Gorjeta
As etapas neste artigo podem variar ligeiramente com base no portal a partir do qual você começou.
Você também pode usar os logs de entrada do Microsoft Entra além dos logs da API REST e das soluções de diagnóstico do ambiente de hospedagem. Usando os logs de entrada do Microsoft Entra, você pode encontrar erros, que podem afetar os logins dos usuários. Os logs de entrada do Microsoft Entra fornecem informações sobre o status HTTP, código de erro, duração de execução e número de novas tentativas que ocorreram na API foi chamada pelo ID do Microsoft Entra.
Os logs de entrada do Microsoft Entra também se integram ao Azure Monitor. Você pode configurar alertas e monitoramento, visualizar os dados e integrar com ferramentas de gerenciamento de eventos e informações de segurança (SIEM). Por exemplo, você pode configurar notificações se o número de erros exceder um determinado limite escolhido.
Para aceder aos registos de início de sessão do Microsoft Entra:
Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na nuvem.
Navegue até Aplicativos de identidade>>Aplicativos corporativos.
Selecione Registos de início de sessão e, em seguida, selecione o registo de início de sessão mais recente.
Para obter mais detalhes, selecione a guia Eventos de autenticação. Informações relacionadas à chamada à API REST da 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 de erro | Nome do erro | Description |
|---|---|---|
| 1003000 | EventHandlerUnexpectedError | Houve um erro inesperado ao processar um manipulador de eventos. |
| 1003001 | CustomExtenstionUnexpectedError | Houve 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 de resposta da extensão personalizada. Verifique se o corpo de 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 personalizadas. Essa exceção é lançada para chamadas de API de extensão personalizadas 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 sua 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 saco 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 de 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 do que as suportadas para esse tipo de extensão personalizada. |
| 1003011 | CustomExtensionNotFound | A extensão personalizada associada a um ouvinte de eventos não pôde ser encontrada. |
| 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 para o registro do aplicativo para a extensão personalizada deve estar no formato "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 | O 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 é encontrada no locatário. |
| 1003018 | CustomExtensionClientServiceDisabled | A entidade de serviço de recurso de extensão personalizada está desabilitada neste locatário. |
| 1003019 | CustomExtensionResourceServicePrincipalDisabled | A entidade de serviço de recurso de extensão personalizada está desabilitada neste locatário. |
| 1003020 | CustomExtensionIncorrectTargetUrlFormat | O URL de destino está em um formato impróprio. Deve ser um URL válido que comece com https. |
| 1003021 | CustomExtensionPermissionNotGrantedToServicePrincipal | A entidade de serviço não tem consentimento de administrador para a função de aplicativo Microsoft Graph CustomAuthenticationExtensions.Receive.Payload (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 personalizada. |
| 1003022 | CustomExtensionMsGraphServicePrincipalDisabledOrNotFound | A entidade de serviço do MS Graph está desativada ou não foi encontrada neste locatário. |
| 1003023 | CustomExtensionBlocked | O ponto de extremidade usado para a extensão personalizada é bloqueado pelo serviço. |
| 1003024 | CustomExtensionResponseSizeExceeded | O tamanho da resposta da extensão personalizada excedeu o limite máximo. |
| 1003025 | CustomExtensionResponseClaimsSizeExceeded | O tamanho total das declarações na resposta de extensão personalizada excedeu o limite máximo. |
| 1003026 | CustomExtensionNullOrEmptyClaimKeyNotSupported | A API de extensão personalizada respondeu com declarações contendo chave nula ou vazia' |
| 1003027 | CustomExtensionConnectionError | Erro ao se conectar à API de extensão personalizada. |
Ligue diretamente para sua API REST
Sua API REST é protegida por um token de acesso do Microsoft Entra. Você pode testar sua API por;
- Obtendo 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.
Para fins de desenvolvimento local e testes, 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 } }Usando sua ferramenta de teste de API preferida, 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 ID do Microsoft Entra 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" } } } }Gorjeta
Se estiver a utilizar um token de acesso obtido a partir do Microsoft Entra ID, selecione Autorização e, em seguida, selecione Token de portador e, em seguida, cole o token de acesso que recebeu do Microsoft Entra ID.
Selecione Enviar e você deve 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" ] } } ] } }
Melhorias comuns de desempenho
Um dos problemas mais comuns é que a API do provedor de declarações personalizado não responde dentro do tempo limite de dois segundos. Se a API REST não responder em tentativas subsequentes, a autenticação falhará. Para melhorar o desempenho da sua API REST, siga as sugestões abaixo:
- Se sua API acessar quaisquer 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.
- Os problemas de desempenho estão frequentemente relacionados com os serviços a jusante. Adicione log, que registra o tempo do processo para chamar qualquer serviço downstream.
- Se você usa 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.
Consulte também
- Criar uma API REST com um evento de início de emissão de token
- Configurar um aplicativo SAML para receber tokens com declarações de um repositório externo
- Artigo de referência do provedor de declarações personalizadas.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários