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/identity
migració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.
- 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
- 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.
- Nota: Entre las distintas credenciales exportadas en esta biblioteca,
Para más información, consulte la directiva de compatibilidad.
Instalar el paquete
Instale Azure Identity con npm
:
npm install --save @azure/identity
Prerrequisitos
- Una suscripción de Azure.
- Opcional: la CLI de Azure o Azure PowerShell también puede ser ú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 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:
- Representamos algunos casos de uso avanzados de en la página Ejemplos de
@azure/identity
identidad de Azure .- En concreto, tenemos una sección De ejemplos avanzados .
- También tenemos una sección que muestra cómo autenticarse directamente con MSAL.
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.
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
.
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.
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 , InteractiveBrowserCredential
que 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:
- Entorno:
DefaultAzureCredential
leerá la información de la cuenta especificada a través de variables de entorno y la usará para autenticarse. - Identidad de carga de trabajo: si la aplicación se implementa en Azure Kubernetes Service con identidad administrada habilitada,
DefaultAzureCredential
se autenticará con ella. - Identidad administrada : si la aplicación se implementa en un host de Azure con identidad administrada habilitada, se
DefaultAzureCredential
autenticará con esa cuenta. - Azure Developer CLI: si el desarrollador ha autenticado una cuenta a través del comando Azure Developer CLI
azd auth login
, seDefaultAzureCredential
autenticará con esa cuenta. - CLI de Azure : si el desarrollador ha autenticado una cuenta mediante el comando de la CLI
az login
de Azure, seDefaultAzureCredential
autenticará con esa cuenta. - Azure PowerShell: si el desarrollador se ha autenticado mediante el comando Azure PowerShell módulo
Connect-AzAccount
, seDefaultAzureCredential
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 enaccess_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 deVisualStudioCodeCredential
y las habilita. Sin este complemento, enVisualStudioCodeCredential
este paquete se producirá unaCredentialUnavailableError
excepción . El complemento proporciona la implementación subyacente de esta credencial, lo que le permite usarlo por sí mismo y como parte de loDefaultAzureCredential
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 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.
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.
Azure SDK for JavaScript
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: a lo largo de 2024, eliminaremos gradualmente los problemas de GitHub como mecanismo de comentarios para el contenido y lo reemplazaremos por un nuevo sistema de comentarios. Para obtener más información, consulte:Enviar y ver comentarios de