Promote Configuration

Overview

The Identity Cloud promotion process lets you move your configuration changes securely from one tenant environment to another.

For more background on tenant environments and promotions, see Tenant Environments.

To promote configuration changes

  1. Go to the Backstage website, and click Support.

  2. On the ForgeRock Support page, click New Ticket.

  3. On the New Ticket page, choose Identity Cloud: Config Request.

  4. In the Request Type dialog box, provide:

    • Hostname: Enter the your tenant FQDN.
      Example: <TenantName>-<Region>-<CompanyName>.forgerock.io.

    • What would you like to change?

      • Choose Move configuration if you want to promote configuration from Development to Staging, or from Staging to Production.

        What is the target environment for the promotion?

        Choose the option that best describes both the source and target of your promotion.

        Who is the primary contact?

        Provide the first and last name of a person authorized to communicate with ForgeRock staff regarding this promotion request.

        What would you like to change?

        Enter a brief description.
        Examples: Custom domain name, Scripts, An environment variable

      • Choose Restore from backup if you want to revert to a previous backup configuration.

        What is the environment name?

        Choose Development, Staging, or Production.

        What is the date of the backup you would like to restore from?

        Enter a date using the format YYYY-MM-DD.
        For example, to indicate December 31, 2021, enter 2021-12-31.
        The Support team restores the most recent backup taken before the date you specify.

  5. Click Submit.

ForgeRock promotes one step at a time. We’ll ask you to check and confirm the staging environment status before we promote the configuration to the production environment.

Promotion process FAQs

What kind of configuration changes can my company make?

For the purposes of promotion, ForgeRock draws a clear line between dynamic and static configuration.

Dynamic configuration changes occur automatically when your application end users use Identity Cloud features. For example, when they configure applications or add users in the Identity Cloud Admin UI, the changes take effect immediately in the development, staging, or production environments.

Static configuration changes occur only when authorized administrators make changes in the development environment, or when configuration changes get promoted to another environment. Only ForgeRock SREs can promote static configuration from development to staging and production environments.

The following tables summarize the types of configuration changes possible, and whom you can authorize to make changes:

Identity Cloud UI Configuration

Feature Administrators & end users
(devops)
ForgeRock SREs
(promotion)

Custom domain names

  • DNS aliases

  • FQDN mappings

  • Cookie domains

  • Base URL service

Gateways & Agents

  • Native/SPA

  • Web (node.js, Java)

  • Service (m2m)

Journeys

Identities

  • Connect (Connector Server)

  • Connect (Server Cluster)

AM Configuration

Feature Administrators & end users
(devops)
ForgeRock SREs
(promotion)

Applications > Agents

  • IG Agent

  • Java Policy Agents

  • Web Policy Agents

Applications > Federation

  • Circle of Trust

  • SAML2 Entity Provider

Applications > OAuth 2.0 (excluding scripts)

  • Clients

  • Remote Consent

  • Software Publisher

  • Trusted JWT Issuer

Password policy (created from Identity Cloud UI)

Authentication trees

Authorization

  • Policy sets

  • Resource types

Scripts (all)

Services (per realm)

  • OAuth 2.0 provider

  • Social IdP services

  • Policy configuration

  • Base URL source

IDM Configuration

Feature Administrators & end users
(devops)
ForgeRock SREs
(promotion)

Managed objects

Sync mappings

Connector mappings

Roles & assignments

Email notifications

How do we determine what is static and dynamic configuration?

ForgeRock considers all configuration static, except for the two types of config data that may be changed at runtime: applications and access policies. These config data types can be created on the fly, and can be used immediately afterwards.

Applications represented by OAuth2 clients can be registered at runtime through the Dynamic Client Registration Protocol. Access policies are created every time an end user shares access to a resource.

ForgeRock recognizes that other types of applications or access policies might not change at runtime. But ForgeRock products handle each data class consistently, so we can leverage potential usage patterns in the future.

What exactly is promoted and what is not?

These artifacts are NOT promoted. They remain unchanged during the promotion process:

  • Identities:
    Users, things, admins, roles, and assignments

  • Applications:
    Connectors, Agents, Federations, OAuth2 clients (using the Applications Admin UI), Gateways and Agents

  • Access policies:
    AM policy sets and resource types

All other configuration is promoted between environments.

How do I manage configuration?

You have the choice of using the Identity Cloud Admin UI, or using the REST APIs for configuration.

Static configuration
  • You make changes in your development environment.

  • ForgeRock SREs promote it to staging or production when you are ready.

Dynamic configuration
  • You configure applications and add users in your development, staging and production environments.

  • Changes take effect immediately.

What if I need to roll back a configuration?

ForgeRock can roll back static configuration for you. Configuration data is maintained in Git repositories within your environment. So, configuration data can be restored as a whole to previous settings.

When you request a rollback, ForgeRock reverts your development environment to the point in time you specify. ForgeRock can then promote that configuration to staging and production environments when confirmed by you.

Dynamic configuration is not altered when rolling back in this way. Users, applications, and access policies remain as they are.

Follow the instructions to promote configuration changes. In the Request Type dialog box, choose Restore from backup.

What if some configuration attributes must vary per environment?

We understand that sometimes you have to use a configuration attribute value that is not identical across development, staging, and production environments. For example, you might need one set of credentials for an external service in the development environment, but a different set of credentials in the production environment.

In cases like this, follow these steps:

  1. Go to the Backstage website, and click Support.

  2. On the ForgeRock Support page, click New Ticket.

  3. On the New Ticket page, choose Identity Cloud: Config Request.

  4. In the Request Type dialog box, provide:

    • Hostname: Enter the your tenant FQDN.
      Example: <TenantName>-<Region>-<CompanyName>.forgerock.io.

    • What would you like to change?
      Choose Move configuration.

      What is the target environment for the promotion?

      Choose the option that best describes both the source and target of your promotion.

      Who is the primary contact?

      Provide the first and last name of a person authorized to communicate with ForgeRock staff regarding this promotion request.

      What would you like to change?

      Enter a brief description.
      Examples: An environment variable

      •   Enter the name and path to the attribute that will be different among environments. •   Specify an attribute value to be used in each environment: Development, Staging, and Production.
      At least one of these should be different from the others.
      •   (Optional) You can supply the values in encrypted form.

  5. Click Submit.

ForgeRock temporarily locks your environment while we add the value to the platform configuration, and configure the values for each environment.

Once completed, we’ll ask you to verify that the platform is still working as you expect it to work.

How do I ask ForgeRock to move configuration for me?

Follow the instructions in the section To promote configuration changes.

ForgeRock promotes one step at a time. We’ll ask you to check and confirm the staging environment status before we promote the configuration to the production environment.

How long does the promotion process take?

Promotion normally takes 2 hours, and is carried out by the end of the next business day. ForgeRock prevents changes to the development environment while promotion is in progress.

Why did I receive a notification about embedded secrets? What do I do?

During the promotion process, Identity Cloud detects the presence of secrets embedded in your configuration. Authorization passwords and authentication signing keys are examples of secrets that might exist in your configuration.

Secrets are encrypted with a different key per environment. For example, in your development environment, if Identity Cloud detects secrets in your Login node and PushNotifications service node, then the secrets won’t work in your staging environment.

You’ll have to securely transfer the secrets values to the Support team. Then, the Support team adds the secrets to the staging environment for you.

To make the transfer, the Support team will provide a process for supplying the secrets in encrypted form over email. Through this exchange, the Support team will guide you through the transfer process.

At each step, a Support member will provide you with command-line examples to:

  • Present your authorization credentials to the Support team for validation.

  • Create a local working space for your secrets file.

  • Encrypt your secrets values.

  • Securely transfer the secrets to the Support team.

  • Remove all sensitive information from your workstation.

To get started, follow these steps:

  1. Create a local file containing the plaintext values of your embedded secrets.

  2. Download and install GNU Privacy Guard (GPG).

  3. Create a Support ticket.

    1. In the field "What Do You Want to Change?", indicate that you want to transfer secrets to a new environment.

    2. Submit the Support ticket.

A Support team member will contact you and provide instructions for the first step in the process. The Support team will provide detailed instructions when you need them at each step in the process.