Différences entre les applications ADAL.NET et MSAL.NET

La migration de vos applications à l’aide d’ADAL vers MSAL offre des avantages de sécurité et de résilience. Cet article décrit les différences entre MSAL.NET et ADAL.NET. Toutes les nouvelles applications doivent utiliser MSAL.NET et le Plateforme d'identités Microsoft, qui est la dernière génération de bibliothèques d’authentification Microsoft. À l’aide de MSAL.NET, vous obtenez des jetons pour les utilisateurs qui se connectent à votre application avec des Microsoft Entra ID (comptes professionnels et scolaires), des comptes Microsoft (personnels) ou Azure AD B2C. Si vous disposez d’une application existante qui utilise ADAL.NET, migrez-la vers MSAL.NET.

Vous devez toujours utiliser ADAL.NET si votre application doit connecter des utilisateurs avec des versions antérieures de Services ADFS (ADFS). Pour plus d’informations, consultez la prise en charge d’ADFS.

Prerequisites

Consultez la vue d’ensemble de MSAL pour en savoir plus sur MSAL.

Différences

Subventions prises en charge

Voici un résumé comparant MSAL.NET et ADAL.NET subventions prises en charge pour les applications clientes publiques et confidentielles.

Applications clientes publiques

L’image suivante résume certaines des différences entre ADAL.NET et MSAL.NET pour une application cliente publique.

Voici les subventions prises en charge dans ADAL.NET et MSAL.NET pour les applications de bureau et mobiles.

Applications clientes confidentielles

L’image suivante résume certaines des différences entre ADAL.NET et MSAL.NET pour une application cliente confidentielle.

Voici les subventions prises en charge dans ADAL.NET, MSAL.NET et Microsoft. Identity.Web pour les applications web, les API web et les applications démon.

Migration à partir d’ADAL 2.x avec des jetons d’actualisation

Dans ADAL.NET v2. X, les jetons d’actualisation ont été exposés pour vous permettre de développer des solutions autour de l’utilisation de ces jetons en les mettant en cache et en utilisant les AcquireTokenByRefreshToken méthodes fournies par ADAL 2.x.

Certaines de ces solutions ont été utilisées dans des scénarios tels que :

• Services de longue durée qui effectuent des actions, notamment l’actualisation des tableaux de bord pour les utilisateurs lorsque les utilisateurs ne sont plus connectés/ connectés à l’application.
• Scénarios WebFarm permettant au client d’apporter le jeton d’actualisation au service web (la mise en cache est effectuée côté client, cookie chiffré et non côté serveur).

MSAL.NET n'expose pas les jetons d'actualisation pour des raisons de sécurité. MSAL gère l’actualisation des jetons pour vous.

Heureusement, MSAL.NET dispose d’une API qui vous permet de migrer vos jetons d’actualisation précédents (acquis avec ADAL) dans les IConfidentialClientApplicationéléments suivants :

/// <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);

Avec cette méthode, vous pouvez fournir le jeton d’actualisation précédemment utilisé avec toutes les étendues (ressources) souhaitées. Le jeton d’actualisation est échangé pour un nouveau jeton et mis en cache dans votre application.

Comme cette méthode est destinée aux scénarios qui ne sont pas typiques, il n’est pas facilement accessible avec le IConfidentialClientApplication sans le faire passer en IByRefreshTokenpremier.

L’extrait de code ci-dessous montre du code de migration dans une application cliente confidentielle.

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 récupère le jeton d’actualisation stocké dans un stockage par une version précédente de l’application utilisée pour utiliser ADAL 2.x. GetTokenCacheForSignedInUser désérialise un cache pour l’utilisateur connecté (car les applications clientes confidentielles doivent avoir un cache par utilisateur).

Un jeton d’accès et un jeton d’ID sont retournés dans la AuthenticationResult valeur pendant que le nouveau jeton d’actualisation est stocké dans le cache. Vous pouvez également utiliser cette méthode pour différents scénarios d’intégration dans lesquels vous disposez d’un jeton d’actualisation.

Jetons v1.0 et v2.0

Il existe deux versions de jetons : les jetons v1.0 et les jetons v2.0. Le point de terminaison v1.0 (utilisé par ADAL) émet des jetons d’ID v1.0 tandis que le point de terminaison v2.0 (utilisé par MSAL) émet des jetons d’ID v2.0. Toutefois, les deux points de terminaison émettent des jetons d’accès de la version du jeton accepté par l’API web. Une propriété du manifeste d’application de l’API web permet aux développeurs de choisir la version du jeton acceptée. Consultez accessTokenAcceptedVersion la documentation de référence du manifeste d’application .

Pour plus d’informations sur les jetons d’accès v1.0 et v2.0, consultez Microsoft Entra jetons d’accès.

Exceptions

Exceptions requises pour l’interaction

À l’aide de MSAL.NET, vous interceptez MsalUiRequiredException comme décrit dans AcquireTokenSilent

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

Pour plus d’informations, consultez Gérer les erreurs et les exceptions dans MSAL.NET

ADAL.NET avait des exceptions moins explicites. Par exemple, lorsque l’authentification silencieuse a échoué dans ADAL, la procédure devait intercepter l’exception et rechercher le user_interaction_required code d’erreur :

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

Pour plus d’informations, consultez le modèle recommandé pour acquérir un jeton dans les applications clientes publiques avec ADAL.NET.

Comportement d’invite

Le comportement d’invite dans MSAL.NET équivaut au comportement d’invite dans ADAL.NET :

Gestion des exceptions de défi de revendication

Parfois, lors de l’acquisition d’un jeton, Microsoft Entra ID lève une exception au cas où une ressource exige davantage de revendications de l’utilisateur (par exemple, l’authentification à deux facteurs).

Dans MSAL.NET, les exceptions de défi de revendication sont gérées de la manière suivante :

• Les Claims surfaces sont exposées dans le MsalServiceException.
• Il existe une WithClaims(String) méthode qui peut s’appliquer aux AcquireTokenXXX générateurs.

Pour plus d’informations, consultez Gestion de MsalUiRequiredException.

Dans ADAL.NET, les exceptions de défi de revendication ont été gérées de la manière suivante :

• AdalClaimChallengeException est une exception (dérivant de AdalServiceException). Le Claims membre contient un fragment JSON avec les revendications, qui sont attendues.
• L’application cliente publique recevant cette exception nécessaire pour appeler la AcquireTokenInteractive substitution ayant un paramètre de revendication. Ce remplacement ne tente même pas d’atteindre AcquireTokenInteractive le cache, car il n’est pas nécessaire. La raison est que le jeton dans le cache n’a pas les revendications appropriées (sinon un AdalClaimChallengeException jeton n’aurait pas été levée). Par conséquent, il n’est pas nécessaire d’examiner le cache. Il ClaimChallengeException peut être reçu dans une api WebAPI effectuant OBO, mais il AcquireTokenInteractive doit être appelé dans une application cliente publique appelant cette API web.

Pour plus d’informations, notamment des exemples, consultez la gestion d’AdalClaimChallengeException.

Étendues

La bibliothèque ADAL utilise le concept de ressources avec resourceId des chaînes, MSAL.NET, mais utilise des étendues. La logique utilisée par Microsoft Entra ID est la suivante :

• Pour le point de terminaison ADAL (v1.0) avec un jeton d’accès v1.0 (le seul possible), aud=resource.
• Pour le point de terminaison MSAL (v2.0) demandant un jeton d’accès pour une ressource acceptant des jetons v2.0, aud=resource.AppId.
• Pour le point de terminaison MSAL (v2.0) demandant un jeton d’accès pour une ressource acceptant un jeton d’accès v1.0, Microsoft Entra ID analyse l’audience souhaitée à partir de l’étendue demandée. Pour ce faire, prenez tout avant la dernière barre oblique et utilisez-la comme identificateur de ressource. Par conséquent, si https://database.windows.net vous attendez un public de https://database.windows.net/, vous devez demander une étendue de https://database.windows.net//.default (notez la double barre oblique avant ./default). Ceci est illustré par des exemples 1 et 2 ci-dessous.

Exemple 1 :

Si vous souhaitez acquérir des jetons pour une application acceptant des jetons v1.0 (par exemple, microsoft API Graph, autrement dithttps://graph.microsoft.com), vous devrez créer scopes en concaténant un identificateur de ressource souhaité avec une autorisation OAuth2 souhaitée pour cette ressource.

Par exemple, pour accéder au nom de l’utilisateur via une API web v1.0 dont l’URI d’ID d’application est ResourceId, vous souhaitez utiliser :

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

Si vous souhaitez lire et écrire avec MSAL.NET Microsoft Entra ID à l'aide de Microsoft API Graph (https://graph.microsoft.com/), vous devez créer une liste d'étendues comme dans l'extrait de code ci-dessous :

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

Exemple 2

Si resourceId se termine par un « / », vous devez avoir un double « / » lors de l’écriture de la valeur d’étendue. Par exemple, si vous souhaitez écrire l’étendue correspondant à l’API Azure Resource Manager (https://management.core.windows.net/), demandez l’étendue suivante (notez les deux barres obliques).

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

Cela est dû au fait que l'API Resource Manager attend une barre oblique dans sa revendication d'audience (aud), puis une barre oblique sépare le nom de l'API de l'étendue.

Si vous souhaitez acquérir un jeton pour toutes les étendues statiques d’une application v1.0, vous devez créer votre liste d’étendues, comme indiqué dans l’extrait de code ci-dessous :

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

Pour un flux d’informations d’identification client, l’étendue à passer serait /.defaultégalement . Cette étendue indique à Microsoft Entra ID : « toutes les autorisations au niveau de l’application auxquelles l’administrateur a consenti dans l’inscription de l’application.

Étapes suivantes

Migrez vos applications d’ADAL vers MSALMigrate your ADAL.NET confidentiel client apps to use MSAL.NET