Identity Cloud

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

&{esv.my.variable}


(requires restart)

Scripts

systemEnv.getProperty("esv.my.variable") (AM)
identityServer.getProperty("esv.my.variable") (IDM)

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

&{esv.my.secret}


(requires restart)

Scripts

systemEnv.getProperty("esv.my.secret") (AM)
identityServer.getProperty("esv.my.secret") (IDM)

Signing and encryption keys

Map to secret ID

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

generic

Use this format for secrets that are not keys, such as passwords.

pem

Use this format for asymmetric keys; for example, a public and private RSA key pair. See Generate an RSA key pair.

base64hmac

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:

  1. From configuration placeholders; see Use ESVs in configuration placeholders.

  2. From scripts; see Use ESVs in scripts.

  3. 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

useInPlaceholders = true

useInPlaceholders = false

Configuration placeholders

  • Secret accessible

  • Uses latest secret version

  • Restart of Identity Cloud services required

  • Secret not accessible

Scripts

  • Secret accessible

  • Uses latest secret version

  • Restart of Identity Cloud services not required

Mapped secret IDs

  • Secret accessible

  • Uses all enabled secret versions

  • Restart of Identity Cloud services not required
You can only set restricted access using the API. The UI currently creates secrets only with unrestricted access.

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 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 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.

Copyright © 2010-2022 ForgeRock, all rights reserved.