Introduction
In the OAuh world, the scope is a mechanism to let an application request limited access to a user’s data. ServiceNow platform supports authentication scopes to allow admins to limit access of an OAuth client application to a specific REST API. Without authentication scopes, an access token received by a client application can be used to fetch all the user’s data using different REST API calls.
Let’s understand using an example; As an admin, I want a 3rd party client application to only to have “read” access to table API data. I do not want to allow an update or delete operation for this client application. The easiest way to achieve this capability is through authentication scopes.
We will create two scopes
- table_read
- table_read_write
We will associate the table_read scope with the HTTP GET method. We will also associate all HTTTP methods with the table_read_write scope. While creating the OAuth client application, we will add the table_read scope to the client.
In this way, the access token granted for this OAuth client will only be able to perform GET calls. An attempt to call other HTTP methods on table API with this access token will fail with HTTP 403.
Step by Step guide to enable and use REST API Auth Scopes
Activate plugins
Install the REST API Auth Scope plugin (com.glide.rest.auth.scope). This plugin has been available since the Tokyo release.
STEP 1: Create Scopes
Go to Authentication Scope (sys_auth_scope) table and create scopes.
We will create two scopes
- table_read
- table_read_write
STEP 2: Configure API access scope for REST APIs
Go to System Web Services > API Auth Scope > REST API Auth Scope and click on new. In this example, we will create a record for Table API and the GET method. This means that Table API’s GET method can only be successfully called using access token issues to an OAuth client with table_read auth scope.
Similarly, we would create another record for Table API. This time we are adding another scope, “table_read_write,” which applies to all HTTP methods of this API.
This will ensure that OAuth client applications without the table_read_write access cannot perform operations like POST and DELETE.
STEP 3: Configure Auth scopes for OAuth Client
We will create two new OAuth clients with the Authorization Code grant type and assign the authentication scope.
The first OAuth client (AuthScopeTestClientRead) with table_read scope would only be able to perform GET operation on Table API. The second OAuth client (AuthScopeTestClientReadWrite) with table_read_write scope would be able to perform all operations on Table API.
STEP 4: Perform OAuth flow to get access token
I have used the postman desktop app to perform OAuth flow to receive access and refresh tokens for both clients. The access token will also have scope details associated with them.
STEP 5: Use the OAuth access token to make the API call
Now, I will use these access tokens to make Table API calls with various operations.
- Scenario 1: Table API GET operation with only table_read scope
- HTTP 200 - Success
- Scenario 2: Table API POST operation with only table_read scope
- HTTP 403-Forbidden
- Scenario 3: Table API POST operation with only table_read_write scope
- HTTP 200 Success
You can also verify other combinations as well. Access tokens associated with the OAuth client with table_read_write scope would also be able to perform GET, DELETE, PUT and other operations.
Best Practices
- The REST API Auth scope feature should be used in conjunction with the REST API Acees policy feature so that you can block other authentication methods, such as Basic Auth for your REST APIs.
- It is always best to associate appropriate scopes with your REST APIs. So that only the intended OAuth client with the required scope can access your APIs.
More Information
- Product Documentation
- YouTube Video by Jason Nichols explaining REST API Auth Scope concept in detail
5 Comments
