Compartir a través de

Cadenas de credenciales en la biblioteca de identidades de Azure para Java

La biblioteca Azure Identity proporciona credenciales, clases públicas que implementan la interfaz TokenCredential de la biblioteca Azure Core. Una credencial representa un flujo de autenticación distinto para adquirir un token de acceso de Microsoft Entra ID. Estas credenciales se pueden encadenar para formar una secuencia ordenada de mecanismos de autenticación que se van a intentar.

Funcionamiento de una credencial encadenada

En tiempo de ejecución, una cadena de credenciales intenta autenticarse mediante la primera credencial de la secuencia. Si esa credencial no puede adquirir un token de acceso, se intenta utilizar la siguiente credencial de la secuencia, y así sucesivamente hasta que se obtenga correctamente un token de acceso. En el siguiente diagrama de secuencia se ilustra este comportamiento:

Diagrama donde se ve una secuencia de cadena de credenciales.

¿Por qué usar cadenas de credenciales?

Una credencial encadenada puede ofrecer las siguientes ventajas:

  • Reconocimiento del entorno: selecciona automáticamente la credencial más adecuada en función del entorno en el que se ejecuta la aplicación. Sin ella, tendría que escribir código como este:

    import com.azure.core.credential.TokenCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// Code omitted for brevity

TokenCredential credential = null;

// Set up credential based on environment (Azure or local development)
String environment = System.getenv("ENV");

if (environment != null && environment.equals("production")) {
    credential = new ManagedIdentityCredentialBuilder()
        .clientId(userAssignedClientId)
        .build();
} else {
    credential = new AzureCliCredentialBuilder()
        .build();
}

  • Transiciones fluidas: la aplicación puede pasar del desarrollo local al entorno de ensayo o producción sin cambiar el código de autenticación.

  • Resiliencia mejorada: incluye un mecanismo de respaldo que pasa a la siguiente credencial cuando la anterior no logra obtener un token de acceso.

Cómo elegir una credencial encadenada

Hay dos enfoques diferentes para el encadenamiento de credenciales:

Información general sobre DefaultAzureCredential

DefaultAzureCredential es una cadena preconfigurada de credenciales fundamentada. Está diseñada para admitir muchos entornos, junto con los flujos de autenticación y las herramientas de desarrollo más comunes. En forma gráfica, la cadena subyacente tiene este aspecto:

Diagrama que muestra el flujo de autenticación DefaultAzureCredential.

El orden en el que DefaultAzureCredential intenta las credenciales es el siguiente.

Pedido de Credencial Descripción
1 Entorno Lee una colección de variables de entorno para determinar si un principal de servicio de aplicación (usuario de la aplicación) está configurado para la aplicación. Si es así, DefaultAzureCredential usa estos valores para autenticar la aplicación en Azure. Este método se puede usar al desarrollar localmente, pero se usa con más frecuencia en entornos de servidor.
2 Identidad de carga de trabajo Si la aplicación se implementa en un host de Azure con la identidad de carga de trabajo habilitada, autentíquela.
3 Identidad administrada Si la aplicación se implementa en un host de Azure con la identidad administrada habilitada, autentique la aplicación en Azure mediante esa identidad administrada.
4 IntelliJ Si el desarrollador se autenticó a través de Azure Toolkit for IntelliJ, autentique esa cuenta.
5 Visual Studio Code Si el desarrollador se autentica a través de la extensión Azure Resources de Visual Studio Code y el paquete azure-identity-broker está instalado, autentique esa cuenta.
6 Azure CLI Si el desarrollador se autentica en Azure mediante el comando az login de Azure CLI, autentique la aplicación en Azure con esa misma cuenta.
7 Azure PowerShell Si el desarrollador se autentica en Azure mediante el cmdlet Connect-AzAccount de Azure PowerShell, autentique la aplicación en Azure con esa misma cuenta.
8 Azure CLI para desarrolladores Si el desarrollador se autentica en Azure mediante el comando azd auth login de la CLI para desarrolladores de Azure, autentíquese con esa cuenta.
9 broker Se autentica utilizando la cuenta predeterminada que ha iniciado sesión en el sistema operativo a través de un intermediario. Requiere que el paquete azure-identity-broker esté instalado, ya que se usa una instancia habilitada para broker de InteractiveBrowserCredential.

En su forma más sencilla, puede usar la versión sin parámetros de DefaultAzureCredential de la siguiente manera:

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

Personalización de DefaultAzureCredential

En las secciones siguientes se describen las estrategias para controlar qué credenciales se incluyen en la cadena.

Excluir una categoría de tipo de credencial

Para excluir todas las credenciales Developer tool o Deployed service, establezca la variable de entorno AZURE_TOKEN_CREDENTIALS a prod o dev, respectivamente. Cuando se usa un valor de prod, la cadena de credenciales subyacente tiene el siguiente aspecto:

Diagrama que muestra DefaultAzureCredential con AZURE_TOKEN_CREDENTIALS establecido en

Cuando se usa un valor de dev , la cadena tiene el siguiente aspecto:

Diagrama que muestra DefaultAzureCredential con AZURE_TOKEN_CREDENTIALS establecido en

Importante

La AZURE_TOKEN_CREDENTIALS variable de entorno se admite en azure-identity las versiones del paquete 1.16.1 y posteriores.

Para asegurarse de que la variable de entorno está definida y establecida en una cadena admitida, llame al método requireEnvVars de la manera siguiente:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Importante

El requireEnvVars método está disponible en las versiones del paquete azure-identity a partir de la 1.18.0.

Para usar un nombre de variable de entorno personalizado en lugar del valor predeterminado AZURE_TOKEN_CREDENTIALS, use AzureIdentityEnvVars.fromString() para crear una referencia a la variable personalizada:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
    .build();

Nota:

El requireEnvVars método produce un IllegalStateException si las variables de entorno especificadas no están establecidas o están vacías.

Uso de una credencial específica

Para excluir todas las credenciales excepto para una, establezca la variable AZURE_TOKEN_CREDENTIALS de entorno en el nombre de la credencial. Por ejemplo, puede reducir la DefaultAzureCredential cadena a AzureCliCredential estableciendo AZURE_TOKEN_CREDENTIALS en AzureCliCredential. La comparación de cadenas se realiza de forma que no distingue mayúsculas de minúsculas. Entre los valores de cadena válidos para la variable de entorno se incluyen:

  • AzureCliCredential
  • AzureDeveloperCliCredential
  • AzurePowerShellCredential
  • EnvironmentCredential
  • IntelliJCredential
  • ManagedIdentityCredential
  • VisualStudioCodeCredential
  • WorkloadIdentityCredential

Importante

La AZURE_TOKEN_CREDENTIALS variable de entorno admite nombres de credenciales individuales en azure-identity las versiones del paquete 1.17.0 y versiones posteriores.

Para asegurarse de que la variable de entorno está definida y establecida en una cadena admitida, llame al método requireEnvVars como se indica a continuación:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Información general sobre ChainedTokenCredential

ChainedTokenCredential es una cadena vacía a la que agrega credenciales para satisfacer las necesidades de la aplicación. Por ejemplo:

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(cliCredential)
    .addLast(ijCredential)
    .build();

En el ejemplo de código anterior se crea una cadena de credenciales adaptada compuesta por dos credenciales de tiempo de desarrollo. Primero se intenta AzureCliCredential, seguido de IntelliJCredentialsi es necesario. En forma gráfica, la cadena tiene este aspecto:

Diagram que muestra el flujo de autenticación de una instancia ChainedTokenCredential compuesta por las credenciales de Azure CLI e IntelliJ.

Sugerencia

Para mejorar el rendimiento, optimice el orden de las credenciales en ChainedTokenCredential de la mayoría a las credenciales menos usadas.

Guía de uso para DefaultAzureCredential

DefaultAzureCredential es sin duda la manera más fácil de empezar a trabajar con la biblioteca de identidades de Azure, pero con esa comodidad se presentan compensaciones. Después de implementar la aplicación en Azure, debe comprender los requisitos de autenticación de la aplicación y considerar si DefaultAzureCredential es adecuado para su escenario.

DefaultAzureCredential ofrece una ventaja clave: desacopla el código de la aplicación de mecanismos de autenticación específicos, lo que le permite cambiar la configuración de autenticación sin modificar el código. Para los desarrolladores experimentados que configuran conscientemente su autenticación de producción, esta flexibilidad puede ser valiosa. Sin embargo, esta flexibilidad incluye posibles inconvenientes:

  • Desafíos de depuración: cuando se produce un error en la autenticación, puede resultar difícil depurar e identificar las credenciales incorrectas. Debe habilitar el registro para ver la progresión de una credencial a la siguiente y el estado de éxito o error de cada una. Para obtener más información, consulte Depuración de una credencial encadenada.
  • Sobrecarga de rendimiento: el proceso de probar secuencialmente varias credenciales puede suponer una sobrecarga de rendimiento. Por ejemplo, cuando se ejecuta en una máquina de desarrollo local, la identidad administrada no está disponible. Por tanto, ManagedIdentityCredential siempre produce un error en el entorno de desarrollo local.
  • Unpredictable behavior: DefaultAzureCredential comprueba la presencia de determinadas variables de entorno. Es posible que alguien pueda agregar o modificar estas variables de entorno en el nivel de sistema en el equipo host. Esos cambios se aplican globalmente y, por tanto, modifican el comportamiento de DefaultAzureCredential en tiempo de ejecución en cualquier aplicación que se ejecute en esa máquina.
  • Desajustes de permisos: DefaultAzureCredential se detiene en la primera credencial que adquiere correctamente un token, independientemente de si esa credencial tiene los permisos correctos. Por ejemplo, una credencial de desarrollo local puede tener permisos más amplios que la identidad administrada de producción, lo que hace que la aplicación funcione localmente, pero no se realicen comprobaciones de autorización después de la implementación.

Depuración de una credencial encadenada

Para diagnosticar un problema inesperado o comprender lo que hace una credencial encadenada, habilite el registro en la aplicación.

Para fines ilustrativos, supongamos que la forma sin parámetros de DefaultAzureCredential se usa para autenticar una solicitud en una cuenta de Blob Storage. La aplicación se ejecuta en el entorno de desarrollo local y el desarrollador se autentica en Azure mediante el Azure CLI. Cuando se ejecuta la aplicación, aparecen las siguientes entradas pertinentes en la salida:

[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

En la salida anterior, puede ver lo siguiente:

  • EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential y VisualStudioCodeCredential cada uno no pudo adquirir un token de acceso de Microsoft Entra, en ese orden.
  • La llamada a AzureCliCredential.getToken se realiza correctamente, tal como se indica en la entrada con sufijo returns a token. Dado que AzureCliCredential se autenticó correctamente, no se intentaron otras credenciales adicionales.
  • Last updated on