Purpose

ServiceNow exposes a REST API for inbound integrations and requires setting up an authentication schema within a ServiceNow Instance to allow client applications to use the API (such as Vanta in this case).

This document provides a step-by-step guide to configure your ServiceNow instance properly and connect it to Vanta.

Pre-requisites

This document assumes that you already have a Tokyo Release ServiceNow Instance assigned and working, and that you also have the OAuth plugin activated in your instance (You can enable it by following the steps mentioned in this document: https://docs.servicenow.com/bundle/tokyo-platform-security/page/administer/security/task/t_ActivateOAuth.html).

Required Steps

Create An OAuth Application

ServiceNow allows setting up Basic Authentication or creating an OAuth Endpoint in your instance to allow Vanta to access the API.

Since it’s more secure to set up an OAuth Endpoint, we’ll explain how to create one for Vanta in ServiceNow.

From your ServiceNow Development Dashboard, go to All > System OAuth > Application Registry tab and click on it.

It will redirect you to a list of all your OAuth endpoints, where you’ll be able to create a new OAuth endpoint by clicking on the New button.

Before setting up your new OAuth Endpoint, pick the Create an OAuth API endpoint for external clients options from the new prompt.

A new screen to configure your new OAuth endpoint will appear. You can fill most of it as you want, making sure you set the Redirect URL to the https://api.vanta.com/auth/o/callback/servicenow/oauth_redirect.do URL.

That should generate the OAuth Endpoint correctly, with the Client ID and Secret you need to link ServiceNow to Vanta.

The other input you need is your the name of your ServiceNow Instance, which can be found in the URL of your Development Dashboard, since all ServiceNow instances follow the next naming convention for them: https://<INSTANCE NAME>.service-now.com, where the <INSTANCE NAME> in your Dashboard's URL your ServiceNow Instance Name.

With that info, you can finally link your ServiceNow Instance to Vanta by passing your Instance Name and your OAuth Endpoint credentials:

Optional Steps

Even though the previous steps are good enough to get the ServiceNow integration to work, ServiceNow doesn't set any API restriction nor scoping for their instances by default.

Instead, it provides the REST API Access Policies feature to restrict access to its API. It’s divided in mechanisms, but these are what we think they’re appropriate for the ServiceNow Integration:

1. Authentication Profile: defines an authentication method and a set of authentication policies
2. Access Policy: restricts API access through a given authentication profile
3. Auth Scope: defines permission scopes for an API

At Vanta, we recommend setting up these features in your ServiceNow Instance because they’ll restrict your API to the core endpoints Vanta needs, but in addition that it’s not necessary for the integration to work, it takes a lot of effort to set up properly and might conflict with any other configuration you may have in your ServiceNow Instance, so that’s why these steps are optional.

Nevertheless, we explain how to set up the ServiceNow Instance properly below if you’re interested in it.

Create An Authentication Profile

Creating an Authentication Profile allows you to define an authentication method for your ServiceNow Instance.

Previously, we defined an OAuth Endpoint for the integration, so we’ll want to set up an Authentication Profile that only authenticates clients through OAuth.

To do that, go to All > System Web Services > API Access Policies > Inbound Authentication Profile tab from your ServiceNow Developer Dashboard.

You’ll be redirected to your list of Authentication Profiles, where you can create a new Authentication Profile by clicking on the New button.

You’ll be asked what kind of profile you want. Pick the Create Standard HTTP Authentication Profile option.

Finally, you'll be able to set up your Authentication Profile as you want now. Make sure you choose the OAuth Type, your previously created OAuth endpoint as the OAuth Entity, and Global Locking Policy as the Authentication Policy.

Create An Access Policy for Table API

With the previous Authentication Profile we defined, we’ll be able to define an Access Policy that will enforce specific API requests to be done through OAuth only.

To create an Access Policy, go to All > System Web Services > API Access Policies > REST API Access Policies tab from your ServiceNow Developer Dashboard.

You’ll be redirected to your list of Access Policies, where you can create a new Access Policy by clicking on the New button.

Vanta requires read access to the Table API in order to fetch users and tasks to perform security tests upon them.

We’ll set up the new Access Policy to enforce the Table API to be accessed through OAuth only.

You’ll need to pick the Table API from the REST API dropdown, check the Apply policy to all methods, versions and resources in the API, and choose your previously created Authentication Profile as an Inbound Authentication Profile.

That should create your new Access Policy in your Dashboard.

If it was set up correctly, you should be able to make requests to the Table API through OAuth without issues:

Using other authentication methods like Basic Auth should fail because the Access Policy doesn’t have a Basic Auth Authentication Profile set for the Table API:

Take into account that this Access Policy only takes effect for Table API requests. Other APIs will work fine with whatever Authentication Profile you set up because an Access Policy wasn’t set up for them:

Create Auth Scopes

We’ve managed to enforce client requests to use OAuth for the Table API, but we haven’t added read-only restrictions to it yet.

ServiceNow allows scoping permissions for its APIs to ensure that OAuth client tokens can only access the APIs they have permission to.

We’ll create an Auth Scope to grant Vanta tokens read-only access to the Table API.

To create an Auth Scope, go to All > System Web Services > API Auth Scopes > REST API Auth Scope tab from your ServiceNow Developer Dashboard.

You’ll be redirected to your list of REST API Auth Scopes, where you can create a new scope by clicking on the New button.

We’ll need to create two auth scopes. One for read access to the Table API and another for write access to the Table API.

Once we are redirected to the next page, we’ll be able to create a new REST API Auth Scope.

For the Read Access Scope, we have to choose the Table API REST API, only check the Apply auth scope to all versions in the API checkbox and pick the /now/table/{tableName} Resource. We’ll also need to create an Auth Scope, which can take any name you want, but it’ll be linked to the REST API Auth Scope we’ll create now (We call it table_api_read below).

That should create the Read Access Auth Scope for the Table API. Now we’ll move forward to create the Write Access Auth Scope for the Table API by clicking on the New button again.

For the Write Access Scope, we have to choose the Table API REST API, check the Apply auth scope to all http methods in this API, Apply auth scope to all versions in the API checkbox and pick the /now/table/{tableName} Resource and Apply auth scope to all resources in this API checkboxes. We’ll also need to create an Auth Scope, which can take any name you want, but it’ll be linked to the REST API Auth Scope we’ll create now (We call it table_api_write below).

That should create the Write Auth Scope for the Table API.

For the Auth Scopes to take effect, we need to link them to an OAuth Application.

Locate your previously created OAuth Application and add the table_api_read Auth Scope only to it. You must not add the table_api_write scope because you would give write access to the OAuth Application tokens.

If it was set up correctly, you should be able to make GET requests to the Table API through OAuth without issues like before, but POST requests should fail because the OAuth Application tokens don’t have the write access scope:

But API requests to other APIs will work fine because they don’t have Auth Scopes created for them in your Instance:

That’s how to set up API restrictions for ServiceNow, at least to prevent POST, PUT and DELETE requests to the Table API.

Ideally, you would need to create REST API Auth Scopes for each ServiceNow REST API (including new APIs you create) and only assign the Read Table API permission to Vanta’s OAuth endpoint. But as stated previously, that requires an Auth Scope for each API endpoint, which is a lot of work to do and it’s not necessary to make the integration work. That’s why these steps are optional.