Tempo de vida do token, expiração e renovação

Antes de começar aqui, certifique-se de entender como fazer logon e adquirir tokens.

Ao usar MSAL.js, você deve entender as implicações da recuperação de tokens para os usuários e como gerenciar o tempo de vida desses tokens.

Tempo de vida e expiração do token

Você pode configurar o tempo de vida dos tokens de acesso, de ID ou SAML (Security Assertion Markup Language) emitidos pela plataforma de identidade da Microsoft. Algumas das informações são resumidas abaixo.

Tokens de ID

Os tokens de ID são associados a uma combinação específica de conta e cliente e geralmente contêm informações de perfil sobre o usuário. Normalmente, o tempo de vida da sessão do usuário de um aplicativo Web corresponderá ao do tempo de vida da sessão do token de ID, que é por padrão 24 horas. Você pode ler mais sobre como configurar tempos de vida de token.

Tokens de acesso

Os tokens de acesso no navegador têm uma expiração recomendada padrão de 1 hora. Após esta 1 hora, todas as chamadas de portador com o token expirado serão rejeitadas. Esse token pode ser atualizado silenciosamente usando o token de atualização recuperado com esse token. Você pode ler mais sobre como configurar tempos de vida de token.

Tokens de atualização

Os tokens de atualização fornecidos a aplicativos de página única são tokens de atualização com tempo de validade limitado (geralmente 24 horas a partir do momento em que são obtidos). Esta é uma janela fixa, não ajustável e não corrediça, para toda a vida. Sempre que um token de atualização é usado para renovar um token de acesso, um novo token de atualização é buscado com o token de acesso renovado. Esse novo token de atualização terá um tempo de vida igual ao tempo de vida restante do token de atualização original. Depois que um token de atualização tiver expirado, um novo fluxo de código de autorização deverá ser iniciado para recuperar um código de autorização e trocá-lo por um novo conjunto de tokens.

Observação: quando um novo token de atualização é obtido, msal.js substitui o token de atualização armazenado em cache pelo novo token de atualização, no entanto, o token de atualização antigo não é invalidado pelo servidor e ainda pode ser usado para obter tokens de acesso até sua expiração.

Renovação de token

O PublicClientApplication objeto expõe uma API chamada acquireTokenSilent que deve recuperar o token não expirado silenciosamente. Ele faz isso em algumas etapas:

  1. Verifique se já existe um token no cache de token para o determinado scopes, client ide authority/ou homeAccountIdentifier.
  2. Se houver um token para os parâmetros fornecidos, garanta que haja uma única correspondência e verifique se ele expirou.
  3. Se o token de acesso não tiver expirado, a MSAL retornará uma resposta com os tokens relevantes.
  4. Se o token de acesso tiver expirado, mas o token de atualização ainda for válido, a MSAL usará o token de atualização fornecido para recuperar um novo conjunto de tokens e retornará uma resposta.
  5. Se o token de atualização tiver expirado, a MSAL tentará recuperar os tokens de acesso silenciosamente usando um iframe oculto. Isso usará o sid ou o nome de usuário no objeto de declarações da conta para obter uma indicação sobre a sessão do usuário. Se essa chamada de iframe oculto falhar, a MSAL repassará um erro do servidor na forma de InteractionRequiredAuthError, solicitando a obtenção de um código de autorização para obter um novo conjunto de tokens. Você pode fazer isso fazendo uma chamada à API de login ou acquireToken com o objeto PublicClientApplication. Se a sessão ainda estiver ativa, o servidor enviará um código sem solicitações de usuário. Caso contrário, o usuário será obrigado a inserir suas credenciais.

Consulte o artigo de objetos de solicitação e resposta para obter mais informações sobre quais parâmetros de configuração você pode definir para o acquireTokenSilent método.

Evitando interrupções interativas no meio da sessão de um usuário

Em alguns casos, talvez você queira invocar preventivamente a interação, se necessário, no início da sessão de um usuário para garantir que ele possa continuar a adquirir tokens silenciosamente e usar seu aplicativo sem interrupções adicionais. É claro que você pode fazer isso invocando a interação sempre que seu aplicativo é carregado pela primeira vez, isso é, no entanto, uma experiência de usuário ruim e menos desempenho quando um usuário já tem tokens de uma sessão anterior ou outra janela/guia. Em vez disso, com alguns parâmetros de solicitação, você pode usar acquireTokenSilent para garantir que o cache tenha os tokens necessários disponíveis para retornar silenciosamente por algum período arbitrário de tempo.

Para garantir que acquireTokenSilent possa retornar tokens válidos por pelo menos 1 hora:

  • Chamar acquireTokenSilent ao carregar a página com o parâmetro da solicitação forceRefresh definido como true. Isso ignorará o cache e obterá um novo token, que depois poderá ser recuperado do cache em chamadas subsequentes.
  • Em chamadas subsequentes, deixe forceRefresh sem definir ou defina-o explicitamente como false para garantir que os tokens possam ser fornecidos pelo cache

Para garantir que acquireTokenSilent possa retornar tokens válidos por no mínimo qualquer período de tempo de até 24 horas:

  • Chamar acquireTokenSilent no carregamento da página com o parâmetro de solicitação forceRefresh definido como true & o parâmetro refreshTokenExpirationOffsetSeconds definido como o tempo desejado (em segundos) sem interação
  • Em chamadas subsequentes, deixe forceRefresh e refreshTokenExpirationOffsetSeconds não definidos para garantir que os tokens possam ser fornecidos a partir do cache

Por exemplo, se você quiser garantir que o usuário possa adquirir tokens silenciosamente pelas próximas 2 horas:

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);
    }
});

Observação: nunca há uma garantia de que um token possa ser adquirido silenciosamente mesmo que o token de atualização ainda não tenha expirado. Os padrões descritos acima são as melhores tentativas de esforço para minimizar a interação em momentos inconvenientes, mas não eliminarão a possibilidade de interações necessárias dentro dos quadros de tempo desejados. Além disso, nem todos os provedores de identidade retornam a expiração do token de atualização. Nesses casos, o refreshTokenExpirationOffsetSeconds parâmetro de solicitação não será avaliado.

Política de Pesquisa de Cache

Opcionalmente, uma Política de Pesquisa de Cache pode ser fornecida à solicitação. As Políticas de Pesquisa de Cache são:

  • CacheLookupPolicy.Default - acquireTokenSilent tentará recuperar um token de acesso do cache. Se o token de acesso tiver expirado ou não puder ser encontrado, o token de atualização será usado para adquirir um novo. Por fim, se o token de atualização tiver expirado, acquireTokenSilent tentará adquirir silenciosamente um novo token de acesso, um token de ID e um token de atualização.
  • CacheLookupPolicy.AccessToken - acquireTokenSilent procurará apenas tokens de acesso no cache. Ele não tentará renovar o acesso ou atualizar tokens.
  • CacheLookupPolicy.AccessTokenAndRefreshToken - acquireTokenSilent tentará recuperar um token de acesso do cache. Se o token de acesso tiver expirado ou não puder ser encontrado, o token de atualização será usado para adquirir um novo. Se o token de atualização tiver expirado, ele não será renovado e acquireTokenSilent falhará.
  • CacheLookupPolicy.RefreshToken - acquireTokenSilent não tentará recuperar tokens de acesso do cache e, em vez disso, tentará trocar o token de atualização armazenado em cache por um novo token de acesso. Se o token de atualização tiver expirado, ele não será renovado e acquireTokenSilent falhará.
  • CacheLookupPolicy.RefreshTokenAndNetwork - acquireTokenSilent não procurará no cache o token de acesso. Ele irá diretamente para a rede com o token de atualização armazenado em cache. Se o token de atualização tiver expirado, será feita uma tentativa de renová-lo. Isso é equivalente à configuração forceRefresh: true.
  • CacheLookupPolicy.Skip - acquireTokenSilent tentará renovar o acesso e atualizar tokens. Ele não será exibido no cache. Isso sempre falhará se cookies de terceiros forem bloqueados pelo navegador.

Trechos de código

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)
            }
        });
    }
});

Redirecionar

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)
    }
});

Próximas etapas

Saiba como fazer log out.

  • Last updated on