Manage ESVs

Overview

For background on ESVs, see Environment Secrets and Variables (ESVs).

Set up your tenant environments

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

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.
If you wish to add more ESVs later, you will need to create an additional series of promotion requests.

Configure your tenant environments

To configure ESVs in each of your tenant environments, set secrets and variables that correspond to each of the placeholders. Then, restart Identity Cloud services; this will substitute secrets and variables into the corresponding configuration placeholders.

You can use the Identity Cloud API or the Identity Cloud Admin UI:

Configure ESV using API

ESV API endpoints

To use the API, see the following Identity Cloud API endpoints:

To authenticate to the API, see Authenticate to ESV API endpoints.

Authenticate to ESV API endpoints

To authenticate to ESV API endpoints, use an access token.

In addition to the default fr:idm:* OAuth scope, there are several additional OAuth scopes that can be used with the ESV API endpoints when you create an access token:

Scope Description

fr:idc:esv:*

Read, create, update, delete, and restart access to ESV API endpoints.

fr:idc:esv:read

Read access to ESV API endpoints.

fr:idc:esv:update

Create, update, and delete access to ESV API endpoints.

fr:idc:esv:restart

Restart access to ESV API endpoints.

Configure ESV using Identity Cloud Admin UI

Create variables

  1. In the Identity Cloud Admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Variables tab.

  3. Click the + Add Variable button.

  4. In the Add a Variable modal window, enter the following information:

    Name

    Enter a variable name. See ESV naming.

    Variable names cannot be modified after the variable has been created.

    Description

    (optional) Enter a description of the purpose of the variable.

    Value

    Enter a variable value.

    If the variable value is JSON, you can optionally click the JSON toggle to turn on JSON validation. You can find the toggle above the top right of the field.

  5. Click Save to create the variable.

Update variables

  1. In the Identity Cloud Admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Variables tab.

  3. Find a variable in the paginated list of variables, then click the + Update button for that variable.

  4. In the Update Variable modal window:

    • At the top, you can optionally click Add a Description to update the variable description:

      1. Click the Add a Description link to open a secondary modal.

      2. In the Edit Variable Description secondary modal window, enter the following information:

        Description

        Enter a new or updated description of the purpose of the variable.

      3. Click Save Description to update the variable description and close the secondary modal.

    • Below that, you will see the read-only Configuration Placeholder field. The placeholder value is derived from the variable name. You can optionally use the clipboard widget to copy the placeholder value.

    • Below that, you can optionally click Edit to update the variable value:

      1. Click the Edit link to open a secondary modal.

      2. In the Edit Variable Value secondary modal window, enter the following information:

        Value

        Enter a new variable value.

        If the variable value is JSON, you can optionally click the JSON toggle to turn on JSON validation. You can find the toggle above the top right of the field.

      3. Click Save Value to update the variable value and close the secondary modal.

  5. Click Done to close the modal.

Create secrets

  1. In the Identity Cloud Admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Secrets tab.

  3. Click the + Add Secret button.

  4. In the Add a Secret modal window, enter the following information:

    Name

    Enter a secret name. See ESV naming.

    Secret names cannot be modified after the secret has been created.

    Description

    (optional) Enter a description of the purpose of the secret.

    Value

    Enter a secret value.

    The field obscures the secret value by default. You can optionally click the visibility toggle () to view the secret value as you enter it.

    If the variable value is JSON, you can optionally click the JSON toggle to turn on JSON validation. You can find the toggle above the top right of the field.

    The initial secret value is used to create the first secret version for the secret.
  5. Click Save to create the variable.

Update secrets

  1. In the Identity Cloud Admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Secrets tab.

  3. Find a secret in the paginated list of secrets, then click the + Update or Updated button for that secret.

  4. In the Update Secret modal window:

    • At the top, you can optionally click Add a Description to update the secret description:

      1. Click the Add a Description link to open a secondary modal.

      2. In the Edit Secret Description secondary modal window, enter the following information:

        Description

        Enter a new or updated description of the purpose of the secret.

      3. Click Save Description to update the secret description and close the secondary modal.

    • Below that, you will see the read-only Configuration Placeholder field. The placeholder value is derived from the secret name. You can optionally use the clipboard widget to copy the placeholder value.

    • Below that, you will see the secret versions interface, which shows a paginated list of secret versions for the secret:

      idcloudui esv secrets manage versions

      See Secret versions for more information about the rules on enabling, disabling, and deleting secret versions.
      1. To add a new secret version, click + New Version to open a secondary modal.

      2. In the Create a New Secret Version secondary modal window:

        1. At the top, you will see the readonly Secret field, which contains the secret name.

        2. Below that, enter the following information:

          Value

          Enter a secret value.

          The field obscures the secret value by default. You can optionally click the visibility toggle () to view the secret value as you enter it.

          If the variable value is JSON, you can optionally click the JSON toggle to turn on JSON validation. You can find the toggle above the top right of the field.

        3. Then, click the + Add Version button to create the secret version and close the secondary modal.

      3. The new secret version should now be visible at the top of the the secret versions interface:

        idcloudui esv secrets manage versions updated

      4. Click Done to close the modal.

Apply updates

When one or more ESVs have been created or updated by any of the tenant administrators, the ESV entry screen will display a blue banner at the top to tell you how many updates are waiting to be applied:

idcloudui esv apply updates banner

Before you apply any updates, ensure that you have made all the ESV changes that you need, as applying the updates will disable the ESV UI for the next 10 minutes and prevent further ESV changes. This behavior will apply to all tenant administrators.

To apply any pending updates:

  1. Click the View Updates button.

  2. In the Pending Updates modal, review the list of ESVs that have been updated, then click Apply n Updates.

  3. In the Apply n Updates? confirmation modal, click the Apply Now button.

  4. The banner will change color from blue to orange while the updates are applied, and the ESV UI will be disabled. This behavior will apply to all tenant administrators.

    idcloudui esv apply updates banner in progress

  5. When the update is complete, the banner will no longer be visible, and the ESV UI will be enabled again.