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

La biblioteca de identidades de Azure proporciona autenticación de tokens de Azure Active Directory (Azure AD) a través de un conjunto de implementaciones de TokenCredential convenientes.

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

Vínculos principales:

Introducción

Migración de v1 a v2 de @azure/identity

Si usa v1 de , consulte la guía de @azure/identitymigración para actualizar a v2.

Entornos admitidos actualmente

  • Versiones de LTS de Node.js
    • Nota: Si la aplicación se ejecuta en Node.js v8 o inferior y no puede actualizar la versión de Node.js a la versión estable más reciente, ancle la @azure/identity dependencia a la versión 1.1.0.
  • Versiones más recientes de Safari, Chrome, Edge y Firefox.
    • Nota: Entre las distintas credenciales exportadas en esta biblioteca, InteractiveBrowserCredential es la única que se admite en el explorador.

Para más información, consulte la directiva de compatibilidad.

Instalar el paquete

Instale Azure Identity con npm:

npm install --save @azure/identity

Prerrequisitos

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 los clientes del SDK de Azure, en los entornos de desarrollo y en producción. Nuestro 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 ofrecidas, consulte la sección Clases de credenciales .

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 va a usar para escenarios de autenticación básicos.

La mayoría de los tipos de credenciales que ofrece @azure/identity el uso de la Biblioteca de autenticación de Microsoft para JavaScript (MSAL.js) . En concreto, usamos las bibliotecas de MSAL.js v2, que usan el 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 que admite Azure.

Cuándo usar algo más

Los @azure/identity tipos de credenciales son implementaciones de @azure/core-auth de la TokenCredential clase. En principio, cualquier objeto con un getToken método que cumpla getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> funcionará como .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 casos avanzados, es posible que los desarrolladores quieran controlar completamente el protocolo de autenticación. Para ese caso de uso, se recomienda usar la Biblioteca de autenticación de Microsoft para JavaScript (MSAL.js) directamente. Puede leer más a través de los vínculos siguientes:

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 autenticación de identidad administrada o entidad de servicio en la aplicación de producción, es habitual que un desarrollador use su propia cuenta para autenticar llamadas a servicios de Azure al depurar y ejecutar el 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 el Azure Developer CLI

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

Para autenticarse con [Azure Developer CLI][azure_developer_cli], los usuarios pueden ejecutar el comando azd auth login. Para los usuarios que se ejecutan en un sistema con un explorador web predeterminado, el Azure Developer CLI iniciará 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 usará el flujo de autenticación de código del dispositivo.

Autenticación mediante la CLI de Azure

Las aplicaciones que usan AzureCliCredential, ya sea directamente o a través de 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 los usuarios de la CLI de Azure, puede ejecutar el comando az login. Para los usuarios que se ejecutan en un sistema con un explorador web predeterminado, la CLI de Azure iniciará el explorador para autenticar al usuario.

Inicio de sesión de la cuenta de la CLI de Azure

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

Inicio de sesión del código del dispositivo de la CLI de Azure

Autenticación mediante Azure PowerShell

Las aplicaciones que usan AzurePowerShellCredential, ya sea directamente o a través de 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 los usuarios pueden ejecutar el Connect-AzAccount cmdlet . De forma predeterminada, ike la CLI Connect-AzAccount de Azure iniciará el explorador web predeterminado para autenticar una cuenta de usuario.

Inicio de sesión de Azure PowerShell cuenta

Si no se puede admitir la autenticación interactiva en la sesión, el -UseDeviceAuthentication argumento obligará al cmdlet a usar en su lugar un flujo de autenticación de código de dispositivo, 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 cuenta de Azure esté instalada. Una vez instalado, abra la paleta de comandos y ejecute el comando Azure: Iniciar sesión .

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

Se trata de un problema conocido que VisualStudioCodeCredential no funciona con las versiones de extensión de la cuenta de Azure más recientes que 0.9.11. Una solución a largo plazo para este problema está en curso. 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 , InteractiveBrowserCredentialque se puede establecer para usar redireccionamiento o elementos emergentes para completar el flujo de autenticación. Es necesario crear primero un registro de App de Azure en el Azure Portal para la aplicación web.

Conceptos clave

Si esta es la primera vez que usa @azure/identity o la Plataforma de identidad de Microsoft (Azure AD), lea Usar @azure/identity con la Plataforma de identidad de Microsoft en primer lugar. En este documento se proporciona una comprensión más profunda de la plataforma y cómo configurar correctamente la cuenta de Azure.

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 Azure AD y ofrece una variedad de clases de credenciales capaces de adquirir un token de Azure AD para autenticar las solicitudes de servicio. Todas las clases de credenciales de esta biblioteca son implementaciones de la clase abstracta TokenCredential, y cualquiera se puede usar para construir clientes de servicio capaces de autenticarse con TokenCredential.

Consulte Clases de credenciales.

DefaultAzureCredential

DefaultAzureCredential es adecuado para la mayoría de los escenarios en los que la aplicación está pensada para ejecutarse en última instancia en Azure. Esto se debe a que combina DefaultAzureCredential las credenciales que se usan normalmente para autenticarse cuando se implementan con credenciales usadas para autenticarse en un entorno de desarrollo.

Nota: DefaultAzureCredential está pensado para simplificar la introducción al SDK mediante el control de escenarios comunes con comportamientos predeterminados razonables. Los desarrolladores que quieran tener más control o cuyo escenario no esté servido por la configuración predeterminada deben usar otros tipos de credenciales.

Si se usa desde Node.js, DefaultAzureCredential intentará autenticarse a través de los siguientes mecanismos en orden:

Flujo de autenticación de DefaultAzureCredential

  1. Entorno:DefaultAzureCredential leerá la información de la cuenta especificada a través de variables de entorno y la usará para autenticarse.
  2. Identidad de carga de trabajo: si la aplicación se implementa en Azure Kubernetes Service con identidad administrada habilitada, DefaultAzureCredential se autenticará con ella.
  3. Identidad administrada : si la aplicación se implementa en un host de Azure con identidad administrada habilitada, se DefaultAzureCredential autenticará con esa cuenta.
  4. Azure Developer CLI: si el desarrollador ha autenticado una cuenta a través del comando Azure Developer CLIazd auth login, se DefaultAzureCredential autenticará con esa cuenta.
  5. CLI de Azure : si el desarrollador ha autenticado una cuenta mediante el comando de la CLI az login de Azure, se DefaultAzureCredential autenticará con esa cuenta.
  6. Azure PowerShell: si el desarrollador se ha autenticado mediante el comando Azure PowerShell móduloConnect-AzAccount, se DefaultAzureCredential autenticará con esa cuenta.

Directiva de continuación

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

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

Nota sobre VisualStudioCodeCredential

Debido a un problema conocido, VisualStudioCodeCredential se ha quitado de la DefaultAzureCredential cadena de tokens. Cuando se resuelva el problema 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 independientes. El @azure/identity paquete exporta una función de nivel superior (useIdentityPlugin) que se puede usar para habilitar un complemento. Proporcionamos dos paquetes de complementos:

  • @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 almacenados en access_token caché persistan 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é.
  • @azure/identity-vscode, que proporciona las dependencias de VisualStudioCodeCredential y las habilita. Sin este complemento, en VisualStudioCodeCredential este paquete se producirá una CredentialUnavailableErrorexcepción . El complemento proporciona la implementación subyacente de esta credencial, lo que le permite usarlo por sí mismo y como parte de lo DefaultAzureCredential descrito anteriormente.

Ejemplos

Puede encontrar más ejemplos del uso de las diversas credenciales en la página Ejemplos de identidades de Azure.

Autenticación con DefaultAzureCredential

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

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.

// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";

// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

Especificación de 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 realiza 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 generalmente es la forma 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 tienen en cuenta al autenticarse. 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 objeto que intentará autenticarse mediante dos instancias configuradas de forma diferente de ClientSecretCredential, para autenticar a KeyClient partir de la @azure/keyvault-keys:

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

// 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
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);

Compatibilidad con identidad administrada

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

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

Cloud configuration

Las credenciales se autentican de forma predeterminada en el punto de conexión de Azure AD 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 authorityHost argumento en el constructor. La AzureAuthorityHosts interfaz define autoridades para nubes conocidas. Para la nube de la Administración Pública de EE. UU., podría crear una instancia de una credencial de esta manera:

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

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. De forma similar, VisualStudioCodeCredential acepta un authorityHost argumento, pero el valor predeterminado es Azure authorityHost: Cloud del Visual Studio Code coincidente.

Clases de credenciales

Autenticación de aplicaciones hospedadas en Azure

Credential: Uso Ejemplo
DefaultAzureCredential Proporciona una experiencia de autenticación simplificada para empezar a desarrollar rápidamente aplicaciones que se ejecutan en Azure. ejemplo
ChainedTokenCredential Permite a los usuarios definir flujos de autenticación personalizados que se componen de varias credenciales. ejemplo
EnvironmentCredential Autentica una entidad de servicio o un usuario por medio de la información de credenciales especificada en las variables de entorno. ejemplo
ManagedIdentityCredential Autentica la identidad administrada de un recurso de Azure. ejemplo
WorkloadIdentityCredential Admite la identidad de carga de trabajo de Azure AD en Kubernetes.

Autenticación de entidades de servicio

Credential: Uso Ejemplo Referencia
ClientAssertionCredential Autentica una entidad de servicio mediante una aserción de cliente firmada. ejemplo Autenticación de entidad de servicio
ClientCertificateCredential Autentica una entidad de servicio mediante un certificado. ejemplo Autenticación de entidad de servicio
ClientSecretCredential Autentica una entidad de servicio mediante un secreto. ejemplo Autenticación de entidad de servicio

Autenticación de usuarios

Credential: Uso Ejemplo Referencia
AuthorizationCodeCredential Autentica a un usuario con un código de autorización obtenido anteriormente. ejemplo Código de autenticación OAuth2
DeviceCodeCredential Autentica de forma interactiva a un usuario en dispositivos con una interfaz de usuario limitada. ejemplo Autenticación con código de dispositivo
InteractiveBrowserCredential Autentica interactivamente a un usuario con el explorador predeterminado del sistema. Obtenga más información sobre cómo sucede aquí. ejemplo Código de autenticación OAuth2
OnBehalfOfCredential Propaga la identidad de usuario delegada y los permisos a través de la cadena de solicitudes. Autenticación en nombre de
UsernamePasswordCredential Autentica a un usuario con un nombre de usuario y una contraseña. ejemplo Autenticación con nombre de usuario y contraseña

Autenticación mediante herramientas de desarrollo

Credential: Uso Ejemplo Referencia
AzureCliCredential Autentíquese en un entorno de desarrollo con la CLI de Azure. ejemplo Autenticación de la CLI de Azure
AzureDeveloperCliCredential Autentíquese en un entorno de desarrollo con el usuario habilitado o la entidad de servicio en Azure Developer CLI. Referencia de Azure Developer CLI
AzurePowerShellCredential Autentíquese en un entorno de desarrollo mediante Azure PowerShell. ejemplo autenticación de Azure PowerShell
VisualStudioCodeCredential Se autentica como el usuario que ha iniciado sesión en la extensión Visual Studio Code cuenta de Azure. Extensión de la cuenta de Azure de VS Code

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

Nombre de la variable Valor
AZURE_CLIENT_ID Identificador de una aplicación de Azure Active Directory
AZURE_TENANT_ID Identificador del inquilino de Azure Active Directory de la aplicación
AZURE_CLIENT_SECRET uno de los secretos de cliente de la aplicación

Entidad de servicio con certificado

Nombre de la variable Valor
AZURE_CLIENT_ID Identificador de una aplicación de Azure Active Directory
AZURE_TENANT_ID Identificador del inquilino de Azure Active Directory de la aplicación
AZURE_CLIENT_CERTIFICATE_PATH ruta de acceso a un archivo de certificado con codificación PEM, incluida la clave privada
AZURE_CLIENT_CERTIFICATE_PASSWORD contraseña del archivo de certificado, si existe

Nombre de usuario y contraseña

Nombre de la variable Valor
AZURE_CLIENT_ID Identificador de una aplicación de Azure Active Directory
AZURE_TENANT_ID Identificador del inquilino de Azure Active Directory de la aplicación
AZURE_USERNAME nombre de usuario (normalmente una dirección de correo electrónico).
AZURE_PASSWORD la contraseña del usuario

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 utilizará el secreto de cliente.

Evaluación continua de 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 GetTokenOptions.enableCae(boolean) API. 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:

  • Almacenar en caché tokens en memoria (valor predeterminado) y en disco (participación).
  • Mejorar la resistencia y el rendimiento.
  • Reduzca el número de solicitudes realizadas a Azure AD para obtener tokens de acceso.

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

Solución de problemas

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

Pasos siguientes

Leer la documentación

La documentación de la API para esta biblioteca se puede encontrar en nuestro sitio de documentación.

Soporte de biblioteca cliente

Bibliotecas de cliente y administración enumeradas en la página de versiones del SDK de Azure que admiten la autenticación de Azure AD 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 de Azure AD B2C

Esta biblioteca no admite el servicio Azure AD B2C .

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

Proporcionar comentarios

Si encuentra errores o tiene sugerencias, cree una incidencia.

Contribuciones

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

Impresiones