Scope

This document will guide you through the process of configuring an OAuth Connection for your Unifi Integration (ServiceNow to ServiceNow). This will involve making configuration changes in both the identity provider and identity consumer instances. As such, this guide will examine the changes for each instance separately on the subsequent pages.

Approach

In this guide, you will configure an additional OAuth Connection to another ServiceNow instance as part of the Incident Guide Integration (created when following the Bidirectional Asynchronous Incident Guide). The external instance will act as the Identity Provider whilst the original instance will act as the Identity Consumer.

It is assumed that the Integration has been configured, packaged and moved to the external instance (see here for details). Therefore, the Process, Web Service & Integration are already in place (if not, please ensure that at least those elements are in place before continuing).

Create Application Registry

In native ServiceNow, navigate to System OAuth > Application Registry and click New.

On the interceptor page, click Connect to a third party OAuth Provider.

The fields to be configured for the Application Registry record are as follows:

*This value is to be left as-is.

Your Application Registries New Record should look like this:

Right-click and Save to remain on the record.

Configure Connection

In Unifi Integration Designer, navigate to Connections and click New.

The fields to be configured for the New Connection modal are as follows:

Outbound Connectivity

The format of the Endpoint URL is as follows:

https://<your_provider_instance>.service-now.com/<your_provider_process_api>

Your New Connection modal should look like this:

Submit and view to further configure the Connection.

Connection Details

The fields to be configured for the Details form are as follows:

Your Details form should look like this:

Save the Connection.

Get OAuth Token

Once you have saved the Connection, the 'Get OAuth Token' button is available.

Click Get OAuth Token.

On the modal that pops up, enter the Username & Password (for the Inbound user of the Identity Provider Instance).

Click Get OAuth Token.

The 'OAuth token flow completed successfully' info message is displayed. Close the modal.

To future proof your OAuth connection, please consider setting up the OAuth Refresh Token Job.

Create Application Registry

In native ServiceNow, navigate to System OAuth > Application Registry and click New.

On the interceptor page, click Create an OAuth API endpoint for external clients.

The fields to be configured for the Application Registry record are as follows:

*These values are to be left as-is.

Your Application Registries New Record should look like this:

Submit the record.

Configure Connection

In Unifi Integration Designer, navigate to Connections and click New.

The fields to be configured for the New Connection modal are as follows:

Outbound Connectivity

The format of the Endpoint URL is as follows:

https://<your_consumer_instance>.service-now.com/<your_consumer_resource_path>

Your New Connection modal should look like this:

Submit and view to further configure the Connection.

Connection Details

The fields to be configured for the Details form are as follows:

Your Details form should look like this:

Save the Connection.

Next, configure the Identity Consumer Instance.

We recommend customers using outbound OAuth use this scheduled job script to ensure outbound OAuth connections remain alive, as explained in this KB Article from ServiceNow.

Without this job, the refresh token will eventually expire which means ServiceNow will no longer be able to retrieve an access token. This in turn will cause outbound requests to fail.

If your OAuth service is including refresh tokens with each access token request, this job may not be required.

This script has been reformatted from the KB Article for ease of use.

function refreshAccessToken(requestorId, oauthProfileId, token) {
    if (!(token && requestorId && oauthProfileId)) return;

    var tokenRequest = new sn_auth.GlideOAuthClientRequest();
    tokenRequest.setGrantType("refresh_token");
    tokenRequest.setRefreshToken(token.getRefreshToken());
    tokenRequest.setParameter('oauth_requestor_context','sys_rest_message');
    tokenRequest.setParameter('oauth_requestor', requestorId);
    tokenRequest.setParameter('oauth_provider_profile',oauthProfileId);

    var oAuthClient = new  sn_auth.GlideOAuthClient();
    var tokenResponse = oAuthClient.requestTokenByRequest(null,tokenRequest);
    var error = tokenResponse.getErrorMessage();
    if (error) gs.warn("Error:" + tokenResponse.getErrorMessage());
}

function isExpired(expiresIn, withinSeconds) {
    if (expiresIn > withinSeconds) return false;
    return true;
}


function getToken(requestorId, oauthProfileId) {
    if (!requestorId || !oauthProfileId) return null;
    var client = new sn_auth.GlideOAuthClient();
    return client.getToken(requestorId, oauthProfileId);
}

function checkAndRefreshAccessToken(grRestMessage) {
    if (grRestMessage.getValue("authentication_type") != "oauth2") return false;
    var accountMsg = grRestMessage.getValue("name");
    if (!accountMsg)
        accountMsg = grRestMessage.getUniqueValue();
    accountMsg = "Account=\"" + accountMsg + "\"";

    var token = getToken(grRestMessage.getUniqueValue(), grRestMessage.getValue('oauth2_profile'));
    var accessToken = token.getAccessToken();

    if (accessToken) {
        if (!isExpired(token.getExpiresIn(), 300)) return;
    }

    if (!token.getRefreshToken()) {
        gs.error("No OAuth refresh token for Rest Message. Manual reauthorization required. " + accountMsg);
        return;
    }

    if (isExpired(token.getRefreshTokenExpiresIn(), 0)) {
        gs.error("OAuth refresh token for Rest Message is expired. Manual reauthorization required. " + accountMsg);
        return;
    }

    gs.info("Refreshing oauth access token for Rest Message account. " + accountMsg);
    refreshAccessToken(grRestMessage.getUniqueValue(), grRestMessage.getValue('oauth2_profile'), token);
}

var grAccount = new GlideRecord("sys_rest_message");
grAccount.addQuery("authentication_type", "oauth2");
grAccount.addNotNullQuery("oauth2_profile");
grAccount.query();

while (grAccount.next()) {
    checkAndRefreshAccessToken(grAccount);
}