OAuth2 Token Refresh - Support and Troubleshooting

OAuth2 Token Refresh Issue A common issue with an OAuth2 application is regarding token expiration and renewal. In this example, we will use the OAuth Email Account configured using Entra ID (Microsoft) as the third-party OAuth provider for reference purpose.

TL;DR : ServiceNow will always update the existing Access & Refresh Tokens with the ones received in the response from the OAuth provider (ServiceNow or Third Party) for the token refresh request. If the OAuth provider sends the existing Refresh Token in the response, the expiration date of the Refresh Token will be extended inadvertently. This issue has been addressed in Yokohama where a new field Extend Refresh Token Expiry is added to the OAuth Entity table. For a grant type of "refresh_token", the expiration date on the Refresh Token is only extended if this field is set to true.

In OAuth flow, we primarily use two types of token:

Access Token - Enables clients to securely call protected web APIs to get access to specific resources [ more information ]. Refresh Token - Is used to obtain new access and refresh token pairs when the current access token expires. [ more information ] Received tokens are maintained in OAuth Credentials [oauth_credential] table and can be linked back to the app using " oauth_requestor_profile " field.

Token lifespan

For Access Tokens , the default lifespan is a value ranging between 60-90 minutes. An Access Token is generally just a JWT and contains information about an entity in the form of claims. These include scopes and expiration date amongst others. Please refer to KB2071947 for more information.

Refresh Tokens , on the other hand, have a much longer lifespan - usually 90 days. The default value of Refresh Token Lifespan (" refresh_token_lifespan ") in OAuth Entity [oauth_entity] record is 100 days (86,40,000 seconds). This value should be adjusted as per the Refresh Token lifetime policy of the OAuth provider (e.g. 90 days for Entra ID). This is important because, unlike Access Token , Refresh Token can only be decoded by the OAuth provider, i.e. Entra ID. The client, ServiceNow, cannot retrieve the expiration date from the Refresh Token and can only use it to refresh the tokens.

Note : Lifespan of tokens is set by the OAuth Provider (i.e. Entra ID in our example) and can only be configured at the provider's end. For more information, refer to Configurable token lifetimes in the Microsoft identity platform .

Token renewal

In reference to our example, ServiceNow provides Refresh Email Access Token Schedule [sys_trigger.do?sys_id=c01b8a732b7ca210c286f216d891bffc] job out of the box, which runs every 3 minutes. This job invokes Scheduled Script Execution Refresh Email Access Token [sysauto_script.do?sys_id=35faf162eb233100469a20425206fedc] and subsequently EmailOAuthHelper Script Include [sys_script_include.do?sys_id=52d69ceaeb233100469a20425206feb6].

Here, it checks if the Access Token is expired and calls the GlideOAuthClient - requestTokenByRequest API to refresh the tokens. This can be verified by searching for " Refreshing oauth access token for email " in the [syslog] table:

When the Access Token refresh request is sent, the OAuth provider generally sends back the Refresh Token along with the new Access Token in the response. Depending on the OAuth provider, the received Request Token can be a new one with an extended expiration date or an existing one. For example, ServiceNow, as an OAuth provider, sends back the existing Refresh Token . However, Entra ID, in our example, sends a new one with an extended expiration date with every request.

This can be verified by adding a few logging statements in EmailOAuthHelper Script Include [sys_script_include.do?sys_id=52d69ceaeb233100469a20425206feb6] as below:

And we can compare the received Refresh Token in the log with the existing one:

ServiceNow will always update the existing Access & Refresh Tokens with the ones received in the response from the OAuth provider (ServiceNow or Third Party) . The issue arises if the received Refresh Token is the one that already exists in the instance, but the expiration date is inadvertently extended by calculating the time since the Refresh Token was received/updated, plus the configured lifespan. This issue is also explained in KB1649654 .

Release Yokohama

Resolution Prior to Yokohama, the expiration date of the received Refresh Token is extended regardless of the grant type.

Starting in Yokohama, a new Boolean field Extend Refresh Token Expiry " extend_refresh_token_expiry " has been added to the OAuth Entity [oauth_entity] record, which is set to false by default [sys_dictionary.do?sys_id=8171982b9820221055904c91e2b65469%26sysparm_view=oauth_provider].

The Refresh Token expiration date will only be extended if this field is set to true, OR if the grant type is other than "refresh_token ." In our example, the grant type is "refresh_token. " Hence, we need to set Extend Refresh Token Expiry to true to extend the Refresh Token expiration date since we receive a new Refresh Token from Entra ID with every request.

Note : This field is not visible in the form by default and must be configured in order to add it to the layout.

Related Links OAuth Client (consumer) refresh token expiry should not get updated Obtain Okta Access and Refresh Token automatically using fix script GlideOAuthClient - Scoped, Global