Inbound OAuth Auth Code Grant Flow Part 1 - Getting Started with Postman

#Authentication , #REST , #OAuth , #REST API , #OAuth2 , #Authorization Code Grant Flow

Josh Nerius

4 minute read

As highlighted in my New Integration/API and Authentication Features Blog Post, Istanbul introduces two new inbound OAuth 2.0 flows:

  1. Authorization Code Grant Flow
  2. Implicit Grant Flow

These flows allow you to build apps that interact with ServiceNow APIs without needing to be directly aware of an end user’s username/password. Some possible use cases include:

  • Building a mobile (iOS or Android) app that interacts with task records in a ServiceNow instance
  • Building a web application that interacts with ServiceNow on behalf of your users

This blog post is a quick tutorial to:

  • Walk you through the process of configuring an inbound Auth Code Grant Flow provider in your instance
  • Demonstrate the flow in action using the Postman API testing tool.

Implicit Grant Flow is a simplified flow meant for in-browser/mobile clients and we’ll discuss it at a later date.

A bit more background

Authorization Code Grant Flow is the most commonly used OAuth 2.0 flow and enables users to authorize applications to make API requests on their behalf. If you’ve ever used an app or website that asks for access to your Google, Facebook, Dropbox or similar account, you’ve already seen this in action.

This OAuth flow redirects the end user from your app to the ServiceNow UI to authenticate and authorize the request. It then redirects the user back to your app with an authorization code that can be used to obtain an access token. This token is then used when making API calls instead of a Basic Authentication header.

1. Create an OAuth Provider Configuration in ServiceNow

If you’ve previously configured an OAuth provider, the process will feel familiar.

  1. Navigate to System OAuth > Application Registry and click New

    I_OAuth_T_1_NavToAppRegistryAndNew.png

  2. Click Create an OAuth API endpoint for external clientsb(

    I_OAuth_T_2_SelectProviderType.png

  3. Give the provider a Name and Redirect URL. _Note: the redirect URL will usually be a resource inside the application connecting to ServiceNow as a client. For this demonstration, we’re using Postman which uses URL https://www.getpostman.com/oauth2/callbackb(

    SN_New_Provider_Form.png


    _

2. Set up Postman

Now that we have an OAuth provider configured, we can set up our external app to use it.

When getting OAuth flows up and running, I always start by using an API testing tool like Postman or Paw. This reduces initial complexity and removes many of the variables that you may have to deal with if you’re integrating this into your own app. In short, it’s a good sanity check to make sure things are working before you start writing code.

If you don’t already have Postman, download it here. Open Postman, and configure a new GET request with the following URL:

https://.service-now.com/api/now/table/incident

Clicking Send will return an error since we haven’t yet provided any credentials for the request.

Postman_No_Creds.png

2.1 Configure Postman for OAuth

Under the Authorization tab, change the Type to OAuth 2.0 and click Get New Access Token

Postman_Select_OAuth.png

Fill out the resulting dialog with the following values:

Postman_New_Token_Details_Dialog.png

Click Request Token and a ServiceNow login window will open. Log in using a username/password of your choosing (the user should have access to the incident table for the upcoming tests to work correctly).

SN_Auth_Login_Page.png

Now that you’ve authenticated, you’ll be asked to authorize the external app (Postman in this case) to interact with ServiceNow on your behalf. Click Allow.

SN_Auth_Authorize_page.png

You’ll be taken back to the Postman UI, and you’ll see an item listed under the Existing Tokens section. Click on the listed token, and you’ll see the token details in the right-hand detail pane.

Where did this token come from? When you clicked Allow, the ServiceNow UI redirected you back to Postman with a code URL parameter. Postman then used this code to ask for an Access Token from the oauth_token.do endpoint we configured earlier.

Click Use Token to add this token to our GET request.

Postman_View_And_Use_Token.png

Click the Headers tab and you will now see an Authorization: Bearer header followed by the Access Token we just generated.

Click Send and you should now see a response payload indicating success!

Postman_View_Header_And_Send_Request.png

Summary

We never entered our user credentials into the Postman app directly - the only place we were asked to provide a username/password was inside the ServiceNow UI. Postman (or whatever app you’re building) will only interact with the instance using Access Tokens, and will never be aware of the users’s credentials.

If you’d like to take this to the next level, check out Inbound OAuth Auth Code Grant Flow Part 2 - Using OAuth and Passport.js in a Node.js/Express Web App.

Comments