Condividi tramite

Acquisire e memorizzare nella cache i token utilizzando Microsoft Authentication Library (MSAL)

  • Articolo

I token di accesso consentono ai client di chiamare in modo sicuro le API Web protette da Azure. Esistono diversi modi per acquisire un token tramite Microsoft Authentication Library (MSAL). Alcuni richiedono l'interazione dell'utente tramite un Web browser, mentre per altri non è necessario. In genere, il metodo usato per acquisire un token dipende dal fatto che l'applicazione sia un'applicazione client pubblica (app desktop o per dispositivi mobili) oppure un'applicazione client riservata (app Web, API Web o app daemon).

MSAL memorizza un token nella cache dopo che è stato acquisito. Il codice dell'applicazione dovrebbe prima tentare di ottenere silenziosamente un token dalla cache prima di provare ad acquisirlo con altri mezzi.

È anche possibile cancellare la cache dei token rimuovendo gli account dalla cache. Questa operazione, tuttavia, non rimuove il cookie di sessione, che si trova nel browser.

Ambiti durante l'acquisizione dei token

Gli ambiti sono le autorizzazioni che un'API web espone affinché le applicazioni client possano richiedere l'accesso. Le applicazioni client richiedono il consenso dell'utente per questi ambiti quando si effettuano richieste di autenticazione per ottenere i token per l'accesso alle API Web. MSAL consente di ottenere token per accedere alle API di Microsoft Identity Platform. Il protocollo v2.0 usa gli ambiti invece delle risorse nelle richieste. Sulla base della configurazione dell'API Web della versione del token che accetta, l'endpoint v2.0 restituisce il token di accesso a MSAL.

Diversi metodi di acquisizione dei token di MSAL richiedono un parametro scopes. Il parametro scopes è un elenco di stringhe che dichiarano le autorizzazioni desiderate e le risorse richieste. Ambiti ben noti sono le autorizzazioni di Microsoft Graph.

Richiedere gli ambiti per un'API Web

Quando l'applicazione deve richiedere un token di accesso con autorizzazioni specifiche per l'API di una risorsa, passare gli ambiti che contengono l'URI dell'ID app dell'API nel formato <app ID URI>/<scope>.

Alcuni valori di ambito di esempio per risorse diverse:

  • API Microsoft Graph: https://graph.microsoft.com/User.Read
  • API Web personalizzata: api://00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Il formato del valore dell'ambito varia a seconda della risorsa (l'API) che riceve il token di accesso e dei valori di attestazione aud da questa accettati.

Solo in Microsoft Graph, l'ambito user.read esegue il mapping a https://graph.microsoft.com/User.Read e i due formati di ambito possono essere usati in modo intercambiabile.

Alcune API Web, come l'API di Azure Resource Manager (https://management.core.windows.net/), prevedono una barra obliqua finale (/) nell'attestazione del destinatario (aud) del token di accesso. In questo caso, passare l'ambito come https://management.core.windows.net//user_impersonation, incluso il doppio slash (//).

Altre API potrebbero richiedere che nessuno schema o host sia incluso nel valore di ambito e prevedono solo l'ID app (un GUID) e il nome dell'ambito, ad esempio:

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Suggerimento

Se la risorsa downstream non è sotto il controllo dell'utente, potrebbe essere necessario provare formati di valore di ambito diversi (ad esempio con/senza schema e host) nel caso in cui si riceva un errore 401 o di altro tipo quando si passa il token di accesso alla risorsa.

Quando le funzionalità fornite dall'applicazione o dai relativi requisiti cambiano, è possibile richiedere autorizzazioni aggiuntive in base alle esigenze usando il parametro di ambito. Tali ambiti dinamici consentono agli utenti di fornire il consenso incrementale agli ambiti.

Ad esempio, è possibile connettere l'utente, ma negargli inizialmente l'accesso alle risorse. In un secondo momento, è possibile offrire all'utente la possibilità di visualizzare il proprio calendario richiedendo l'ambito del calendario nel metodo di acquisizione dei token e ottenendo il consenso dell'utente a tale scopo. Ad esempio, richiedendo gli ambiti https://graph.microsoft.com/User.Read e https://graph.microsoft.com/Calendar.Read.

Acquisizione di token silenziosamente (dalla cache)

MSAL gestisce una cache dei token (o due cache per le applicazioni client riservate) e memorizza un token nella cache dopo che è stato acquisito. In molti casi, tentando di ottenere silenziosamente un token, verrà ottenuto un altro token con più ambiti a partire da un token nella cache. È inoltre possibile aggiornare un token quando si avvicina alla scadenza (perché la cache dei token contiene anche un token di aggiornamento).

Il codice sorgente dell'applicazione deve prima tentare di ottenere un token in modo automatico dalla cache. Se la chiamata al metodo restituisce un errore o un'eccezione che indica che è necessaria l'interfaccia utente, provare ad acquisire un token con altri mezzi.

Esistono due flussi in cui non si deve tentare di acquisire un token in modo automatico:

  • Il flusso di credenziali client, che non utilizza la cache dei token utente ma utilizza una cache dei token dell'applicazione. Questo metodo verifica la cache dei token dell'applicazione prima di inviare una richiesta al servizio token di sicurezza (STS).
  • Il flusso del codice di autorizzazione nelle app Web, in quanto riscatta un codice che l'applicazione ha ottenuto facendo accedere l'utente e ottenendo il consenso per più autorizzazioni. Poiché il codice e non l'account viene passato come un parametro, il metodo non può eseguire una ricerca nella cache prima di riscattare il codice, pertanto è necessaria una chiamata al servizio.

Per le applicazioni Web che usano il flusso del codice di autorizzazione OpenID Connect, il modello consigliato nei controller è il seguente:

  • Instanziare un'applicazione client confidenziale con una cache token a serializzazione personalizzata.
  • Acquisire il token usando il flusso del codice di autorizzazione

Acquisizione dei token

Il metodo di acquisizione di un token varia a seconda del fatto che si tratti di un client pubblico o di un'applicazione client riservata.

Applicazioni client pubbliche

Nelle applicazioni client pubbliche (desktop e per dispositivi mobili), è possibile:

  • Ottenere token in modo interattivo chiedendo all'utente di eseguire l'accesso tramite un'interfaccia utente o una finestra popup.
  • Ottenere un token in modo automatico per l'utente connesso usando l'autenticazione integrata di Windows (IWA/Kerberos) se l'applicazione desktop è in esecuzione in un computer Windows aggiunto a un dominio o ad Azure.
  • Ottenere un token con nome utente e password nelle applicazioni client desktop .NET Framework (operazione non consigliata). Non usare nome utente e password nelle applicazioni client riservate.
  • Ottenere un token tramite il flusso del codice del dispositivo nelle applicazioni in esecuzione sui dispositivi che non dispongono di un Web browser. Vengono forniti un URL e un codice all'utente, che quindi passa a un Web browser in un altro dispositivo, immette il codice ed esegue l'accesso. Microsoft Entra ID invia quindi un token al dispositivo senza browser.

Applicazioni client riservate

Per le applicazioni client riservate (app Web, API Web o un'app daemon come un servizio di Windows), è possibile:

  • Acquisire i token per l'applicazione stessa, anziché per un utente, usando il flusso di credenziali client. Questa tecnica può essere usata per strumenti di sincronizzazione o per strumenti che elaborano gli utenti in generale e non un utente specifico.
  • Usare il flusso On-Behalf-Of (OBO) per consentire a un'API web di chiamare un'altra API per conto dell'utente. L'applicazione viene identificata con le credenziali del client al fine di acquisire un token basato su un'asserzione utente (ad esempio, SAML o un token JWT). Questo flusso è usato dalle applicazioni che devono accedere alle risorse di un determinato utente nelle chiamate da servizio a servizio. I token devono essere memorizzati nella cache in base alla sessione, non in base all'utente.
  • Acquisire i token usando il flusso del codice di autorizzazione nelle app Web dopo che l'utente esegue l'accesso tramite l'URL della richiesta di autorizzazione. Un'applicazione OpenID Connect in genere usa questo meccanismo, che consente all'utente di eseguire l'accesso tramite OpenID Connect e quindi di accedere alle API Web per conto dell'utente. I token possono essere memorizzati nella cache in base all'utente o in base alla sessione. Se la memorizzazione dei token nella cache avviene in base all'utente, è consigliabile limitare la durata della sessione, in modo che Microsoft Entra ID possa controllare frequentemente lo stato dei criteri di accesso condizionale.

Risultati dell'autenticazione

Quando il client richiede un token di accesso, Microsoft Entra ID restituisce anche un risultato dell'autenticazione che include i metadati relativi al token di accesso. Queste informazioni includono l'ora di scadenza del token di accesso e gli ambiti per cui è valido. Questi dati consentono all'app di eseguire la memorizzazione intelligente nella cache dei token di accesso senza la necessità di analizzare il token di accesso stesso. Il risultato dell'autenticazione espone:

  • Il token di accesso per l'API Web per l'accesso alle risorse. Questa stringa, in genere, è un token JWT con codifica Base64, ma il client non deve mai fare riferimento al contenuto del token di accesso. Il formato non rimane necessariamente stabile e può essere crittografato per la risorsa. Scrivere codice che dipende dal contenuto del token di accesso sul client è una delle fonti più comuni di errori e di interruzioni della logica del client.
  • Il token ID per l'utente (un token JWT).
  • La scadenza del token, che indica la data/ora in cui scade il token.
  • L'ID tenant contiene il tenant in cui è stato trovato l'utente. Per gli utenti guest (scenari Microsoft Entra B2B), l'ID tenant è il tenant guest, non il tenant univoco. Quando il token viene inviato a nome di un utente, il risultato dell'autenticazione contiene anche le informazioni sull'utente. Per i flussi client riservati in cui vengono richiesti token senza utente (per l'applicazione), queste informazioni sull'utente sono null.
  • Ambiti per cui è stato emesso il token.
  • ID univoco per l'utente.

(Impostazioni avanzate) Accesso ai token memorizzati nella cache dell'utente in app e servizi in background

È possibile usare l'implementazione della cache dei token di MSAL per consentire alle app, alle API e ai servizi in background di usare la cache dei token di accesso per continuare a eseguire operazioni per conto degli utenti in loro assenza. Questa opzione è particolarmente utile se le app e i servizi in background devono continuare a funzionare per conto dell'utente dopo che questi è uscito dall'app Web front-end.

Attualmente, la maggior parte dei processi in background usa le autorizzazioni per le applicazioni quando deve operare con i dati di un utente senza che questi sia presente per autenticare o ripetere l'autenticazione. Poiché le autorizzazioni per le applicazioni richiedono spesso il consenso dell'amministratore, il che presuppone l'elevazione dei privilegi, ne derivano conflitti non necessari nella misura in cui lo sviluppatore non intendeva ottenere un'autorizzazione diversa da quella per cui l'utente aveva inizialmente dato il proprio consenso per l'app.

Questo codice di esempio in GitHub illustra come evitare questi conflitti non necessari accedendo alla cache dei token di MSAL dalle app in background:

Accedere alla cache dei token dell'utente autenticato tramite app, API e servizi in background

Nota

Quando si acquisiscono token in modo interattivo usando broker di autenticazione, il broker di autenticazione eseguirà prima la ricerca nella cache e restituirà il token memorizzato nella cache, se disponibile (problema di GitHub - acquireToken usa la memorizzazione nella cache).

Vedi anche

Diverse piattaforme supportate da MSAL includono informazioni aggiuntive relative alla cache dei token nella documentazione per la libreria della piattaforma. Ad esempio: