Diferencias entre las aplicaciones ADAL.NET y MSAL.NET

La migración de las aplicaciones del uso de ADAL al uso de MSAL incluye ventajas de seguridad y resistencia. En este artículo se describen las diferencias entre MSAL.NET y ADAL.NET. Todas las aplicaciones nuevas deben usar MSAL.NET y el Plataforma de identidad de Microsoft, que es la última generación de bibliotecas de autenticación de Microsoft. Con MSAL.NET, adquiere tokens para los usuarios que inician sesión en la aplicación con Microsoft Entra ID (cuentas profesionales y educativas), cuentas de Microsoft (personal) (MSA) o Azure AD B2C. Si tiene una aplicación existente que usa ADAL.NET, migrela a MSAL.NET.

Todavía tiene que usar ADAL.NET si la aplicación necesita iniciar sesión a los usuarios con versiones anteriores de Servicios de federación de Active Directory (AD FS) (ADFS). Para obtener más información, consulte Compatibilidad con ADFS.

Prerequisites

Consulte introducción a MSAL para obtener más información sobre MSAL.

Diferencias

Concesiones admitidas

A continuación se muestra un resumen que compara MSAL.NET y ADAL.NET concesiones admitidas para aplicaciones cliente públicas y confidenciales.

Aplicaciones cliente públicas

En la imagen siguiente se resumen algunas de las diferencias entre ADAL.NET y MSAL.NET para una aplicación cliente pública.

Estas son las concesiones admitidas en ADAL.NET y MSAL.NET para aplicaciones de escritorio y móviles.

Aplicaciones cliente confidenciales

En la imagen siguiente se resumen algunas de las diferencias entre ADAL.NET y MSAL.NET para una aplicación cliente confidencial.

Estas son las concesiones admitidas en ADAL.NET, MSAL.NET y Microsoft. Identity.Web para aplicaciones web, API web y aplicaciones de demonio.

Migración desde ADAL 2.x con tokens de actualización

En ADAL.NET v2. X, los tokens de actualización se expusieron, lo que le permite desarrollar soluciones en torno al uso de estos tokens mediante el almacenamiento en caché de estos tokens y el uso de los AcquireTokenByRefreshToken métodos proporcionados por ADAL 2.x.

Algunas de esas soluciones se usaron en escenarios como:

• Servicios de larga duración que realizan acciones que incluyen la actualización de paneles para los usuarios cuando los usuarios ya no están conectados o han iniciado sesión en la aplicación.
• Escenarios de WebFarm para permitir que el cliente traiga el token de actualización al servicio web (el almacenamiento en caché se realiza en el lado cliente, la cookie cifrada y no el lado servidor).

MSAL.NET no expone tokens de actualización por motivos de seguridad. MSAL controla la actualización de tokens por usted.

Afortunadamente, MSAL.NET tiene una API que permite migrar los tokens de actualización anteriores (adquiridos con ADAL) a IConfidentialClientApplication:

/// <summary>
/// Acquires an access token from an existing refresh token and stores it and the refresh token into
/// the application user token cache, where it will be available for further AcquireTokenSilent calls.
/// This method can be used in migration to MSAL from ADAL v2 and in various integration
/// scenarios where you have a RefreshToken available.
/// (see https://aka.ms/msal-net-migration-adal2-msal2)
/// </summary>
/// <param name="scopes">Scope to request from the token endpoint.
/// Setting this to null or empty will request an access token, refresh token and ID token with default scopes</param>
/// <param name="refreshToken">The refresh token from ADAL 2.x</param>
IByRefreshToken.AcquireTokenByRefreshToken(IEnumerable<string> scopes, string refreshToken);

Con este método, puede proporcionar el token de actualización usado anteriormente junto con los ámbitos (recursos) que desee. El token de actualización se intercambiará por uno nuevo y se almacenará en caché en la aplicación.

Como este método está pensado para escenarios que no son típicos, no es fácilmente accesible con sin IConfidentialClientApplication convertirlo primero en IByRefreshToken.

El fragmento de código siguiente muestra algún código de migración en una aplicación cliente confidencial.

TokenCache userCache = GetTokenCacheForSignedInUser();
string rt = GetCachedRefreshTokenForSignedInUser();

IConfidentialClientApplication app;
app = ConfidentialClientApplicationBuilder.Create(clientId)
 .WithAuthority(Authority)
 .WithRedirectUri(RedirectUri)
 .WithClientSecret(ClientSecret)
 .Build();
IByRefreshToken appRt = app as IByRefreshToken;

AuthenticationResult result = await appRt.AcquireTokenByRefreshToken(null, rt)
                                         .ExecuteAsync()
                                         .ConfigureAwait(false);

GetCachedRefreshTokenForSignedInUser recupera el token de actualización almacenado en algún almacenamiento por una versión anterior de la aplicación que usó para usar ADAL 2.x. GetTokenCacheForSignedInUser deserializa una memoria caché para el usuario que ha iniciado sesión (como las aplicaciones cliente confidenciales deben tener una memoria caché por usuario).

Un token de acceso y un token de identificador se devuelven en el AuthenticationResult valor mientras el nuevo token de actualización se almacena en la memoria caché. También puede usar este método para varios escenarios de integración en los que tiene un token de actualización disponible.

Tokens de las versiones 1.0 y 2.0

Hay dos versiones de tokens: tokens v1.0 y tokens v2.0. El punto de conexión v1.0 (usado por ADAL) emite tokens de identificador v1.0 mientras que el punto de conexión v2.0 (usado por MSAL) emite tokens de identificador v2.0. Sin embargo, ambos puntos de conexión emiten tokens de acceso de la versión del token que acepta la API web. Una propiedad del manifiesto de aplicación de la API web permite a los desarrolladores elegir qué versión del token se acepta. Consulte accessTokenAcceptedVersion la documentación de referencia del manifiesto de aplicación .

Para obtener más información sobre los tokens de acceso v1.0 y v2.0, consulte Microsoft Entra tokens de acceso.

Exceptions

Excepciones necesarias de interacción

Con MSAL.NET, se detecta MsalUiRequiredException como se describe en AcquireTokenSilent

catch(MsalUiRequiredException exception)
{
 try {"try to authenticate interactively"}
}

Para obtener más información, consulte Control de errores y excepciones en MSAL.NET

ADAL.NET tenían excepciones menos explícitas. Por ejemplo, cuando se produjo un error de autenticación silenciosa en ADAL, el procedimiento era detectar la excepción y buscar el código de user_interaction_required error:

catch(AdalException exception)
{
 if (exception.ErrorCode == "user_interaction_required")
 {
  try
  {“try to authenticate interactively”}}
 }
}

Para obtener más información, consulte el patrón recomendado para adquirir un token en aplicaciones cliente públicas con ADAL.NET.

Comportamiento de la petición

El comportamiento del mensaje en MSAL.NET es equivalente al comportamiento del mensaje en ADAL.NET:

Control de excepciones de desafío de notificación

En ocasiones al adquirir un token, Microsoft Entra ID produce una excepción en caso de que un recurso requiera más notificaciones del usuario (por ejemplo, autenticación en dos fases).

En MSAL.NET, las excepciones de desafío de notificación se controlan de la siguiente manera:

• Claims Se muestran en .MsalServiceException
• Hay un WithClaims(String) método que se puede aplicar a los AcquireTokenXXX generadores.

Para obtener más información, consulte Control de MsalUiRequiredException.

En ADAL.NET, las excepciones de desafío de notificaciones se controlaron de la siguiente manera:

• AdalClaimChallengeException es una excepción (derivada de AdalServiceException). El Claims miembro contiene algún fragmento JSON con las notificaciones, que se esperan.
• La aplicación cliente pública que recibe esta excepción necesaria para llamar a la AcquireTokenInteractive invalidación que tiene un parámetro de notificaciones. Esta invalidación de AcquireTokenInteractive ni siquiera intenta alcanzar la memoria caché, ya que no es necesaria. El motivo es que el token de la memoria caché no tiene las notificaciones correctas (de lo contrario, no se habría producido una AdalClaimChallengeException excepción). Por lo tanto, no es necesario examinar la memoria caché. ClaimChallengeException Se puede recibir en una WEBAPI que realiza OBO, pero AcquireTokenInteractive es necesario llamar a en una aplicación cliente pública que llama a esta API web.

Para obtener más información, incluidos los ejemplos, consulte control de AdalClaimChallengeException.

Ámbitos

ADAL usa el concepto de recursos con resourceId cadena, MSAL.NET, sin embargo, usa ámbitos. La lógica usada por Microsoft Entra ID es la siguiente:

• Para el punto de conexión de ADAL (v1.0) con un token de acceso v1.0 (el único posible), aud=resource.
• En el caso de MSAL (punto de conexión v2.0) que solicita un token de acceso para un recurso que acepta tokens v2.0, aud=resource.AppId.
• En el caso de MSAL (punto de conexión v2.0) que solicita un token de acceso para un recurso que acepta un token de acceso v1.0, Microsoft Entra ID analiza la audiencia deseada desde el ámbito solicitado. Para ello, se toma todo antes de la última barra diagonal y se usa como identificador de recurso. Por lo tanto, si https://database.windows.net espera una audiencia de https://database.windows.net/, deberá solicitar un ámbito de https://database.windows.net//.default (observe la barra diagonal doble antes de ./default). Esto se muestra en los ejemplos 1 y 2 siguientes.

Ejemplo 1

Si quiere adquirir tokens para una aplicación que acepta tokens v1.0 (por ejemplo, microsoft Graph API, que es https://graph.microsoft.com), deberá crear scopes mediante la concatenación de un identificador de recurso deseado con un permiso OAuth2 deseado para ese recurso.

Por ejemplo, para acceder al nombre del usuario a través de una API web v1.0 cuyo URI de identificador de aplicación es ResourceId, querrá usar:

var scopes = new [] { ResourceId+"/user_impersonation" };

Si desea leer y escribir con MSAL.NET Microsoft Entra ID mediante microsoft Graph API (https://graph.microsoft.com/), crearía una lista de ámbitos como en el fragmento de código siguiente:

string ResourceId = "https://graph.microsoft.com/"; 
string[] scopes = { ResourceId + "Directory.Read", ResourceId + "Directory.Write" }

Ejemplo 2

Si resourceId termina con "/", deberá tener un doble "/" al escribir el valor de ámbito. Por ejemplo, si desea escribir el ámbito correspondiente a la API de Azure Resource Manager (), solicite el siguiente ámbito (https://management.core.windows.net/tenga en cuenta las dos barras diagonales).

var resource = "https://management.core.windows.net/"
var scopes = new[] {"https://management.core.windows.net//user_impersonation"};
var result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();

// then call the API: https://management.azure.com/subscriptions?api-version=2016-09-01

Esto se debe a que la API de Resource Manager espera una barra diagonal en su notificación de audiencia (aud) y, a continuación, hay una barra diagonal para separar el nombre de la API del ámbito.

Si quiere adquirir un token para todos los ámbitos estáticos de una aplicación v1.0, crearía la lista de ámbitos, tal como se muestra en el fragmento de código siguiente:

ResourceId = "someAppIDURI";
var scopes = new [] { ResourceId+"/.default" };

Para un flujo de credenciales de cliente, el ámbito que se va a pasar también sería /.default. Este ámbito indica a Microsoft Entra ID: "todos los permisos de nivel de aplicación a los que el administrador ha consentido en el registro de la aplicación.

Pasos siguientes

Migre las aplicaciones de ADAL a MSALMigrate your ADAL.NET confidential client apps to use MSAL.NET