ServiceNow OAuth 2.0 Setup Guide

Architecture Overview

Implementation Steps

var rm = new RESTMessageV2('Your_REST_Message_Name', 'get');
rm.setStringParameterNoEscape('endpoint', 'https://api.external-system.com/data');
try {
    var response = rm.execute();
    var httpStatus = response.getStatusCode();
    if (httpStatus == 200) {
        var responseBody = response.getBody();
        var jsonResponse = JSON.parse(responseBody);
        gs.info('OAuth API call successful: ' + jsonResponse);
    } else if (httpStatus == 401) {
        gs.error('OAuth token may be expired, automatic refresh should occur on retry');
    }
} catch (ex) {
    gs.error('OAuth REST call failed: ' + ex.getMessage());
}

// Test OAuth token validation in a Scripted REST API
(function process(request, response) {
    var token = request.getHeader('Authorization');
    if (!token || !token.startsWith('Bearer ')) {
        response.setStatus(401);
        response.getWriter().write('Missing or invalid OAuth token');
        return;
    }
    
    var accessToken = token.substring(7); // Remove 'Bearer '
    var tokenGR = new GlideRecord('oauth_token');
    tokenGR.addQuery('access_token', accessToken);
    tokenGR.query();
    
    if (tokenGR.next() && tokenGR.expires > gs.nowDateTime()) {
        response.setStatus(200);
        response.getWriter().write('Valid OAuth token');
    } else {
        response.setStatus(401);
        response.getWriter().write('Expired or invalid OAuth token');
    }
})(request, response);

Common Use Cases

Troubleshooting

Pro Tips

• →Implement OAuth token caching strategies by creating custom Script Includes that check token expiration before making REST calls, reducing unnecessary token refresh requests and improving API performance. Store frequently accessed tokens in GlideRecord queries with indexed fields for faster retrieval during high-volume integrations.
• →Configure OAuth scope restrictions at the table level using Access Control Lists (ACLs) to ensure external OAuth clients can only access specific ServiceNow data they need, following the principle of least privilege. Create custom scopes for different integration patterns and map them to specific table operations for granular security control.
• →Use ServiceNow's OAuth audit capabilities by enabling OAuth-specific logging sources and creating custom reports on the oauth_token and oauth_entity_profile tables to monitor token usage patterns, identify potential security issues, and track integration performance metrics over time.
• →Implement circuit breaker patterns in your OAuth REST integrations by tracking consecutive failures and temporarily disabling OAuth calls when external systems are unavailable, preventing cascading failures and reducing unnecessary token refresh attempts during system outages.
• →Leverage ServiceNow's OAuth 2.0 PKCE support for mobile and single-page applications by configuring the OAuth Entity with PKCE enabled, providing enhanced security for public OAuth clients that cannot securely store client secrets.
• →Create reusable OAuth configuration templates using Update Sets that include pre-configured OAuth Entities, Providers, and Connection Aliases for common integration patterns, enabling faster deployment across multiple ServiceNow instances and maintaining consistent security configurations.

Known Limitations

• —ServiceNow's OAuth 2.0 implementation has a maximum token lifetime of 7200 seconds (2 hours) for access tokens and 31,536,000 seconds (1 year) for refresh tokens, which may not align with some external systems' security requirements. Custom token lifetime configurations require careful consideration of security policies and integration reliability needs.
• —OAuth token storage in ServiceNow is limited to 1000 active tokens per OAuth Entity by default, which can cause issues in high-volume integrations with multiple concurrent users or service accounts. Monitor token usage patterns and implement token cleanup jobs to prevent hitting these limits in production environments.
• —The OAuth 2.0 Device Authorization Grant (RFC 8628) flow is not natively supported in ServiceNow, limiting integration options for IoT devices and command-line applications that cannot display web-based authorization interfaces. Custom implementations may be required for these specific use cases using Scripted REST APIs and custom token management.
• —ServiceNow's OAuth JWT validation only supports RSA and HMAC signing algorithms, with limited support for newer algorithms like EdDSA or elliptic curve signatures. This may require coordination with external OAuth providers to ensure compatible signing methods are used for token validation.
• —Cross-domain OAuth redirects may face browser security restrictions with modern CORS policies and SameSite cookie settings, potentially affecting OAuth authorization flows for applications hosted on different domains than the ServiceNow instance. Additional configuration may be required for third-party OAuth integrations.

Frequently Asked Questions