Cadenas de credenciales en la biblioteca cliente de identidades de Azure para Java
La biblioteca cliente de identidades de Azure incluye credenciales, clases públicas que implementan la interfaz TokenCredential de la biblioteca de 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:
¿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.
Resistencia mejorada: incluye un mecanismo de reserva que pasa a la siguiente credencial cuando la anterior no puede adquirir un token de acceso.
Cómo elegir una credencial encadenada
Hay dos filosofías dispares para encadenar credenciales:
- Usar una cadena preconfigurada: empiece con una cadena predefinida y ya estructurada que admita los posibles modos de autenticación más comunes. Para este enfoque, consulte la sección Información general sobre DefaultAzureCredential.
- "Crear" una cadena: comience con una cadena vacía e incluya solo lo que necesita. Para este enfoque, consulte la sección Información general sobre ChainedTokenCredential.
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:
Orden en el que DefaultAzureCredential
intenta las credenciales.
compra | Credential: | Descripción |
---|---|---|
1 | Entorno | Lee una colección de variables de entorno para determinar si una entidad de servicio de aplicación (usuario de aplicación) está configurada para la aplicación. Si es así, DefaultAzureCredential usa estos valores para autenticar la aplicación en Azure. Este método se usa con más frecuencia en entornos de servidor, pero también se puede usar al desarrollar localmente. |
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, autentica esa cuenta. |
3 | Identidad administrada | Si la aplicación se implementa en un host de Azure con la identidad administrada habilitada, se autentica la aplicación en Azure usando esa identidad administrada. |
4 | Caché de tokens compartidos | Si el desarrollador se autenticó en Azure iniciando sesión en Visual Studio, se autentica la aplicación en Azure con esa misma cuenta. (Solo Windows). |
5 | IntelliJ | Si el desarrollador se autentica a través del Azure Toolkit for IntelliJ, autentique la cuenta. |
6 | CLI de Azure | Si el desarrollador se autenticó en Azure mediante el comando az login de la CLI de Azure, se autentica la aplicación en Azure con esa misma cuenta. |
7 | Azure PowerShell | Si el desarrollador se autenticó en Azure mediante el cmdlet Connect-AzAccount de Azure PowerShell, se autentica la aplicación en Azure con esa misma cuenta. |
8 | CLI de desarrollo de Azure | Si el desarrollador se autenticó en Azure mediante el comando azd auth login de la CLI para desarrolladores de Azure, se autentica con esa cuenta. |
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();
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.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;
// Code omitted for brevity
ManagedIdentityCredential miCredential = new ManagedIdentityCredentialBuilder()
.clientId(userAssignedClientId)
.build();
AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
.build();
ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
.addLast(miCredential)
.addLast(cliCredential)
.build();
El ejemplo de código anterior crea una cadena de credenciales adaptada formada por dos credenciales. La variante de identidad administrada asignada por el usuario de ManagedIdentityCredential
se intenta primero, seguida de AzureCliCredential
, si es necesario. En forma gráfica, la cadena tiene este aspecto:
Sugerencia
Para mejorar el rendimiento, optimice el orden de las credenciales en ChainedTokenCredential
para el entorno de producción. Las credenciales diseñadas para su uso en el entorno de desarrollo local deben agregarse en último lugar.
Guía de uso para DefaultAzureCredential
DefaultAzureCredential
es, sin duda, la manera más fácil de empezar a trabajar con la biblioteca cliente de identidades de Azure, pero esa comodidad conlleva ventajas y desventajas. Una vez que implemente la aplicación en Azure, debe comprender los requisitos de autenticación de la aplicación. Por esa razón, considere encarecidamente la posibilidad de pasar de DefaultAzureCredential
a una de las siguientes soluciones:
- Una implementación de credencial específica, como
ManagedIdentityCredential
. - Una implementación de
ChainedTokenCredential
reducida optimizada para el entorno Azure en el que se ejecuta la aplicación.
Aquí se detallan los motivos:
- 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. - Comportamiento imprevisible:
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 deDefaultAzureCredential
en tiempo de ejecución en cualquier aplicación que se ejecute en esa máquina.
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 que se vea de ejemplo, supongamos que se usa la forma sin parámetros de DefaultAzureCredential
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 la CLI de Azure. 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 SharedTokenCacheCredential 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 AzureCliCredential returns a token
En la salida anterior, puede ver lo siguiente:
EnvironmentCredential
,WorkloadIdentityCredential
,ManagedIdentityCredential
,SharedTokenCacheCredential
yIntelliJCredential
no pudieron adquirir el 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 sufijoreturns a token
. Dado queAzureCliCredential
se realizó correctamente, no se intentaron más credenciales.