Automating OAuth 2.0 Authorization Flow For Connnector SuiteApps

December 20, 2023 | 6 minute read
Vlastimil Martinek
Senior Manager for SDN Solutions Engineering at Oracle NetSuite
Text Size 100%:

What is there to automate?

Let’s first spend this inital section showing some obsolete practice how NetSuite customers should not be guided to authorize an integration when they first install an Integrated SuiteApp.

  1. enable required features in NetSuite account
  2. install the SuiteApp from Marketplace
  3. assign the role defined by this integration to your designated employee record
  4. create new access token with choosing an application and assigning a user and role
  5. put the generated token ID and token secret along with NetSuite account ID into the integrated solution on the other side, either into some configuration screen or somehow deliver these secrets to responsible person.

Then the authorization process is usually complete and what follows are some additional setup steps that differ based on the actual solution. You should agree that it is certainly easy to implement but it doesn’t add to user’s comfort.

Steps 1,2 and 3 are inevitably required to be manual and it is by design: SuiteApps cannot arbitrarily alter account setting like enable features, only administrator can do that and also the administrator will decide if a solution should be installed from NetSuite Marketplace to their account or not. Also, customer’s administrator needs to decide who will be an integration user that will be used to communicate on behalf of the integrated solution and also assign a custom role to this user. The role comes as part of the SuiteApp and clearly defines permissions to access all the data and ONLY the data that the solution needs.

 But the authorization steps 4 and 5 that follow don’t have to be based on a manual interaction. You will learn in this posts how to authorize seamlessly your SuiteApp according to latest best practice and avoid unnecessary config screens.

What options do we have?

One of the most important goals for every integrated solution should be to ensure user-friendly authorization process with minimum manual steps. Since release 2019.2, there has been an option to minimize number of initial setup steps by adopting 3-step TBA authorization flow which is now a standard practice with Token-based authentication (NetSuite’s implementation of OAuth1.0 protocol). This flow helps greatly on automating the token exchange and no dedicated config screen or other manual setup is needed in external system to authorize solution in NetSuite account. The only required input from a user/administrator is providing the right NetSuite credentials on the consent screen and chosing a role to be used.

In case of OAuth2.0 authorization framework, which is currently the preferred method, NetSuite supports two different flows:

  • Authorization Code Grant flow
  • Client Credentials flow (Machine-to machine flow)

Authorization Code Grant flow is useful on scenarios where user interaction is a common practice. It requires an existing NetSuite user to authenticate providing credentials on consent screen so the flow can continue for a short time interval, usually one hour. After that, another consent screen is needed to re-authenticate.

Integrated or Hybrid SuiteApp acting as a connector to automatically sync data falls into a typical scenario where Client credentials method is needed. Certificate lifespan can be set up to 2 years. This method does not require user interaction and the main hassle lies within manually uploading and setting up certificates in target NetSuite account(s). This strategy presumes the SuiteApp owner manages certificate generation on their side. In following sections we will focus on adoption of this method as it is by far the most useful for SuiteApp developers who need to integrate solutions to NetSuite.

Client credentials management endpoint

As of July 2023 NetSuite supports API access to manage certificates. You may learn more in other blog post showing how to manage certificates. With this API, developers are able to programmatically ensure rotation of certificate(s) on a particular account so customer doesn’t need to get notified to manually update every time it’s going to expire. Since the validity of a certificate can be set to a maximum of two years the rotation would be a rare event but still a little uncomfortable for end users, until now.

 The only question remains which is how to programmatically upload the first certificate to a customer’s NetSuite account. Let me first show examples to highlight important parameters for the certificates API:

List all certificates for an integration

GET request on

/services/rest/auth/oauth2/v1/clients/{client_id}/certificates/


Full Example

Curl 'https://<account>.app.netsuite.com/services/rest/auth/oauth2/v1/clients/<consumer_key>/certificates/' -H 'Authorization: <access_token>' -H 'Content-Type: application/json' -v --insecure --tlsv1.2

 

Upload new certificate

POST request on

/services/rest/auth/oauth2/v1/clients/{clientId}/certificates

Full Example

curl 'https://<account>.app.netsuite.com/services/rest/auth/oauth2/v1/clients/<consumer_key>/certificates' -H 'Authorization: Bearer <access_token>' -H 'Content-Type: application/json' -X POST -d '{ "fileContent":"-----BEGIN CERTIFICATE-----...","role":1067,"entity":7 }' -v --insecure --tlsv1.2

Revoke certificate

POST request on

/services/rest/auth/oauth2/v1/clients/{clientId}/certificates/{certificateId}/revoke

Full Example

curl 'https://<account>.app.netsuite.com/services/rest/auth/oauth2/v1/clients/<consumer_key>/certificates/<certificate_id>/revoke' -H 'Authorization: <access_token>' -H 'Content-Type: application/json' -X POST -v --insecure --tlsv1.2

 

How to automate your authorization process

Looking at the requests above, you can see that developer should have all parameters available except the access token. Client ID (or the consumer key), account ID, certificate ID are all known parameters to the creator of the SuiteApp. Let’s list the necessary steps to start using Client credentials flow right after SuiteApp installation or whenever the certificate is going to expire:

initiate Authorization code Grant flow from external system to obtain the access token .
upload/revoke certificate(s) using the access token, see  how to manage certificates.
initiate Client Credentials flow, see other blog post for details on how to compose JWT token.
With the above steps you can avoid manual upload of first certificate into NetSuite or manually setting up an access token as well as any manual certificate rotation. External system will ask NetSuite user to authenticate just once on the consent screen and from that moment the connector can authorize thru client credentials flow whenever needed, during the certificate lifespan.

Let’s  go in detail only throught step A to see how to obtain the access token:

1. GET request to authorization endpoint

https://<account>.app.netsuite.com/app/login/oauth2/authorize.nl

or alternatively

https://system.netsuite.com/app/login/oauth2/authorize.nl

Example:

curl 'https://<account>.app.netsuite.com/app/login/oauth2/authorize.nl?redirect_uri=https%3A%2F%2Fmyredirecturl.com&client_id=142a9c39061f28aa7ecd61d6c9e42397e0fe5fa0156d078098940e2398bc53a&response_type=code&scope=restlets+rest_webservices&state=lku2XLx1BpT5Q0F3MRPHb94j'

If the customer authorized himself on consent screen, a redirect to your redirect URI was initiated:

https:// myredirecturl.com/netsuite/oauth2callback?state=lku2XLx1BpT5Q0F3MRPHb94j&role=1006&entity=15&company=1234567&code=70b827f926a512f098b1289f0991abe3c767947a43498c2e2f80ed5aef6a5c50

If authorization failed, error parameter is being returned instead of code parameter.

The code parameter is required in the following step:

2. POST request to token endpoint

https://<account>.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token

Example:

Curl 'https:// <account>.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token?code=70b827f926a512f098b1289f0991abe3c767947a43498c2e2f80ed5aef6a5c50&redirect_uri=https://myredirecturl.com&grant_type=authorization_code'

Request must include client credentials - client_id and client_secret in the HTTP authorization header

The response returns an access token along with other parameters like refresh token in JWT format. With this access token you are now ready to programatically upload certificate to customer’s NetSuite account which is the prerequisity for your connector to successfully authorize thru the client credentials flow. Ready to go!

There is one last question that comes from SuiteApp developers:  "If we manage certificates for OAuth2, should we create one certificate to represent the solution for everyone or do we need to manage unique certificate for each and every customer?" The short answer is - both is currently possible. Each apporach has advantages and drawbacks, while having one certificate is usually much easier to manage, opting for unique certificate is considered to be more secure.

Thanks for reading this article, hopefully you’ve learned something new or got some answers you were looking for. See you in a next post!

Vlastimil Martinek

Senior Manager for SDN Solutions Engineering at Oracle NetSuite

With nine years of dedicated service at Oracle, I have cemented my expertise in the realm of software integrations and partner relations within the SuiteCloud Developer Network (SDN) landscape. My tenure at Oracle is marked by a deep collaboration spirit with SDN partners, where I have gained a lot of experience about software integration with different technologies. 


Previous Post

Using faker-js/SimpleFaker to produce test data in Oracle Database 23c

Martin Bach | 7 min read

Next Post


Validating Custom Password Fields in SuiteScript 2.x

Rajesh Seth | 2 min read