Authorizing SuiteTalk Web Services apps with NetSuite’s Three-Step Authorization Flow

With version 2019.2, NetSuite started rolling out a new feature called the Three-Step TBA Authorization Flow. This feature will undoubtedly take a lot of the pain out of using TBA for Web Services for both NetSuite Admins and end-users. As App developers, we will also benefit from the fact that with this flow, NetSuite takes back the complexity of handling 2FA and SSO login options, leaving us only a few simple steps to implement.

Before we look at the internals of how this flow works, lets go through the sample app and see this flow in action.

Prepare to run the sample app

Before we get started, you need few things to be setup in your NetSuite Account. Very first step is to ensure that you are on NetSuite version 2019.2 or higher.

Create an Integration Record for the Sample App

Go to Setup > Integration > Manage Integrations > New.

create-integration-rec-menu

Be sure to create an Integration record with the 3 Token-Based Authentication options enabled. Enabling User Credentials is optional (and irrelevant for this scenario). In the Callback URL field, enter https://localhost:5001/authorize. This is the URL which will receive the oauth_token and oauth_verifier once the user has authorized your application. We will be configuring our sample application to run on localhost:5001 later on.

Integration-record-setup

When you hit ‘Save’, NetSuite will generate a Consumer Secret and Consumer Key for this Integration. Copy these values to a secure location as you will need them later.

Next up, you need a role with User Access Token permission. Either add this permission to your existing role or creat a new role with the permission.

Get the Sample App

The sample app is bundled with Celigo Service Manager for NetSuite: an open source library that makes it simple for you to work with NetSuite SuiteTalk Webservies.

First, clone the Service Manager repo to a local folder.

From the command line, run npm install in the Samples\ThreeStepAuth\ClientAppfolder.

Open ServiceManage.sln in VisualStudio. Ensure that Samples\ThreeStepAuth is set as the startup project.

Configure the Sample App

In Visual Studio, open Samples\ThreeStepAuth\Properties\launchSettings.json file.  Under the launch profile of your choice (or on all profiles), add the following Enviornment Variables:

Celigo__UnitTests__NetSuite__TBA__ConsumerKey

Celigo__UnitTests__NetSuite__TBA__ConsumerSecret

Assign the Consumer Key and Secret values NetSuite generated for you (above) to these two variables.

Your finished launcherSettings.json should looks something like below. I’m running the Project profile rather than IISExpress. Also note that I am running the app on https://localhost:5001. You’d recall that we set a resource from localhost:5001 as the callback URL in the Integration Record. Therefore it is important that you run the sample on localhost:5001 for this to work.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:6670/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "ThreeStepAuth": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "Celigo__UnitTests__NetSuite__TBA__ConsumerKey": "consumer_key_for_your_integration_record",
        "Celigo__UnitTests__NetSuite__TBA__ConsumerSecret": "consumer_secret_for_your_integration_record",
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "https://localhost:5001/"
    }
  }
}

Running the Sample App

Hit F5 to run the app.

NOTE: If you see a timeout exception below, rather than the app starting up, just wait a few seconds and refresh the page. This is just due to the delay in launching the Angular app, as opposed to the ASP.NET Core server.

TimeoutException: The Angular CLI process did not start listening for requests within the timeout period of 50 seconds. Check the log output for error information.

Once started, enter your NetSuite Account number in to the login text box:

Sample-screen1

I would also recommend to open the developer tools of the browser, and follow along the console output to see what’s going on.

You should see the browser navigate to the NetSuite login screen. Login with your NetSuite credentials here and move along the rest of the NetSuite screens and Allow the the app to access NetSuite on your behalf:

sample-app-ns-login

sample-app-ns-role-selection

sample-app-ns-approval-screen

Note that on the last screen, I have two roles. This is because I have two roles compatible with the Three-stop Authorization (i.e. has the User Access Token permission mentioned above). Here, if I simply click Allow, I’ll be authorizing the app to use my Administrator role. If I want to use the other role, I can do so by clicking “Choose role” next to it.

Once you click Allow, you will be returned to the sample app, which will show you the authorized TBA Token ID and Token Secret (which will be printed on to the console of the browser Dev Tools).

sample-app-completion

Managing Generated Token

Be aware that, your app is not expected to run this flow on each user login. You are expected to retain the user’s Token ID and Secret for subsequent web service calls, across user sessions. Each time the flow is run, it generates a new Token ID and Secret pair (without invalidating the previously generated ones). A user is only allowed to have a finite number of them. A user can remove these tokens anytime by clicking on “Manage Access Tokens” on the NetSuite Dashboard’s Settings portlet.

Conclusion

The Three-Step Authorization flow is a really useful feature, given how difficult it had been to get users on board Token Based Authentication in the past. Last I checked, NetSuite’s official documentation on how to implement the flow is still being worked on. So, I hope the sample code here would be useful to anyone looking to use this feature in their apps. I will also try to follow up this post with a walkthrough of the implementation in the near future.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.