Biblioteca cliente de Azure Identity para JavaScript: versión 4.5.0

La biblioteca de identidades de Azure proporciona de identificador de Microsoft Entra (anteriormente, la autenticación de tokens de Azure Active Directory) mediante un conjunto de implementaciones de token TokenCredential convenientes.

Para obtener ejemplos de varias credenciales, consulte la página de ejemplos de identidad de Azure .

Vínculos clave:

• código fuente
• paquete (npm)
• documentación de referencia de api de
• Microsoft Entra Documentación de identidad
• ejemplos de

Empezar

Entornos admitidos actualmente

• versiones ltS de Node.js
• Versiones más recientes de Safari, Chrome, Edge y Firefox.
  • Nota: entre las distintas credenciales exportadas en esta biblioteca, InteractiveBrowserCredential es la única admitida en el explorador.

Para obtener más información, consulte nuestra directiva de soporte técnico de .

Instalación del paquete

Instale Azure Identity con npm:

npm install --save @azure/identity

Prerrequisitos

• Una suscripción de Azure .
• Opcional: el de la CLI de Azure o azure PowerShell también puede resultar útil para autenticarse en un entorno de desarrollo y administrar roles de cuenta.

Cuándo debe usarse @azure/identity

Las clases de credenciales expuestas por @azure/identity se centran en proporcionar la manera más sencilla de autenticar localmente a los clientes del SDK de Azure, en los entornos de desarrollo y en producción. El objetivo es simplificar y admitir razonablemente los protocolos de autenticación para cubrir la mayoría de los escenarios de autenticación posibles en Azure. Estamos expandiendo activamente para cubrir más escenarios. Para obtener una lista completa de las credenciales que se ofrecen, consulte la sección clases de credenciales de .

Todos los tipos de credenciales proporcionados por @azure/identity se admiten en Node.js. En el caso de los exploradores, InteractiveBrowserCredential es el tipo de credencial que se usará para escenarios de autenticación básicos.

La mayoría de los tipos de credenciales ofrecidos por @azure/identity usan la biblioteca de autenticación de Microsoft para JavaScript (MSAL.js). En concreto, usamos las bibliotecas de MSAL.js v2, que usan flujo de código de autorización de OAuth 2.0 con PKCE y son compatibles con OpenID. Aunque @azure/identity se centra en la simplicidad, las bibliotecas de MSAL.js, como @azure/msal-common, @azure/msal-node, y @azure/msal-browser, están diseñadas para proporcionar una sólida compatibilidad con los protocolos de autenticación compatibles con Azure.

Cuándo usar algo más

Los tipos de credenciales de @azure/identity son implementaciones de @azure/core-authclase TokenCredential. En principio, cualquier objeto con un método de getToken que satisfaga getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> funciona como un TokenCredential. Esto significa que los desarrolladores pueden escribir sus propios tipos de credenciales para admitir casos de autenticación no cubiertos por @azure/identity. Para más información, consulte credenciales personalizadas.

Aunque nuestros tipos de credenciales admiten muchos escenarios avanzados, es posible que los desarrolladores quieran usar Biblioteca de autenticación de Microsoft para JavaScript (MSAL.js) directamente. Considere la posibilidad de usar MSAL.js en los escenarios siguientes:

• Los desarrolladores que desean el control total del protocolo de autenticación y su configuración.
• Nuestros tipos de credenciales están diseñados para usarse con clientes de Azure SDK con almacenamiento en caché inteligente y actualización de tokens controladas en la capa HTTP principal. Si tiene que usar getToken directamente, puede beneficiarse del uso de MSAL.js para tener más control sobre el flujo de autenticación y el almacenamiento en caché de tokens.

Puede leer más a través de los vínculos siguientes:

• Se presentan algunos casos de uso avanzados de en la página ejemplos de identidad de Azure .
  • Allí tenemos específicamente una sección Ejemplos avanzados.
  • También tenemos una sección que muestra cómo Autenticar con MSAL directamente.

Para flujos de trabajo de autenticación avanzada en el explorador, tenemos una sección en la que se muestra cómo usar la biblioteca de @azure/msal-browser directamente para autenticar clientes de Azure SDK.

Autenticación del cliente en el entorno de desarrollo

Aunque se recomienda usar la identidad administrada en la aplicación hospedada en Azure, es habitual que un desarrollador use su propia cuenta para autenticar llamadas a los servicios de Azure al depurar y ejecutar código localmente. Hay varias herramientas de desarrollo que se pueden usar para realizar esta autenticación en el entorno de desarrollo.

Autenticación mediante la CLI para desarrolladores de Azure

Los desarrolladores que codifican fuera de un IDE también pueden usar el de la CLI para desarrolladores de Azure para autenticarse. Las aplicaciones que usan el DefaultAzureCredential o el AzureDeveloperCliCredential pueden usar esta cuenta para autenticar las llamadas en su aplicación cuando se ejecutan localmente.

Para autenticarse con elde la CLI para desarrolladores de Azure , los usuarios pueden ejecutar el comando . Para los usuarios que se ejecutan en un sistema con un explorador web predeterminado, la CLI para desarrolladores de Azure inicia el explorador para autenticar al usuario.

En el caso de los sistemas sin un explorador web predeterminado, el comando azd auth login --use-device-code usa el flujo de autenticación de código de dispositivo.

Autenticación mediante la CLI de Azure

Las aplicaciones que usan el AzureCliCredential, ya sea directamente o a través del DefaultAzureCredential, pueden usar la cuenta de la CLI de Azure para autenticar las llamadas en la aplicación cuando se ejecutan localmente.

Para autenticarse con la CLI de Azure , ejecute el comando az login. Para los usuarios que se ejecutan en un sistema con un explorador web predeterminado, la CLI de Azure inicia el explorador para autenticar al usuario.

En el caso de los sistemas sin un explorador web predeterminado, el comando az login usa el flujo de autenticación de código de dispositivo. El usuario también puede forzar a la CLI de Azure a usar el flujo de código del dispositivo en lugar de iniciar un explorador especificando el argumento --use-device-code.

Autenticación mediante Azure PowerShell

Las aplicaciones que usan el AzurePowerShellCredential, ya sea directamente o a través del DefaultAzureCredential, pueden usar la cuenta conectada a Azure PowerShell para autenticar las llamadas en la aplicación cuando se ejecutan localmente.

Para autenticarse con azure PowerShell, ejecute el cmdlet Connect-AzAccount. De forma predeterminada, como la CLI de Azure, Connect-AzAccount inicia el explorador web predeterminado para autenticar una cuenta de usuario.

Si no se puede admitir la autenticación interactiva en la sesión, el argumento -UseDeviceAuthentication obliga al cmdlet a usar un flujo de autenticación de código de dispositivo en su lugar, similar a la opción correspondiente en la credencial de la CLI de Azure.

Autenticación mediante Visual Studio Code

Los desarrolladores que usan Visual Studio Code pueden usar la extensión de cuenta de Azure para autenticarse a través del editor. Las aplicaciones que usan VisualStudioCodeCredential pueden usar esta cuenta para autenticar las llamadas en su aplicación cuando se ejecutan localmente.

Para autenticarse en Visual Studio Code, asegúrese de que la extensión de cuenta de Azure esté instalada. Una vez instalado, abra el paleta de comandos de y ejecute el comando Azure: Iniciar sesión.

Además, use el paquete del complemento @azure/identity-vscode. Este paquete proporciona las dependencias de VisualStudioCodeCredential y lo habilita. Consulte complementos de .

Se trata de un problema conocido que VisualStudioCodeCredential no funciona con extensión de cuenta de Azure versiones más recientes que 0.9.11. Hay una corrección a largo plazo para este problema. Mientras tanto, considere la posibilidad de autenticarse a través de la CLI de Azure.

Autenticación del cliente en exploradores

Para autenticar clientes de Azure SDK en exploradores web, ofrecemos el InteractiveBrowserCredential, que se puede establecer para usar el redireccionamiento o elementos emergentes para completar el flujo de autenticación. Es necesario crear primero una de registro de aplicaciones de Azure en Azure Portal para la aplicación web.

Conceptos clave

Si es la primera vez que usa @azure/identity o id. de Microsoft Entra, lea Using @azure/identity with Microsoft Entra ID (Uso de @azure/identity con el identificador de Entra de Microsoft primero). En este documento se proporciona una comprensión más profunda de la plataforma y cómo configurar la cuenta de Azure correctamente.

Credenciales

Una credencial es una clase que contiene o puede obtener los datos necesarios para que un cliente del servicio autentique las solicitudes. Los clientes de servicio en el SDK de Azure aceptan credenciales cuando se construyen. Los clientes de servicio usan esas credenciales para autenticar las solicitudes en el servicio.

La biblioteca de identidades de Azure se centra en la autenticación de OAuth con el identificador de Microsoft Entra y ofrece varias clases de credenciales capaces de adquirir un token de Microsoft Entra para autenticar las solicitudes de servicio. Todas las clases de credenciales de esta biblioteca son implementaciones de la TokenCredential clase abstracta, y cualquiera de ellas se puede usar para construir clientes de servicio capaces de autenticarse con un TokenCredential.

Consulte clases de credenciales .

DefaultAzureCredential

DefaultAzureCredential simplifica la autenticación al desarrollar aplicaciones que se implementan en Azure mediante la combinación de credenciales usadas en entornos de hospedaje de Azure con credenciales usadas en el desarrollo local. Para obtener más información, consulte Información general sobre DefaultAzureCredential.

Directiva de continuación

A partir de la versión 3.3.0, DefaultAzureCredential intenta autenticarse con todas las credenciales de desarrollador hasta que se realice correctamente, independientemente de los errores que experimentaron las credenciales anteriores del desarrollador. Por ejemplo, una credencial de desarrollador puede intentar obtener un token y producir un error, por lo que DefaultAzureCredential continúa con la siguiente credencial del flujo. Las credenciales de servicio implementadas detienen el flujo con una excepción iniciada si pueden intentar recuperar tokens, pero no reciben una.

Esto permite probar todas las credenciales de desarrollador en la máquina mientras tiene un comportamiento predecible implementado.

Nota sobre VisualStudioCodeCredential

Debido a un problema conocido , VisualStudioCodeCredential se ha quitado de la cadena de tokens de DefaultAzureCredential. Cuando el problema se resuelva en una versión futura, este cambio se revertirá.

Complementos

Azure Identity para JavaScript proporciona una API de complemento que nos permite proporcionar cierta funcionalidad a través de paquetes de complementos de independientes. El paquete @azure/identity exporta una función de nivel superior (useIdentityPlugin) que se puede usar para habilitar un complemento. Proporcionamos dos paquetes de complementos:

• @azure/identity-broker, que proporciona compatibilidad con la autenticación asincrónica a través de un agente nativo, como el Administrador de cuentas web.
• @azure/identity-cache-persistence, que proporciona almacenamiento en caché de tokens persistente en Node.js mediante un sistema de almacenamiento seguro nativo proporcionado por el sistema operativo. Este complemento permite que los valores de access_token almacenados en caché se conserven entre sesiones, lo que significa que no es necesario repetir un flujo de inicio de sesión interactivo siempre que haya disponible un token almacenado en caché.

Ejemplos

Puede encontrar más ejemplos de uso de varias credenciales en página de ejemplos de identidad de Azure

Autenticación con DefaultAzureCredential

En este ejemplo se muestra cómo autenticar el KeyClient desde la biblioteca cliente de @azure/keyvault-keys mediante DefaultAzureCredential.

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

Especificar una identidad administrada asignada por el usuario con DefaultAzureCredential

Un escenario relativamente común implica la autenticación mediante una identidad administrada asignada por el usuario para un recurso de Azure. Explore el ejemplo de autenticación de una identidad administrada asignada por el usuario con DefaultAzureCredential para ver cómo se hace una tarea relativamente sencilla que se puede configurar mediante variables de entorno o en código.

Definición de un flujo de autenticación personalizado con ChainedTokenCredential

Aunque DefaultAzureCredential suele ser la manera más rápida de empezar a desarrollar aplicaciones para Azure, es posible que los usuarios más avanzados quieran personalizar las credenciales que se consideran al autenticarse. El ChainedTokenCredential permite a los usuarios combinar varias instancias de credenciales para definir una cadena personalizada de credenciales. En este ejemplo se muestra cómo crear un ChainedTokenCredential que intenta autenticarse mediante dos instancias configuradas de forma diferente de ClientSecretCredential, para autenticar el KeyClient desde la @azure/keyvault-keys:

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);
// The chain can be used anywhere a credential is required
const client = new KeyClient(vaultUrl, credentialChain);

Compatibilidad con identidades administradas

El de autenticación de identidad administrada de se admite a través del o las clases de credenciales de directamente para los siguientes servicios de Azure:

• Azure App Service y Azure Functions
• azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines
• conjuntos de escalado de Azure Virtual Machines

Para obtener ejemplos de cómo usar la identidad administrada para la autenticación, consulte los ejemplos.

Configuración de la nube

Las credenciales se autentican de forma predeterminada en el punto de conexión de Microsoft Entra para la nube pública de Azure. Para acceder a los recursos de otras nubes, como Azure Government o una nube privada, configure las credenciales con el argumento authorityHost en el constructor. La enumeración AzureAuthorityHosts define autoridades para nubes conocidas. Para la nube de la Administración Pública de EE. UU., podría crear instancias de una credencial de esta manera:

import { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

Como alternativa a especificar el argumento authorityHost, también puede establecer la variable de entorno AZURE_AUTHORITY_HOST en la dirección URL de la autoridad de la nube. Este enfoque es útil al configurar varias credenciales para autenticarse en la misma nube o cuando el entorno implementado necesita definir la nube de destino:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

La enumeración AzureAuthorityHosts define autoridades para nubes conocidas para su comodidad; Sin embargo, si la autoridad de la nube no aparece en AzureAuthorityHosts, puede pasar cualquier dirección URL de autoridad válida como argumento de cadena. Por ejemplo:

import { ClientSecretCredential } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

No todas las credenciales requieren esta configuración. Las credenciales que se autentican a través de una herramienta de desarrollo, como AzureCliCredential, usan la configuración de esa herramienta. Del mismo modo, VisualStudioCodeCredential acepta un argumento de authorityHost, pero el valor predeterminado es la authorityHost que coincide con la configuración de Azure: Cloud de Visual Studio Code.

Clases de credenciales

Cadenas de credenciales

Autenticación de aplicaciones hospedadas en Azure

Autenticación de entidades de servicio

Autenticación de usuarios

Autenticación mediante herramientas de desarrollo

Variables de entorno

DefaultAzureCredential y EnvironmentCredential se pueden configurar con variables de entorno. Cada tipo de autenticación requiere valores para variables específicas.

Entidad de servicio con secreto

Entidad de servicio con certificado

Nombre de usuario y contraseña

La configuración se intenta en el orden anterior. Por ejemplo, si los valores del secreto de cliente y el certificado están presentes, se utiliza el secreto de cliente.

Evaluación continua del acceso

A partir de la versión 3.3.0, es posible acceder a los recursos protegidos por evaluación continua de acceso (CAE) por solicitud. Esto se puede habilitar mediante la API de GetTokenOptions.enableCae(boolean). CAE no es compatible con las credenciales de desarrollador.

Almacenamiento en caché de tokens

El almacenamiento en caché de tokens es una característica proporcionada por la biblioteca de identidades de Azure que permite a las aplicaciones:

• Caché de tokens en memoria (valor predeterminado) y en disco (participación).
• Mejorar la resistencia y el rendimiento.
• Reduzca el número de solicitudes realizadas a Microsoft Entra ID para obtener tokens de acceso.

La biblioteca de identidades de Azure ofrece almacenamiento en caché de disco persistente y en memoria. Para obtener más información, consulte la documentación de almacenamiento en caché de tokens de .

Autenticación asincrónica

Un agente de autenticación es una aplicación que se ejecuta en la máquina de un usuario y administra los protocolos de enlace de autenticación y el mantenimiento de tokens para las cuentas conectadas. Actualmente, solo se admite el Administrador de cuentas web de Windows (WAM). Para habilitar la compatibilidad, use el paquete @azure/identity-broker. Para más información sobre la autenticación mediante WAM, consulte la documentación del complemento de agente de .

Solución de problemas

Para obtener ayuda con la solución de problemas, consulte la guía de solución de problemas de .

Pasos siguientes

Lea la documentación.

Puede encontrar documentación de API para esta biblioteca en nuestro sitio de documentación de .

Compatibilidad con la biblioteca cliente

Las bibliotecas de administración y cliente que aparecen en la página de versiones del SDK de Azure de que admiten la autenticación de Microsoft Entra aceptan credenciales de esta biblioteca. Obtenga más información sobre el uso de estas bibliotecas en su documentación, que está vinculada desde la página de versiones.

Problemas conocidos

Compatibilidad con Azure AD B2C

Esta biblioteca no admite el servicio de azure AD B2C.

Para ver otros problemas abiertos, consulte el repositorio de GitHub de la biblioteca.

Proporcionar comentarios

Si encuentra errores o tiene sugerencias, abrir un problema.

Contribuyendo

Para contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.