Biblioteca cliente de Azure Identity para .NET: versión 1.10.3

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

Código | fuentePaquete (NuGet) | Documentación | de referencia de APIdocumentación de identificador de Microsoft Entra

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Identity para .NET con NuGet:

dotnet add package Azure.Identity

Requisitos previos

• Una suscripción de Azure.
• La CLI de Azure también puede ser útil para autenticarse en un entorno de desarrollo, crear cuentas y administrar roles de cuenta.

Autenticar el cliente

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

Autenticación mediante Visual Studio

Los desarrolladores que usan Visual Studio 2017 o posterior pueden autenticar una cuenta de Microsoft Entra a través del IDE. Las aplicaciones que usan DefaultAzureCredential o VisualStudioCredential pueden usar esta cuenta para autenticar las llamadas en su aplicación cuando se ejecutan localmente.

Para autenticarse en Visual Studio, seleccione el menú Opciones de herramientas> para iniciar el cuadro de diálogo Opciones. A continuación, vaya a las Azure Service Authentication opciones para iniciar sesión con su cuenta de Microsoft Entra.

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.

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

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

Para autenticarse con la CLI de Azure, los usuarios pueden 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 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.

Autenticación mediante Azure PowerShell

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

Para autenticarse con Azure PowerShell, los usuarios pueden ejecutar el comando Connect-AzAccount. Para los usuarios que se ejecutan en un sistema con un explorador web predeterminado y la versión 5.0.0 o posterior de Azure PowerShell, iniciará el explorador para autenticar al usuario.

En el caso de los sistemas sin un explorador web predeterminado, el comando Connect-AzAccount usará el flujo de autenticación de código del dispositivo. El usuario también puede forzar Azure PowerShell usar el flujo de código del dispositivo en lugar de iniciar un explorador especificando el UseDeviceAuthentication argumento .

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 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 Microsoft Entra id. y ofrece una variedad de 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 en Azure.Core y cualquiera de ellas se puede usar para construir clientes de servicio capaces de autenticarse con .TokenCredential

Consulte Clases de credenciales para obtener una lista completa de los tipos de credenciales disponibles.

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 DefaultAzureCredential combina las credenciales que se suelen usar para autenticarse cuando se implementa, con las 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.

DefaultAzureCredential intenta realizar la autenticación mediante los siguientes mecanismos, en este orden, y se detiene cuando lo consigue:

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 un host de Azure con la identidad de carga de trabajo habilitada, se DefaultAzureCredential autenticará con esa cuenta.
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. Visual Studio : si el desarrollador se ha autenticado a través de Visual Studio, se DefaultAzureCredential autenticará con esa cuenta.
5. Visual Studio Code: actualmente se excluye de forma predeterminada como autenticación del SDK a través de Visual Studio Code se interrumpe debido al problema 27263. VisualStudioCodeCredential Se volverá a habilitar en el DefaultAzureCredential flujo una vez que se haya implementado una corrección. El problema n.º 30525 realiza un seguimiento de esto. Mientras tanto, Visual Studio Code los usuarios pueden autenticar su entorno de desarrollo mediante la CLI de Azure.
6. 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.
7. Azure PowerShell: si el desarrollador ha autenticado una cuenta a través del comando Azure PowerShellConnect-AzAccount, se DefaultAzureCredential autenticará con esa cuenta.
8. 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.
9. Explorador interactivo: si está habilitado, DefaultAzureCredential autenticará de forma interactiva al desarrollador mediante el explorador predeterminado del sistema actual. De forma predeterminada, este tipo de credencial está deshabilitado.

Directiva de continuación

A partir de la versión 1.10.1, 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. Antes de la versión 1.10.1, las credenciales de desarrollador detendrían de forma similar el flujo de autenticación si se produjo un error en la recuperación de tokens.

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

Ejemplos

Autenticación con DefaultAzureCredential

En el siguiente ejemplo se muestra la autenticación de SecretClient de la biblioteca cliente Azure.Security.KeyVault.Secrets con DefaultAzureCredential.

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

Habilitación de la autenticación interactiva con DefaultAzureCredential

La autenticación interactiva está deshabilitada de DefaultAzureCredential forma predeterminada. En este ejemplo se muestran dos maneras de habilitar la parte de autenticación interactiva de DefaultAzureCredential. Cuando se habilite, DefaultAzureCredential se revertirá a la autenticación interactiva del desarrollador a través del explorador predeterminado del sistema si no hay otras credenciales disponibles. A continuación, en este ejemplo se autentica desde EventHubProducerClient la biblioteca cliente Azure.Messaging.EventHubs mediante la DefaultAzureCredential autenticación interactiva habilitada.

// the includeInteractiveCredentials constructor parameter can be used to enable interactive authentication
var credential = new DefaultAzureCredential(includeInteractiveCredentials: true);

var eventHubClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Especificación de una identidad administrada asignada por el usuario con DefaultAzureCredential

Muchos hosts de Azure permiten la asignación de una identidad administrada asignada por el usuario. En este ejemplo se muestra cómo configurar DefaultAzureCredential para autenticar una identidad asignada por el usuario cuando se implementa en un host de Azure. A continuación, se autentica un elemento BlobClient de la biblioteca cliente Azure.Storage.Blobs con credenciales.

// When deployed to an azure host, the default azure credential will authenticate the specified user assigned managed identity.

string userAssignedClientId = "<your managed identity client Id>";
var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });

var blobClient = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);

Además de configurar mediante ManagedIdentityClientId código, también se puede establecer mediante la AZURE_CLIENT_ID variable de entorno . Estos dos enfoques son equivalentes al usar .DefaultAzureCredential

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 la identidad administrada y revertir a la autenticación a través de la CLI de Azure si la identidad administrada no está disponible en el entorno actual. Así, se usa la credencial para autenticar un elemento EventHubProducerClient desde la biblioteca cliente Azure.Messaging.EventHubs.

// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.

var credential = new ChainedTokenCredential(new ManagedIdentityCredential(), new AzureCliCredential());

var eventHubProducerClient = new EventHubProducerClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Compatibilidad con identidad administrada

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

Ejemplos

En estos ejemplos se muestra cómo autenticar desde SecretClient la biblioteca cliente Azure.Security.KeyVault.Secrets mediante ManagedIdentityCredential.

Autenticación con una identidad administrada asignada por el usuario

var credential = new ManagedIdentityCredential(clientId: userAssignedClientId);
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Autenticación con una identidad administrada asignada por el sistema

var credential = new ManagedIdentityCredential();
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

Cloud configuration

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

var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { 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.

Clases 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

Nota: Todas las implementaciones de credenciales de la biblioteca de identidades de Azure son threadsafe y varios clientes de servicio pueden usar una única instancia de credenciales.

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

Evaluación continua de acceso

A partir de la versión 1.10.0, el acceso a los recursos protegidos por evaluación continua de acceso (CAE) es posible por solicitud. Este comportamiento se puede habilitar estableciendo la IsCaeEnabled propiedad de a través de TokenRequestContext su constructor. CAE no es compatible con las credenciales de identidad administrada y 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) o en disco (participación).
• Mejorar la resistencia y el rendimiento.
• Reduzca el número de solicitudes realizadas al identificador de Microsoft Entra 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

Los errores derivados de la autenticación se pueden generar en cualquier método de cliente de servicio que realice una solicitud al servicio. Esto se debe a que la primera vez que se solicita el token desde la credencial está en la primera llamada al servicio, y es posible que las llamadas posteriores necesiten actualizar el token. Para distinguir estos errores de los errores en las clases de identidad de Azure del cliente de servicio, se generan detalles AuthenticationFailedException sobre el origen del error en el mensaje de excepción, así como posiblemente el mensaje de error. Dependiendo de la aplicación, estos errores pueden o no ser recuperables.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

try
{
    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
    Console.WriteLine($"Authentication Failed. {e.Message}");
}

Para obtener más información sobre cómo tratar los errores derivados de solicitudes erróneas para Microsoft Entra identificador o puntos de conexión de identidad administrada, consulte la documentación del identificador de Microsoft Entra sobre los códigos de error de autorización.

Registro

La biblioteca de identidades de Azure proporciona las mismas funcionalidades de registro que el resto del SDK de Azure.

La manera más sencilla de ver los registros para ayudar a depurar problemas de autenticación es habilitar el registro de la consola.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Todas las credenciales se pueden configurar con opciones de diagnóstico, de la misma manera que otros clientes del SDK.

PRECAUCIÓN: Las solicitudes y respuestas de la biblioteca de identidades de Azure contienen información confidencial. Se debe tomar precauciones para proteger los registros, al personalizar la salida, para evitar poner en peligro la seguridad de la cuenta.

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsLoggingContentEnabled = true
    }
};

Al solucionar problemas de autenticación, es posible que también quiera habilitar el registro de información confidencial. Para habilitar este tipo de registro, establezca la IsLoggingContentEnabled propiedad trueen . Para registrar solo los detalles de la cuenta que se usó para intentar la autenticación y la autorización, establezca en IsAccountIdentifierLoggingEnabledtrue.

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsAccountIdentifierLoggingEnabled = true
    }
};

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de credenciales son seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de credenciales siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de clienteAcceso a la respuesta | Diagnóstico | Burla | Duración del cliente

Pasos siguientes

Bibliotecas cliente que admiten la autenticación con Azure Identity

Muchas de las bibliotecas cliente enumeradas aquí admiten la autenticación con TokenCredential y la biblioteca de identidades de Azure. Allí también encontrará vínculos donde puede obtener más información sobre su uso, incluida documentación adicional y ejemplos.

Problemas conocidos

Esta biblioteca no admite actualmente escenarios relacionados con el servicio Azure AD B2C .

Puede encontrar problemas abiertos para la Azure.Identity biblioteca aquí.

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 será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para 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.