Fixing the Refresh Token Issue in ServiceNow OAuth Integrations

OAuth is a well-established authentication method, widely used when developing integrations. However, a subtle issue in ServiceNow’s OAuth implementation can cause integrations between ServiceNow instances to fail intermittently.

Understanding the Problem

When using OAuth for authentication, two tokens are typically issued:

• Access Token: A short-lived token used to access resources on the target system.
• Refresh Token: A long-lived token used to obtain a new access token when the previous one expires.

The problem arises specifically in the refresh token process within ServiceNow. According to the OAuth specification, when a refresh token is used with the refresh_token grant type, the OAuth server should return a new access token and, optionally, a new refresh token if the refresh token is renewed.

However, ServiceNow’s OAuth server returns the same refresh token instead of issuing a new one. While this might seem insignificant, it leads to a major issue: the client instance assumes that the refresh token’s expiration has been extended when, in reality, it remains unchanged.

The Consequence

Over time, the client instance will store a refresh token it believes is still valid, when in fact, it has expired. This results in failed authentication requests and broken integrations, often without an immediately obvious cause.

The Solution: Preventing the Misleading Refresh Token Update

Fortunately, ServiceNow provides a way to control this behavior. By leveraging the OAuth API Script field in the Application Registry (oauth_entity), we can prevent the client instance from incorrectly extending the refresh token’s validity.

Implementation Steps

1. Create a New Script Include
   • The Script Include name must start with OAuth.
   • Extend the out-of-the-box OAuthUtil Script Include.
2. Reference the Script Include in the Application Registry Record
   • This ensures the custom logic is applied when handling OAuth token responses.

Here’s an example script you can implement:

var OAuthCustomUtil = Class.create();
OAuthCustomUtil.prototype = Object.extendsObject(global.OAuthUtil, {
	
	postprocessAccessToken: function(accessTokenResponse) {
		var contentType = accessTokenResponse.getContentType();
		
		if (contentType && contentType.indexOf('application/json') != -1) {
			var tokenResponse = (new global.JSON()).decode(accessTokenResponse.getBody());
			var paramMap = accessTokenResponse.getparameters();
			for (param in tokenResponse) {
				if(param == 'refresh_token' && this.oauthContext.getQueryParameter('grant_type') == 'refresh_token') {
					continue; // it's not possible to get a new refresh token when refresh_token is the grant_type, however the ServiceNow OAuth implementation insists on sending this when using the refresh_token grant type. If we were to allow this to be added to the paramMap below, the expiry date of the already existing refresh token stored in this instance would be extended, when in reality it has not been extended
				}
				paramMap.put(param, tokenResponse[param].toString());
			}
		}
	},

    type: 'OAuthCustomUtil'
});

By implementing this fix, the client instance will no longer store an outdated refresh token, preventing unexpected authentication failures.

Conclusion

While ServiceNow’s OAuth implementation generally works well, this refresh token behaviour can cause significant issues in long-running integrations. By applying this simple OAuth API Script fix, you can ensure your integrations remain stable and avoid unexpected authentication failures. Now it’s up to you to put something in place that will notify you when a refresh token is due to expire, so that you can come in and get a new one.

If you’re working with OAuth-based integrations in ServiceNow, be sure to test your implementation thoroughly and consider applying this fix to avoid potential disruptions.