Biblioteca cliente de Azure Identity para Python: versión 1.14.1

La biblioteca de identidades de Azure proporciona compatibilidad con la autenticación de tokens de Azure Active Directory (Azure AD) en el SDK de Azure. Proporciona un conjunto de TokenCredential implementaciones, que se pueden usar para construir clientes del SDK de Azure que admiten la autenticación de tokens de Azure AD.

Código | fuentePaquete (PyPI) | Paquete (Conda) | Documentación | de referencia de APIDocumentación de Azure AD

Introducción

Instalar el paquete

Instale Azure Identity con pip:

pip install azure-identity

Requisitos previos

• Una suscripción de Azure
• Python 3.7 o una versión reciente de Python 3 (esta biblioteca no admite versiones de fin de vida)

Autenticación durante el desarrollo local

Al depurar y ejecutar código localmente, es habitual que los desarrolladores usen sus propias cuentas para autenticar llamadas a servicios de Azure. La biblioteca de identidades de Azure admite la autenticación mediante herramientas de desarrollo para simplificar el desarrollo local.

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 DefaultAzureCredential o 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 está instalada la extensión de la cuenta de Azure. Una vez instalado, abra la paleta de comandos y ejecute el comando Azure: Iniciar sesión .

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

Autenticación mediante la CLI de Azure

DefaultAzureCredential y AzureCliCredential pueden autenticarse como el usuario que ha iniciado sesión en la CLI de Azure. Para iniciar sesión en la CLI de Azure, ejecute az login. En un sistema con un explorador web predeterminado, la CLI de Azure iniciará el explorador para autenticar a un usuario.

Cuando no haya ningún explorador predeterminado disponible, az login usará el flujo de autenticación de código del dispositivo. Este flujo también se puede seleccionar manualmente mediante la ejecución az login --use-device-codede .

Autenticación mediante el Azure Developer CLI

Los desarrolladores que codifican fuera de un IDE también pueden usar el 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 el 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.

Conceptos clave

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 una instancia de credencial cuando se construyen y usan esa credencial para autenticar las solicitudes.

La biblioteca de identidades de Azure se centra en la autenticación de OAuth con Azure AD. Ofrece varias clases de credenciales capaces de adquirir un token de acceso de Azure AD. Consulte la sección Clases de credenciales a continuación para obtener una lista de las clases de credenciales de esta biblioteca.

DefaultAzureCredential

DefaultAzureCredential es adecuado para la mayoría de las aplicaciones que se ejecutarán en Azure, ya que combina credenciales de producción comunes con credenciales de desarrollo. DefaultAzureCredential intenta autenticarse a través de los siguientes mecanismos, en este orden, deteniendo cuando se realiza correctamente:

Nota: DefaultAzureCredential está pensado para simplificar la introducción a la biblioteca 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.

1. Ambiente - 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, DefaultAzureCredential se autenticará con ella.
4. CLI de Azure : si un usuario ha iniciado sesión mediante el comando de la CLI az login de Azure, DefaultAzureCredential se autenticará como ese usuario.
5. Azure PowerShell: si un usuario ha iniciado sesión a través del comando de Connect-AzAccount Azure PowerShell, DefaultAzureCredential se autenticará como ese usuario.
6. Azure Developer CLI: si el desarrollador se ha autenticado a través del comando Azure Developer CLIazd auth login, se DefaultAzureCredential autenticará con esa cuenta.
7. Explorador interactivo : si está habilitado, DefaultAzureCredential autenticará interactivamente a un usuario a través del explorador predeterminado. Este tipo de credencial está deshabilitado de forma predeterminada.

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á.

Ejemplos

A continuación se proporcionan los ejemplos siguientes:

• Autenticación con DefaultAzureCredential
• Definición de un flujo de autenticación personalizado con ChainedTokenCredential
• Credenciales asincrónicas

Autenticación con DefaultAzureCredential

Puede encontrar más detalles sobre cómo configurar el entorno para usar , DefaultAzureCredential en la documentación de referencia de la clase.

En este ejemplo se muestra cómo BlobServiceClient autenticar desde la biblioteca azure-storage-blob mediante DefaultAzureCredential.

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Habilitación de la autenticación interactiva con DefaultAzureCredential

La autenticación interactiva está deshabilitada de DefaultAzureCredential forma predeterminada y se puede habilitar con un argumento de palabra clave:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Cuando se habilita, DefaultAzureCredential recurre a la autenticación interactiva a través del explorador web predeterminado del sistema cuando no hay ninguna otra credencial disponible.

Especificar una identidad administrada asignada por el usuario para DefaultAzureCredential

Muchos hosts de Azure permiten la asignación de una identidad administrada asignada por el usuario. Para configurar DefaultAzureCredential para autenticar una identidad asignada por el usuario, use el argumento de palabra managed_identity_client_id clave :

DefaultAzureCredential(managed_identity_client_id=client_id)

Como alternativa, establezca la variable AZURE_CLIENT_ID de entorno en el identificador de cliente de la identidad.

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

DefaultAzureCredential por lo general, es la manera más rápida de empezar a desarrollar aplicaciones para Azure. Para escenarios más avanzados, ChainedTokenCredential vincula varias instancias de credenciales para que se intenten secuencialmente al autenticarse. Probará cada credencial encadenada a su vez hasta que uno proporcione un token o no se autentique debido a un error.

En el ejemplo siguiente se muestra cómo crear una credencial que primero intentará autenticarse mediante la identidad administrada. La credencial volverá a autenticarse a través de la CLI de Azure cuando una identidad administrada no esté disponible. En este ejemplo se usa desde EventHubProducerClient la biblioteca cliente azure-eventhub .

from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential

managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)

client = EventHubProducerClient(namespace, eventhub_name, credential_chain)

Credenciales asincrónicas

Esta biblioteca incluye un conjunto de API asincrónicas. Para usar las credenciales asincrónicas en azure.identity.aio, primero debe instalar un transporte asincrónico, como aiohttp. Para más información, consulte la documentación de azure-core.

Las credenciales asincrónicas deben cerrarse cuando ya no sean necesarias. Cada credencial asincrónica es un administrador de contexto asincrónico y define un método asincrónico close . Por ejemplo:

from azure.identity.aio import DefaultAzureCredential

# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()

# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
  ...

En este ejemplo se muestra la autenticación asincrónica de azure-keyvault-secrets con una credencial asincrónicaSecretClient.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)

Compatibilidad con identidad administrada

La autenticación de identidad administrada se admite a través de o DefaultAzureCredentialManagedIdentityCredential 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

Ejemplos

Autenticación con una identidad administrada asignada por el usuario

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)

Autenticación con una identidad administrada asignada por el sistema

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)

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 authority argumento . AzureAuthorityHosts define autoridades para nubes conocidas:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Si la autoridad de la nube no aparece en AzureAuthorityHosts, puede especificar explícitamente su dirección URL:

DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")

Como alternativa a especificar el authority argumento , también puede establecer la AZURE_AUTHORITY_HOST variable de entorno 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:

AZURE_AUTHORITY_HOST=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 authority argumento, pero el valor predeterminado es la configuración "Azure: Cloud" de VS Code que coincide con la autoridad.

Clases de credenciales

Autenticación de aplicaciones hospedadas en Azure

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

Autenticación de entidades de servicio

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

Autenticación de usuarios

Credential:	Uso	Referencia
AuthorizationCodeCredential	Autentica a un usuario con un código de autorización obtenido previamente.	Código de autenticación OAuth2
DeviceCodeCredential	Autentica de forma interactiva a un usuario en dispositivos con una interfaz de usuario limitada.	Autenticación con código de dispositivo
InteractiveBrowserCredential	Autentica interactivamente a un usuario con el explorador predeterminado del sistema.	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 (no admite la autenticación multifactor).	Autenticación con nombre de usuario y contraseña

Autenticación mediante herramientas de desarrollo

Credential:	Uso	Referencia
AzureCliCredential	Se autentica en un entorno de desarrollo con la CLI de Azure.	Autenticación de la CLI de Azure
AzureDeveloperCliCredential	Se autentica en un entorno de desarrollo con el Azure Developer CLI.	Referencia de Azure Developer CLI
AzurePowerShellCredential	Se autentica en un entorno de desarrollo con el Azure PowerShell.	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 PEM o PKCS12, 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_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.

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) o 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

Consulte la guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

Control de errores

Las credenciales se generan CredentialUnavailableError cuando no pueden intentar la autenticación porque carecen de estado o datos necesarios. Por ejemplo, EnvironmentCredential generará esta excepción cuando esté incompleta.

Las credenciales producen azure.core.exceptions.ClientAuthenticationError cuando no logran autenticarse. ClientAuthenticationError tiene un atributo , que describe por qué se produjo un message error en la autenticación. Cuando se genera mediante DefaultAzureCredential o ChainedTokenCredential, el mensaje recopila mensajes de error de cada credencial de la cadena.

Para más información sobre el control de errores específicos de Azure AD, consulte la documentación del código de error de Azure AD.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. Las credenciales registran información básica, incluidas las sesiones HTTP (direcciones URL, encabezados, etc.) en el nivel INFO. Estas entradas de registro no contienen secretos de autenticación.

El registro detallado de nivel DEBUG, incluidos los cuerpos de solicitud/respuesta y los valores de encabezado, no está habilitado de forma predeterminada. Se puede habilitar con el logging_enable argumento . Por ejemplo:

credential = DefaultAzureCredential(logging_enable=True)

PRECAUCIÓN: Los registros de nivel de DEPURAción de las credenciales contienen información confidencial. Estos registros deben protegerse para evitar poner en peligro la seguridad de la cuenta.

Pasos siguientes

Soporte de biblioteca cliente

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

Problemas conocidos

Esta biblioteca no admite Azure AD B2C.

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

Proporcionar comentarios

Si encuentra errores o tiene sugerencias, abra un problema.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestra CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.