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 usando Microsoft Authentication Library (MSAL). Alcuni richiedono l'interazione dell'utente tramite un Web browser, mentre altri non richiedono l'interazione dell'utente. In genere, il metodo usato per acquisire un token dipende dal fatto che l'applicazione sia un'applicazione client pubblica (desktop o mobile) o un'applicazione client riservata (app Web, API Web o app daemon).

MSAL memorizza nella cache un token dopo l'acquisizione. Il codice dell'applicazione deve prima provare a ottenere un token automaticamente dalla cache prima di tentare di acquisire un token con altri mezzi.

È anche possibile cancellare la cache dei token rimuovendo gli account dalla cache. Questo non rimuove tuttavia il cookie di sessione presente nel browser.

Ambiti durante l'acquisizione dei token

Gli ambiti sono le autorizzazioni esposte da un'API Web a cui le applicazioni client possono 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 ambiti anziché 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 scopes parametro . Il scopes parametro è un elenco di stringhe che dichiarano le autorizzazioni desiderate e le risorse richieste. Gli ambiti noti sono le autorizzazioni di Microsoft Graph.

Ambiti di richiesta per un'API Web

Quando l'applicazione deve richiedere un token di accesso con autorizzazioni specifiche per un'API della risorsa, passare gli ambiti contenenti l'URI 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://11111111-1111-1111-1111-111111111111/api.read

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

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

Alcune API Web, ad esempio l'API di Azure Resource Manager (https://management.core.windows.net/) prevedono una barra finale (/) nell'attestazione del gruppo di 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 nessun schema o host sia incluso nel valore dell'ambito e si aspettano solo l'ID app (un GUID) e il nome dell'ambito, ad esempio:

11111111-1111-1111-1111-111111111111/api.read

Suggerimento

Se la risorsa downstream non è sotto il controllo, potrebbe essere necessario provare diversi formati di valore di ambito (ad esempio con/senza schema e host) se si ricevono 401 o altri errori 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. Questi ambiti dinamici consentono agli utenti di fornire il consenso incrementale agli ambiti.

Ad esempio, è possibile accedere all'utente, ma inizialmente negare loro l'accesso a qualsiasi risorsa. Successivamente, è possibile concedere loro la possibilità di visualizzare il calendario richiedendo l'ambito del calendario nel metodo di acquisizione del token e ottenendo il consenso dell'utente a tale scopo. Ad esempio, richiedendo gli https://graph.microsoft.com/User.Read ambiti 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 nella cache un token dopo l'acquisizione. 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 provare a ottenere un token in modo invisibile all'utente 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 è consigliabile tentare di acquisire automaticamente un token:

  • Flusso di credenziali client, che non usa la cache dei token utente, ma una cache dei token dell'applicazione. Questo metodo si occupa della verifica della cache dei token dell'applicazione prima di inviare una richiesta al servizio token di sicurezza.
  • Flusso del codice di autorizzazione nelle app Web, perché riscatta un codice ottenuto dall'applicazione accedendo all'utente e concedendole il consenso a più ambiti. Poiché un codice e non un account viene passato come parametro, il metodo non può cercare nella cache prima di riscattare il codice, che richiama una chiamata al servizio.

Per le applicazioni Web che usano il flusso del codice di autorizzazione OpenID Connessione, il modello consigliato nei controller consiste nel:

  • 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 dipende dal fatto che si tratti di un client pubblico o di un'applicazione client riservata.

Applicazioni client pubbliche

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

  • Ottenere i token in modo interattivo con l'accesso dell'utente tramite un'interfaccia utente o una finestra popup.
  • Ottenere un token automaticamente per l'utente connesso usando autenticazione di Windows integrato (IWA/Kerberos) se l'applicazione desktop è in esecuzione in un computer Windows aggiunto a un dominio o ad Azure.
  • Ottenere un token con un nome utente e una password nelle applicazioni client desktop .NET Framework (non consigliato). Non usare nome utente e password nelle applicazioni client riservate.
  • Ottenere un token tramite il flusso del codice del dispositivo nelle applicazioni in esecuzione nei 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 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 la sincronizzazione di strumenti o strumenti che elaborano gli utenti in generale e non per un utente specifico.
  • Usare il flusso on-behalf-of (OBO) per un'API Web per chiamare un'API per conto dell'utente. L'applicazione viene identificata con le credenziali client per acquisire un token basato su un'asserzione utente (ad esempio, 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 a una sessione, non su base 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. OpenID Connessione'applicazione usa in genere questo meccanismo, che consente all'utente di accedere usando OpenID Connessione e quindi di accedere alle API Web per conto dell'utente. I token possono essere memorizzati nella cache per un utente o per una sessione. Se si memorizzano nella cache i token su base 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 cercare all'interno del token di accesso. Il formato non è garantito per rimanere stabile e può essere crittografato per la risorsa. Persone scrittura di codice a seconda del contenuto del token di accesso nel client è una delle origini più comuni di errori e interruzione della logica client.
  • Token ID per l'utente (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.

(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 agire per conto degli utenti in assenza. Questa operazione è particolarmente utile se le app e i servizi in background devono continuare a lavorare per conto dell'utente dopo che l'utente ha chiuso l'app Web front-end.

Attualmente, la maggior parte dei processi in background usa le autorizzazioni dell'applicazione quando devono lavorare con i dati di un utente senza che siano presenti per autenticare o ripetere l'autenticazione. Poiché le autorizzazioni dell'applicazione richiedono spesso il consenso dell'amministratore, che richiede l'elevazione dei privilegi, si verificano problemi non necessari perché lo sviluppatore non intende ottenere l'autorizzazione oltre a quella a cui l'utente ha originariamente acconsentito per l'app.

Questo esempio di codice in GitHub illustra come evitare questo attrito non necessario 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

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