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).

Create An OAuth Application

• ServiceNow allows you to set up basic authentication or create an OAuth endpoint in your instance to allow Vanta to access the API.
• Since setting up an OAuth Endpoint is more secure, 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 can 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, setting 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 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 or scoping for their instances by default.

Instead, it provides the REST API Access Policies feature to restrict access to its API. It’s divided into 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. However, 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.

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.

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

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

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

• Finally, you can 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 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 the New button

Vanta requires read access to the Table API to fetch users and tasks to perform security tests on 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 a 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:

• Consider 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 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 is for read access to the Table API, and the other is for write access to the Table API.

Once redirected to the next page, we can 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 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.