Refresh token expiration - SSO

Refresh Token Expiration Policy

Expiration of refresh tokens can be configured by creating an expiration policy with an expiration time, either with Management UI or SSO API.

The expiration policy determines whether the refresh token’s lifespan is counted from the creation time or from the authentication time.

The expiration time specifies how long the refresh token remains valid, according to the selected expiration policy.

The policy types are as follows:

• none – the default; there is no policy, which means refresh token never expire, they can only be revoked manually

• fixed – refresh tokens are valid for a specified time after the creation time

• dynamic – refresh tokens are valid for a specified time after the authentication time

  • Correction from: was this was incorrectly stated previously as: “last login time”.

Configuring the Refresh Token Policy in Management UI

1. Go to the site you want to create the Refresh Token Policy to.
   Click Mappings tab.
   Click Create new mapping.
   Fill in the name, and choose OAuth Refresh Token in the NameID Format field.
   Click Ok.
   
   

   Open

   

   Creation of a Refresh Token Policy.

    

2. In the Mappings tab of the newly created refresh token policy, you can configure the expiration in the Refresh Token Expiration Policy section.
   Choose the desired policy type and expiration time.
   
   

   Open

   

   Configuration of policy type and expiration time for a Refresh Token Policy.

    

3. Link this refresh token mapping to applications, by clicking Applications tab.
   Click Add… and choose the desired application.
   Click Ok.
   
   

   Open

   

   Linking an Application to a Refresh Token Policy.

    

4. With this configuration, any refresh token issued for this application will be valid according to the specified refresh token policy.
   
   

Configuring the Refresh Token Policy with SSO API

1. Create a refresh token policy by calling the refreshTokenPolicy endpoint on the site you wish to create it on.
   The expiration policy type and time are configured through the configuration parameter:

   configuration=expirationPolicy fixed configuration=expirationTime 10

   Example request:

   PUT /sso-api/refreshTokenPolicy/System/refreshTokenPolicyAPI Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: Bearer ... name=refreshTokenPolicyAPI&configuration=expirationPolicy%20fixed&configuration=expirationTime%2010

   Example response:

   { "type": "refreshTokenPolicy", "id": "/refreshTokenPolicy/System/refreshTokenPolicyAPI", "attributes": { "name": "refreshTokenPolicyAPI", "configuration": [ "expirationTime 10", "expirationPolicy fixed" ] } }

2. Link the policy to an application.
   Example request:

   PUT /sso-api/refreshTokenPolicy/System/refreshTokenPolicyAPI/$link/application/System/SampleApp Accept: application/json Authorization: Bearer ...

   Example response:

   { "type": "refreshTokenPolicy", "id": "/refreshTokenPolicy/System/refreshTokenPolicyAPI", "objects": [ { "type": "application", "id": "/application/System/SampleApp", "link": "application" } ] }

3. With this configuration any refresh token issued for this application will be valid according to the specified refresh token policy.

See Management API - SSO for more information.

Refresh Token Introspection

Information about a refresh token can be obtained by using the introspection endpoint /uas/oauth2/introspection.
Example request:

Example response for a valid refresh token:

The exp claims represents the expiration time according to the specified policy:

• for fixed policy it is calculated from issue time: iat + expiration time

• for dynamic policy it is calculated from last logon time: auth_time + expiration time

If the expiration time has already passed, the refresh token will be invalidated and removed from the database.

Example response for an invalid, expired or removed token:

See Authorization code grant and native applications - SSO for more information about introspection.

Refresh Token Cleaner Service

Expired tokens are only removed if they are invalid upon introspection call.

Otherwise, there is a scheduled cleaner service that can be configured to run periodically to clean the database from expired tokens.

By default the service is set to run every day at 01.00. This setting can be changed by adding a com.ubisecure.ubilogin.uas.refresh-token.cleaner.scheduling property to uas.properties.

For example:

Refresh Token Cleanup Lock

Additionally to the cleaning service, a cleanup lock can be configured, which prevents two or more SSO nodes from performing the cleanup at the same time.

The configuration parameters for the cleanup lock are:

• cleanupLockEnabled

  • If set to true, SSO checks that it is able to obtain a lock before performing the refresh token cleanup.

  • If set to false, SSO doesn’t check for a lock before performing the refresh token cleanup.

  • Default: false

• cleanupLockCheckWait

  • The time (in seconds) how long an SSO node waits before starting refresh token cleanup to check if it was able to obtain lock successfully. This is to control the race condition of two or more nodes from trying to obtain the lock at same time.

  • Default: 10

• cleanupLockTimeout

  • The time (in seconds) after which a lock can be forcefully released and given to another SSO node. That’s to mitigate the possibility that a lock is left active in case of an unexpected error by allowing active SSO nodes to obtain a lock even if one already exists, provided that the age of the existing lock is older than the value specified for this parameter.

  • Default: 600

To enable the cleanup lock or change its settings, modify the desired refresh token policy with the configuration parameter:

Example response:

Remember that while the lock is configured per refresh token policy, the cleanup service will run periodically for all existing refresh token policies.