Orchestration SDKs

Managing sessions and tokens in JavaScript

PingOne Advanced Identity Cloud PingAM JavaScript

After a user successfully authenticates, you can manage their session and associated tokens.

This section covers how to obtain a user object and session token, sign the user out, and manage OpenID Connect (OIDC) tokens, including retrieving, refreshing, and revoking them.

Getting a session token

After successfully navigating a journey and reaching the LoginSuccess node type, you can use the getSessionToken() method to obtain the users' session token.

Getting the session token in JavaScript
let step = await journeyClient.start(); // Initiate the authentication flow

// Handle callbacks in a loop until success or failure
while (step?.type === 'Step') {
  //...
}

if (step?.type === 'LoginSuccess') {
  console.log('Login successful!', step.getSessionToken());
} else if (step?.type === 'LoginFailure') {
  console.error('Login failed:', step.payload.message);
}

The LoginSuccess node type provides functions for obtaining the following properties:

getSessionToken()

The session token string itself.

For example, nlw0pDx5TBk3Rvq7T5tjJYI.*AAJTSQACMDIAAE1TkyMWVhTLABwyajjliTTAydzg9AARWZW9lZU5yd1FeXBlAANDVFMAAlMxIwMQ..*

getSuccessUrl()

The URL a user could be redirected to after authentication, such as their profile page.

For example, /enduser/?realm=/alpha

getRealm()

The realm of the authenticated user.

For example, /alpha

Signing users out

To sign a user out of the server and finish the authentication journey entirely, call the terminate() method on the journeyClient object:

Signing users out on JavaScript
await journeyClient.terminate();

This clears the user’s session, both locally and on the server, and revokes any associated OIDC tokens.

Managing OIDC tokens

If you used the OIDC module alongside the Journey, you can interact with the issued OpenID Connect tokens, such as obtaining data from the user info endpoint, or revoking the access token.

Retrieving an access token

After authenticating a user and obtaining a session token, you can call oidcClient.authorize.background() to start an OAuth 2.0 flow in the background. The response contains a code and state parameter.

Use the oidcClient.token.exchange() method, and pass in the code and state parameters to obtain an OIDC access token on behalf of the user.

You can instead use oidcClient.token.get({backgroundRenew: true}) to perform both steps.

This method returns an existing token if valid, refreshes a token if it has expired, or attempts to fetch a new token if necessary.
Obtaining user info

Use the oidcClient.user.info() method to call the OIDC /oauth2/userinfo endpoint with the access token to retrieve details of the relevant user account.

The response contains values such as first and last name, and other details:

{
  "name": "Babs Jensen",
  "family_name": "Jensen",
  "given_name": "Babs",
  "sub": "a0325ea4-9d9b-4056-931b-ab64704cc3da",
  "subname": "a0325ea4-9d9b-4056-931b-ab64704cc3da"
}
Refreshing an access token

You can ensure an access token is current by using the oidcClient.token.get() method.

This method doesn’t just fetch the token; it also contains the logic to automatically refresh it if needed.

When you call oidcClient.token.get({backgroundRenew: true}), the OIDC client performs these actions:

  1. It retrieves the stored tokens.

  2. It checks if the access token has expired or is within the oauthThreshold (a pre-configured buffer time before expiration).

  3. If the token is still valid, it returns the existing tokens.

  4. If the token is expired (or you use the forceRenew: true option), it automatically initiates a background process to get a new authorization code and exchange it for a new set of tokens.

Revoking an access token

Use the oidcClient.token.revoke(); method to invalidate access and refresh tokens on the server, and delete them from the client app.

This does not affect any session tokens, which remain intact.

You can use the oidcClient.user.logout() method to revoke OIDC tokens, and also the user’s session tokens.

Example

The following code shows how to get an SSO token.

The code then calls methods for obtaining access tokens, getting user info, and signing out:

Managing OpenID Connect tokens in JavaScript
let step = await journeyClient.start(); // Initiate the authentication flow

// Handle callbacks in a loop until success or failure
while (step?.type === 'Step') {
  //...
}

if (step?.type === 'LoginSuccess') {
  // Get session token
  console.log('Login successful!', step.getSessionToken());

  // Start OIDC
  let oidcClient = await oidc({ config });

  const tokens = await oidcClient.token.get({backgroundRenew: true});

  // Get user info
  const user = await oidcClient.user.info();

  // Initiate the logout process
  //  - Revokes OAuth 2.0 access and refresh tokens on the server
  //  - Deletes locally-stored OAuth 2.0 tokens
  //  - Terminates sessions on the server
  //  - Deletes locally-stored session tokens
  oidcClient.user.logout()

} else if (step?.type === 'LoginFailure') {
  console.error('Login failed:', step.payload.message);
}