Differenze tra le app ADAL.NET e MSAL.NET

La migrazione delle applicazioni dall'uso di ADAL all'uso di MSAL offre vantaggi per la sicurezza e la resilienza. Questo articolo illustra le differenze tra MSAL.NET e ADAL.NET. Tutte le nuove applicazioni devono usare MSAL.NET e le Microsoft Identity Platform, ovvero la generazione più recente di librerie di autenticazione Microsoft. Usando MSAL.NET, si acquisiscono token per gli utenti che accedono all'applicazione con Microsoft Entra ID (account aziendali e dell'istituto di istruzione), account Microsoft (account personali) o Azure AD B2C. Se si dispone di un'applicazione esistente che usa ADAL.NET, eseguirne la migrazione in MSAL.NET.

È comunque necessario usare ADAL.NET se l'applicazione deve accedere agli utenti con versioni precedenti di Active Directory Federation Services (ADFS). Per altre informazioni, vedere Supporto di ADFS.

Prerequisiti

Per altre informazioni su MSAL, vedere Panoramica di MSAL .

Differenze

Concessioni supportate

Di seguito è riportato un riepilogo del confronto tra MSAL.NET e ADAL.NET le concessioni supportate per le applicazioni client pubbliche e riservate.

Applicazioni client pubbliche

L'immagine seguente riepiloga alcune delle differenze tra ADAL.NET e MSAL.NET per un'applicazione client pubblica.

Ecco le concessioni supportate in ADAL.NET e MSAL.NET per le applicazioni desktop e per dispositivi mobili.

Applicazioni client riservate

L'immagine seguente riepiloga alcune delle differenze tra ADAL.NET e MSAL.NET per un'applicazione client riservata.

Ecco le concessioni supportate in ADAL.NET, MSAL.NET e Microsoft. Identity.Web per applicazioni Web, API Web e applicazioni daemon.

Migrazione da ADAL 2.x con token di aggiornamento

In ADAL.NET v2. X, i token di aggiornamento sono stati esposti consentendo di sviluppare soluzioni per l'uso di questi token memorizzandoli nella cache e usando i AcquireTokenByRefreshToken metodi forniti da ADAL 2.x.

Alcune di queste soluzioni sono state usate in scenari come:

• Servizi a esecuzione prolungata che eseguono azioni, inclusi l'aggiornamento dei dashboard per gli utenti quando gli utenti non sono più connessi/connessi all'app.
• Scenari WebFarm per consentire al client di portare il token di aggiornamento al servizio Web (la memorizzazione nella cache viene eseguita sul lato client, cookie crittografato e non sul lato server).

MSAL.NET non espone i token di aggiornamento per motivi di sicurezza. MSAL gestisce automaticamente i token di aggiornamento.

Fortunatamente, MSAL.NET ha un'API che consente di eseguire la migrazione dei token di aggiornamento precedenti (acquisiti con ADAL) in 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 questo metodo, è possibile fornire il token di aggiornamento usato in precedenza insieme a qualsiasi ambito (risorse) desiderato. Il token di aggiornamento verrà scambiato per uno nuovo e memorizzato nella cache nell'applicazione.

Poiché questo metodo è destinato a scenari che non sono tipici, non è facilmente accessibile con senza prima eseguire il IConfidentialClientApplication cast a IByRefreshToken.

Il frammento di codice seguente mostra il codice di migrazione in un'applicazione client riservata.

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 il token di aggiornamento archiviato in alcune risorse di archiviazione da una versione precedente dell'applicazione che usava ADAL 2.x. GetTokenCacheForSignedInUser deserializza una cache per l'utente connesso (poiché le applicazioni client riservate devono avere una cache per utente).

Un token di accesso e un token ID vengono restituiti nel AuthenticationResult valore mentre il nuovo token di aggiornamento viene archiviato nella cache. È anche possibile usare questo metodo per vari scenari di integrazione in cui è disponibile un token di aggiornamento.

Token v1.0 e v2.0

Esistono due versioni di token: token v1.0 e token v2.0. L'endpoint v1.0 (usato da ADAL) genera token ID v1.0 mentre l'endpoint v2.0 (usato da MSAL) genera token ID v2.0. Tuttavia, entrambi gli endpoint generano token di accesso della versione del token accettata dall'API Web. Una proprietà del manifesto dell'applicazione dell'API Web consente agli sviluppatori di scegliere la versione del token accettata. Vedere accessTokenAcceptedVersion la documentazione di riferimento sul manifesto dell'applicazione .

Per altre informazioni sui token di accesso v1.0 e v2.0, vedere Microsoft Entra token di accesso.

Eccezioni

Eccezioni necessarie per l'interazione

Usando MSAL.NET, si intercetta MsalUiRequiredException come descritto in AcquireTokenSilent

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

Per informazioni dettagliate, vedere Gestire errori ed eccezioni in MSAL.NET

ADAL.NET presentava eccezioni meno esplicite. Ad esempio, quando l'autenticazione invisibile all'utente non è riuscita in ADAL, la procedura doveva intercettare l'eccezione e cercare il user_interaction_required codice di errore:

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

Per informazioni dettagliate, vedere il modello consigliato per acquisire un token nelle applicazioni client pubbliche con ADAL.NET.

Comportamento tempestivo

Il comportamento della richiesta in MSAL.NET equivale al comportamento della richiesta in ADAL.NET:

Gestione delle eccezioni di richiesta di attestazione

A volte quando si acquisisce un token, Microsoft Entra ID genera un'eccezione nel caso in cui una risorsa richieda più attestazioni dell'utente (ad esempio l'autenticazione a due fattori).

In MSAL.NET le eccezioni di richiesta di attestazione vengono gestite nel modo seguente:

• L'oggetto Claims viene superficieto nell'oggetto MsalServiceException.
• Esiste un WithClaims(String) metodo che può essere applicato ai AcquireTokenXXX generatori.

Per informazioni dettagliate, vedere Gestione di MsalUiRequiredException.

In ADAL.NET le eccezioni di richiesta di attestazione sono state gestite nel modo seguente:

• AdalClaimChallengeException è un'eccezione (derivazione da AdalServiceException). Il Claims membro contiene un frammento JSON con le attestazioni previste.
• L'applicazione client pubblica che riceve questa eccezione necessaria per chiamare l'override AcquireTokenInteractive con un parametro di attestazione. Questo override di AcquireTokenInteractive non tenta nemmeno di raggiungere la cache perché non è necessario. Il motivo è che il token nella cache non ha le attestazioni corrette (altrimenti non sarebbe stato generato un'eccezione AdalClaimChallengeException ). Di conseguenza, non è necessario esaminare la cache. Può ClaimChallengeException essere ricevuto in un'API Web che esegue OBO, ma deve AcquireTokenInteractive essere chiamato in un'applicazione client pubblica che chiama questa API Web.

Per informazioni dettagliate, inclusi gli esempi, vedere Gestione di AdalClaimChallengeException.

Ambiti

ADAL usa il concetto di risorse con resourceId stringa, MSAL.NET, tuttavia, usa gli ambiti. La logica usata da Microsoft Entra ID è la seguente:

• Per l'endpoint ADAL (v1.0) con un token di accesso v1.0 (l'unico possibile), aud=resource.
• Per MSAL (endpoint v2.0) che richiede un token di accesso per una risorsa che accetta token v2.0, aud=resource.AppId.
• Per MSAL (endpoint v2.0) che richiede un token di accesso per una risorsa che accetta un token di accesso v1.0, Microsoft Entra ID analizza il gruppo di destinatari desiderato dall'ambito richiesto. Questa operazione viene eseguita prendendo tutto prima dell'ultima barra e usandolo come identificatore di risorsa. Di conseguenza, se https://database.windows.net prevede un gruppo di destinatari di , è necessario richiedere un ambito di https://database.windows.net//.default (notare la doppia barra prima di https://database.windows.net/./default). Questo è illustrato negli esempi 1 e 2 seguenti.

Esempio 1

Se si vogliono acquisire token per un'applicazione che accetta token v1.0 (ad esempio, microsoft API Graph, ovvero https://graph.microsoft.com), è necessario creare scopes concatenando un identificatore di risorsa desiderato con un'autorizzazione OAuth2 desiderata per tale risorsa.

Ad esempio, per accedere al nome dell'utente tramite un'API Web v1.0 il cui URI ID app è ResourceId, si vuole usare:

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

Se si vuole leggere e scrivere con MSAL.NET Microsoft Entra ID usando microsoft API Graph (https://graph.microsoft.com/), è necessario creare un elenco di ambiti come nel frammento di codice seguente:

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

Esempio 2

Se resourceId termina con un valore "/", è necessario avere un doppio "/" quando si scrive il valore dell'ambito. Ad esempio, se si vuole scrivere l'ambito corrispondente all'API Azure Resource Manager (https://management.core.windows.net/), richiedere l'ambito seguente (prendere nota delle due barre).

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

Ciò è dovuto al fatto che l'API Resource Manager prevede una barra nell'attestazione del gruppo di destinatari (aud) e quindi è presente una barra per separare il nome dell'API dall'ambito.

Se si vuole acquisire un token per tutti gli ambiti statici di un'applicazione v1.0, è necessario creare l'elenco degli ambiti, come illustrato nel frammento di codice seguente:

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

Per un flusso di credenziali client, anche l'ambito da passare sarà /.default. Questo ambito indica di Microsoft Entra ID: "tutte le autorizzazioni a livello di app a cui l'amministratore ha acconsentito nella registrazione dell'applicazione.

Passaggi successivi

Eseguire la migrazione delle app da ADAL a MSALMigrate your ADAL.NET confidential client apps to use MSAL.NET