Introduction

In the OAuth ecosystem, scopes serve as a mechanism to define and restrict an application's access to a user’s data. ServiceNow utilizes authentication scopes to enable administrators to control the level of access an OAuth client application has to specific REST APIs. Without scopes, an access token granted to a client application could be used to retrieve all user data via various REST API calls.

To illustrate this, consider a scenario where an administrator wants to allow a third-party client application to only retrieve data from the Table API, preventing it from modifying or deleting records. The most efficient way to enforce this restriction is by utilizing authentication scopes.

In this guide, we will create two authentication scopes:

• table_read
• table_read_write

The table_read scope will be assigned to the HTTP GET method, while table_read_write will be associated with all HTTP methods. When setting up an OAuth client application, we will assign it the table_read scope.

As a result, any access token issued for this OAuth client will only allow GET requests. Attempts to perform other HTTP operations, such as POST or DELETE, will be denied with an HTTP 403 Forbidden error.

---

Step-by-Step Guide to Enabling and Using REST API Authentication Scopes

Step 1: Activate the Required Plugin

Before proceeding, ensure the REST API Auth Scope plugin (com.glide.rest.auth.scope) is installed and activated. This plugin is available from the Tokyo release onward.

---

Step 2: Create Authentication Scopes

Navigate to the Authentication Scope (sys_auth_scope) table and create the following scopes:

1. table_read
2. table_read_write

---

Step 3: Configure API Access Scopes for REST APIs

To enforce these scopes, follow these steps:

1. Navigate to System Web Services > API Auth Scope > REST API Auth Scope and create a new record.
2. Assign the table_read scope to the Table API’s GET method. This ensures that only OAuth clients with this scope can successfully perform GET requests.

Similarly, create another record associating the table_read_write scope with all HTTP methods of the Table API. This ensures that OAuth clients without this scope will be restricted from performing operations like POST, DELETE, or PUT.

---

Step 4: Assign Authentication Scopes to OAuth Clients

Next, we will create two OAuth client applications using the Authorization Code grant type and assign the respective scopes:

1. OAuth Client 1 (AuthScopeTestClientRead) → Assigned the table_read scope (limited to GET requests).
2. OAuth Client 2 (AuthScopeTestClientReadWrite) → Assigned the table_read_write scope (allows all HTTP methods).

---

Step 5: Obtain an Access Token via OAuth Flow

Using an OAuth 2.0 authentication flow (e.g., via Postman), request an access token for both OAuth clients. The issued tokens will include the assigned scopes, specifying their permitted operations.

---

Step 6: Make API Calls Using the Access Token

Using the generated access tokens, we can now perform REST API calls and observe the enforced restrictions:

Scenario 1: GET Request with table_read Scope

• Expected Outcome: HTTP 200 OK (Success)

Scenario 2: POST Request with table_read Scope

• Expected Outcome: HTTP 403 Forbidden (Access Denied)

Scenario 3: POST Request with table_read_write Scope

• Expected Outcome: HTTP 200 OK (Success)

Similarly, tokens issued to clients with the table_read_write scope will allow GET, PUT, DELETE, and other HTTP methods.

---

Best Practices

• Use REST API Auth Scopes alongside REST API Access Policies to prevent unauthorized access through other authentication methods like Basic Auth.
• Always associate the appropriate scopes with REST APIs to ensure that only authorized OAuth clients can interact with them.

By implementing authentication scopes effectively, organizations can enhance security and ensure controlled access to REST APIs within the ServiceNow platform.