Resolver problemas de autenticação da Identidade do Azure

  • Artigo

Este artigo aborda técnicas de investigação de falhas, erros comuns para os tipos de credenciais na biblioteca de cliente Java do Azure Identity e etapas de mitigação para resolver esses erros. Como há muitos tipos de credenciais 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. Estão disponíveis as seguintes secções:

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

Manipular exceções do Azure Identity

Conforme observado na seção Tratamento de exceções no SDK do Azure para Java de 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 lançar. Para a Identidade do Azure especificamente, há alguns tipos de exceção importantes que são importantes 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 ao serviço que precisem atualizar o token.

Para distinguir essas falhas de falhas no cliente de serviço, as classes de Identidade do Azure são geradas ClientAuthenticationException com detalhes que descrevem a origem do erro na mensagem de exceção e, possivelmente, 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 ser autenticada 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, de que a credencial encadeada deve continuar a tentar outros tipos de credenciais posteriormente na cadeia.

Problemas de permissão

As chamadas para clientes de serviço que resultam em HttpResponseException um StatusCode de 401 ou 403 geralmente indicam que o chamador não tem permissões suficientes para a API especificada. Verifique a documentação de 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.

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

ClientAuthenticationException é lançado quando ocorrem erros inesperados durante a autenticação de uma credencial. Esses erros podem incluir erros recebidos de solicitações para o serviço de token de segurança (STS) do Microsoft Entra e geralmente contêm informações úteis para o 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 - neste caso, ClientSecretCredential. Essas informações são úteis ao diagnosticar problemas com tipos de credenciais encadeadas, como DefaultAzureCredential ou ChainedTokenCredential.

  • Código de erro STS e mensagem: O código de erro e a mensagem retornados do Microsoft Entra STS - neste caso, AADSTS7000215: Invalid client secret provided. essas informações podem fornecer informações sobre o motivo específico da falha na solicitação. Por exemplo, neste 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 AADSTS de Códigos de erro de autenticação e autorização do Microsoft Entra.

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

Habilitar e configurar o registro em log

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

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

Atenção

As 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óximos passos

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 cliente Java, recomendamos que você registre um problema no repositório do SDK do Azure para Java GitHub.