Solución de problemas con la autenticación de identidad de Azure

Artículo
10/23/2023

En este artículo se tratan las técnicas de investigación de errores, los errores comunes para los tipos de credenciales de la biblioteca cliente de Java de Identidad de Azure y los pasos de mitigación para resolver estos errores. Dado que hay muchos tipos de credenciales disponibles en el SDK de Azure para Java, hemos dividido la guía de solución de problemas en secciones basadas en el escenario de uso. Están disponibles las siguientes secciones:

En el resto de este artículo se tratan las técnicas generales de solución de problemas y las instrucciones que se aplican a todos los tipos de credenciales.

Control de excepciones de identidad de Azure

Como se indicó en la sección Control de excepciones del SDK de Azure para Java de Información general sobre la solución de problemas, hay un conjunto completo de excepciones y códigos de error que puede iniciar el SDK de Azure para Java. Para Azure Identity específicamente, hay algunos tipos de excepciones clave que son importantes para comprender.

ClientAuthenticationException

Cualquier método cliente de servicio que realice una solicitud al servicio puede generar excepciones derivadas de errores de autenticación. Estas excepciones son posibles porque el token se solicita desde la credencial en la primera llamada al servicio y en cualquier solicitud posterior al servicio que necesite actualizar el token.

Para distinguir estos errores de errores en el cliente de servicio, las clases de identidad de Azure generan ClientAuthenticationException detalles que describen el origen del error en el mensaje de excepción y, posiblemente, el mensaje de error. En función de la aplicación, estos errores pueden recuperarse o no. En el código siguiente se muestra un ejemplo de detección ClientAuthenticationExceptionde :

// 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 es un tipo de excepción especial derivado de ClientAuthenticationException. Este tipo de excepción se usa para indicar que la credencial no se puede autenticar en el entorno actual debido a la falta de configuración o configuración necesarias. Esta excepción también se usa como señal para los tipos de credenciales encadenados, como DefaultAzureCredential y ChainedTokenCredential, que la credencial encadenada debe seguir probando otros tipos de credenciales más adelante en la cadena.

Problemas de permisos

Las llamadas a los clientes de servicio que dan como HttpResponseException resultado un StatusCode de 401 o 403 a menudo indican que el autor de la llamada no tiene permisos suficientes para la API especificada. Compruebe la documentación del servicio para determinar qué roles son necesarios para la solicitud específica. Asegúrese de que al usuario autenticado o a la entidad de servicio se le han concedido los roles adecuados en el recurso.

Búsqueda de información relevante en mensajes de excepción

ClientAuthenticationException se produce cuando se producen errores inesperados mientras se autentica una credencial. Estos errores pueden incluir errores recibidos de solicitudes al servicio de token de seguridad (STS) de Microsoft Entra y a menudo contienen información útil para el diagnóstico. Tenga en cuenta el siguiente ClientAuthenticationException mensaje:

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

Este mensaje de error contiene la siguiente información:

Tipo de credencial con error: tipo de credencial que no se pudo autenticar; en este caso, ClientSecretCredential. Esta información es útil al diagnosticar problemas con tipos de credenciales encadenadas, como DefaultAzureCredential o ChainedTokenCredential.
Código y mensaje de error stS: el código de error y el mensaje devueltos por el STS de Microsoft Entra; en este caso, AADSTS7000215: Invalid client secret provided. esta información puede proporcionar información sobre la razón específica por la que se produjo un error en la solicitud. Por ejemplo, en este caso específico, porque el secreto de cliente proporcionado es incorrecto. Para obtener más información sobre los códigos de error STS, consulte la sección Códigos de error de AADSTS de los códigos de error de autenticación y autorización de Microsoft Entra.
Id. de correlación y marca de tiempo: identificador de correlación y marca de tiempo de llamada que se usa para identificar la solicitud en los registros del lado servidor. Esta información es útil para admitir ingenieros al diagnosticar errores inesperados de STS.

Habilitación y configuración del registro

El SDK de Azure para Java ofrece un artículo de registro coherente para ayudar a solucionar errores de aplicación y para ayudar a acelerar su resolución. Los registros generados capturan el flujo de una aplicación antes de alcanzar el estado terminal para ayudar a encontrar el problema raíz. Para obtener instrucciones sobre el registro, consulte Configuración del registro en el SDK de Azure para Java y Solución de problemas a través de la vista.

La biblioteca MSAL subyacente, MSAL4J, también tiene un registro detallado. Este registro es muy detallado e incluye todos los datos personales, incluidos los tokens. Este registro es más útil cuando se trabaja con soporte técnico del producto. A partir de la versión 1.10.0, las credenciales que ofrecen este registro tienen un método denominado enableUnsafeSupportLogging().

Precaución

Las solicitudes y respuestas de la biblioteca de identidades de Azure contienen información confidencial. Debe tomar precauciones para proteger los registros al personalizar la salida para evitar poner en peligro la seguridad de la cuenta.

Pasos siguientes

Si la guía de solución de problemas de este artículo no ayuda a resolver problemas al usar las bibliotecas cliente de Azure SDK para Java, se recomienda presentar un problema en el repositorio de GitHub del SDK de Azure para Java.

Compartir vía