Durata dei token, scadenza e rinnovo

Prima di iniziare, assicurarsi di comprendere come accedere e acquisire i token.

Durante l'uso di MSAL.js, è necessario comprendere le implicazioni del recupero dei token per gli utenti e come gestire la durata di questi token.

Durata e scadenza dei token

È possibile configurare la durata del token di accesso, ID o token SAML (Security Assertion Markup Language) rilasciati dal Microsoft Identity Platform. Di seguito sono riepilogate alcune informazioni.

Token di identificazione

I token ID sono associati a una combinazione specifica di account e client e in genere contengono informazioni sul profilo sull'utente. In genere, la durata della sessione utente di un'applicazione Web corrisponderà a quella della durata della sessione del token ID, ovvero per impostazione predefinita di 24 ore. Altre informazioni sulla configurazione della durata dei token.

Token di accesso

I token di accesso nel browser hanno una scadenza consigliata predefinita di 1 ora. Trascorsa questa ora, tutte le chiamate con token bearer scaduto saranno rifiutate. Questo token può essere aggiornato automaticamente usando il token di aggiornamento recuperato con questo token. Altre informazioni sulla configurazione della durata dei token.

Token di aggiornamento

I token di aggiornamento forniti alle applicazioni a pagina singola sono token di aggiornamento a tempo limitato (in genere 24 ore dal momento in cui sono stati ottenuti). Questa è una finestra non regolabile, non scorrevole, a vita. Ogni volta che viene usato un token di aggiornamento per rinnovare un token di accesso, viene recuperato un nuovo token di aggiornamento con il token di accesso rinnovato. Questo nuovo token di aggiornamento avrà una durata uguale alla durata rimanente del token di aggiornamento originale. Una volta scaduto un token di aggiornamento, è necessario avviare un nuovo flusso del codice di autorizzazione per recuperare un codice di autorizzazione e scambiarlo per un nuovo set di token.

Nota: quando si ottiene un nuovo token di aggiornamento, msal.js sostituisce il token di aggiornamento memorizzato nella cache con il nuovo token di aggiornamento, ma il token di aggiornamento precedente non viene invalidato dal server e può comunque essere usato per ottenere i token di accesso fino alla scadenza.

Rinnovo del token

L'oggetto PublicClientApplication espone un'API denominata acquireTokenSilent che è destinata a recuperare in modo invisibile all'utente un token non scaduto. Lo fa in pochi passaggi:

  1. Controllare se esiste già un token nella cache dei token per l'oggetto scopes, client id, authoritye/o homeAccountIdentifierspecificato.
  2. Se esiste un token per i parametri forniti, assicurati che ci sia un'unica corrispondenza e verificane la scadenza.
  3. Se il token di accesso non è scaduto, MSAL restituirà una risposta con i token pertinenti.
  4. Se il token di accesso è scaduto ma il token di aggiornamento è ancora valido, MSAL userà il token di aggiornamento specificato per recuperare un nuovo set di token e quindi restituirà una risposta.
  5. Se il token di aggiornamento è scaduto, MSAL tenterà di recuperare automaticamente i token di accesso usando un iframe nascosto. Verranno usati il sid o il nome utente nell'oggetto delle attestazioni dell'account per ottenere un'indicazione sulla sessione dell'utente. Se questa chiamata iframe nascosta ha esito negativo, MSAL passerà un errore dal server come InteractionRequiredAuthError, chiedendo di recuperare un codice di autorizzazione per recuperare un nuovo set di token. A tale scopo, è possibile eseguire una chiamata api acquireToken o di accesso con l'oggetto PublicClientApplication . Se la sessione è ancora attiva, il server invierà un codice senza richieste dell'utente. In caso contrario, l'utente dovrà immettere le credenziali.

Per altre informazioni sui parametri di configurazione che è possibile impostare per il metodo, vedere acquireTokenSilent.

Evitare interruzioni interattive durante la sessione di un utente

In alcuni casi può essere necessario richiamare anticipatamente l'interazione, se necessario, all'inizio della sessione di un utente per assicurarsi che possano continuare ad acquisire i token in modo invisibile all'utente e usare l'applicazione senza ulteriori interruzioni. È naturalmente possibile ottenere questo risultato richiamando l'interazione ogni volta che l'applicazione viene caricata per la prima volta, tuttavia, si tratta di un'esperienza utente scarsa e meno efficiente quando un utente dispone già di token da una sessione precedente o da un'altra finestra/scheda. Con alcuni parametri di richiesta, invece, è possibile usare acquireTokenSilent per assicurarsi che nella cache siano disponibili i token necessari per restituire automaticamente per un periodo di tempo arbitrario.

Per garantire che acquireTokenSilent possa restituire token validi per un periodo massimo di 1 ora:

  • Chiama acquireTokenSilent al caricamento della pagina con il parametro di richiesta forceRefresh impostato su true. In questo modo si ignora la cache e si acquisisce un nuovo token che può quindi essere servito dalla cache nelle chiamate successive.
  • Nelle chiamate successive, lasciare forceRefresh non impostato o impostato esplicitamente su false per garantire che i token possano essere recuperati dalla cache

Per garantire che acquireTokenSilent possa restituire token validi per un periodo di tempo minimo fino a 24 ore:

  • Chiama acquireTokenSilent al caricamento della pagina con il parametro della richiesta forceRefresh impostato su true & il parametro refreshTokenExpirationOffsetSeconds impostato sulla durata desiderata (in secondi) durante la quale non devono verificarsi interazioni
  • Nelle chiamate successive, lasciare forceRefresh e refreshTokenExpirationOffsetSeconds non impostati per garantire che i token possano essere recuperati dalla cache

Ad esempio, se si vuole assicurarsi che l'utente possa acquisire i token in modo invisibile all'utente per le 2 ore successive:

var request = {
    scopes: ["Mail.Read"],
    account: currentAccount,
    forceRefresh: true,
    refreshTokenExpirationOffsetSeconds: 7200 // 2 hours * 60 minutes * 60 seconds = 7200 seconds
};

const tokenResponse = await msalInstance.acquireTokenSilent(request).catch(async (error) => {
    if (error instanceof InteractionRequiredAuthError) {
        // fallback to interaction when silent call fails
        await msalInstance.acquireTokenRedirect(request);
    }
});

Nota: non esiste mai una garanzia che un token possa essere acquisito automaticamente anche se il token di aggiornamento non è ancora scaduto. I modelli descritti in precedenza sono tentativi di sforzo ottimale per ridurre al minimo l'interazione in momenti scomodi, ma non elimineranno la possibilità di interazioni necessarie entro gli intervalli di tempo desiderati. Inoltre, non tutti i provider di identità restituiscono la scadenza del token di aggiornamento. In questi casi il refreshTokenExpirationOffsetSeconds parametro della richiesta non verrà valutato.

Criteri di ricerca cache

Un criterio di ricerca della cache può essere fornito facoltativamente alla richiesta. I criteri di ricerca della cache sono:

  • CacheLookupPolicy.Default - acquireTokenSilent tenterà di recuperare un token di accesso dalla cache. Se il token di accesso è scaduto o non è possibile trovare il token di aggiornamento verrà usato per acquisirne uno nuovo. Infine, se il token di aggiornamento è scaduto, acquireTokenSilent tenterà di acquisire automaticamente un nuovo token di accesso, un token ID e un token di aggiornamento.
  • CacheLookupPolicy.AccessToken - acquireTokenSilent cercherà solo i token di accesso nella cache. Non tenterà di rinnovare i token di accesso o di aggiornamento.
  • CacheLookupPolicy.AccessTokenAndRefreshToken - acquireTokenSilent tenterà di recuperare un token di accesso dalla cache. Se il token di accesso è scaduto o non viene trovato, il token di aggiornamento verrà usato per acquisirne uno nuovo. Se il token di aggiornamento è scaduto, non verrà rinnovato e acquireTokenSilent avrà esito negativo.
  • CacheLookupPolicy.RefreshToken - acquireTokenSilent non tenterà di recuperare i token di accesso dalla cache e tenterà invece di scambiare il token di aggiornamento memorizzato nella cache per un nuovo token di accesso. Se il token di aggiornamento è scaduto, non verrà rinnovato e acquireTokenSilent avrà esito negativo.
  • CacheLookupPolicy.RefreshTokenAndNetwork - acquireTokenSilent non cercherà nella cache il token di accesso. Passerà direttamente alla rete con il token di aggiornamento memorizzato nella cache. Se il token di aggiornamento è scaduto, verrà effettuato un tentativo di rinnovarlo. Equivale all'impostazione forceRefresh: true.
  • CacheLookupPolicy.Skip - acquireTokenSilent tenterà di rinnovare i token di accesso e di aggiornamento. Non cercherà nella cache. Ciò avrà sempre esito negativo se i cookie di terze parti sono bloccati dal browser.

Frammenti di codice

var username = "test@contoso.com";
var currentAccount = msalInstance.getAccount({ username });
var silentRequest = {
    scopes: ["Mail.Read"],
    account: currentAccount,
    forceRefresh: false,
    cacheLookupPolicy: CacheLookupPolicy.Default // will default to CacheLookupPolicy.Default if omitted
};

var request = {
    scopes: ["Mail.Read"],
    loginHint: currentAccount.username // For v1 endpoints, use upn from idToken claims
};

const tokenResponse = await msalInstance.acquireTokenSilent(silentRequest).catch(async (error) => {
    if (error instanceof InteractionRequiredAuthError) {
        // fallback to interaction when silent call fails
        return await msalInstance.acquireTokenPopup(request).catch(error => {
            if (error instanceof InteractionRequiredAuthError) {
                // fallback to interaction when silent call fails
                return msalInstance.acquireTokenRedirect(request)
            }
        });
    }
});

Redirect

var username = "test@contoso.com";
var currentAccount = msalInstance.getAccount({ username });
var silentRequest = {
    scopes: ["Mail.Read"],
    account: currentAccount,
    forceRefresh: false,
    cacheLookupPolicy: CacheLookupPolicy.Default // will default to CacheLookupPolicy.Default if omitted
};

var request = {
    scopes: ["Mail.Read"],
    loginHint: currentAccount.username // For v1 endpoints, use upn from idToken claims
};

const tokenResponse = await msalInstance.acquireTokenSilent(silentRequest).catch(error => {
    if (error instanceof InteractionRequiredAuthError) {
        // fallback to interaction when silent call fails
        return msalInstance.acquireTokenRedirect(request)
    }
});

Operazioni successive

Scopri come effettuare la disconnessione.

  • Last updated on