Compartilhar via

Solucionar problemas de autenticação de identidade do Azure

Este artigo aborda técnicas de investigação de falhas, erros comuns para os tipos de credencial na biblioteca de clientes Java de Identidade do Azure e etapas de mitigação para resolver esses erros. Como há muitos tipos de credencial disponíveis no SDK do Azure para Java, dividimos o guia de solução de problemas em seções com base no cenário de uso. As seguintes seções estão disponíveis:

O restante deste artigo aborda técnicas gerais de solução de problemas e diretrizes que se aplicam a todos os tipos de credencial.

Identificar exceções de identidade do Azure

Conforme observado no tratamento de exceções na seção SDK do Azure para Java da visão geral de solução de problemas, há um conjunto abrangente de exceções e códigos de erro que o SDK do Azure para Java pode gerar. Especificamente para a Identidade do Azure, há alguns tipos de exceção importantes para entender.

ClientAuthenticationException

Qualquer método de cliente de serviço que faça uma solicitação ao serviço pode gerar exceções decorrentes de erros de autenticação. Essas exceções são possíveis porque o token é solicitado da credencial na primeira chamada para o serviço e em quaisquer solicitações subsequentes para o serviço que precisam atualizar o token.

Para distinguir essas falhas das falhas no cliente de serviço, as classes de identidade do Azure geram ClientAuthenticationException com detalhes que descrevem a origem do erro na mensagem de exceção e possivelmente com a mensagem de erro. Dependendo do aplicativo, esses erros podem ou não ser recuperáveis. O código a seguir mostra um exemplo de captura ClientAuthenticationException:

// Create a secret client using the DefaultAzureCredential
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://myvault.vault.azure.net/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

try {
    KeyVaultSecret secret = client.getSecret("secret1");
} catch (ClientAuthenticationException e) {
    //Handle Exception
    e.printStackTrace();
}

CredentialUnavailableException

CredentialUnavailableException é um tipo de exceção especial derivado de ClientAuthenticationException. Esse tipo de exceção é usado para indicar que a credencial não pode se autenticar no ambiente atual devido à falta de configuração ou configuração necessária. Essa exceção também é usada como um sinal para tipos de credenciais encadeadas, como DefaultAzureCredential e ChainedTokenCredential, que a credencial encadeada deve continuar a tentar outros tipos de credencial posteriormente na cadeia.

Problemas de permissão

Chamadas para clientes do serviço que resultam em HttpResponseException com um StatusCode 401 ou 403 geralmente indicam que o chamador não tem permissões suficientes para a API especificada. Verifique a documentação do serviço para determinar quais funções são necessárias para a solicitação específica. Verifique se o usuário autenticado ou a entidade de serviço recebeu as funções apropriadas no recurso.

Localizar informações relevantes em mensagens de exceção

ClientAuthenticationException é lançado quando ocorrem erros inesperados enquanto uma credencial está sendo autenticada. Esses erros podem incluir erros recebidos de solicitações ao serviço de token de segurança (STS) do Microsoft Entra e geralmente contêm informações úteis para diagnóstico. Considere a seguinte ClientAuthenticationException mensagem:

ClientSecretCredential authentication failed: A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details.

Original exception:
AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.
Trace ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Correlation ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Timestamp: 2022-01-01 00:00:00Z

Esta mensagem de erro contém as seguintes informações:

  • Tipo de credencial com falha: o tipo de credencial que não conseguiu autenticar - nesse caso, ClientSecretCredential. Essas informações são úteis ao diagnosticar problemas com tipos de credenciais encadeadas, como DefaultAzureCredential ou ChainedTokenCredential.

  • Código e mensagem de erro STS: o código de erro e a mensagem retornados do Microsoft Entra STS – nesse caso, AADSTS7000215: Invalid client secret provided. esses dados podem esclarecer o motivo específico pelo qual a solicitação falhou. Por exemplo, nesse caso específico, porque o segredo do cliente fornecido está incorreto. Para obter mais informações sobre códigos de erro STS, consulte a seção códigos de erro do AADSTS dos códigos de erro de autenticação e autorização do Microsoft Entra.

  • ID de correlação e carimbo de data/hora: a ID de correlação e o carimbo de data/hora de chamada usados para identificar a solicitação nos logs do lado do servidor. Essas informações são úteis para dar suporte aos engenheiros ao diagnosticar falhas de STS inesperadas.

Habilitar e configurar o registro em log

O SDK do Azure para Java oferece uma história de log consistente para ajudar na solução de problemas de erros do aplicativo e para ajudar a agilizar sua resolução. Os logs produzidos capturam o fluxo de um aplicativo antes de atingir o estado do terminal para ajudar a localizar o problema raiz. Para obter diretrizes sobre o registro em log, consulte Configurar o registro em log no SDK do Azure para Java e Visão geral de solução de problemas.

A biblioteca MSAL subjacente, MSAL4J, também possui registro em log detalhado. Esse registro é altamente detalhado e inclui todos os dados pessoais, incluindo tokens. Esse registro em log é mais útil ao trabalhar com o suporte ao produto. A partir da v1.10.0, as credenciais que oferecem esse registro em log têm um método chamado enableUnsafeSupportLogging().

Cuidado

Solicitações e respostas na biblioteca de Identidades do Azure contêm informações confidenciais. Você deve tomar precauções para proteger os logs ao personalizar a saída para evitar comprometer a segurança da conta.

Próximas etapas

Se as diretrizes de solução de problemas neste artigo não ajudarem a resolver problemas quando você usa o SDK do Azure para bibliotecas de clientes Java, recomendamos que você registre um problema no repositório GitHub do Azure SDK para Java.

  • Last updated on