Differenze tra ADAL.NET e MSAL.NET app

La migrazione delle applicazioni dall'uso di ADAL all'uso di MSAL offre vantaggi in termini di sicurezza e resilienza. Questo articolo illustra le differenze tra MSAL.NET e ADAL.NET. Nella maggior parte dei casi si vuole usare MSAL.NET e il Microsoft Identity Platform, ovvero l'ultima generazione di librerie di autenticazione Microsoft. Tramite MSAL.NET è possibile acquisire i token per gli utenti eseguendo l'accesso all'applicazione con Azure AD (account aziendali e dell'istituto di istruzione), account Microsoft (personali) o Azure AD B2C.

Se si ha già familiarità con ADAL.NET e l'endpointAzure AD for developers (v1.0), è possibile conoscere le diverse Microsoft Identity Platform? . È 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.

ADAL NET MSAL NET
Pacchetti NuGet e spazi dei nomi ADAL è stato utilizzato dal pacchetto NuGet Microsoft.IdentityModel.Clients.ActiveDirectory. Lo spazio dei nomi era Microsoft.IdentityModel.Clients.ActiveDirectory . Aggiungere il pacchetto NuGet Microsoft.Identity.Client e usare lo spazio Microsoft.Identity.Client dei nomi . Se si sta creando un'applicazione client riservata, vedere Microsoft.Identity.Web.
Ambiti e risorse ADAL.NET acquisisce i token per le risorse. MSAL.NET acquisisce i token per gli ambiti. Diversi MSAL.NET AcquireTokenXXX override richiedono un parametro denominato scopes( IEnumerable<string> scopes ). Questo parametro è un semplice elenco di stringhe che dichiarano le autorizzazioni e le risorse richieste. Gli ambiti noti sono gli ambiti Graph microsoft. È anche possibile accedere alle risorse v1.0 usando MSAL.NET.
Classi di base ADAL.NET usato AuthenticationContext come rappresentazione della connessione al servizio token di sicurezza (STS) o al server di autorizzazione, tramite un'autorità. MSAL.NET è progettato per le applicazioni client. Definisce le interfacce per le applicazioni client pubbliche e per le applicazioni client riservate, nonché un'interfaccia di base per il contratto comune a entrambi IPublicClientApplication IConfidentialClientApplication i tipi di IClientApplicationBase applicazioni.
Acquisizione di token Nei client pubblici, ADAL usa AcquireTokenAsync e per le chiamate di AcquireTokenSilentAsync autenticazione. Nei client pubblici, MSAL usa AcquireTokenInteractive e per le stesse chiamate di AcquireTokenSilent autenticazione. I parametri sono diversi da quelli di ADAL.

Nelle applicazioni client Confidential sono disponibili metodi di acquisizione dei token con un nome esplicito a seconda dello scenario. Un'altra differenza è che, MSAL.NET, non è più necessario passare l'oggetto dell'applicazione ClientID in ogni chiamata AcquireTokenXX. ClientIDL'oggetto viene impostato una sola volta quando si compila o IPublicClientApplication IConfidentialClientApplication .
IAccount e IUser ADAL definisce la nozione di utente tramite l'interfaccia IUser. Tuttavia, un utente è un umano o un agente software. Di conseguenza, un utente può essere proprietario di uno o più account nel Microsoft Identity Platform (diversi account Azure AD, Azure AD B2C, account personali Microsoft). L'utente può anche essere responsabile di uno o più Microsoft Identity Platform account. MSAL.NET definisce il concetto di account (tramite l'interfaccia IAccount). L'interfaccia IAccount rappresenta informazioni su un singolo account. L'utente può avere diversi account in tenant diversi. MSAL.NET fornisce informazioni migliori negli scenari guest, in quanto vengono fornite informazioni sull'account principale. Altre informazioni sulle differenze tra IUser e IAccount.
Persistenza della cache ADAL.NET consente di estendere la classe TokenCache per implementare la funzionalità di persistenza desiderata nelle piattaforme senza un archivio sicuro (.NET Framework e .NET Core) usando i metodi BeforeAccess e BeforeWrite. Per informazioni dettagliate, vedere Serializzazione della cachedei token in ADAL.NET . MSAL.NET rende la cache dei token una classe sealed, eliminando la possibilità di estenderla. Di conseguenza, l'implementazione della persistenza della cache dei token deve essere sotto forma di classe helper che interagisce con la cache dei token sealed. Questa interazione è descritta nella serializzazione della cache dei token in MSAL.NET articolo. La serializzazione per un'applicazione client pubblica (vedere Cache dei tokenper un'applicazione client pubblica ) è diversa da quella di per un'applicazione client riservata (vedere Cache dei token per un'app Web o un'API Web).
Autorità comune ADAL usa Azure AD versione 1.0. https://login.microsoftonline.com/commonl'autorità Azure AD versione 1.0 (utilizzata da ADAL) consente agli utenti di accedere usando qualsiasi account AAD aziendale o dell'istituto di istruzione. Azure AD versione 1.0 non consente l'accesso con account personali Microsoft. Per altre informazioni, vedere convalida dell'autorità in ADAL.NET. MSAL usa Azure AD versione 2.0. https://login.microsoftonline.com/commonl'autorità Azure AD versione 2.0 (utilizzata da MSAL) consente agli utenti di accedere con qualsiasi account dell'organizzazione (aziendale o dell'istituto di istruzione AAD) o con un account personale Microsoft. Per limitare l'accesso usando solo gli account dell'organizzazione (account aziendale o dell'istituto di istruzione) in MSAL, è necessario usare https://login.microsoftonline.com/organizations l'endpoint. Per informazioni dettagliate, vedere il parametro authority nell'applicazione client pubblica.

Concessioni supportate

Di seguito è riportato un riepilogo MSAL.NET e ADAL.NET le concessioni supportate sia per le applicazioni client pubbliche che per le applicazioni client riservate.

Applicazioni client pubbliche

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

Screenshot che mostra 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 applicazioni desktop e per dispositivi mobili.

Concedi MSAL.NET ADAL.NET
Interattività Acquisizione dei token in modo interattivo in MSAL.NET Autenticazione interattiva
Autenticazione Windows integrata Autenticazione Windows integrata Autenticazione integrata di Windows (Kerberos)
Nome utente/password Autenticazione nome utente-password Acquisizione di token con nome utente e password
Flusso di codice del dispositivo Flusso del codice del dispositivo Profilo di dispositivo per i dispositivi senza Web browser

Applicazioni client riservate

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

Screenshot che mostra 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.

Tipo di app Concedi MSAL.NET ADAL.NET
App Web, API Web, daemon Client Credentials Flussi di credenziali client in MSAL.NET Flussi di credenziali client in ADAL.NET
API Web On-Behalf-Of On-Behalf-Of in MSAL.NET Chiamate da servizio a servizio per conto dell'utente con ADAL.NET
app Web Codice di autenticazione Acquisizione di token con codici di autorizzazione nelle app Web con MSAL.NET Acquisizione di token con codici di autorizzazione nelle app Web con ADAL.NET

Migrazione da ADAL 2.x con token di aggiornamento

In ADAL.NET v2.x sono stati esposti i token di aggiornamento, consentendo di sviluppare soluzioni basate sull'uso di tali token, memorizzandoli nella cache e usando i metodi AcquireTokenByRefreshToken forniti da ADAL versione 2.x.

Alcune soluzioni di questo tipo sono state usate in scenari come:

  • Servizi a esecuzione lunga che eseguono azioni, tra cui 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 nel servizio Web (la memorizzazione nella cache viene eseguita sul lato client, sul 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 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 agli ambiti (risorse) desiderati. Il token di aggiornamento verrà scambiato con uno nuovo e memorizzato nella cache nell'applicazione.

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

Il frammento di codice seguente mostra 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 (perché le applicazioni client riservate devono avere una sola 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: i token v1.0 e i token v2.0. L'endpoint v1.0 (usato da ADAL) genera token ID v1.0 mentre l'endpoint v2.0 (usato da MSAL) emette 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 nella documentazione di riferimento del manifesto dell'applicazione.

Per altre informazioni sui token di accesso v1.0 e v2.0, vedere Azure Active Directory token di accesso.

Eccezioni

Eccezioni di interazione richiesta

Tramite MSAL.NET, è possibile intercettare 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 eccezioni meno esplicite. Ad esempio, quando l'autenticazione invisibile all'utente non è riuscita in ADAL, la procedura era rilevare 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 della richiesta

Il comportamento della richiesta MSAL.NET è equivalente al comportamento della richiesta in ADAL.NET:

ADAL.NET MSAL.NET Descrizione
PromptBehavior.Auto NoPrompt Azure AD il comportamento migliore,ovvero l'accesso degli utenti in modo invisibile all'utente se hanno eseguito l'accesso con un solo account o la visualizzazione del selettore dell'account se hanno eseguito l'accesso con diversi account.
PromptBehavior.Always ForceLogin Reimposta la casella di accesso e forza l'utente a immettere nuovamente le proprie credenziali.
PromptBehavior.RefreshSession Consent Forza l'utente a concedere nuovamente il consenso a tutte le autorizzazioni.
PromptBehavior.Never Never Non usare; usare invece il modello consigliato per le app client pubbliche.
PromptBehavior.SelectAccount SelectAccount Visualizza il selettore dell'account e forza l'utente a selezionare un account.

Gestione delle eccezioni relative alla richiesta di attestazione

A volte quando si acquisisce un token, Azure AD genera un'eccezione nel caso in cui una risorsa richieda più attestazioni all'utente ,ad esempio l'autenticazione a due fattori.

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

  • Claims è disponibile in MsalServiceException.
  • È presente un .WithClaim(claims) 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 (derivante da AdalServiceException ). Il membro Claims contiene alcuni frammenti JSON con le attestazioni che sono previste.
  • L'applicazione client pubblica che riceve questa eccezione deve chiamare AcquireTokenInteractive l'override con un parametro di attestazioni. Questo override AcquireTokenInteractive di non tenta nemmeno di accedere alla cache perché non è necessario. Il motivo è che il token nella cache non ha le attestazioni giuste (in caso contrario, non sarebbe AdalClaimChallengeException stato generato un. Di conseguenza, non è necessario esaminare la cache. L'oggetto può essere ricevuto in un oggetto WebAPI che effettua OBO, ma deve essere chiamato in un'applicazione ClaimChallengeException client pubblica che chiama questa API AcquireTokenInteractive Web.

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

Ambiti

ADAL usa il concetto di risorse con stringa, MSAL.NET resourceId tuttavia usa gli ambiti. La logica usata da Azure AD è 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, Azure AD analizza i destinatari desiderati dall'ambito richiesto. Questa operazione viene eseguita prendendo tutto prima dell'ultima barra e usandola come identificatore di risorsa. Di conseguenza, se si prevede un gruppo di destinatari di , sarà necessario richiedere un ambito di (notare la doppia https://database.windows.net https://database.windows.net/ barra prima di https://database.windows.net//.default ./default). Di seguito sono illustrati gli esempi 1 e 2.

Esempio 1

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

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

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

Se si vuole leggere e scrivere con MSAL.NET Azure Active Directory usando l'API Microsoft Graph ( ), si creerà un elenco di ambiti come nel frammento di codice https://graph.microsoft.com/ seguente:

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

Esempio 2

Se resourceId termina con '/', è necessario avere un valore double '/' quando si scrive il valore dell'ambito. Ad esempio, se si vuole scrivere l'ambito corrispondente all'API Azure Resource Manager ( ), richiedere l'ambito https://management.core.windows.net/ seguente (si notino le 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

Questo perché l'API Resource Manager prevede una barra nell'attestazione del gruppo di destinatari ( ) e quindi è presente una barra per separare il nome aud dell'API dall'ambito.

Se si vuole acquisire un token per tutti gli ambiti statici di un'applicazione v1.0, creare l'elenco di 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 è /.default . Questo ambito indica Azure AD: "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 MSAL Eseguire la migrazione ADAL.NET app client riservate per usare MSAL.NET