Environment secrets and variables (ESVs)
Overview
ESVs let you individually configure the development, staging, and production environments in your Identity Cloud tenant.
Use variables to set 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 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.
ESVs are an Identity Cloud only feature. In particular, ESV secrets should not be confused with secrets in the self-managed AM or IDM products. |
ESVs
Variables
Use ESV variables to set configuration values that need to be different for each tenant environment.
Variables are simple key/value pairs. Unlike secrets, they are not versioned. They should not contain sensitive values.
Variables can be accessed from configuration placeholders or scripts. Variables referenced in configuration placeholders can be accessed only after you restart Identity Cloud services. Variables referenced in scripts can be accessed as soon as the ESV is set.
The following table shows how to reference an ESV variable with the name esv-my-variable
:
Context | How to reference | Access as soon as set |
---|---|---|
Configuration placeholders |
|
|
Scripts |
|
Secrets
Use ESV secrets to set configuration values that need encrypting. The values may or may not need to be different for each tenant environment.
Secrets can be accessed from configuration placeholders or scripts. Secrets referenced in configuration placeholders can be accessed only after you restart Identity Cloud services. Secrets referenced in scripts can be accessed as soon as the ESV is set.
Secrets that are signing and encryption keys can accessed by mapping them to secret IDs. Secrets referenced by secret ID mappings can be accessed as soon as the ESV is set.
The following table shows how to reference an ESV secret with the name esv-my-secret
:
Context | How to reference | Access as soon as set |
---|---|---|
Configuration placeholders |
|
|
Scripts |
|
|
Signing and encryption keys |
Secret versions
Instead of having a single value, ESV secrets have one or more secret versions, each containing their own value. By design, the value of a secret version cannot be read back after it 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 your configuration.
The following rules ensure that a secret always has at least one enabled version:
-
When you create a secret, the first version of the secret is automatically created and is enabled.
-
You cannot disable the latest version of a secret.
-
You cannot delete the latest version of a secret if the previous version is disabled.
Secret versions are an important feature of key rotation; see Rotate keys in mapped ESV secrets. |
Encoding format
You can use the encoding
parameter to set an encoding format when you create an ESV secret:
Encoding format | Description |
---|---|
|
Use this format for secrets that are not keys, such as passwords. |
|
Use this format for asymmetric keys; for example, a public and private RSA key pair. See Generate an RSA key pair. |
|
Use this format for symmetric keys; for example, a SHA-512 HMAC key. See Generate a HMAC key. |
You can only choose an encoding format using the API. The UI currently creates secrets only
with the generic encoding format.
|
Control access to secrets
There are 3 contexts where you can access an ESV secret:
-
From configuration placeholders; see Use ESVs in configuration placeholders.
-
From scripts; see Use ESVs in scripts.
-
From mapped secret IDs (for signing and encryption keys); see Use ESVs for signing and encryption keys.
However, if the secret contains a signing and encryption key, you may want to restrict access from
configuration placeholder and script contexts. To do this, you can use the useInPlaceholders
boolean parameter when you create the secret:
Context | Unrestricted access | Restricted access |
---|---|---|
|
|
|
Configuration placeholders |
|
|
Scripts |
|
|
Mapped secret IDs |
|
You can only set restricted access using the API. The UI currently creates secrets only with unrestricted access. |
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 development, staging, and production 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 asesv-myvariable123
. Scripts that reference the legacy ESV will still work; bothbyos-myvariable123
andesv-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 ofesv-<hash>-<name>
will also automatically create abyos-<hash>-<name>
duplicate.For example, creating a new ESV called
esv-7765622105-myvariable
will automatically create another ESV calledbyos-7765622105-myvariable
. Scripts that reference the legacy ESV will still work; bothbyos-7765622105-myvariable
andesv-7765622105-myvariable
resolve to the same ESV.