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 deve tentare di ottenere un token in modo automatico dalla cache prima che 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 esposte da un'API Web in modo che 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 finale (/) nell'attestazione dei destinatari (aud) del token di accesso. In questo caso, passare l'ambito come https://management.core.windows.net//user_impersonation, inclusa la doppia barra (//).

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 in modo automatico (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, se si tenta di ottenere automaticamente un token, verrà acquisito un altro token con più ambiti in base a 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 usa la cache dei token utente, ma 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, poiché riscatta un codice che l'applicazione ha ricevuto connettendo l'utente e ottenendo il consenso per più ambiti. 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:

  • Creare un'istanza di un'applicazione client riservata con una cache dei token con 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 chiedere a un'API Web di chiamare un'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. La scrittura di codice dipendente dal contenuto del token di accesso nel client è una delle più comuni fonti di errori e interruzioni per la logica 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 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:

Accesso alla cache dei token dell'utente connesso da app, API e servizi in background

Vedi anche

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