API Authentication Strategy Pattern Guide

intermediateTested on Xanadu

The API Authentication Strategy Pattern provides a structured approach to implementing secure authentication for both inbound and outbound API calls in ServiceNow. This pattern establishes a centralized authentication manager that handles multiple authentication methods including OAuth 2.0, Basic Authentication, and API keys while managing token lifecycle, automatic renewal, and credential rotation.

This pattern solves the common challenge of inconsistent authentication implementation across different integrations, credential sprawl, and lack of centralized token management. It provides a unified interface for different authentication strategies while abstracting the complexity of token refresh, expiration handling, and security logging from individual API implementations.

The pattern works by implementing a strategy pattern where each authentication method is encapsulated in its own class with a common interface. A central authentication manager coordinates between strategies, handles credential storage in encrypted fields, manages token refresh cycles, and provides comprehensive audit logging for security compliance.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Use This When

Use this pattern when your ServiceNow instance has multiple API integrations requiring different authentication methods, when you need centralized management of API credentials and tokens, or when compliance requirements demand detailed audit trails for API authentication events. This pattern is essential for enterprise environments with complex integration landscapes.

Avoid When

Avoid this pattern for simple, single-integration scenarios where basic REST message authentication suffices, or when you have very limited API usage that doesn't justify the overhead of centralized management. Don't use this for internal ServiceNow-to-ServiceNow communications where mutual authentication or certificate-based auth might be more appropriate.

Implementation

Server-side

var APIAuthenticationManager = Class.create();
APIAuthenticationManager.prototype = {
    initialize: function() {
        this.strategies = {
            'oauth': new OAuthStrategy(),
            'basic': new BasicAuthStrategy(),
            'apikey': new APIKeyStrategy()
        };
    },

    authenticate: function(integrationName, authType) {
        var strategy = this.strategies[authType];
        if (!strategy) {
            gs.error('APIAuthManager: Unsupported auth type: ' + authType);
            return null;
        }
        
        var credentials = this._getCredentials(integrationName);
        if (!credentials) {
            gs.error('APIAuthManager: No credentials found for: ' + integrationName);
            return null;
        }
        
        var authResult = strategy.authenticate(credentials);
        this._logAuthEvent(integrationName, authType, authResult.success);
        return authResult;
    },

    _getCredentials: function(integrationName) {
        var gr = new GlideRecord('u_api_credentials');
        gr.addQuery('u_integration_name', integrationName);
        gr.query();
        
        if (gr.next()) {
            return {
                clientId: gr.getDecryptedValue('u_client_id'),
                clientSecret: gr.getDecryptedValue('u_client_secret'),
                tokenUrl: gr.getDisplayValue('u_token_url'),
                apiKey: gr.getDecryptedValue('u_api_key'),
                username: gr.getDecryptedValue('u_username'),
                password: gr.getDecryptedValue('u_password'),
                scope: gr.getDisplayValue('u_scope'),
                accessToken: gr.getDecryptedValue('u_access_token'),
                tokenExpiry: gr.getDisplayValue('u_token_expiry'),
                refreshToken: gr.getDecryptedValue('u_refresh_token')
            };
        }
        return null;
    },

    _logAuthEvent: function(integration, authType, success) {
        var gr = new GlideRecord('u_api_auth_log');
        gr.initialize();
        gr.u_integration_name = integration;
        gr.u_auth_type = authType;
        gr.u_success = success;
        gr.u_timestamp = new GlideDateTime();
        gr.u_user = gs.getUserID();
        gr.u_session = gs.getSessionID();
        gr.insert();
    },

    type: 'APIAuthenticationManager'
};

var OAuthStrategy = Class.create();
OAuthStrategy.prototype = {
    authenticate: function(credentials) {
        // Check if token is valid and not expired
        if (this._isTokenValid(credentials)) {
            return { success: true, token: credentials.accessToken, type: 'bearer' };
        }
        
        // Try refresh token first
        if (credentials.refreshToken) {
            var refreshResult = this._refreshToken(credentials);
            if (refreshResult.success) {
                return refreshResult;
            }
        }
        
        // Fall back to client credentials flow
        return this._getNewToken(credentials);
    },

    _isTokenValid: function(credentials) {
        if (!credentials.accessToken || !credentials.tokenExpiry) {
            return false;
        }
        
        var expiry = new GlideDateTime(credentials.tokenExpiry);
        var now = new GlideDateTime();
        var bufferMinutes = 5; // Refresh 5 minutes before expiry
        
        expiry.addSeconds(-bufferMinutes * 60);
        return now.before(expiry);
    },

    _refreshToken: function(credentials) {
        try {
            var request = new sn_ws.RESTMessageV2();
            request.setEndpoint(credentials.tokenUrl);
            request.setHttpMethod('POST');
            request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
            
            var body = 'grant_type=refresh_token&refresh_token=' + encodeURIComponent(credentials.refreshToken) +
                      '&client_id=' + encodeURIComponent(credentials.clientId) +
                      '&client_secret=' + encodeURIComponent(credentials.clientSecret);
            request.setRequestBody(body);
            
            var response = request.execute();
            var responseBody = response.getBody();
            var tokenData = JSON.parse(responseBody);
            
            if (response.getStatusCode() == 200 && tokenData.access_token) {
                this._updateStoredToken(credentials, tokenData);
                return { success: true, token: tokenData.access_token, type: 'bearer' };
            }
            
            gs.warn('OAuth refresh failed: ' + responseBody);
            return { success: false, error: 'Token refresh failed' };
        } catch (ex) {
            gs.error('OAuth refresh error: ' + ex.message);
            return { success: false, error: ex.message };
        }
    },

    _getNewToken: function(credentials) {
        try {
            var request = new sn_ws.RESTMessageV2();
            request.setEndpoint(credentials.tokenUrl);
            request.setHttpMethod('POST');
            request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
            
            var body = 'grant_type=client_credentials&client_id=' + encodeURIComponent(credentials.clientId) +
                      '&client_secret=' + encodeURIComponent(credentials.clientSecret);
            if (credentials.scope) {
                body += '&scope=' + encodeURIComponent(credentials.scope);
            }
            request.setRequestBody(body);
            
            var response = request.execute();
            var responseBody = response.getBody();
            var tokenData = JSON.parse(responseBody);
            
            if (response.getStatusCode() == 200 && tokenData.access_token) {
                this._updateStoredToken(credentials, tokenData);
                return { success: true, token: tokenData.access_token, type: 'bearer' };
            }
            
            gs.error('OAuth token request failed: ' + responseBody);
            return { success: false, error: 'Token request failed' };
        } catch (ex) {
            gs.error('OAuth token error: ' + ex.message);
            return { success: false, error: ex.message };
        }
    },

    _updateStoredToken: function(credentials, tokenData) {
        var gr = new GlideRecord('u_api_credentials');
        gr.addQuery('u_integration_name', credentials.integrationName);
        gr.query();
        
        if (gr.next()) {
            gr.setValue('u_access_token', tokenData.access_token);
            if (tokenData.refresh_token) {
                gr.setValue('u_refresh_token', tokenData.refresh_token);
            }
            
            var expiry = new GlideDateTime();
            expiry.addSeconds(tokenData.expires_in || 3600);
            gr.setValue('u_token_expiry', expiry);
            gr.update();
        }
    },

    type: 'OAuthStrategy'
};

var BasicAuthStrategy = Class.create();
BasicAuthStrategy.prototype = {
    authenticate: function(credentials) {
        if (!credentials.username || !credentials.password) {
            return { success: false, error: 'Missing username or password' };
        }
        
        var encoded = GlideStringUtil.base64Encode(credentials.username + ':' + credentials.password);
        return { success: true, token: encoded, type: 'basic' };
    },
    
    type: 'BasicAuthStrategy'
};

var APIKeyStrategy = Class.create();
APIKeyStrategy.prototype = {
    authenticate: function(credentials) {
        if (!credentials.apiKey) {
            return { success: false, error: 'Missing API key' };
        }
        
        return { success: true, token: credentials.apiKey, type: 'apikey' };
    },
    
    type: 'APIKeyStrategy'
};

The code implements a strategy pattern with a central APIAuthenticationManager that coordinates different authentication strategies (OAuth, Basic Auth, API Key). Each strategy handles its specific authentication logic while the manager provides unified credential storage, automatic token refresh for OAuth, and comprehensive audit logging. The OAuth strategy includes intelligent token lifecycle management with automatic refresh before expiration and fallback to new token acquisition.

Alternatives

ServiceNow Application Registry with OAuth

Uses built-in ServiceNow OAuth capabilities through Application Registry for standardized OAuth flows. Simpler to configure but less flexible for custom authentication schemes and limited to OAuth 2.0 patterns supported by ServiceNow.

REST Message Authentication Profiles

Leverages ServiceNow's native REST message authentication profiles for simpler credential management. Good for basic scenarios but lacks centralized lifecycle management, custom audit logging, and advanced token refresh strategies.

Credential Store with Custom Wrapper

Uses ServiceNow's credential store (Discovery Credentials table) with a lightweight wrapper script include. Provides good security with less complexity but requires more manual token management and lacks sophisticated refresh logic.

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue