Uso de exploradores web (MSAL.NET)

Recomendamos usar intermediarios para autenticarse, ya que ofrecen más ventajas que los navegadores. En equipos Windows, el intermediario es Web Account Manager (WAM); en Android e iOS, Microsoft Authenticator o Intune Portal de empresa. La autenticación interactiva requiere el uso de un agente o un explorador web. MSAL.NET admite un explorador web del sistema o una vista web incrustada.

Exploradores web en MSAL.NET

La interacción se produce en un explorador web

Es importante comprender que al adquirir un token de forma interactiva, el contenido del cuadro de diálogo no lo proporciona la biblioteca, sino Microsoft Entra ID. El extremo de autenticación devuelve HTML y JavaScript para controlar la interacción, y se representa en un navegador web o en un control web. Permitir que el Microsoft Entra ID controlar la interacción HTML tiene muchas ventajas:

• La contraseña, si se ha escrito, nunca la almacena la aplicación ni la biblioteca de autenticación.
• Permite el redireccionamiento a otros proveedores de identidades (por ejemplo, iniciar sesión con una cuenta profesional o educativa, o una cuenta personal con MSAL o con una cuenta social con Azure AD B2C).
• Permite que el Microsoft Entra ID controle el acceso condicional, por ejemplo, al hacer que el usuario realice la autenticación multifactor (MFA) durante la fase de autenticación (como escribir un PIN de Windows Hello o llamar a en su teléfono o en una aplicación de autenticación en su teléfono). En los casos en que la autenticación multifactor requerida aún no está configurada, el usuario puede configurarla en ese mismo momento en el mismo cuadro de diálogo. El usuario escribe su número de teléfono móvil y se le guía para instalar una aplicación de autenticación y escanear una etiqueta QR para agregar su cuenta. Esta interacción controlada por el servidor es una excelente experiencia.
• Permite al usuario cambiar su contraseña en este mismo cuadro de diálogo cuando la contraseña ha expirado (proporcionando campos adicionales para la contraseña antigua y la nueva contraseña).
• Habilita la personalización de marca del inquilino o de la aplicación (imágenes) controladas por el administrador de inquilinos de Microsoft Entra o un propietario de la aplicación.
• Permite a los usuarios dar su consentimiento para permitir que la aplicación acceda a los recursos y ámbitos en su nombre justo después de la autenticación.

Vista web integrada frente al navegador del sistema

MSAL.NET es una biblioteca de varios marcos y tiene código específico del marco para hospedar un explorador en un control de interfaz de usuario (por ejemplo, en .NET WinForms o WebView2; en .NET MAUI, controles móviles nativos, etc.). Este control se denomina vista web incrustada . Como alternativa, MSAL.NET también puede abrir un explorador web del sistema.

Por lo general, se recomienda usar el valor predeterminado de la plataforma y normalmente es el explorador del sistema. El navegador del sistema recuerda mejor a los usuarios que ya han iniciado sesión. Para cambiar este comportamiento, use WithUseEmbeddedWebView(Boolean)

Disponibilidad del explorador

† El explorador del sistema requiere http://localhost URI de redirección.

†† Versión net6.0-windows o superior para utilizar el navegador integrado.

††† Haga referencia a Microsoft.Identity.Client.Desktop y llame a WithWindowsDesktopFeatures para usar el navegador integrado.

Explorador web del sistema

El uso del explorador del sistema tiene la ventaja significativa de compartir el estado de single Sign-On (SSO) con aplicaciones web y otras aplicaciones sin necesidad de un agente (WAM, Portal de empresa, Authenticator, etc.).

Sin embargo, en las aplicaciones de escritorio, abrir un navegador del sistema da lugar a una experiencia de usuario deficiente, ya que el usuario ve el navegador, donde es posible que ya tenga otras pestañas abiertas. Y cuando se ha producido la autenticación, los usuarios obtienen una página en la que se les pide que cierren esta ventana. Si el usuario no presta atención, puede cerrar todo el proceso (incluidas otras pestañas, que no están relacionadas con la autenticación). El aprovechamiento del explorador del sistema en el escritorio también requeriría abrir puertos locales y escucharlos, lo que podría requerir permisos avanzados para la aplicación. Usted, como desarrollador, usuario o administrador, podría ser renuente a este requisito.

Cómo usar el explorador del sistema predeterminado

En .NET, MSAL iniciará el explorador del sistema como un proceso independiente. MSAL.NET no tiene control sobre este explorador, pero una vez que el usuario finaliza la autenticación, la página web se redirige de tal manera que MSAL.NET pueda interceptar la llamada al URI de redireccionamiento especificado al crear una instancia de cliente pública.

MSAL.NET no puede detectar si el usuario navega fuera o simplemente cierra el explorador. Se recomienda que las aplicaciones que usan esta técnica definan un tiempo de espera mediante .CancellationToken Se recomienda un tiempo de espera de al menos unos minutos para tener en cuenta los casos en los que se le pida al usuario que cambie la contraseña o realice la autenticación multifactor.

MSAL.NET debe estar a la escucha en http://localhost:port para interceptar el código con el que responde Microsoft Entra ID cuando el usuario finaliza la autenticación. Consulte Flujo de código de autorización para obtener más información.

Para habilitar el explorador del sistema:

1. Durante el registro de aplicaciones en el portal, configure http://localhost como un URI de redirección (actualmente no compatible con Azure B2C).
2. Al construir la aplicación cliente pública, especifique este URI de redirección.
3. Agregue .WithUseEmbeddedWebView(false).

var pca = PublicClientApplicationBuilder
            .Create("<CLIENT_ID>")
            // or use a known port if you wish "http://localhost:1234"
            .WithRedirectUri("http://localhost")
            .Build();

var result = await pca.AcquireTokenInteractive(s_scopes)
                    .WithUseEmbeddedWebView(false)
                    .ExecuteAsync();

Al configurar http://localhost, MSAL.NET encontrará un puerto abierto aleatorio y lo usará. El uso http://localhost de como URI de redirección es seguro. Ningún otro proceso puede estar a la escucha en un socket local en el que MSAL ya esté a la escucha. No se produce ninguna comunicación de red cuando el explorador redirige a este URI. Incluso si una aplicación malintencionada intercepta el código de autenticación (ningún ataque conocido, pero es posible si una aplicación malintencionada tiene acceso de administrador a la máquina), no puede intercambiarlo por un token porque necesita un secreto temporal que solo conoce la aplicación, tal como se describe en el protocolo PKCE . La aplicación no puede escuchar en el punto de conexión localhost HTTPS (https://localhost) porque el puerto 443 está reservado y MSAL no puede escucharlo.

Limitaciones

Azure B2C y ADFS 2019 aún no implementan la opción ningún puerto. Por lo tanto, no se puede establecer el URI de redirección http://localhost (sin puerto), sino solo el URI http://localhost:1234 (con puerto). Esto significa que tendrá que realizar su propia administración de puertos, por ejemplo, puede reservar algunos puertos y configurarlos como URI de redirección. Entonces, la aplicación puede ir probando los puertos hasta que uno esté libre; luego, MSAL puede usarlo.

Para obtener más información, consulte Excepciones de Localhost.

Linux y macOS

En Linux, MSAL.NET abre el explorador del sistema predeterminado con una herramienta como xdg-open. Abrir el navegador con sudo no es compatible con MSAL y hará que MSAL genere una excepción.

En macOS, el explorador se abre invocando open <url>.

Personalización de la experiencia

MSAL.NET puede responder con un mensaje HTTP o una redirección HTTP cuando se recibe un token o se produce un error.

var options = new SystemWebViewOptions()
{
    HtmlMessageError = "<p> An error occurred: {0}. Details {1}</p>",
    BrowserRedirectSuccess = new Uri("https://www.microsoft.com");
}

await pca.AcquireTokenInteractive(s_scopes)
         .WithUseEmbeddedWebView(false)
         .WithSystemWebViewOptions(options)
         .ExecuteAsync();

Abrir un explorador específico

Puede personalizar la forma en que MSAL.NET abre el explorador. Por ejemplo, en lugar de usar el explorador que sea el valor predeterminado, puede forzar la apertura de un explorador específico:

var options = new SystemWebViewOptions()
{
    OpenBrowserAsync = SystemWebViewOptions.OpenWithEdgeBrowserAsync
}

Vistas web en aplicaciones móviles

Las vistas web insertadas se pueden habilitar en aplicaciones .NET MAUI. Puede optar por usar vistas web incrustadas o exploradores del sistema. La elección depende de la experiencia de usuario y de los aspectos de seguridad que quiera abordar.

Diferencias entre la vista web insertada y el explorador del sistema

Hay algunas diferencias visuales entre la vista web insertada y el explorador del sistema en MSAL.NET.

Inicio de sesión interactivo con MSAL.NET mediante la vista web insertada:

Inicio de sesión interactivo con MSAL.NET mediante el explorador del sistema:

Opciones de desarrollador

Como desarrollador que usa MSAL.NET, tiene varias opciones para mostrar el cuadro de diálogo de inicio de sesión interactivo desde Microsoft Entra ID:

• Explorador del sistema. El explorador del sistema se establece de forma predeterminada en la biblioteca. Si usa Android, consulte exploradores del sistema para obtener información específica sobre qué exploradores se admiten para la autenticación. Al usar el explorador del sistema en Android, se recomienda que el dispositivo tenga un explorador que admita pestañas personalizadas de Chrome; De lo contrario, se puede producir un error en la autenticación.
• Vista web incrustada. Para usar solo la vista web incrustada en MSAL.NET, el generador AcquireTokenInteractive incluye un método WithUseEmbeddedWebView.

En una aplicación de iOS:

var result = app.AcquireTokenInteractive(scopes)
                .WithUseEmbeddedWebView(useEmbeddedWebview)
                .ExecuteAsync();

En una aplicación android:

var result = app.AcquireTokenInteractive(scopes)
                .WithParentActivityOrWindow(activity)
                .WithUseEmbeddedWebView(useEmbeddedWebview)
                .ExecuteAsync();

Elección entre la vista web incrustada o el explorador del sistema en iOS

En tu aplicación iOS, en AppDelegate.cs puedes inicializar ParentWindow con null. No se usa en iOS.

App.ParentWindow = null; // no UI parent on iOS

Elección entre la vista web incrustada o el explorador del sistema en Android

En tu aplicación de Android, en MainActivity.cs puedes configurar la actividad principal para que el resultado de la autenticación le sea devuelto:

 App.ParentWindow = this;

Luego, en el MainPage.xaml.cs:

var result = await App.PCA.AcquireTokenInteractive(App.Scopes)
                      .WithParentActivityOrWindow(App.ParentWindow)
                      .WithUseEmbeddedWebView(true)
                      .ExecuteAsync();

Detección de la presencia de pestañas personalizadas en Android

Si quieres usar el navegador web del sistema para habilitar el inicio de sesión único con las aplicaciones que se ejecutan en el navegador, pero te preocupa la experiencia de usuario en dispositivos Android que no disponen de un navegador compatible con pestañas personalizadas, puedes decidirlo llamando a IPublicClientApplication.IsSystemWebViewAvailable. Este método devuelve true si el administrador de paquetes de Android detecta pestañas personalizadas y false si no se detectan en el dispositivo.

En función del valor devuelto por este método y sus requisitos, puede tomar una decisión:

• Puede devolver un mensaje de error personalizado al usuario, por ejemplo: "Instale Chrome para continuar con la autenticación" o
• Puede revertir para iniciar la página de inicio de sesión en una vista web incrustada.

bool useSystemBrowser = app.IsSystemWebViewAvailable();

authResult = await App.PCA.AcquireTokenInteractive(App.Scopes)
                      .WithParentActivityOrWindow(App.ParentWindow)
                      .WithUseEmbeddedWebView(!useSystemBrowser)
                      .ExecuteAsync();