PingOne Advanced Identity Cloud

ESVs

Environment secrets and variables (ESVs) let you individually configure your sandbox[1], development, UAT[2], staging, and production tenant environments in PingOne Advanced Identity Cloud.

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 Advanced Identity Cloud only feature. In particular, ESV secrets should not be confused with secrets in the self-managed AM or IDM products.

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. The value of a variable must not exceed a maximum length of 65535 bytes (just under 64KiB).

You can reference ESV variables from configuration placeholders or scripts after you have:

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}

Learn more in Configure placeholders to use with ESVs.


(requires restart)

Scripts

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

Learn more in Use ESVs in scripts.


(requires restart)

Variable types

You must use the expressionType parameter to set a type when you create an ESV variable. This lets Advanced Identity Cloud correctly transform the value of the ESV to match the configuration property type when substituting it into configuration.

The type is set when the ESV is created, and it cannot be modified.

Before the expressionType parameter was introduced, it was only possible to set types from within configuration, using expression level syntax; for example, {"$int": "&{esv.journey.ldap.port|1389}"}. The expressionType parameter supplements this expression level syntax and allows the ESV type to be identified without inspecting configuration.

Make sure the type that you set in configuration matches the type that you set in the ESV expressionType parameter.
Expression type Description Examples

string

String value (default)

Name

esv-email-provider-from-email

Placeholder

{"string": "&{esv.email.provider.from.email}"}
or
&{esv.email.provider.from.email}

Value

example@forgerock.com

array

JSON array

Name

esv-cors-accepted-origins

Placeholder

{"$array": "&{esv.cors.accepted.origins}"}

Value

["http://example.org", "http://example.com"]

Name

esv-provisioner-base-contexts

Placeholder

{"$array": "&{esv.provisioner.base.contexts}"}

Value

["dc=example,dc=com"]

object

JSON object

Name

esv-journey-welcome-description

Placeholder

{"$object": "&{esv.journey.welcome.description}"}

Value

{"en":"Example description","fr":"Exemple de description"}

bool

Boolean value

Name

esv-email-provider-use-ssl

Placeholder

{"$bool": "&{esv.email.provider.use.ssl}"}

Value

true

int

Integer value

Name

esv-email-provider-port

Placeholder

{"$int": "&{esv.email.provider.port}"}

Value

465

number

This type can transform any number value (integers, doubles, longs, and floats).

list

Comma-separated list

Name

esv-journey-ldap-servers

Placeholder

{"$list": "&{esv.journey.ldap.servers}"}

Value

userstore-0.userstore:1389,userstore-1.userstore:1389,userstore-2.userstore:1389
Ping Identity recommends using array type variables instead of list type variables. The two types are functionally equivalent, but the array type is more compatible with the UI.
Existing ESVs will be migrated to use the expressionType parameter. If any existing ESVs contain combined types, they will be split into separate ESVs by the migration process.

ESV variables in Advanced Identity Cloud global configuration

Ping Identity manages Advanced Identity Cloud global configuration on your behalf; however, the global configuration contains a single static ESV placeholder to let you override the default maximum size for SAML requests (20480 bytes). To override the default value of the static placeholder in any environment, create a new ESV variable with a corresponding name and a custom value:

Static placeholder

&{esv.global.saml.max.content.length|20480}

Default value

20480

ESV name to create

esv-global-saml-max-content-length

Possible values

Specify an integer

Learn more in https://backstage.forgerock.com/knowledge/kb/article/a37324869.

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.

You can reference ESV secrets from configuration placeholders or scripts after you have:

You can reference secrets that are signing and encryption keys by mapping them to secret labels. Secrets referenced by secret label mappings can be accessed as soon as the ESV is set; restarting Advanced Identity Cloud services is not required.

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}

Learn more in Configure placeholders to use with ESVs.


(requires restart)

Scripts

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

Learn more in Use ESVs in scripts.


(requires restart)

Signing and encryption keys

Map to secret label

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. The value of a secret version must not exceed a maximum length of 65535 bytes (just under 64KiB). To create a new secret version, its value must be different to the value of the latest secret version.

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. Learn more in 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. Learn more in Generate an RSA key pair.

base64aes

Use this format for AES keys; for example, an AES-256 key. Learn more in Generate an AES or HMAC key.

base64hmac

Use this format for HMAC keys; for example, a HMAC-SHA-512 key. Learn more in Generate an AES or 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; learn more in Configure placeholders to use with ESVs.

  2. From scripts; learn more in Use ESVs in scripts.

  3. From mapped secret labels (for signing and encryption keys); learn more in 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 Advanced Identity Cloud services required

  • Secret not accessible

Scripts

  • Secret accessible

  • Uses latest secret version

  • Restart of Advanced Identity Cloud services not required

Mapped secret labels

  • Secret accessible

  • Uses all enabled secret versions

  • Restart of Advanced 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

Preconditions to delete an ESV

Before you delete an ESV, you may need to remove references to it from your environment:

  • You cannot delete an ESV if it is referenced in a configuration placeholder. You must first remove the placeholder from configuration. Learn more in Delete an ESV referenced by a configuration placeholder.

  • You cannot delete an ESV if it is referenced in a script. You must first remove any scripts that reference the ESV.

  • You cannot delete an ESV if it is referenced in an orphaned script[3]. You must first remove any orphaned scripts. You can do this by running a self-service promotion (which automatically cleans up orphaned scripts).

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

1. A sandbox environment is an add-on capability.
2. A user acceptance testing (UAT) environment is an add-on capability.
3. Orphaned scripts are a legacy problem that can affect tenants that received support-assisted promotions before the introduction of self-service promotions.