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

La biblioteca 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 realizar la siguiente credencial de la secuencia, etc., hasta que se obtenga correctamente un token de acceso. En el diagrama de secuencia siguiente se muestra este comportamiento:

Diagrama que ilustra el flujo de autenticación de la cadena de credenciales con intentos secuenciales en varias credenciales hasta la adquisición correcta de tokens.

¿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 él, tendría que escribir código como este:

import { 
    ManagedIdentityCredential, 
    AzureCliCredential 
} from "@azure/identity";

let credential;
if (process.env.NODE_ENV === "production") {
    credential = new ManagedIdentityCredential();
} else {
    credential = new AzureCliCredential();
}

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:

"Desmontar" una cadena: comience con una cadena preconfigurada y excluya lo que no necesita. 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ñado 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	¿Habilitado de forma predeterminada?
1	Entorno	Lee una colección de las variables de entorno para determinar si una entidad de servicio principal de la 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.	Sí
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.	Sí
3	Identidad Administrada	Si la aplicación se implementa en un host de Azure con identidad administrada habilitada, autentíquela en Azure mediante esa identidad administrada.	Sí
4	Visual Studio Code	Si el desarrollador se autentica a través de la extensión Recursos de Azure de Visual Studio Code y el paquete @azure/identity-vscode está instalado, autentíquela.	Sí
5	CLI de Azure	Si el desarrollador se autentica en Azure mediante el comando `az login` de la CLI de Azure, autentíquela en Azure con esa misma cuenta.	Sí
6	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.	Sí
7	CLI para desarrolladores de Azure	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.	Sí
8	broker	Se autentica mediante 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.	Sí

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

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

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 de la cadena DefaultAzureCredential con AZURE_TOKEN_CREDENTIALS establecido en

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

Diagrama de la cadena DefaultAzureCredential con AZURE_TOKEN_CREDENTIALS establecido en

Para asegurarse de que la variable de entorno está definida y establecida en una cadena admitida, establezca la propiedad AZURE_TOKEN_CREDENTIALS en :

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

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
ManagedIdentityCredential
VisualStudioCodeCredential
WorkloadIdentityCredential

Importante

La AZURE_TOKEN_CREDENTIALS variable de entorno admite nombres de credenciales individuales en @azure/identity las versiones del paquete 4.11.0 y versiones posteriores.

Para asegurarse de que la variable de entorno está definida y establecida en una cadena admitida, establezca la propiedad requiredEnvVars en AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Información general sobre ChainedTokenCredential

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

import { 
    ChainedTokenCredential, 
    AzureCliCredential, 
    VisualStudioCodeCredential 
} from "@azure/identity";

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

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

Diagrama de la configuración ChainedTokenCredential que muestra AzureCliCredential como método de autenticación principal con VisualStudioCodeCredential como opción de reserva secundaria.

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 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 ese motivo, reemplace DefaultAzureCredential por una implementación de TokenCredential específica, como ManagedIdentityCredential.

Este es el motivo:

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 Depurar una credencial.
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 de DefaultAzureCredential en tiempo de ejecución en cualquier aplicación que se ejecute en esa máquina.

Depurar una credencial

Para diagnosticar un problema inesperado o comprender lo que hace una credencial, habilite el registro en tu aplicación. Por ejemplo:

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

En la salida anterior, observe que DefaultAzureCredential adquirió correctamente un token mediante AzureCliCredential.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-10-10