by Tom M.

Introduction

ServiceNow is a cloud platform that manages digital enterprise workflows. The platform provides a lot of tools for custom development in their own application, but it also provides the ability to run external web applications inside their application (in an IFRAME) and interact with the ServiceNow environment through the OpenFrame API. ServiceNow also provides quite a large set of REST API's so external applications can interact with the data.

ServiceNow is an OAuth provider where you can define multiple OAuth clients that are granted access to the environment. Your application can then request an access token with either an "authorization" or "implicit" grant flow.

When retrieving a access token with OAuth the application navigates to the OAuth providers endpoint with some query string parameters. The required query string parameters depend on the grant flow:

Implicit grant
https://{service_now_instance}.service-now.com/oauth_auth.do?response_type=token&redirect_uri={redirect_url}&client_id={client_id}&state={some_app_state_value}

Authorization code
https://{service_now_instance}.service-now.com/oauth_auth.do?response_type=code&redirect_uri={redirect_url}&client_id={client_id}&state={some_app_state_value}

Authorization code with PKCE
https://{service_now_instance}.service-now.com/oauth_auth.do?response_type=code&redirect_uri={redirect_url}&client_id={client_id}&state={some_app_state_value}&code_challenge={some_challenge}&code_challenge_method="S256 or omit the parameter"

When no user is logged on in ServiceNow, a ServiceNow logon screen is shown where the user can enter his credentials. When the provided credentials are valid (or a user is already logged on in ServiceNow), a "grant access" page is shown where the user is notified that the application requests access to ServiceNow. When user presses the "Allow" button, the window redirects to the redirect URL with either the access token in case of an implicit grant flow or an authorization code. An authorization code is short lived and can be used once to request an access and a refresh token.

In case of an authorization code grant flow, the access token can be requested by posting a request with some specific keys in the x-www-form-urlencoded body to:

https://{service_now_instance}.service-now.com/oauth_token.do

The body should contain the following keys:

grant_type: should have the value "authorization_code"
code: the received code from the first request
redirect_uri: the redirect URL that's specified in the OAuth configuration and is equal to the redirect_url specified in the first request
client_id: the client_id that identifies the application which is specified in the OAuth configuration and is equal to the client_id specified in the first request
client_secret: the secret of the application which is specified in the OAuth configuration. This key can be omitted when Authorization Code with PKCE is used.
code_verifier: this key is required when Authorization Code with PKCE is used.

The response contains a JSON string containing the access_token, refresh_token and the expiration duration in seconds among other property.

Setup OAuth

To have access to the OAuth settings, your ServiceNow admin user must temporarily elevate his security permissions. These additional privileges will remain granted until the user logs on again. To elevate your privileges, click your user image in the top/right corner of ServiceNow and select "Elevate role" in the popup menu.

This shows a new popup window where you can grant the "security_admin" privilege to your user. So, check the privilege and press the "Update" button.

Click on the "All" top menu item which opens a side panel to the left which contains all possible options of ServiceNow. At the top of the pane there's a "Filter" input field where limit the huge amount of menu items. Type "OAuth" in the top filter input field and select the "Application Registry" menu item to create a new OAuth client.

The first question that's asked is which type of application you want to create. Select the first option "Create an OAuth API endpoint for external clients".

In the next screen you can start defining your external application.

The "Name" of your application doesn't really matter, it's simply to identify your application later in the settings.
"Client ID" and "Client secret" fields are automatically generated and are later on required to retrieve the access token.
The "Redirect URL" is the location of your application that will receive the authorization code or the access token in case of an implicit grant flow.
"Logo URL" contains the location to the URL that's shown on the ServiceNow "grant access" screen.
When the "Public client" field is checked, then PKCE is enabled. This means that implicit grant is disabled and the authorization code requires the "code_challenge" and "code_verifier" parameters.
The "Refresh Token Lifespan" and "Access Token Lifespan" specify the duration in seconds when the corresponding tokens are valid. When the tokens are expired, the user must grant the application access again.

User permissions

The user must have the permission to grant the application access to ServiceNow. This is done by editing the user and assigning the role "oauth_user" to the user.

CORS

The final step is to grant your application that's running from a different domain access to the REST API's.

Click on the "All" menu item in the top menu bar. In the filter input field, type "CORS" and click on "CORS rules". Next, add a new rule.

This opens the following page.

The rule should have a "Name" which is just a short description of the application.
In the "REST API" dropdown, you determine which REST API can be accessed by the application that's hosted on the specified domain.
"Domain" specifies the base URL of the application that sends the requests to the REST API.
In the "HTTP Methods" section, select the methods your application is allowed to send.