Environment Secrets and Variables (ESVs)

Overview

Environment secrets and variables (ESVs) let you individually configure the development, staging, and production environments in your Identity Cloud tenant.

Use variables to set configuration values that need to be different for each tenant environment. For example, an authentication node might need one URL in your development environment, but a different URL in your production environment.

Use secrets to set configuration values that need encrypting. The values may or may not need to be different for each tenant environment. For example, an MFA push notification node might need an authorization password to use an external SMS service.

To define where an ESV should be inserted into your environment configuration, you must use a promotion request. The functionality to do this using API and UI will be available at a later date.

To use an ESV in your scripts, you can reference it directly, without needing to request a promotion first. See Use ESVs in Scripts.

ESVs

Variables

Use variables to set configuration values that need to be different for each tenant environment.

Variables are simple key/value pairs that can be read back. Unlike secrets, they are not versioned. They should not contain sensitive values.

Variables require a restart to substitute them into their corresponding placeholders in the environment configuration.

Secrets

Use secrets to set configuration values that need encrypting. The values may or may not need to be different for each tenant environment.

Secrets require a restart to substitute them into their corresponding placeholders in the environment configuration.

Secret versions

Rather than have a single value, secrets instead have one or more secret versions, each containing their own value. By design, the value of a secret version cannot be read back after the secret version has been created.

You can enable or disable secret versions by setting their status field to ENABLED or DISABLED. The latest version of a secret must be enabled for it to be used in Identity Cloud configuration.

The following rules prevent a secret from having no enabled secret versions:

When you create a secret, the first secret version of the secret is automatically created and is enabled.
You cannot disable the latest secret version of a secret.
You cannot delete the latest secret version of a secret if the previous secret version is disabled.

Comparison of secrets and variables

esv variable secret comparison

ESV naming

ESV API naming convention

The names of secrets and variables need to be prefixed with esv- and can only contain alphanumeric characters, hyphens, and underscores; for example, esv-mysecret-1 or esv-myvariable_1. The maximum length, including prefix, is 124 characters.

ESV legacy naming convention and API compatibility

Before the introduction of the ESV API endpoints, if ESVs were defined on your behalf as part of the promotion process, they were prefixed with byos-. Identity Cloud uses compatibility behavior to let you still use these legacy ESVs. The compatibility behavior depends on how far the legacy ESVs were promoted through your tenant environments:

Development, staging, and production environments: If you promoted a legacy ESV to all your tenant environments, it will have been duplicated during the ESV migration process, so will be available in the API using the new esv- prefix.

For example, byos-myvariable123 will appear as esv-myvariable123. Scripts that reference the legacy ESV will still work; both byos-myvariable123 and esv-myvariable123 resolve to the same ESV.
Development and staging environments only: If you never promoted a legacy ESV to your production environment, it will have been ignored during the ESV migration process. However, you can still use the ESV API to create it in your production environment, as the compatibility behaviour looks for new ESVs that have a naming format like a legacy ESV (byos-<hash>-<name>). So any ESVs that are created with a naming format of esv-<hash>-<name> will also automatically create a byos-<hash>-<name> duplicate.

For example, creating a new ESV called esv-7765622105-myvariable will automatically create another ESV called byos-7765622105-myvariable. Scripts that reference the legacy ESV will still work; both byos-7765622105-myvariable and esv-7765622105-myvariable resolve to the same ESV.

ESV descriptions

ESVs have a description field. This lets you provide further information on how and where to use an ESV.

Define and promote ESVs

An example of using a variable would be to define a URL that a user is redirected to after logging in. In each environment, the URL would need a different value; for example, dev-www.example.com (development), staging-www.example.com (staging), and www.example.com (production).

To define and promote the variable:

Decide on a variable name; for example, esv-myurl. See ESV naming.
Set a variable in each of the development, staging, and production environments. To do this, choose one of the following options:
- Use the variable API endpoint to create the variable, then use the restart API endpoint to restart Identity Cloud services.
- Use the Identity Cloud Admin UI to create the variable, then apply the update.

Make a development environment promotion request to insert a corresponding placeholder into the environment configuration and promote it to your development environment. You will need to specify which part of the environment configuration to insert the placeholder; for example, in the authentication settings. Following the example above, this placeholder would be called &{esv.myurl}.

ESV placeholders can only be inserted into static configuration. See the promotion FAQs for more information on what static configuration is, and which areas of configuration are classified as static.

It is not yet possible to use the API or UI to define where an ESV should be inserted into environment configuration. This functionality will be available at a later date.

Test that the variable is working correctly in your development environment. If an update is necessary, choose one of the following options:
- Use the variable API endpoint to update the variable, then use the restart API endpoint to restart Identity Cloud services.
- Use the Identity Cloud Admin UI to update the variable, then apply the update.
Make a promotion request to promote the placeholders to your staging environment.
Test your staging environment as described in step 4.
Make a promotion request to promote the placeholders to your production environment.
Test your production environment as described in step 4.

The following illustration demonstrates the process:

esv set variable