Refresh Tokens

Configure and use refresh tokens to get long-lived, secure sessions in your app.

Configuring Refresh Tokens

Refresh tokens are disabled by default. To enable this functionality visit Authentication → Session Management in the Passage Console. From there, choose your session timeouts.

• The auth token lifetime should be short when enabling refresh tokens, from seconds to about 10 minutes.

• The absolute expiration corresponds to the expiration of a refresh token and should be the maximum session length that you want to enforce.

• The inactivity timeout will expire refresh tokens of users who have been inactive on your site for the specified period of time, so users will be required to re-authenticate on next visit.

Using Refresh Tokens in Your Frontend

See PassageUser Class for the full list of functionality exposed in the passage-auth NPM package.

Once refresh tokens are enabled, future login requests will include a refresh_token and refresh_token_expiration parameters in the AuthResult. If you are using a Passage Element, this will be transparent to you and Passage will automatically store the refresh token in local storage to be used when needed. You can also use the onSuccess callback to store the refresh token in a custom location.

You only want to use refresh tokens when an auth token is expired. You should NOT refresh the token on every API request. You should use the getAuthToken() method on the PassageUser class to get the correct auth token to send to your application. The method checks if the auth token is expired, & tries to refresh it silently as needed. It's a promise because the potential refresh is a network request.

import axios from 'axios';
import { PassageUser } from '@passageidentity/passage-elements/passage-user';

const user = new PassageUser();

user.getAuthToken().then((authToken) =>
    axios.get(`${API_URL}/${PATH}`, {
        headers: {
            Authorization: `Bearer ${authToken}`,
        },
    }),
);

When a user logs out of your application, call user.signOut() to revoke the refresh token for the current session.

Backend SDK Support

All of our backend SDKs have support for revoking user sessions. This can be helpful in the event that you think a user's account may have been compromised or if they choose to close their account with you. This function will revoke ALL refresh tokens for a user.

Node.js

user.SignOut()

Go

psg, err := passage.New(PassageAppID, &passage.Config{
    APIKey: PassageApiKey, 
})
psg.SignOut(userID)

Python

psg = Passage(PASSAGE_APP_ID, PASSAGE_API_KEY)
success = psg.revokeUserRefreshTokens(user_id)

Ruby

require 'passageidentity'

class ApplicationController < ActionController::Base
    PassageClient = Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY)

  def authorize!
    begin
      revoke = PassageClient.auth.revoke_user_refresh_tokens(USER_ID)
    rescue Exception => e
      # handle exception (user is not authorized)
      # unauthorized
      redirect_to "/unauthorized"
    end
  end
end

Deactivating a user via the Console or the backend SDKs with also revoke all refresh tokens for the user.