Inicialización de aplicaciones cliente mediante MSAL.NET

En este artículo se describe la inicialización del cliente público y las aplicaciones cliente confidenciales mediante el Biblioteca de autenticación de Microsoft para .NET (MSAL.NET). Para más información sobre los tipos de aplicación cliente, consulte Aplicaciones cliente públicas y cliente confidencial.

Con MSAL.NET 3.x, la forma recomendada de crear instancias de una aplicación es mediante los generadores de aplicaciones: PublicClientApplicationBuilder y ConfidentialClientApplicationBuilder. Ofrecen un mecanismo eficaz para configurar la aplicación a partir del código, un archivo de configuración o incluso mediante la combinación de ambos enfoques.

Prerequisites

Antes de inicializar una aplicación, primero debe registrarla para que la aplicación se pueda integrar con el Plataforma de identidad de Microsoft. Consulte el Inicio rápido: Registrar una aplicación con la plataforma de identidad de Microsoft para obtener más información. Después del registro, necesitará la siguiente información, que se puede encontrar en la página de registro de la aplicación en el Centro de administración Microsoft Entra.

  • Id. de aplicación (cliente): se trata de una cadena que representa un GUID.
  • Identificador de directorio (inquilino): proporciona funcionalidades de administración de identidades y acceso (IAM) a las aplicaciones y los recursos usados por su organización. Puede especificar si está escribiendo una aplicación de línea de negocio únicamente para su organización (también denominada aplicación de inquilino único).
  • La dirección URL del proveedor de identidades (llamada instancia) y la audiencia de inicio de sesión de su aplicación. Estos dos parámetros se conocen colectivamente como autoridad.
  • Credenciales de cliente : que pueden adoptar la forma de un secreto de aplicación (cadena de secreto de cliente) o certificado (de tipo X509Certificate2) si es una aplicación cliente confidencial.
  • Para las aplicaciones web y, a veces, para las aplicaciones cliente públicas (en particular cuando su aplicación necesita usar un intermediario), debe configurar el URI de redirección en el que el proveedor de identidades devolverá a su aplicación los tokens de seguridad.

Inicialización de aplicaciones

Hay muchas maneras diferentes de crear instancias de aplicaciones cliente.

Inicialización de una aplicación cliente pública a partir del código

El código siguiente crea una instancia de una aplicación cliente pública para iniciar sesión de usuarios en la nube pública de Microsoft Azure con sus cuentas profesionales, educativas o personales de Microsoft.

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

Inicialización de una aplicación cliente confidencial a partir del código

De la misma manera, el código siguiente crea una instancia de una aplicación confidencial (una aplicación web ubicada en https://myapp.azurewebsites.net) que controla los tokens de los usuarios de la nube pública de Microsoft Azure, con sus cuentas profesionales y educativas, o sus cuentas de Microsoft personales. La aplicación se identifica con el proveedor de identidades compartiendo un secreto de cliente:

string redirectUri = "https://myapp.azurewebsites.net";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

Sin embargo, en producción se recomiendan certificados, ya que son más seguros que los secretos de cliente. Se pueden crear y cargar en el Centro de administración Microsoft Entra. El código sería el siguiente:

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certificate)
    .WithRedirectUri(redirectUri )
    .Build();

Inicialización de una aplicación cliente pública a partir de las opciones de configuración

El código siguiente crea una instancia de una aplicación cliente pública desde un objeto de configuración, que se puede rellenar mediante programación o leer desde un archivo de configuración:

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
    .Build();

Inicialización de una aplicación cliente confidencial a partir de opciones de configuración

El mismo tipo de patrón se aplica a las aplicaciones cliente confidenciales. También puede agregar otros parámetros mediante .WithXXX modificadores. En este ejemplo se usa .WithCertificate.

ConfidentialClientApplicationOptions options = GetOptions(); // your own method
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(options)
    .WithCertificate(certificate)
    .Build();

Modificadores del builder

En los fragmentos de código que usan generadores de aplicaciones, muchos .With métodos se pueden aplicar como modificadores (por ejemplo, .WithCertificate y .WithRedirectUri).

Modificadores comunes a aplicaciones cliente públicas y confidenciales

Los modificadores que puede establecer en un cliente público o en un generador de aplicaciones cliente confidenciales se pueden encontrar en la AbstractApplicationBuilder<T> clase . Los distintos métodos pueden encontrarse en la documentación de SDK de Azure para .NET.

Modificadores específicos de aplicaciones Xamarin.iOS

Los modificadores que puede establecer en un generador de aplicaciones cliente público en Xamarin.iOS son:

Modificador Description
.WithIosKeychainSecurityGroup() solo Xamarin.iOS: establece el grupo de seguridad de la cadena de claves de iOS (para la persistencia de caché).

Modificadores específicos de las aplicaciones cliente confidenciales

Los modificadores específicos de un generador de aplicaciones cliente confidenciales se pueden encontrar en la ConfidentialClientApplicationBuilder clase . Los distintos métodos se pueden encontrar en la documentación del SDK de Azure para .NET.

Los modificadores como .WithCertificate(X509Certificate2 certificate) y .WithClientSecret(string clientSecret) son mutuamente excluyentes. Si proporciona ambos, MSAL genera una excepción descriptiva.

Ejemplo de uso de modificadores

Supongamos que la aplicación es una aplicación de línea de negocio, que solo es para su organización. A continuación, puede escribir:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
        .Build();

La programación para nubes nacionales ha simplificado, por lo que si desea que la aplicación sea una aplicación multiinquilino en una nube nacional, puede escribir, por ejemplo:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

También hay una anulación para ADFS (MSAL.NET solo admite ADFS 2019 o una versión posterior):

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

Por último, si es desarrollador de Azure AD B2C, puede especificar su inquilino de esta manera:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

Consulte también

Documentación de referencia de API

Paquete en NuGet

Código fuente de la biblioteca

Ejemplos de código

Pasos siguientes

Después de inicializar la aplicación cliente, la siguiente tarea es agregar compatibilidad con el inicio de sesión de usuario, el acceso de API autorizado o ambos.

Nuestra documentación del escenario de aplicación proporciona instrucciones para iniciar sesión en un usuario y adquirir un token de acceso para acceder a una API en nombre de ese usuario:

  • Last updated on