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:
- table_read
- table_read_write
Step 3: Configure API Access Scopes for REST APIs
To enforce these scopes, follow these steps:
- Navigate to System Web Services > API Auth Scope > REST API Auth Scope and create a new record.
- 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:
- OAuth Client 1 (AuthScopeTestClientRead) → Assigned the table_read scope (limited to GET requests).
- 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.
@Vidya Lakshmihey! hope you're doing well. i can't see an option to pick specific table in the REST API Auth Scope that i am creating, i want to be able to only read a couple of tables, instead, it seems like i have access to all of the tables. my dev instance is currently using the Yokohoma version
cc @Bharath38
@Vidya Lakshmihi hope you're doing well! I dont see an option to mention the specific tables that i need access to in the REST API Auth Scope that i'm creating. i need read access to only a couple of tables, but im getting access to all of the tables instead i.e. read and write. how do i limit that? PSA the screenshot for this, i am currently on the Yokohoma release in my dev instance
cc @Bharath38
