Identity Cloud

Use ESVs in configuration placeholders

Overview

Identity Cloud lets you reference ESVs from configuration placeholders. This lets you use different configuration values for the development, staging, and production environments at run time.

For example, suppose you wanted to set a different email sender for each environment. You could set the configuration value of the email sender to an ESV, with different values in each environment; for example, dev-mycompany@example.com (development), staging-mycompany@example.com (staging), and mycompany@example.com (production).

Identity Cloud does not yet support the ability to define where placeholders should be inserted into your configuration. Instead, you must use a promotion request.

The functionality to insert placeholders into your configuration using the API and the UI will be available later this year.

Secrets and variables that are defined in configuration placeholders, but have no corresponding ESV set, will cause promotions to fail.

Set up configuration placeholders to reference ESVs

To set up configuration placeholders to reference ESVs, first create the ESVs using the Identity Cloud API or the Identity Cloud admin UI:

Then, use a series of promotion requests. Initially, create a development environment promotion request; this will add placeholders into your configuration and promote them to your development environment. Later, use further promotion requests to promote the placeholders to your staging and production environments.

If you wish to add more ESVs later, you will need to create an additional series of promotion requests.

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

Update ESVs referenced by configuration placeholders

If you update an ESV that is referenced by a configuration placeholder, you also need to restart Identity Cloud services; this will substitute updated secrets and variables into the corresponding configuration placeholders:

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:

  1. Decide on a variable name; for example, esv-myurl. See tenants/esvs.adoc#esv_naming.

  2. Set a variable in each of the development, staging, and production environments. To do this, choose one of the following options:

  3. Submit 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. For the example variable esv-myurl from step 1, this placeholder would be called &{esv.myurl}.

    Configuration 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 the UI to define where a placeholder should be inserted into your configuration. This functionality will be available at a later date.
  4. Test that the variable is working correctly in your development environment. If an update is necessary, choose one of the following options:

  5. Submit a promotion request to promote the placeholders to your staging environment.

  6. Test your staging environment as described in step 4.

  7. Submit a promotion request to promote the placeholders to your production environment.

  8. Test your production environment as described in step 4.

The following illustration demonstrates the process:

image$esv set variable

Copyright © 2010-2022 ForgeRock, all rights reserved.