Secure Credentials Storage for SuiteCloud SDK

Starting 2025.1, SuiteCloud SDK uses Public-Key Cryptography Standards #12 (PKCS#12) to generate a credentials file that is password protected.

When you authenticate for the first time using SuiteCloud SDK tools, the PKCS#12 credentials file is created and stored on your local machine in the .suitecloud-sdk folder within your home directory. This file contains encrypted authentication data, thus eliminating the need for repeated authentication in subsequent sessions. The file name of the credentials file is based on the authentication option that you used to authenticate: credentials_browser_based.p12 for browser-based authentication or credentials_ci.p12 for machine-to-machine authentication.

Important:

Browser-based authentication and Machine-to-machine authentication use different credential files to store authentication data. You can set up your environment to use only one authentication option at a time.

SuiteCloud SDK checks for specific environment variables and the availability of secure storage to determine if you have the appropriate setup for the authentication option that you are trying to run. For more information, see Execution Context for Secure Credentials Storage.

To keep your credentials file secure, SuiteCloud SDK encrypts it using a password or passkey:

For browser-based authentication, the passkey is auto-generated and updated regularly by SuiteCloud SDK. This passkey is stored in your machine's secure storage service (such as Credential Manager for Windows, Keyring for Linux, or Keychain for MacOS).
For machine-to-machine authentication or browser-based authentication in fallback mode, you must manually define the passkey using an environment variable and regularly update it.

When you delete the credentials file, previously configured authentication IDs will be lost. A new credentials file will be created when you set up your account again.

Read the following topics for more information:

Watch the following help video for information about Secure Credentials Storage for SuiteCloud SDK:

Browser-Based Authentication Standard Process and Fallback Mode

When you authenticate using browser-based authentication, SuiteCloud SDK creates the credentials file (credentials_browser_based.p12) and encrypts it using an auto-generated passkey. The passkey is stored in your machine's secure storage and is regularly updated when the token expires.

When you perform operations that require NetSuite authentication, SuiteCloud SDK retrieves the passkey from secure storage and uses it to decrypt the credentials file. For this reason, you should ensure that secure storage is accessible and properly configured on your machine if you want to use browser-based authentication.

If secure storage is unavailable, you can define a fallback passkey by creating the SUITECLOUD_FALLBACK_PASSKEY environment variable. This passkey must contain 32 to 100 alphanumeric characters. For information about how to set environment variables for different operating systems, see Setting Up Environment Variables for SuiteCloud SDK Tools.

Important:

The fallback passkey is meant to be used as a temporary solution for when secure storage is temporarily unavailable, locked, or not properly configured. If for some reason secure storage cannot be used, you can choose to continue using the fallback passkey for browser-based authentication.

In this case, changing the passkey is your responsibility, and it should be done regularly for optimal security. Note that when you change the passkey, the current credentials file will no longer work. After changing the passkey, you must delete the old credentials file and set up your account again.

When secure storage is available in your machine, be sure to remove the fallback passkey environment variable. Otherwise, you will get an error.

Machine-to-Machine Authentication (CI/CD)

Machine-to-machine authentication uses two environment variables:

SUITECLOUD_CI – Set the value to 1 (preferred value) or any value other than zero to indicate that you want to run operations in a CI/CD environment using machine-to-machine authentication.
SUITECLOUD_CI_PASSKEY – Specify the passkey that will be used to create the credentials file. The passkey must contain 32 to 100 alphanumeric characters. This value must be updated regularly.

Important:
When you change the passkey, the current credentials file will no longer work. After changing the passkey, you must delete the old credentials file and set up your account again.

To set up and manage authentication IDs that work with machine-to-machine authentication, only the SUITECLOUD_CI_PASSKEY environment variable needs to be set. To use the authentication IDs to run operations that require authentication, you need to set both the SUITECLOUD_CI_PASSKEY and SUITECLOUD_CI environment variables.

When you authenticate using machine-to-machine authentication, SuiteCloud SDK creates the credentials file (credentials_ci.p12) and encrypts it using the passkey defined in the SUITECLOUD_CI_PASSKEY environment variable. When you perform operations that require NetSuite authentication, SuiteCloud SDK retrieves the passkey from the environment variable and uses it to decrypt the credentials file.

To use your authentication credentials in your CI/CD environment, you need to do the following:

Upload the credentials_ci.p12 file to your CI/CD environment securely.
Set the SUITECLOUD_CI_PASSKEY environment variable in the CI/CD environment and specify the same passkey value that you used to create the credentials file.
Set the SUITECLOUD_CI environment variable to 1 in the CI/CD environment to enable machine-to-machine authentication.

With the credentials and environment variables in place, SuiteCloud SDK tools can perform operations that require NetSuite authentication within the CI/CD pipeline.

For information about how to set environment variables for different operating systems, see Setting Up Environment Variables for SuiteCloud SDK Tools.

General Notices