NetSuite OAuth 2.0 Authentication for SDF (SuiteCloud Development Framework)

You may have heard about the new method of authentication for the SuiteCloud SDK aka SDF with the release of 2024.2 (or 2.0.0 if we’re talking @oracle/suitecloud-cli)

SDF authentication prior to this release was setup using one of 2 methods:

1. Browser-Based
2. Token Based Authentication

While Browser-Based authentication is still supported and encouraged for user interactions, TBA auth, which was ideal for CI environments is no longer supported. OAuth 2.0 must be used instead, and this means that we need to create new authentication ids for all our SDF connections. It also introduces a new command for doing so.

You might be familiar with how it was done previously:

suitecloud account:savetoken --account 123456 --authid my-ci --tokenid XXX --tokensecret XXX

This program is no longer supported from 2.0.0 onwards, and we now have a new command for OAuth2.0 which looks like this:

suitecloud account:setup:ci --account 123456 --authid my-ci --certificateid XXXX --privatekeypath ~/pathtomykey/private-key.pem

So what's the difference?

We now need to pass a certificate id and a path to a private key as command line arguments.

This blog post will explain every step you need to take to obtain these values and start communicating using the OAuth 2.0 protocol.

Step One - Create Certificate

We need to create an SSL certificate for whichever machine (your personal computer, or some container when using CI) will be attempting to use SDF in your account.  The certificate consists of a public key which will be uploaded into NetSuite, and a private key which must be used by the service attempting to establish a secure connection. Any machine holding the private key for the certificate will be able to access and use SDF in that account.

So first, generate the certificate.  Using NetSuite’s example, we can use the openssl tool:

openssl req -new -x509 -newkey rsa:4096 -keyout private.pem -sigopt rsa_padding_mode:pss -sha256 -sigopt rsa_pss_saltlen:64 -out public.pem -nodes

NB: you should probably also specify the validity duration for the certificate, by passing the -days option with a value representing the amount of days. -days 730 says it's valid for 2 years. Certificates are valid in NetSuite for a maximum of 2 years anyway, and so NetSuite will cap the duration if a value greater than that is given)

Of note from the above:

• X509 is the standard format for the public key
• RSA:4096 is the encryption algorithm used, and the size of the key, NetSuite recommends 4096 bits making it very secure 
• -keyout specifies where the private key will be saved, and what name will be used, in this case private.pem (you could change this to whatever name as long as you keep the .pem extension)
• -out specifies where the public key will be saved, as with -keyout, you could rename this to anything you like, such as: -out sdf-pub.pem

The end result is 2 files, the public and private keys generated above.

The public key, which will be uploaded to NetSuite, determines the --certificateid arg from the new suitecloud command.

The private key which should be kept secret determines the -–privatekeypath arg.

Step Two - Upload the public key into your NetSuite account

Head over to:

1. Setup > Integration > Oauth Client Credentials (M2M) Setup

2. Hit CREATE NEW

3. Select the Entity (Employee), and Role to be used for this SDF profile. 

Previously using TBA, you would usually generate access tokens for a specific user and role for the SuiteCloud Development Integration application, and the connection would assume the role of whichever user the tokens were generated for. This is no different.  The certificate will be tied to the User and Role combination you assign here.

‍

4. Select SuiteCloud Development Integration as the Application

‍

‍

5. Upload the public certificate you generated in Step One here.

‍

‍

‍NB: You can only use the same certificate once per Integration + User + Role combination‍

NB: If you want to live happily ever after, select a user having the Administrator role.  For the brave souls and SDF tinkerers please proceed to assign a role of your own choosing.  I document my experience following this noble path here: https://www.bundlet.com/blog/creating-a-restricted-netsuite-role-for-sdf

‍

6. Finally, copy the value NetSuite spits out in the Certificate Id Column.  I’m hoping by now, you know where we’re headed with this one.

‍

‍

This is the first value we need to set in the –-certificateid arg in the account:setup:ci command

‍

Step 3 - Create the Auth ID in the SuiteCloud project

Assuming you have already created an SDF project and are running this from within a valid project folder:

‍(otherwise you might stumble across the following error - No manifest.xml file was found in /Users/xxx. Run "account:setup:ci" in a valid project folder.)

Then run the command:

suitecloud account:setup:ci 

--account 6535743_RP // get from Setup > Company > Company Information > Account ID

--authid my-ci // authentication id alias

--certificateid GGImz4iH6mPJ8n3qQWas6XNiAy-Mx-1g8GSqIjyAQR8 // netsuite cert id

--privatekeypath ~/pathtomykey/private-key.pem // path to local private key

One more time without the line breaks and the notes:

suitecloud account:setup:ci --account 6535743_RP --authid my-ci --certificateid GGImz4iH6mPJ8n3qQWas6XNiAy-Mx-1g8GSqIjyAQR8 --privatekeypath ~/pathtomykey/private-key.pem

‍

You might be warned about the current credentials file for your machine being incompatible with the new version.  You probably need to wipe this file and run the command again. 

‍Some of your authentication details are not compatible with the current version of this SuiteCloud SDK tool. Delete the /Users/username/.suitecloud-sdk/credentials file to proceed. The authentication IDs you set up previously will be lost. Ensure that you update all the SuiteCloud SDK tools to the latest version.

‍

NB: (you will lose access to your current saved authentication ids in doing so!)

----

If all went well, you should be presented with that beautiful green text we’ve all come to know and love while using the SDF cli confirming that the setup was successful.

‍

‍