Biblioteca cliente de autenticación asincrónica de Azure Identity para .NET, versión 1.0.0

La biblioteca amplía la biblioteca Azure.Identity para proporcionar compatibilidad con el agente de autenticación. Incluye las dependencias necesarias y proporciona la InteractiveBrowserCredentialBrokerOptions clase . Esta clase de opciones se puede usar para crear un InteractiveBrowserCredential capaz de usar el agente de autenticación del sistema en lugar del explorador del sistema cuando esté disponible.

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

Requisitos previos

• La biblioteca Azure.Identity es una dependencia de Azure.Identity.Broker.

Autenticar el cliente

Conceptos clave

Este paquete permite la compatibilidad con el agente de autenticación mediante InteractiveBrowserCredentialBrokerOptions, en combinación con InteractiveBrowserCredential en el Azure.Identity paquete.

Identificadores de ventana primaria

Al autenticarse de forma interactiva a través InteractiveBrowserCredential de construido con InteractiveBrowserCredentialBrokerOptions, se requiere un identificador de ventana principal para asegurarse de que el cuadro de diálogo de autenticación se muestra correctamente en la ventana de solicitud. En el contexto de las interfaces gráficas de usuario en los dispositivos, un identificador de ventana es un identificador único que el sistema operativo asigna a cada ventana. Para el sistema operativo Windows, este identificador es un valor entero que actúa como referencia a una ventana específica.

Acceso directo a la cuenta Microsoft (MSA)

Las cuentas de Microsoft (MSA) son cuentas personales creadas por los usuarios para acceder a los servicios de Microsoft. El paso a través de MSA es una configuración heredada que permite a los usuarios obtener tokens a recursos que normalmente no aceptan inicios de sesión de MSA. Esta característica solo está disponible para aplicaciones propias. Los usuarios que se autentican con una aplicación configurada para usar el acceso directo de MSA pueden establecer la InteractiveBrowserCredentialBrokerOptions.IsLegacyMsaPassthroughEnabled propiedad true en para permitir que WAM muestre estas cuentas personales.

URI de redirección

Microsoft Entra aplicaciones dependen de los URI de redirección para determinar dónde enviar la respuesta de autenticación después de que un usuario haya iniciado sesión. Para habilitar la autenticación asincrónica a través de WAM, se debe registrar un URI de redireccionamiento que coincida con el siguiente patrón en la aplicación:

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Ejemplos

Configuración de InteractiveBrowserCredential para usar el agente de autenticación del sistema

En este ejemplo se muestra cómo configurar con InteractiveBrowserCredential el tipo InteractiveBrowserCredentialBrokerOptions de opciones especializadas para habilitar la autenticación asincrónica.

IntPtr parentWindowHandle = GetForegroundWindow();

// Create an interactive browser credential which will use the system authentication broker
var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle));

// Use the credential to authenticate a secret client
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

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.

Tratamiento 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 de 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.

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

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.

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 AAD B2C .

Los problemas abiertos actualmente para la biblioteca Azure.Identity se pueden encontrar 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.