Solucionar problemas de autenticação de 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 de Identidade do Azure 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. As seguintes seções estão disponíveis:

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 de Identidade do Azure

Conforme observado na seção Tratamento de exceções na seção 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 de 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 das falhas no cliente de serviço, as classes de Identidade do Azure geram ClientAuthenticationException 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 do serviço para determinar quais funções são necessárias para a solicitação específica. Certifique-se de que 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 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

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

  • Tipo de credencial com falha: o tipo de credencial que falhou ao 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 e mensagem STS: O código de erro e a mensagem retornados do Microsoft Entra STS - nesse 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 de chamada usados para identificar a solicitação em logs do lado 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 log consistente para ajudar na solução de problemas de erros de aplicativos e para ajudar a agilizar sua resolução. Os logs produzidos capturam o fluxo de um aplicativo antes de acessarem o estado do terminal para ajudar a localizar o problema raiz. Para obter orientação sobre log, consulte Configurar o log no SDK do Azure para Java e Solução de problemas sobre exibição.

A biblioteca MSAL subjacente, MSAL4J, também tem registro detalhado. Esse registro é 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().

Cuidado

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óximas etapas

Se a orientação de solução de problemas neste artigo não ajudar a resolver problemas ao usar o SDK do Azure para bibliotecas de cliente Java, recomendamos que você registre um problema no repositório do Azure SDK para Java GitHub.