Execution Context for Secure Credentials Storage

The execution context in SuiteCloud SDK controls the way authentication and credential management work. It is used by the SuiteCloud SDK tools to determine the following:

The authentication option that you are allowed to use, either browser-based authentication or machine-to-machine authentication
The credentials file used to store authentication details and perform operations that require authentication
The passkey used to encrypt and decrypt the credentials file

Note:

Auth IDs created in the browser-based context are not accessible in the machine-to-machine context, and inversely. This means that an auth ID created in one context cannot be retrieved or used in the other context.

The environment variables set in your machine and the availability of secure storage are used to determine the execution context. You can set up one or more of the following environment variables (or none of them, if you want to use the default execution context).

SUITECLOUD_FALLBACK_PASSKEY: Used to store the passkey to encrypt and decrypt the credentials_browser_based.p12 file when you are using browser-based authentication in fallback mode.
SUITECLOUD_CI: Used to indicate that you want to run operations in a CI/CD environment using machine-to-machine authentication.
SUITECLOUD_CI_PASSKEY: Used to store the passkey to encrypt and decrypt the credentials_ci.p12 file when you are using machine-to-machine authentication.

The following table shows the conditions used to determine the execution context and provides detailed information about it. If your setup does not match any of the conditions listed in this table, it is considered to be in an invalid execution context.

Execution Context	Environment variable configuration and secure storage status	Description
Browser-based (default)	Secure storage is available. Environment variables configuration: `SUITECLOUD_FALLBACK_PASSKEY` is not set `SUITECLOUD_CI_PASSKEY` is not set `SUITECLOUD_CI` is not set	Allows browser-based authentication. This is the default execution context. It is meant to be used on a user machine. Uses the `credentials_browser_based.p12` credentials file. Uses the auto-generated passkey stored in the machine's secure storage to unlock the credentials file. This passkey is automatically refreshed when the token changes. Allows all other operations, except for machine-to-machine authentication.
Browser-based fallback	Secure storage is unavailable. Environment variables configuration: `SUITECLOUD_FALLBACK_PASSKEY` is set to a value between 32 and 100 alphanumeric characters. `SUITECLOUD_CI_PASSKEY` is not set `SUITECLOUD_CI` is not set	Allows browser-based authentication. This execution context is meant to be used when secure storage is unavailable on a user machine. Uses the `credentials_browser_based.p12` credentials file. Uses the passkey defined in the `SUITECLOUD_FALLBACK_PASSKEY` environment variable to unlock the credentials file. This passkey is not automatically refreshed and must be manually updated. Allows all other operations, except for machine-to-machine authentication.
Machine-to-machine authentication setup	Secure storage status is not relevant in this case. Environment variables configuration: `SUITECLOUD_FALLBACK_PASSKEY` is not set `SUITECLOUD_CI_PASSKEY` is set to a value between 32 and 100 alphanumeric characters. `SUITECLOUD_CI` is not set	Allows machine-to-machine authentication. This execution context can be used to set up and manage authentication IDs that will be used in a CI/CD environment. Uses the `credentials_ci.p12` credentials file. Uses the passkey defined in the `SUITECLOUD_CI_PASSKEY` environment variable to unlock the credentials file. This passkey is not automatically refreshed and must be manually updated. Only allows operations for management of authentication IDs.
Machine-to-machine	Secure storage status is not relevant in this case. Environment variables configuration: `SUITECLOUD_FALLBACK_PASSKEY` is not set `SUITECLOUD_CI_PASSKEY` is set to a value between 32 and 100 alphanumeric characters. `SUITECLOUD_CI` is set to 1	Allows machine-to-machine authentication. This execution context is meant to be used in a CI/CD environment. Uses the `credentials_ci.p12` credentials file. Uses the passkey defined in the `SUITECLOUD_CI_PASSKEY` environment variable to unlock the credentials file. This passkey is not automatically refreshed and must be manually updated. Allows all other operations, except for browser-based authentication.

Execution Context

Environment variable configuration and secure storage status

Description

Browser-based (default)

Secure storage is available.

Environment variables configuration:

SUITECLOUD_FALLBACK_PASSKEY is not set
SUITECLOUD_CI_PASSKEY is not set
SUITECLOUD_CI is not set

Allows browser-based authentication.
This is the default execution context. It is meant to be used on a user machine.
Uses the credentials_browser_based.p12 credentials file.
Uses the auto-generated passkey stored in the machine's secure storage to unlock the credentials file. This passkey is automatically refreshed when the token changes.
Allows all other operations, except for machine-to-machine authentication.

Browser-based fallback

Secure storage is unavailable.

Environment variables configuration:

SUITECLOUD_FALLBACK_PASSKEY is set to a value between 32 and 100 alphanumeric characters.
SUITECLOUD_CI_PASSKEY is not set
SUITECLOUD_CI is not set

Allows browser-based authentication.
This execution context is meant to be used when secure storage is unavailable on a user machine.
Uses the credentials_browser_based.p12 credentials file.
Uses the passkey defined in the SUITECLOUD_FALLBACK_PASSKEY environment variable to unlock the credentials file. This passkey is not automatically refreshed and must be manually updated.
Allows all other operations, except for machine-to-machine authentication.

Machine-to-machine authentication setup

Secure storage status is not relevant in this case.

Environment variables configuration:

SUITECLOUD_FALLBACK_PASSKEY is not set
SUITECLOUD_CI_PASSKEY is set to a value between 32 and 100 alphanumeric characters.
SUITECLOUD_CI is not set

Allows machine-to-machine authentication.
This execution context can be used to set up and manage authentication IDs that will be used in a CI/CD environment.
Uses the credentials_ci.p12 credentials file.
Uses the passkey defined in the SUITECLOUD_CI_PASSKEY environment variable to unlock the credentials file. This passkey is not automatically refreshed and must be manually updated.
Only allows operations for management of authentication IDs.

Machine-to-machine

Secure storage status is not relevant in this case.

Environment variables configuration:

SUITECLOUD_FALLBACK_PASSKEY is not set
SUITECLOUD_CI_PASSKEY is set to a value between 32 and 100 alphanumeric characters.
SUITECLOUD_CI is set to 1

Allows machine-to-machine authentication.
This execution context is meant to be used in a CI/CD environment.
Uses the credentials_ci.p12 credentials file.
Uses the passkey defined in the SUITECLOUD_CI_PASSKEY environment variable to unlock the credentials file. This passkey is not automatically refreshed and must be manually updated.
Allows all other operations, except for browser-based authentication.

For more information, see Setting Up Environment Variables for SuiteCloud SDK Tools.

Related Topics