OAuth 2.0 with Inbound REST

[Ankur Bawiskar]

What is OAuth:

• OAuth (Open Authorization) is an open-standard for token-based authentication and authorization on the Internet..
• OAuth Authorization Framework is available on IETF (RFC6749)
• OAuth 2.0 is the latest version for OAuth.
• OAuth 2.0 allows users access instance resources by obtaining token rather than entering login credentials with each resource request.
• Different services on web already supporting OAuth 2.0
  
  1. Google
  2. Github
  3. Salesforce
  4. Facebook

Different Grant types for OAuth 2.0:

• Grant types are methods through which applications can gain access tokens & by which limited access to the resources are granted.
• OAuth 2.0 provides four standard grant types that can be used to customize the authentication and authorization process depending on the application requirements:
  
  1. Authorization Code
  2. Implicit
  3. Resource Owner Password Credentials (Password)
  4. Client Credentials

ServiceNow & OAuth 2.0:

• ServiceNow supports following authentication for Inbound REST APIs
  
  1. Basic Authentication which consists of combination of Username & Password
  2. OAuth which uses Access Token
• OAuth plugin is active on new & upgraded instances. If not then activate the “OAuth 2.0” plugin.
• Ensure system property “com.snc.platform.security.oauth.is.active” has value as true so that instance can generate the OAuth 2.0 tokens.
• For Inbound based on OAuth ServiceNow only supports following grant types -> Resource Owner Password Credentials (Password) & Authorization Code
• OAuth based authentication is supported only for REST API Endpoints in ServiceNow and not for SOAP APIs

Steps for setting up OAuth 2.0 for Inbound REST:

• Navigate to System OAuth > Application Registry and then click New.
• On the interceptor page, click Create an OAuth API endpoint for external clients and then fill in the form.

Name	Unique Name that identifies the application
Client ID	This will be auto-generated by the instance
Client Secret	This will be auto-generated by the instance
Refresh Token Lifespan	8,640,000 seconds (100 days) & can be increased
Access Token Lifespan	1800 seconds (30 Minutes) & can be increased

• Create an user in User table. This user should be active, not locked out so that instance can produce an access token for OAuth. For example:

User ID	rest.user
Password	rest.user
Web service access only	true

Screenshots:

Client Secret is automatically set and can be seen when you toggle the visibility icon (lock icon)

Test OAuth 2.0 using Postman tool to get Access Token:

• Postman is a Google Chrome app for interacting with HTTP APIs. It has friendly GUI for constructing requests/reading responses for the APIs. You can download postman tool from here (Postman)
• Steps
  
  1. Open Postman application & set the HTTP Method as POST
  2. Endpoint URL as https://instanceName.service-now.com/oauth_token.do. This is the default endpoint for getting access tokens.
  3. Requests should be formatted as URL-encoded; Requests Parameters should be sent in HTTP POST body
  4. Access requests made within the access token's expiration time always return the current access token
• Different request parameters to be sent in the format of Key Values; After filling all the values hit the SEND button

Key	Value
grant_type	password
client_id	dbd9663cd987f3c042381b764d1b153c
client_secret	LKw*^N-r#7
username	rest.user
password	rest.user

Screenshots:

Response containing Access Token & Refresh Token

Test OAuth 2.0 using Postman to get Access Token using Refresh token:

• You can get the access token using the refresh token received previously. This doesn’t require sending the user credentials.
• Transmitting refresh tokens is generally more secure than transmitting user credentials. Ensure you generate this request before the refresh token expiration.
• Steps
  
  1. Open Postman application & set the HTTP Method as POST
  2. Endpoint URL -> https://instanceName.service-now.com/oauth_token.do. This is the default endpoint for getting access tokens.
  3. Requests should be formatted as URL-encoded; Requests Parameters should be sent in HTTP POST body.
  4. Access requests made within the refresh token expiration time always return the current refresh token.
• Different request parameters to be sent in the format of Key Values; After filling all the values hit the SEND button.

Key	Value
grant_type	refresh_token
client_id	dbd9663cd987f3c042381b764d1b153c
client_secret	LKw*^N-r#7
refresh_token	<previousRefreshTokenValue>

 
Screenshots: Response containing Access Token & Refresh Token

 Test OAuth 2.0 Access Token in the actual endpoint:

• Steps
  
  1. Give the appropriate HTTP Method; For example purpose I have used GET and have used Scripted REST API to fetch Incident Description based on incident number passed in URL
  2. Endpoint URL - https://instanceName.service-now.com/api/30520/fetchincidentapi/incident/INC0000003
  3. HTTP Method – GET
  4. In the Headers Section give the following Key Value Pairs
     
     • Key -> Authorization
     • Value -> Bearer <AccessToken>

Screenshots: Response received from API

Benefits of OAuth 2.0 & Best Practices:

• Open industry-standard protocol for secure authorization of Web APIs so no licensing fees
• Allows limited access to user’s data and allows accessing only when authorization token has not expired
• Adds extra layer of security by using access token; when token expires a new access token has to be requested
• Easy, simple and widely used by most of the 3rd party applications

Thanks for reading the blog and do provide your inputs/suggestions if any.

Hope you find this article helpful. Don’t forget to Mark it Helpful, Bookmark.
Thanks,
Ankur Bawiskar

ServiceNow MVP 2020,2019,2018

My Articles & Blogs