4.4 Using refresh tokens

You can configure the web.oauth2 authentication server to allow you to extend your authenticated session after obtaining the initial access token using a refresh token.

The process is as follows:

1. Configure the authentication server to allow refresh tokens.

   See section 4.4.1, Configuring the authentication server.

2. Call the authentication /connect/authorize endpoint with a scope that allows refresh tokens.

   See section 4.4.2, Obtaining the authorization code.

3. Call the authentication /connect/token endpoint and receive a refresh token in addition to the access token.

   See section 4.4.3, Obtaining the access and refresh tokens.

4. If the access token has expired, or is close to expiry, call the authentication /connect/token endpoint with the refresh token to obtain a fresh access token and refresh token without having to re-authenticate.

   See section 4.4.4, Using the refresh token to obtain a new access token.

5. Repeat the process of obtaining fresh access tokens and refresh tokens as often as required. You can use a refresh token up until its expiry (by default, after two hours) so if you are continually making calls to the API, and can request a fresh access token and refresh token every two hours, you do not need to authenticate until you hit the limit (by default, six days).

This is the same feature of the authentication server that is used for timeouts and re-authentication for the MyID Operator Client; for information about how this system works, see the Timeouts and re-authentication section in the MyID Operator Client guide.

4.4.1 Configuring the authentication server

You can configure the authentication server for end-user authentication using either PKCE or client secrets; see section 4.1.1, Configuring the authentication service for PKCE or section 4.1.2, Configuring the authentication service for a client secret.

To allow the use of refresh tokens, you must make the following additional configuration changes:

1. In a text editor, open the appsettings.Production.json file for the web service.

   By default, this is:

   C:\Program Files\Intercede\MyID\web.oauth2\appsettings.Production.json

   This file is the override configuration file for the appsettings.json file for the web service. If this file does not already exist, you must create it in the same folder as the appsettings.json file.

2. In the client section for your API client, add the following settings:

   • AllowOfflineAccess – set to true to allow refresh tokens.

   • SlidingRefreshTokenLifetime – the number of seconds within which you can extend the authentication. The default is 7200 (two hours).

   • AbsoluteRefreshTokenLifetime – the number of seconds after which you must re-authenticate, even if you have been continually extending the authentication. The default is 518400 (six days).

   For example:

   Copy

   "Clients":  [
     {
     "ClientId":  "myid.mysystem",
     "ClientName":  "My External System",
     "AllowOfflineAccess":  true,
     "SlidingRefreshTokenLifetime":  7200,
     "AbsoluteRefreshTokenLifetime":  518400,
     ... 

3. Save the configuration file.

4. Recycle the web service app pool:

   1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
   2. Right-click the myid.web.oauth2.pool application pool, then from the pop-up menu click Recycle.

   This ensures that the web service has picked up the changes to the configuration file.

4.4.2 Obtaining the authorization code

You can call the /connect/authorize endpoint to obtain an authorization code using either PKCE or a client secret; see section 4.2.2, Requesting an authorization code (for PKCE) or section 4.3.1, Requesting an authorization code (for client secrets).

When you request the authorization code, instead of requesting a scope of myid.rest.basic, request a scope of:

myid.rest.basic offline_access

This means that when you request an access token using the returned authorization code, it will additionally provide a refresh token.

4.4.3 Obtaining the access and refresh tokens

You can call the /connect/token endpoint to obtain an access token using either PKCE or a client secret; see section 4.2.3, Requesting an access token (for PKCE) or section 4.3.2, Requesting an access token (for client secrets).

If you have configured the authentication server to allow it, and added the offline_access scope to the request for the authorization code, the request returns a block of JSON containing the following:

• access_token – your access token.

• expires_in – the lifetime in seconds for the access token. Determined by the AccessTokenLifetime setting in the web.oauth2 application settings file.

• token_type – always Bearer.

• refresh_token – your refresh token, which will be valid for the number of seconds determined by the SlidingRefreshTokenLifetime setting in the web.oauth2 application settings file.

• scope – myid.rest.basic offline_access.

4.4.4 Using the refresh token to obtain a new access token

If the access token has expired, or is about to expire (which you can determine from the expires_in node of the returned JSON), you can use your refresh token to obtain a fresh access token.

1. Post the following information to the MyID token URL:

   https://<server>/web.oauth2/connect/token

   • client_id – the ID of your system; for example:

     myid.myclient

   • grant_type – set this to refresh_token

   • refresh_token – set this to refresh token you obtained previously.

2. Capture the fresh access_token and refresh_token that are returned in the block of JSON.

   You can now use this access token to call the API, and can use the new refresh token to obtain further access tokens as necessary.

Note: If the old access token has not yet expired, you can continue to use it; requesting a fresh access token does not invalidate the previous one. However, you can use a refresh token only once.

If your access token has expired and your refresh token has expired, or if you have exceeded the limit since the original authorization code was requested (as determined by the AbsoluteRefreshTokenLifetime setting in the web.oauth2 application settings file) you must call /connect/authorize again to re-authenticate.

If the refresh token has expired, or if the AbsoluteRefreshTokenLifetime limit has been exceeded, a response of invalid_grant is returned.