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 usando Microsoft Authentication Library (MSAL). Alcuni richiedono l'interazione dell'utente tramite un Web browser, mentre altri non richiedono l'interazione dell'utente. In generale, il metodo usato per acquisire un token è diverso a seconda che l'applicazione sia un'applicazione client pubblica, ad esempio un'app desktop o per dispositivi mobili, oppure un'applicazione client riservata, ad esempio un'app Web, un'API Web o un'applicazione 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, attraverso la rimozione degli 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 ad Azure AD per sviluppatori (v1.0) e le API di Microsoft Identity Platform. Il protocollo della versione 2.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 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.

In MSAL è anche possibile accedere alle risorse v1.0. Per altre informazioni, vedere Ambiti per un'applicazione v1.0.

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 tuttavia 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 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

In genere, 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, ad esempio app desktop e per 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. Azure AD invia quindi un token al dispositivo senza browser.

Applicazioni client riservate

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

  • Acquisire i token per l'applicazione stessa e non per un utente, usando il flusso delle 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.
  • 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 usando OpenID Connect e quindi di accedere alle API Web per conto dell'utente.

Risultati dell'autenticazione

Quando il client richiede un token di accesso, Azure AD restituisce anche un risultato di 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 (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 B2B con Azure AD), 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.