Identity Cloud

Introduction to self-service promotions


Identity Cloud lets you run self-service promotions to move configuration between a sequential pair of tenant environments; either from the development environment to the staging environment (staging promotion), or from the staging environment to the production environment (production promotion).

Non-sequential promotions (between the development environment and the production environment) are not supported.

You can run promotions using the following options:


The following videos summarize the concepts and processes of self-service promotions.

The Identity Cloud configuration model

How are configuration promotions changing?

Migrating to self-service promotions

Lower and upper environments

The environments in a sequential pair of environments are referred to as the lower environment (the configuration source), and the upper environment (the configuration destination); the terms lower environment and upper environment therefore refer to different environments, depending on whether you are running a staging promotion or a production promotion:

Development environment Staging environment Production environment

Staging promotion

(configuration source)

(configuration destination)

Production promotion

(configuration source)

(configuration destination)

Environment locking

Locking an environment prevents configuration changes that could disrupt a promotion. However, all authentication flows continue to work as normal.

Before you run a promotion, you must lock the lower and upper environments. This prevents anyone else from locking either of those environments, which ensures only one promotion can be run at the same time in the same set of development, staging, and production environments.

Locking the lower and upper environments also blocks access to the ESV API in those environments. This prevents anyone else from accidentally disrupting the promotion by manipulating ESV configuration values. If the lower environment is also the development environment, then most Identity Cloud API endpoints are also restricted.

When a promotion is complete, you must unlock the lower and upper environments to return the environments back to full functionality.

Configuration integrity checks

When you run a promotion, Identity Cloud performs integrity checks on your static configuration to protect the stability of the upper environment.

Integrity check for missing ESVs

This integrity check looks for ESVs referenced in your static configuration, but not set in the upper environment.

Identity Cloud runs this integrity check on the whole configuration, not just promoted configuration.

Integrity check for encrypted secrets

This integrity check looks for encrypted secrets embedded directly in your static configuration. It is best practice to store encrypted secrets in an ESV secret and update your configuration to reference the ESV secret instead.

Identity Cloud runs this integrity check on the whole configuration, not just promoted configuration.

Promotion process FAQs (self service)

Can I partially promote configuration? Or promote the configuration for an individual realm?

ForgeRock promotes configuration for the whole environment, so promotions always include all realms and all other static configuration. It is therefore not possible to promote partial configuration of any kind between environments, or promote the configuration for an individual realm between environments.

What kind of configuration changes can my company make?

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

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

Most dynamic configuration is not promotable, with the following exceptions:

  • SAML v2.0 applications. These are promoted as they are associated with dashboard static configuration.

  • OAuth 2.0 applications. These can be optionally promoted using the UI.

Static configuration

Static configuration changes occur only when authorized administrators make changes in the development environment, or when configuration changes get promoted to another environment.

All static configuration is promotable.

The following tables summarize the types of configuration changes possible:

Identity Cloud UI Configuration

Feature Dynamic
(not promoted)

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)

Password policy

AM Configuration

Feature Dynamic
(not promoted)

Applications > Agents

  • IG Agent

  • Java Policy Agents

  • Web Policy Agents

Applications > Federation

  • Circle of Trust

  • SAML v2.0 Entity Provider

Applications > OAuth 2.0 (excluding scripts)

  • Clients

  • Remote Consent

  • Software Publisher

  • Trusted JWT Issuer

(API promotions)

(UI promotions)


  • 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
(not promoted)

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 configuration 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:
    Gateways and Agents

  • Access policies:
    AM policy sets and resource types

All other configuration can be 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.

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

  • Changes take effect immediately.

Static configuration
  • You make changes in your development environment.

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

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. You can then promote that configuration to staging and production environments.

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

How long does the promotion process take?

Promotions normally take 10–45 minutes.

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 Define and promote an ESV for an explanation of how this type of configuration is handled.

Copyright © 2010-2023 ForgeRock, all rights reserved.