Promote Configuration


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

For more background on tenant environments, 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>

    • What would you like to do?

      • Choose Configuration promotion if you want to promote configuration, or if you want to add new ESV placeholders to your development environment configuration.

        What is the target environment for the promotion?

        Choose the option that best describes the target of your promotion.

        • Dev

        • Dev → Staging

        • Staging → Prod

        Who is the primary contact?

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

        Are there any "Environment Secrets and Variables"?

        If the promotion has a feature that requires variables or secrets, add the following to the description for each variable or secret:

        • Enter the secret or variable name set in advance.

        Secrets and variables can be managed using the following options:

        • Enter the name and path to the corresponding environment configuration attribute for the promoted feature.

      • 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 Dynamic

Custom domain names

  • DNS aliases

  • FQDN mappings

  • Cookie domains

  • Base URL service

Gateways & Agents

  • Native/SPA

  • Web (node.js, Java)

  • Service (m2m)


Custom themes


  • Connect (Connector Server)

  • Connect (Server Cluster)

AM Configuration

Feature Dynamic
ForgeRock SREs

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


  • Policy sets

  • Resource types

Scripts (all)

Services (per realm)

  • OAuth 2.0 provider

  • Social IdP services

  • Policy configuration

  • Base URL source

IDM Configuration

Feature Dynamic

Managed objects

Connector configurations

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

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. Promotions occur during GMT business hours, and US Central time business hours Monday-Friday excluding ForgeRock holidays. ForgeRock prevents changes to the development environment while promotion is in progress.

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.

See Environment Secrets and Variables (ESVs) for an explanation of how this type of configuration is handled, then follow the process in To promote configuration changes.

Can I promote the configuration for an individual Alpha or Bravo realm?

ForgeRock promotes configuration at the environment level, so promotions always include both realms. It is therefore not possible to promote the configuration for an individual Alpha or Bravo realm between environments.