Execution Context for Secure Credentials Storage

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

Which authentication option you're allowed to use—either browser-based or machine-to-machine authentication.
The credentials file used to store authentication details and do operations that require authentication
The passkey used to encrypt and decrypt the credentials file

Note:

Auth IDs created in the browser-based context aren't accessible in the machine-to-machine context, and inversely. So, an auth ID made in one context can't be used in the other.

The environment variables on your machine and whether secure storage is available determine the execution context. You can set up one or more of these environment variables—or none, if you want to use the default context.

SUITECLOUD_FALLBACK_PASSKEY: Stores the passkey to encrypt and decrypt the credentials_browser_based.p12 file when you're 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: Stores the passkey to encrypt and decrypt the credentials_ci.p12 file when you're using machine-to-machine authentication.

The table below shows the conditions for each execution context and gives more details. If your setup doesn't match any of these, it's considered 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	It allows browser- based authentication. This is the default execution context, meant for use on a user's machine. Uses the `credentials_browser_based.p12` credentials file. It uses the auto-generated passkey stored in your machine's secure storage to unlock the credentials file. This passkey is automatically refreshed when the token changes. It 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	It allows browser- based authentication. This execution context is for when secure storage isn't available on a user's machine. Uses the `credentials_browser_based.p12` credentials file. It uses the passkey defined in the `SUITECLOUD_FALLBACK_PASSKEY` environment variable to unlock the credentials file. This passkey isn't automatically refreshed and must be manually updated. It 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	It allows machine-to-machine authentication. This execution context can be used to set up and manage authentication IDs for a CI/CD environment. It uses the `credentials_ci.p12` credentials file. It uses the passkey defined in the `SUITECLOUD_CI_PASSKEY` environment variable to unlock the credentials file. This passkey isn't refreshed automatically and has to be updated manually. It only allows you to set up a new auth ID or select an existing one. Other commands (such as deploy, validate, etc.) will not work. Browser-based authentication is not allowed in this setup.
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	It allows machine-to-machine authentication. This execution context is meant for use in a CI/CD environment. It uses the `credentials_ci.p12` credentials file. It 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. It allows all other operations (such as deploy, validate, etc.), 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

It allows browser- based authentication.
This is the default execution context, meant for use on a user's machine.
Uses the credentials_browser_based.p12 credentials file.
It uses the auto-generated passkey stored in your machine's secure storage to unlock the credentials file. This passkey is automatically refreshed when the token changes.
It 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

It allows browser- based authentication.
This execution context is for when secure storage isn't available on a user's machine.
Uses the credentials_browser_based.p12 credentials file.
It uses the passkey defined in the SUITECLOUD_FALLBACK_PASSKEY environment variable to unlock the credentials file. This passkey isn't automatically refreshed and must be manually updated.
It 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

It allows machine-to-machine authentication.
This execution context can be used to set up and manage authentication IDs for a CI/CD environment.
It uses the credentials_ci.p12 credentials file.
It uses the passkey defined in the SUITECLOUD_CI_PASSKEY environment variable to unlock the credentials file. This passkey isn't refreshed automatically and has to be updated manually.
It only allows you to set up a new auth ID or select an existing one. Other commands (such as deploy, validate, etc.) will not work.
Browser-based authentication is not allowed in this setup.

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

It allows machine-to-machine authentication.
This execution context is meant for use in a CI/CD environment.
It uses the credentials_ci.p12 credentials file.
It 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.
It allows all other operations (such as deploy, validate, etc.), except for browser-based authentication.

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

Related Topics