PingOne Advanced Identity Cloud

Manage self-service promotions using the UI

For background on self-service promotions in PingOne Advanced Identity Cloud, learn more in Introduction to self-service promotions.

Lower and upper environments

Before you run a promotion using the UI, you must know which tenant environment is the lower environment and which is the upper environment. Learn more in Lower and upper environments.

The UI uses a push model to promote configuration, so you need to run a promotion from the UI in the lower environment. However, you also need to have a tenant administrator account in the upper environment, as the UI in the lower environment needs to authenticate to the upper environment.

When a promotion is complete, you can view a report in the lower environment. You can also view the report in the upper environment.

Promotions UI functionality in the lower environment

In the lower environment, the promotions UI lets you:

  • View changes awaiting promotion to the upper environment

  • Promote changes to the upper environment

  • View history of promotions sent to the upper environment

This lower environment functionality exists in your development and staging environments only. It does not exist in your production environment, as that environment does not send promotions to another environment.

View changes awaiting promotion to the upper environment

  1. In the Advanced Identity Cloud admin UI of the lower environment, open the TENANT menu (upper right)

  2. Click Promote configuration to open the Promotion tab in the Tenant Settings page.

  3. The Promotion tab shows the following information:

    1. A summary of the promotion status for the environment:

      1. Your development environment shows information about promoting from your development environment to your staging environment:

        idcloudui promotion summary development

        If you have a UAT[1] environment, your development environment promotes to your UAT environment instead. The revised promotion order is development → UAT → staging. If you have a second UAT environment, the revised promotion order is development → UAT → UAT2 → staging.

        Learn more in Additional UAT environments.

      2. Your staging environment shows information about promoting from your staging environment to your production environment:

        idcloudui promotion summary staging

    2. A summary of any changes to static configuration made by you or other tenant administrators.

      For example, in the screenshot below, the UI indicates that two configuration changes have been made—one to a journey and one to an email template:

      idcloudui promotion view changes development

Sign in to the upper environment

When you run a promotion or view promotion history, the UI in the lower environment shows a sign-in screen for the upper environment. This lets the UI in the lower environment authenticate to the upper environment using your upper environment tenant administrator account.

In your development environment, the sign-in screen title is Sign in to Staging:

idcloudui promotion screen title sign in development

In your staging environment, the sign-in screen title is Sign in to Production:

idcloudui promotion screen title sign in staging

If you have a UAT[1] environment, your development environment shows a sign-in screen to your UAT environment instead. Learn more in Additional UAT environments.

To sign in:

  1. Check your browser settings:

    1. Ensure your browser has third-party cookies enabled for your tenant domain:

    2. Ensure your browser is not in incognito mode.

    If your browser does not have third-party cookies enabled or is in incognito mode, authentication to the upper environment will fail without an error message and redisplay the sign-in screen.

  2. Click Sign in to Staging (from your development environment) or Sign in to Production (from your staging environment) to open a pop-up browser window showing the sign-in screen for the upper environment:

    1. Enter the credentials of your tenant administrator account for the upper environment.

    2. Click Next.

    3. Complete the authentication journey to the upper environment:

      • If 2-step verification is already enabled for your tenant administrator account, follow the UI prompts to provide your second authentication factor.

      • If 2-step verification is not yet enabled for your tenant administrator account:

        1. Click Set up.

        2. Follow the UI prompts to set up a second authentication factor for your tenant administrator account.

        3. Follow the UI prompts to provide your second authentication factor.

      • Otherwise, if 2-step verification is not mandatory in the upper environment, you can click Skip for now to defer the setup of 2-step verification.

    4. After you have successfully authenticated, the pop-up browser window closes automatically.

Promote changes to the upper environment

  1. In the Advanced Identity Cloud admin UI of the lower environment, open the TENANT menu (upper right)

  2. Click Promote configuration.

  3. Review the static configuration changes that are awaiting promotion. Learn more in View changes awaiting promotion to the upper environment.

    If there are any scripts awaiting promotion, ensure that they do not emit any personally identifiable information (PII) of your end users into Advanced Identity Cloud logs.

    Ping Identity recommends that you establish a review and testing process for all scripts to prevent PII leaking out of your Advanced Identity Cloud tenant environments.

  4. Click Promote n Changes.

  5. If the UI shows a sign-in screen for the upper environment, follow the steps in Sign in to the upper environment.

  6. In the Lock Tenants? screen, click Lock and Continue to lock the lower and upper environments.

    idcloudui promotion lock tenants development

    Allow 1–2 minutes for the locking process to complete. When the environments are locked, the UI has restricted functionality.

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

  7. In the Review Promotion screen, check the static configuration changes that are awaiting promotion.

    • If you want to cancel the promotion:

      1. Click Cancel Promotion.

      This unlocks the lower and upper environments. Allow 1–2 minutes for the unlocking process to complete.

    • If you want to proceed with the promotion:

      1. Click Start Promotion

      2. In the Start Promotion? modal window:

        1. If your static configuration contains directly embedded encrypted secrets that you have yet to store in ESVs, check Ignore Encrypted Secrets to bypass the integrity check for encrypted secrets.

        2. Click Start Promotion again.

      This promotes the static configuration changes from the lower environment to the upper environment. At the end of the promotion process, Advanced Identity Cloud services are restarted in the upper environment, and both environments are automatically unlocked. Allow 10–45 minutes for these combined processes to complete.

      If the UI shows an error message during the promotion process, learn more in the following:

  8. When the promotion completes you have a choice of actions:

    • Click View report to view the promotion immediately in the promotion history.

    • Click Done to return to the Promotion tab.

      idcloudui promotion success

View history of promotions sent to the upper environment

  1. In the Advanced Identity Cloud admin UI of the lower environment, open the TENANT menu (upper right)

  2. Click Promote configuration.

  3. Click View promotion history.

  4. If the UI shows a sign-in screen for the upper environment, follow the steps in Sign in to the upper environment.

  5. In the Promotion History page, click a promotion date in the left menu to review a report:

idcloudui promotion history development

Promotions UI functionality in the upper environment

In the upper environment, the promotions UI lets you:

  • View a history of promotions received from the lower environment

This upper environment functionality exists in your staging and production environments only. It does not exist in your development environment, as that environment does not receive promotions from another environment.

View history of promotions received from the lower environment

  1. In the Advanced Identity Cloud admin UI of the upper environment, open the TENANT menu (upper right)

  2. Click Tenant settings.

  3. Click the Details tab.

  4. Click View updates.

  5. In the Tenant Updates page, click a promotion date in the left menu to review a report.

Learn more in the screenshot in View history of promotions sent to the upper environment.

Restricted functionality

When you run a promotion and lock the upper and lower environments, the UI restricts some functionality under Tenant Settings > Promotion until the environments are unlocked.

Restricted functionality in the lower environment

In the lower environment, the UI has the following restricted functionality:

  • The left menu is hidden.

  • The page header shows Tenant Locked on the left.

  • The page header shows a restricted drop-down list on the right.

idcloudui promotion review development

If you sign out and immediately sign back in, you are redirected back to Tenant Settings > Promotion.

Other tenant administrators who are logged in and working in other parts of the UI do not have this restricted functionality. They and are not redirected to Tenant Settings > Promotion unless they sign out and immediately sign back in while the upper and lower environments are locked.

Restricted functionality in the upper environment

In the upper environment (staging environment only), the UI has the following restricted functionality:

  • The Promote n Changes button is disabled to prevent you from initiating a separate promotion.

idcloudui promotion summary tenant locked staging

Troubleshooting

Resolve failed integrity check for missing ESVs

When you run a promotion, the UI may show an error message that you have missing ESVs:

idcloudui promotion error esvs

This happens when the upper environment failed an integrity check for missing ESVs.

To resolve this:

  1. Click Download Report to download a CSV report of the affected configuration.

  2. Click Cancel and Unlock Tenants. This unlocks the lower and upper environments. Allow 1–2 minutes for the unlocking process to complete.

  3. For each ESV in the report, create an equivalent ESV in the upper environment.

  4. Start the promotion steps again.

Resolve failed integrity check for encrypted secrets

When you run a promotion, the UI may show an error message that you have encrypted secrets in your configuration:

idcloudui promotion error encrypted secrets

This happens when your lower environment configuration failed an integrity check for encrypted secrets.

To resolve this:

  1. Click Download Report to download a CSV summary of the affected configuration.

  2. Click Cancel and Unlock Tenants. This unlocks the lower and upper environments. Allow 1–2 minutes for the unlocking process to complete.

  3. For each encrypted secret in the report:

    1. Create an ESV secret containing the encrypted secret in each of the development, staging, and production environments.

    2. Update your configuration to reference the new ESV secret.

  4. Start the promotion steps again.

Resolve tenant locked errors

When you run a promotion, the UI may show an error message that your tenant is locked:

idcloudui promotion error tenant locked

This happens when a previous promotion failed and left the environments in an error state that cannot be automatically resolved.

To resolve environment errors that are preventing a promotion or a rollback submit a support ticket:

  1. Open a How-To ticket with Backstage Support.

  2. On the How Do I...? page, provide values for the following fields:

    Field Value

    Product

    Select the following from the lists:

    • PingOne Advanced Identity Cloud

    • Tenant Settings

    • Self-Service Promotion

    What are you trying to achieve?

    Enter one of the following:

    • Resolve environment errors preventing a self-service promotion

    • Resolve environment errors preventing a self-service rollback

    Please provide a short description

    Enter one of the following:

    • An error has occurred during a self-service promotion to the development/staging/production environment.

    • An error has occurred during a self-service rollback from the staging/production environment.

    Enter the error code and message (API users only).

  3. Click Submit.

Revert a promotion

You can revert a promotion using the API. Learn more in Run a rollback.

Revert configuration in your development environment

To revert configuration in your development environment, submit a support ticket:

  1. Open an Identity Cloud: Config request with Backstage Support.

  2. On the Advanced Identity Cloud: Config Request page, provide values for the following fields:

    Field Value

    Hostname

    Enter the FQDN of the upper environment from the promotion you need to revert.

    What would you like to do?

    Select Restore from backup

  3. In the Restore from backup section, provide values for the following fields:

    Field Value

    What is the environment name?

    Select Dev.

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

    Enter the date when you last had stable configuration, using the format YYYY-MM-DD.

  4. Click Submit.