PingOne Advanced Identity Cloud

Tenant environments

Data residency

When you sign up for PingOne Advanced Identity Cloud, you specify the region where you want your data to reside. This is key in helping you meet data residency compliance requirements while letting you place data as close to your users as possible.

Advanced Identity Cloud uses pre-configured ranges of IP addresses in Google Cloud Platform (GCP) regions. The IP addresses are not exclusive to Ping Identity.

Regions

The tables in this section show all the region abbreviations for the data regions that Advanced Identity Cloud uses. The region abbreviations are used in the naming convention of your tenant environment FQDNs.

The tables also indicate secondary backup regions when available.

United States

Region Abbreviation Secondary backup region[1]

Oregon (us-west1)

usw1

A different region within the United States

Los Angeles (us-west2)

usw2

A different region within the United States

Iowa (us-central1)

usc1

A different region within the United States

South Carolina (us-east1)

use1

A different region within the United States

North Virginia (us-east4)

use4

A different region within the United States

Canada

Region Abbreviation Secondary backup region[1]

Montréal (northamerica-northeast1)

nane1

A different region within Canada

Brazil

Region Abbreviation Secondary backup region[1]

São Paulo (southamerica-east1)

sae1

Regional selection is available. For more information, please contact your Ping Identity representative.

Europe

Region Abbreviation Secondary backup region[1]

London (europe-west2)

ew2

A different region within Europe

Belgium (europe-west1)

ew1

A different region within Europe

Netherlands (europe-west4)

ew4

A different region within Europe

Zurich (europe-west6)

ew6

A different region within Europe

Frankfurt (europe-west3)

ew3

A different region within Europe

Finland (europe-north1)

en1

A different region within Europe

Paris (europe-west9)

ew9

A different region within Europe

Asia

Region Abbreviation Secondary backup region[1]

Singapore (asia-southeast1)

ase1

Regional selection is available. For more information, please contact your Ping Identity representative.

Jakarta (asia-southeast2)

ase2

Regional selection is available. For more information, please contact your Ping Identity representative.

Hong Kong (asia-east2)

ae2

Regional selection is available. For more information, please contact your Ping Identity representative.

Australia

Region Abbreviation Secondary backup region[1]

Sydney (australia-southeast1)

ausse1

A different region within Australia

 

Development, staging, and production tenant environments

Each PingOne Advanced Identity Cloud account includes a development, a staging, and a production tenant environment. These three environments let you build, test, and deploy your IAM applications:

Tenant Environment Description

Development

Used for building and adding new features.

The number of identity objects in a development environment is limited to 10,000.

The 10,000 limit applies to the total sum of all identity object types combined, including applications, assignments, custom identity objects, groups, OAuth 2.0 clients, organizations, relationships, roles, SAML entities, policies, and users.

Staging

Used for testing development changes, including stress tests and scalability tests with realistic deployment settings.

Production

Used for deploying applications into operation for end users.

Manage configuration

Advanced Identity Cloud has two types of configuration, dynamic and static. Learn more about the difference between them in What kind of configuration changes can my company make?.

You can change dynamic configuration in any environment, but you can only change static configuration in your development environment. Advanced Identity Cloud therefore uses a promotion model to move static configuration changes through the three environments.

Promote static configuration

The development environment is mutable. This means that you can make static configuration changes to the environment through one of the admin UIs or through the REST API.

The staging and production environments are not mutable. This means that you cannot make static configuration changes to these environments directly. Instead, you must move the changes from the development environment to the staging environment by running a promotion, then move the changes from the staging environment to the production environment by running a further promotion.

In situations where you want a static configuration value (such as an authentication token) to be distinct in each environment, you can set the value as an ESV in each environment, then insert the ESV placeholder into your configuration, then move the configuration to your staging and production environments by running sequential promotions. Learn more in Configure placeholders to use with ESVs.

Tenant environment Mutable Make static configuration changes

Development

Yes

Use admin UIs or REST API

Staging

No

Promote configuration

Production

No

Promote configuration

UAT tenant environment

Advanced Identity Cloud add-on capability

Contact your Ping Identity representative if you want to add a UAT environment to your PingOne Advanced Identity Cloud subscription. Learn more in Add-on capabilities.

A user acceptance testing (UAT) tenant environment is an additional environment that you can add into your standard promotion group of development, staging, and production tenant environments. It has the same capabilities as your staging environment, allowing you to test your development changes in a production-like environment.

Having a UAT environment in addition to your staging environment lets you perform different kinds of testing in parallel; for example, you could perform user acceptance testing in your UAT environment alongside load testing in your staging environment (or the other way around if you prefer).

You can add as many UAT environments as you need to your promotion group of environments. They are inserted into the self-service promotion process before the staging environment:

  • If you add one UAT environment, the revised promotion order is development > UAT > staging > production:

    environments with uat

  • If you add a second UAT environment, the revised promotion order is development > UAT > UAT2 > staging > production:

    environments with uat and uat2

  • The promotion order is revised in the same way for each additional UAT environment you add. For example, if you add a third and a fourth UAT environment, the revised promotion order is development > UAT > UAT2 > UAT3 > UAT4 > staging > production.

Set up tenant administrators

A new UAT environment is set up with an initial super administrator (as specified to your Ping Identity representative when requesting the environment).

You can set up additional tenant admin console users in the same way as you did for your development, staging, and production environments. Learn more in Invite tenant administrators.

Set up configuration

Existing customers

A new UAT environment contains no configuration; Ping Identity does not copy any configuration from your existing environments.

You need to promote your configuration from your development environment to your UAT environment. Observe the following warnings:

  • Make sure you promote from your development environment to your UAT environment before you promote from your UAT environment to your staging environment; otherwise, you will overwrite the configuration in your staging environment.

  • Make sure the configuration in your development environment matches the configuration in your staging environment, as this configuration eventually gets promoted through your UAT environment to your production environment.

  • Make sure all required ESVs are created in your UAT environment.

New customers

A new UAT environment contains no configuration, but neither does a new development, staging, or production environment. Therefore, your only additional consideration is that there is an extra environment inserted into the promotion process between your development environment and your staging environment.

You need to configure your development environment before you can promote to your UAT environment. Learn more about managing environments and promoting configuration between them in Introduction to self-service promotions.

Sandbox tenant environment

Advanced Identity Cloud add-on capability

Contact your Ping Identity representative if you want to add a sandbox environment to your PingOne Advanced Identity Cloud subscription. Learn more in Add-on capabilities.

A sandbox tenant environment is a standalone environment separate from your group of development, staging, and production tenant environments. It tracks the rapid release channel, which lets you test the newest features and fixes from Ping Identity before they reach your other environments. It’s mutable like your development environment, but because changes can’t be promoted, you have more freedom to test various use cases. You can run experiments without worrying about accidentally promoting your changes to your upper environments.

For example, you can create user journeys and test them before deciding which one you’d like to use in your development environment. You can safely do this in a sandbox environment because nothing in that environment is part of the promotion process. This means you don’t need to worry about cleaning up unused user journeys.

environments with sandbox

Sandbox usage guidelines

There are some important guidelines to note when using a sandbox environment. In particular, the environment should not be used for load testing, and it should not contain personally identifiable information (PII):

Feature Description

Production use

No

Static & dynamic configuration

Mutable via the UI and REST APIs

Configuration promotion

No

Max number of identity objects

10,000 identity objects

The 10,000 limit applies to the total sum of all identity object types combined, including applications, assignments, custom identity objects, groups, OAuth 2.0 clients, organizations, relationships, roles, SAML entities, policies, and users.

Log retention

1 day

Monitored via Statuspage.io

No

SLA

N/A (support provided at lowest priority level, see below)

Personally identifiable information (PII)

No

Load testing

No

Level of support

Business hours Monday–Friday (excluding public holidays in Australia, Singapore, France, United Kingdom, United States, and Canada)

Outbound static IP addresses

Ping Identity allocates outbound static IP addresses to each of your development, staging, and production tenant environments (and to any sandbox[2] and UAT[3] tenant environments). This lets you identify network traffic originating from PingOne Advanced Identity Cloud and from individual environments within Advanced Identity Cloud.

Having static IP addresses for outbound requests lets you implement IP allowlisting in your enterprise network. Some examples of IP allowlisting are:

  • Adding IP addresses to your firewall settings to restrict access to your internal APIs

  • Adding IP addresses to your email server settings so emails sent from Advanced Identity Cloud are not marked as spam

environments ip addresses

FAQ

Why would I need to know my outbound static IP addresses?

You can add them to an allowlist that restricts access to your network infrastructure, adding an extra layer of access security. For example, you may want to allow only Advanced Identity Cloud to make API calls to an SMTP server inside your network.

How are outbound static IP addresses being introduced?

  • Outbound static IP address functionality is available and enabled by default if your tenant environments were created on or after the following dates:

    • March 30, 2023 (sandbox[2] environments)

    • April 18, 2023 (development, UAT[3], staging, and production environments)

    For these tenant environments, learn more in How can I find out what my outbound static IP addresses are?

  • Outbound static IP address functionality is available but not enabled if your tenant environments were created between the following dates:

    • May 10, 2022 and March 30, 2023 (sandbox[2] environments)

    • May 10, 2022 and April 18, 2023 (development, UAT[3], staging, and production environments)

    For these tenant environments, learn more in How do I enable outbound static IP addresses for my tenants?.

  • Outbound static IP address functionality is not available if your tenant environments were created before May 10, 2022.

    For these tenant environments, the functionality will become available in 2024. For more information, please contact your Ping Identity representative.

How can I find out what my outbound static IP addresses are?

Outbound static IP address functionality is available and enabled by default if your tenant environments were created on or after the following dates:

  • March 30, 2023 (sandbox[2] environments)

  • April 18, 2023 (development, UAT[3], staging, and production environments)

You can view your outbound static IP addresses in your tenant global settings.

How do I enable outbound static IP addresses for my tenants?

Outbound static IP address functionality is available but not enabled if your tenant environments were created between the following dates:

  • May 10, 2022 and March 30, 2023 (sandbox[2] environments)

  • May 10, 2022 and April 18, 2023 (development, UAT[3], staging, and production environments)

To enable outbound static IP addresses and get your IP addresses:

  1. Go to https://support.pingidentity.com.

  2. Click Create a case.

  3. Follow the steps in the case submission wizard by selecting your account and contract and answering questions about your tenant environments.

  4. On the Please answer the following questions to help us understand the issue you’re facing page, enter the following details, and then click Next:

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Configuration

    What version of the product are you using?

    Select NA

  5. On the Tell us about the issue page, enter the following details, and then click Next:

    Field Value

    Provide a descriptive title for your issue

    Enter Enable outbound static IP addresses

    Describe the issue below

    Enter a comma-separated list of FQDNs for your sandbox[2], development, UAT[3], staging, and production tenant environments.

  6. Click Submit.

  7. Ping Identity support enables outbound static IP addresses and provides you with the IP addresses.

Tenant settings

PingOne Advanced Identity Cloud provides you with a unified view of your tenant’s customer, workforce, and device profiles. Use the Advanced Identity Cloud admin console to manage all aspects of your tenant including realms, identities, applications, user journeys, and password policy.

You can review tenant details and access global settings for your tenant by opening the account menu in the top right of the Advanced Identity Cloud admin console, then clicking the Tenant Settings menu option.

View tenant details

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

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

    150

  2. Click Tenant Settings.

  3. Click Details.

    • Tenant Name
      The identifier assigned to the tenant during onboarding and registration. This identifier is not configurable.

    • Environment Tag
      The type of tenant environment. The possible values are:

      • Other
        Indicates a sandbox[2] environment.

      • Dev
        Indicates a development environment.

      • UAT
        Indicates a UAT[3] environment.

      • Staging
        Indicates a staging environment.

      • Prod
        Indicates a production environment.

    • Identity Cloud Version
      The release version the environment is on.

    • Region and Backup Region
      The regions where your data resides.

Invite and view tenant administrators

Tenant administrators Super administrators[4]

Action allowed?

No

Yes

Click the Admins tab on the Tenant Settings page to access options to:

Manage federated access

Tenant administrators Super administrators[4]

Action allowed?

No

Yes

Click the Federation tab on the Tenant Settings page to access options to:

Access global settings

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

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

  2. Click Tenant Settings.

  3. Click Global Settings.

Tenant administrator settings

Tenant administrator groups

There are two groups of users that can access a tenant admin console:

  • Tenant administrator: Users in this group can manage realm settings and most tenant settings except for those related to managing other tenant administrators. All tenant administrator identities get the same realm permissions, and these are not configurable.

  • Super administrator: Users in this group are tenant administrators with the following elevated permissions:

    • Invite tenant administrators.

    • Grant super administrator privileges to tenant administrators.

    • Revoke super administrator privileges from tenant administrators.

    • Enable federated access for a tenant.

    • Enforce federated access for some or all administrators in a tenant.

The tenant provisioning process initially creates a single super administrator.

Register to access a tenant admin console

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

If you are added as a tenant administrator to an Advanced Identity Cloud tenant, you receive an email that prompts you to complete the registration process.

  1. When you receive the Complete your Ping Identity Advanced Identity Cloud registration email, click Complete Registration.

  2. Perform one of the following sets of steps:

    • To use your email and password to register with Advanced Identity Cloud, on the Complete Registration page:

      1. Enter your email address, first name, last name, and your password.

      2. Click Next.

      3. Choose a country of residency, accept Ping Identity’s privacy policy, and click Next.

      4. Choose to set up 2-step verification or skip this option. The Advanced Identity Cloud dashboard should now display.

    • To use Microsoft Azure or AD FS to register with Advanced Identity Cloud, on the Complete Registration page:

      1. Choose to continue with Microsoft Azure or AD FS.

      2. Enter your credentials and log in.

      3. Choose a country of residency, accept Ping Identity’s privacy policy, and click Next. The Advanced Identity Cloud dashboard should now display.

Sign on to a tenant admin console

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

You can access the sign-on page of a tenant admin console using the following URL:

https://<tenant-env-fqdn>/login/admin

For example, if your tenant environment FQDN is "openam-mycompany-ew2.id.forgerock.io", use the URL "https://openam-mycompany-ew2.id.forgerock.io/login/admin".

Upon successful authentication, you are automatically switched to the Alpha realm.

Multiple failed authentication attempts cause Advanced Identity Cloud to lock a tenant administrator’s account. Learn more about unlocking an account in Unlock a tenant administrator’s account.

Edit your own tenant administrator profile

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

  1. In the Advanced Identity Cloud admin console, open the TENANT menu (upper right), and click your username.

    access admin profile

  2. On your tenant administrator profile page:

    • To edit your name or email address, click Edit Personal Info.
      Provide the information, then click Save.

    • In the Sign-in & Security card:

      • To change your username, click Update.

        • Enter your current password, then click Next.

        • Enter your new username, then click Next.
          You’ll receive an email confirming your username has been changed.

      • To change your password, click Reset.

        • Enter your current password, then click Next.

        • Enter your new password, then click Next.
          You’ll receive an email confirming your password has been changed.

      • By default, 2-Step Verification is enabled.
        Learn more in Manage tenant administrator 2-step verification.

    • To view the social identity providers you can use to log into your account, view the Social Sign-in card.

    • To view the devices that have accessed your account, view the Trusted Devices card.

    • To view the applications you have granted access to your account, view the Authorized Applications card.

    • To download your account data, in the Account Controls card, beside Download your data, click the downward pointing arrow, and click Download.

    • To delete your account data, in the Account Controls card, beside Delete account, click the downward pointing arrow, and click Delete Account.

Invite tenant administrators

Tenant administrators Super administrators[4]

Action allowed?

No

Yes

Send invitations to people when you want to authorize them to view or manage settings for your tenant.

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

    tenant menu

  2. Click Invite admins.

  3. In the Invite Admins dialog box, enter a comma-separated list of email addresses for the people you want to authorize.

  4. Grant people specific administrator access by selecting either Super Admin or Tenant Admin.

  5. Click Send Invitations.
    Advanced Identity Cloud sends an email to each address, containing instructions to set up an administrator account.

After each invitee completes the instructions in the invitation email, they become a super administrator or tenant administrator (depending on your choice in step 4).

View the tenant administrators list

Tenant administrators Super administrators[4]

Action allowed?

No

Yes

From the tenant administrators list, you can invite, deactivate, or delete other tenant administrators.

  1. In the Advanced Identity Cloud admin console, click the tenant name to expand the settings menu.

  2. Click Tenant Settings > Admins.

    • To invite a new tenant administrator:

    • To deactivate a tenant tenant administrator:

      • Find a tenant administrator with the label Active.

      • Click More (), and select Deactivate.

    • To delete a tenant administrator, click More (), and select Delete.

      When you deactivate a tenant administrator, their status changes, but they remain on the list of tenant administrators.

      When you delete a tenant administrator, their username is removed from the list of tenant administrators, and permissions are removed from their user profile. This operation cannot be undone!

Unlock a tenant administrator’s account

Tenant administrators Super administrators[4]

Action allowed?

No

Yes

If Advanced Identity Cloud locks out one of your company’s tenant administrators due to multiple failed login attempts, the account can be unlocked by a super administrator.

  1. In the Advanced Identity Cloud admin console, open the TENANT menu (upper right), and click your username.

  2. Click Tenant Settings > Admins.

  3. Find the entry for the tenant administrator who was locked out.

  4. In the same row, click More () and choose Activate.

If you are the only super administrator in your organization and your account is locked, create a support case in the Ping Identity Support Portal.

Modify a tenant administrator’s group

Tenant administrators Super administrators[4]

Action allowed?

No

Yes

To modify a tenant administrator’s group

  1. Go to Tenant Settings > Admins.

  2. Click a tenant administrator.

  3. In the Group section, click Edit.

  4. On the Edit Group page:

    • To grant super administrator access, select Super Admin.

    • To grant tenant administrator access, select Tenant Admin.

      ui federation edit group access

  5. Click Save.

Manage tenant administrator 2-step verification

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

2-step verification, also known as multifactor authentication (MFA), prevents unauthorized actors from signing on as a tenant administrator by asking for a second factor of authentication.

Advanced Identity Cloud provides tenant administrators with the following second factor options:

  • ForgeRock Authenticator
    Lets you register the following authenticator applications:

    • The ForgeRock Authenticator application.

    • Any third-party authenticator application that supports the Time-Based One-Time Password (TOTP) open standard. For example, Google Authenticator or Salesforce Authenticator.

  • Security Key or Touch ID
    Lets you register an authenticator device such as the fingerprint scanner on your laptop or phone. Learn more in MFA: Authenticate using a device with WebAuthn.

Register for 2-step verification

You can register for 2-step verification when you sign on to the Advanced Identity Cloud admin console for the first time:

idcloudui tenant administrator set up 2 step verification

  • Click Set up to let Advanced Identity Cloud guide you through the device registration process.

    The ForgeRock Authenticator option also lets you register any TOTP compliant third-party authenticator application.

  • Alternatively, click Skip for now to temporarily skip registration for 2-step verification. You’ll be asked to register again the next time you sign on.

    The option to skip registration for 2-step verification is a deprecated feature, and soon 2-step verification will be mandatory in all tenants. To understand if this affects you, read the Tenant administrator mandatory 2-step verification FAQ.

Manage verification codes

During registration for 2-step verification, Identity Cloud displays 10 verification codes.

Be sure to copy the codes and store them in a secure location.

  • You’ll use the verfication codes as recovery codes if you cannot use your registered device to sign in.

  • You can use each verification code only once. Then, the code expires.

  • If, for some reason, you need to re-register a device, first delete your previously registered device.

Change 2-step verification options

  1. In the Advanced Identity Cloud admin console, open the TENANT menu (upper right) and choose your tenant administrator username.

  2. On your tenant administrator profile page, find 2-Step Verification and click Change.

    The 2-Step/Push Authentication page lists devices you’ve registered for MFA.

    To delete a device, click its More () menu, and choose Delete.

    • When you delete a device from the list, 2-step or push authentication is disabled. You cannot undo the delete operation.

    • Once you sign off and attempt to sign back on again, you will be asked if you want to set up a second factor.

Configure federated access for tenant administrators

Federated access lets tenant administrators use your company’s single sign-on (SSO) to sign on to your PingOne Advanced Identity Cloud tenant environments.

By using federation to authenticate your tenant administrators to Advanced Identity Cloud, you can quickly and easily provision and deprovision users from your centralized identity provider (IdP) instead of managing them separately in each Advanced Identity Cloud tenant environment.

The groups feature allows you to add and remove tenant administrators depending on their group membership in your IdP. You can also specify the level of administrator access (super administrator[4] or tenant administrator) for groups of users.

Advanced Identity Cloud lets you configure federated access in two main ways:

Configure federated access using PingOne

You can configure PingOne as a federation IdP for PingOne Advanced Identity Cloud. To do this, configure it in PingOne itself. Learn more in Set up SSO to PingOne Advanced Identity Cloud.

After you configure PingOne as a federation IdP, each configured tenant environment in Advanced Identity Cloud automatically displays PingOne in its list of federation IdPs:

  1. Sign on to the Advanced Identity Cloud admin console for any of the environments you configured for federated access using PingOne.

  2. Go to Tenant settings.

  3. Click Federation.

  4. If configured correctly in PingOne, the list contains a PingOne federation IdP:

    federation pingone list item

  5. Click the PingOne list item to view its configuration settings page. For PingOne, this is a basic page containing the Status and the Well-Known Endpoint of the PingOne federation IdP:

    federation pingone configuration settings page

If you configure a federation IdP in PingOne, the corresponding Advanced Identity Cloud tenant environments are configured automatically. You do not need to promote configuration changes.

Configure federated access using PingOne Advanced Identity Cloud

You can configure the following federation IdPs using the Advanced Identity Cloud admin console:

  • Entra ID[5] using OIDC.

  • AD FS using OIDC.

  • Any other federation IdP that’s OIDC compliant.

If you configure a federation IdP using the Advanced Identity Cloud admin console, you must do so in your development environment and promote the configuration changes. You must also store the federation IdP secrets for each of your environments in ESV secrets and set corresponding placeholders in your configuration. Learn more in Configure federated access across your tenant environments.

Configure federated access across your tenant environments

The high-level process to set up federated access across your tenant environments is as follows:

  1. Set up a federation IdP for each of your tenant environments and note the client secrets.

  2. In your development environment:

    1. Follow the instructions in Configure a mutable environment to use a federation IdP, entering the federation IdP values for your development environment. These values will be replaced by ESVs in the following steps.

    2. Create the following ESVs to substitute into configuration:

      • Federation IdP fields:

        Field ESV type

        Client ID

        Variable

        Well-known endpoint

        Variable

        Authorization endpoint

        Variable

        Client secret

        Secret

        Issuer

        Variable

        Redirect URI

        Variable

        Token endpoint

        Variable

      • (Optional) Federation IdP groups fields:

        Field ESV type

        Super administrators[4] group ID

        Variable

        Tenant administrators group ID

        Variable

    3. Restart Advanced Identity Cloud services.

    4. Use the following instructions to update the federation IdP configuration:

  3. (Optional) If you have a UAT[3] environment, adapt the next step to suit the revised promotion order. Learn more in Additional UAT environments.

  4. In your staging environment:

    1. Repeat step 2b for your staging environment. Ensure the ESV names are the same as you set up in the development environment.

    2. Run a promotion to move the configuration change from your development environment to your staging environment. Learn more in:

  5. In your production environment:

    1. Repeat step 2b for your production environment. Ensure the ESV names are the same as you set up in the development environment.

    2. Run a further promotion to move the configuration change from your staging environment to your production environment.

  6. (Optional) If you have a sandbox[2] environment:

    1. Repeat step 2a for your sandbox environment.

    2. (Optional) Repeat step 2b – d for your sandbox environment.

  7. Configure federation sign-on requirements in each environment.

Ensure that the federation IdP for each environment is configured with a redirect URL. If you are using the same federation IdP for your sandbox[2], development, UAT[3], staging, and production environments, ensure that it is configured with redirect URLs for each environment.
Set up a federation IdP

You can find instructions for setting up a federation IdP in the following guides:

Configure a mutable environment to use a federation IdP

After you’ve set up a federation IdP, you can configure it in a mutable environment (development or sandbox[2]) to provide federated access to tenant administrators.

To understand how the instructions in this section fit into the process of configuring federated access across your tenant environments, refer to step 2a in the high-level process.

  1. Sign on to the Advanced Identity Cloud admin console of your mutable environment (development or sandbox[2]) as a super administrator[4].

  2. Go to Tenant settings.

  3. Click Federation.

  4. Click + Identity Provider.

  5. Select the federation provider to use:

    • Microsoft Azure

    • ADFS

    • OIDC

  6. Click Next.

  7. Follow the steps on the Configure Application page and click Next.

  8. On the Identity Provider Details page:

    1. Complete the following fields:

      • Name: The name of the provider.

      • Application ID: The ID for the application.

      • Application Secret: The client secret for the application.

      • Well-known Endpoint:

        • For Entra ID, this is the URL from the OpenID Connect metadata document field. In the URL, make sure to replace organization with the actual tenant ID for your tenant.

        • For AD FS, this is the endpoint from the OpenID Connect section.

        • For OIDC, refer to your IdP vendor’s documentation on locating a client’s well-known endpoint.

        When you populate the Well-known Endpoint field with a valid URL, the following fields are automatically populated:

        • Authorization Endpoint: The endpoint for authentication and authorization. The endpoint returns an authorization code to the client.

        • Token Endpoint: The endpoint that receives an authorization code. The endpoint returns an access token.

        • User Info Endpoint: The endpoint that receives an access token. The endpoint returns user attributes.

      • (For OIDC only): OAuth Scopes: The scopes the application uses for user authentication. The default scopes are openid, profile, and email.

      • (For OIDC only): Client Authentication Method: Options are client_secret_post and client_secret_basic. The default option is client_secret_post.

      • Button Text: The text for the application button.

    2. Click Save. By default all users are given the tenant administrator level of access when they access the tenant using your IdP. To give some or all users the super administrator[4] level of access, configure groups in the next step.

  9. (Optional) Configure group membership to determine administrator access level (super administrator[4] or tenant administrator).

    1. Set up groups in your IdP:

    2. On the Identity Provider Details page:

      1. Select one of the following options:

        • For Entra ID: Enable Use group membership to allow federated login to Ping Identity.

        • For AD FS: Enable Use ADFS group membership to allow federated login to Ping Identity.

        • For OIDC: Enable Use OIDC group membership to allow federated login to Ping Identity.

      2. Enter the name of the group claim in the Group Claim Name field. For example, groups.

        By default, Entra ID sends the ID of the group. You might need to configure it to send the name of the group.

      3. To apply an access level to specific IdP groups:

        • To apply the super administrator[4] access level:

          1. Locate the Group Identifiers field to the left of Super Admins.

          2. Enter one or more group identifiers. For example, 8c578f67-cac4-49eb-8f28-8e4f2c22945e.

        • (Optional) To apply the tenant administrator access level:

          1. Locate the Group Identifiers field to the left of Tenant Admins.

          2. Enter one or more group identifiers. For example, 3623050d-3604-45a2-942e-f6be9ec9f9ed.

      4. Click Save.

Configure federation sign-on requirements

After you have enabled federated access to your tenant environments, you can choose how strictly to enforce it. It can be enforced for just tenant administrators or for both tenant administrators and super administrators[4]. These settings are stored in dynamic configuration, so need to be configured per environment.

To understand how the instructions in this section fit into the process of configuring federated access across your tenant environments, refer to step 5 in the high-level process.

  1. Sign on to the Advanced Identity Cloud admin console as a super administrator[4].

  2. Go to Tenant settings, then click the Federation tab.

  3. In the Enforcement section, click Edit.

  4. On the Edit Tenant Federation Enforcement page, select one of the following items:

    • Optional for All Admins: Allow all administrators to use either their Advanced Identity Cloud credentials or federated access to sign on.

    • Required for All Admins Except Super Admins: Require all administrators that are not super administrators to use federated access to sign on. Super administrators can use their Advanced Identity Cloud credentials or federated access to sign on.

    • Required for All Admins: Require all administrators to use federated access to sign on. If you choose this option, then subsequently need to switch to a lower enforcement level, you must create a support case in the Ping Identity Support Portal.

  5. Click Update. It can take about 10 minutes for the changes to take effect.

  6. On the Change Federation Enforcement? modal:

    • To confirm your changes, click Confirm.

    • To cancel your changes, click Cancel.

Deactivate a federation IdP

You can deactivate a federation IdP and reactivate it later. For example, you might want to deactivate a federation IdP if the provider is experiencing technical issues. If you deactivate all federation IdPs for a tenant, tenant administrators can no longer use federation to sign on to the tenant.

You can only deactivate a federation IdP if one of the following is true:

  • Optional for All Admins is selected as the federation enforcement level (learn more in Configure federation sign-on requirements).

  • More than one federation IdP is enabled in the Advanced Identity Cloud tenant.

To deactivate a federation IdP:

  1. Sign on to the Advanced Identity Cloud admin console of your development environment as a super administrator[4].

  2. Go to Tenant settings, then click Federation.

  3. Perform one of the following actions:

    • To deactivate a federation IdP, click the ellipsis icon () to the right of an active federation IdP, then click Deactivate.

    • To activate a federation IdP, click the ellipsis icon () to the right of a deactivated federation IdP, then click Activate.

  4. Run a series of promotions to move the updated configuration to your UAT[3], staging, and production environments.

Rotate a federation IdP client secret

Most IdPs force you to rotate the client secrets they generate by setting an expiry on the secret. To ensure that federated access continues uninterrupted,you must create and configure a new client secret before the old one expires. If the client secret is stored in an ESV, you can rotate it by creating a new secret version.

For your development, UAT[3], staging, or production environment:

  1. In the IdP’s UI:

    1. Locate the client configured for the Advanced Identity Cloud environment.

    2. Create a new secret and make a note of it:

      • For Azure AD, add a new client secret to the application.

      • For AD FS, reset the client secret for the application group.

      • For OIDC, refer to your IdP vendor’s documentation on creating a new client secret.

  2. In Advanced Identity Cloud admin console:

    1. Add a new secret version to the ESV secret using the value of the new federation IdP secret from the previous step. Learn more in Update an ESV referenced by a configuration placeholder.

    2. Restart Advanced Identity Cloud services.

Set up Microsoft Active Directory Federation Services as a federation IdP

To use Microsoft Active Directory Federation Services (AD FS) as a federation IdP for a PingOne Advanced Identity Cloud tenant environment, you must create a relying party trust. The trust is a set of identifiers, names, and rules that identify the partner or web-application to the federation service.

Afterward, you must create an application group that uses single sign-on (SSO) to access applications that are outside the corporate firewall.

The instructions in this document assume that you have a self-hosted instance of AD FS version 4.0, running on Windows Server 2016 or higher.

Step 1: Create a relying party trust

In this step, you create a relying party trust. The trust is a set of identifiers, names, and rules that identify the partner or web-application to the federation service.

  1. Open the Server Manager console by clicking Server Manager on the Start screen or clicking Server Manager in the taskbar on the desktop.

  2. In AD FS Management, select Tools > AD FS.

  3. On the AD FS dialog, in the left panel, click Relying Party Trusts.

  4. In the Actions pane, select Add Relying Party Trust.

  5. On the Welcome page of the Add Relying Party Trust wizard, select Claims aware.

  6. On the Select Data Source page, select Enter data about the relying party manually.

  7. On the Specify Display Name page, enter a display name.

  8. Complete the steps in the wizard until you reach the Configure Identifiers page.

  9. On the Configure Identifiers page, add a relying party trust identifier for each of your tenant environments using the following URL format:

    https://<tenant-env-fqdn>/am

    For example, if your tenant environment FQDN is openam-mycompany-ew2.id.forgerock.io, use https://openam-mycompany-ew2.id.forgerock.io/am.

  10. On the Choose Access Control Policy page, select the appropriate settings according to your corporate policy.

  11. Complete the steps in the wizard until you reach the Finish page.

Step 2: Create an application group

In this step, you create an application group that uses single sign-on (SSO) to access applications.

  1. In the AD FS editor, select Application Groups.

  2. In the Actions pane, select Add Application Group.

  3. Complete the Add Application Groups wizard as follows:

    1. On the Welcome page of the Add Application Groups wizard, provide a name and a description and select the Server application accessing a web API template.

    2. On the Server application page:

      • Accept the proposed Name.

      • Note the Client Identifier.

        In Advanced Identity Cloud, enter this value in an application’s Application ID field (or set in an ESV mapped to that field).

      • Add tenant Redirect URIs for each of your tenant environments using the following URL format:

        https://<tenant-env-fqdn>/login/admin

        For example, if your tenant environment FQDN is openam-mycompany-ew2.id.forgerock.io, use https://openam-mycompany-ew2.id.forgerock.io/login/admin.

    3. Click Register to create the application.

    4. On the Configure Application Credentials page:

      1. Select Generate a shared secret. The secret acts as a password for the application.

      2. Use the Copy to clipboard button to copy the secret.

        In Advanced Identity Cloud, enter this value in an application’s Application Secret field (or set in an ESV mapped to that field).

    5. Click Next.

    6. On the Configure Web API page, add the client identifier you noted earlier.

    7. Click Next.

    8. On the Choose Access Control Policy page, select the appropriate settings according to your corporate policy.

    9. Click Next.

    10. On the Configure Application Permissions page, check the following permitted scopes:

      • allatclaims: Lets the application request the claims in the access token that is added to the ID token.

      • email: Lets the application request an email claim for the signed-in user.

      • openid: Lets the application request use of the OpenID Connect authentication protocol.

      • profile: Lets the application request profile-related claims for the signed-in user.

    11. Click Next.

    12. On the Summary page, review your selections.

    13. Click Next.

    14. On the Complete page, click Close.

Step 3: Include additional identity claims in tokens

In this step, you configure AD FS to include additional claims in the identity tokens it issues. This is necessary because AD FS does not support the /userinfo endpoint.

  1. In the AD FS editor, select Application Groups.

  2. In the Actions pane, select Add Application Group.

  3. Double-click your application group.

  4. In the Applications section, in the Web API area, select your application, and click Edit.

  5. Click the Issuance Transform Rules tab, and click Add Rule.

  6. To include active directory attributes of the users that are accessing Advanced Identity Cloud, in the Claim rule template drop-down field, select Send LDAP Attributes as Claims.

  7. In the Claim rule name field, enter a name for the claim rule. For example, Profile Attributes.

  8. In the Attribute store drop-down field, select Active Directory.

  9. To map LDAP attributes to name spaces in Advanced Identity Cloud, complete the Mapping of LDAP attributes to outgoing claim types table:

    federation map ldap attributes
    LDAP Attribute (Select or type to add more) Outgoing Claim Type (Select or type to add more)

    E-Mail Addresses

    mail

    Given-Name

    givenName

    Surname

    sn

  10. Click Finish.

  11. On the Issuance Transform Rules tab, click Apply.

  12. Click OK twice.

Step 4: Obtain the well-known endpoint for the AD FS OpenID Connect service

In this step, you identify the well-known URI that the AD FS OpenID Connect service uses.

  1. In the AD FS editor, select Service > Endpoints.

  2. In the middle pane, scroll down to the OpenID Connect section.

  3. In the OpenID Connect section, note the URL path. The well-known end point URL is the concatenation of the host name of the machine running AD FS and the URL path you just noted.

    In Advanced Identity Cloud, enter this value in an application’s Well-known Endpoint field (or set in an ESV mapped to that field).

Step 5: Use group membership to enable federation in AD FS

Groups let you add and remove sets of administrators based on their group membership in your IdP. You can also specify the level of administrator access (super administrator[4] or tenant administrator) for groups of users.

Create groups containing Advanced Identity Cloud tenant administrators

You must create two groups of administrators in AD FS for each of your Advanced Identity Cloud environments:

For each tenant:

  • The first group should consist of the users that will be super administrators in your Advanced Identity Cloud tenant.

  • The second group should consist of the users that will be tenant administrators in your Advanced Identity Cloud tenant.

When naming each group, use a prefix that identifies the group as relevant for Advanced Identity Cloud; this allows the AD FS claim scripts to only include relevant groups. Make sure to include the tenant name as part of the group name to help you identify the tenant the group is for.

Example: group name template

<prefix>-<tenant identifier>-<admin type>.

Example: group name

aic-dev-superadmin

In this example:

  • aic represents the prefix.

  • dev represents the tenant identifier.

  • superadmin represents the admin type.

Example: All group names for a standard promotion group of tenants and a sandbox tenant.

  • aic-dev-superadmin

  • aic-dev-tenantadmin

  • aic-staging-superadmin

  • aic-staging-tenantadmin

  • aic-prod-superadmin

  • aic-prod-tenantadmin

  • aic-sandbox-superadmin

  • aic-sandbox-tenantadmin

Include additional claims in the tokens for Advanced Identity Cloud

To use group membership to enable federation, you must add issuance transform rules to enable AD FS to add additional group claims.

You must add the following two rules in AD FS:

  • Store Groups rule: A rule that collects all the user groups and stores them in a claim with the indicated name. The script produces a potentially large claim.

  • Issue Groups rule: A rule that takes the long list of groups that the Store Groups script creates and only selects the groups with the Group Name Prefix that is relevant for the claim.

    1. In the AD FS editor, select Application Groups.

    2. In the Actions pane, select the group you previously created.

    3. Right-click the group and select Properties.

    4. In the Applications section, in the Web API area, select your application, and click Edit.

    5. Click the Issuance Transform Rules tab.

    6. Click Add Rule.

    7. To include active directory attributes of the users that are accessing Advanced Identity Cloud, in the Claim rule template drop-down field, select Send Claims Using a Custom Rule.

    8. In the Custom rule field, enter the rule definition for the Store Groups rule.

      • Store Groups rule template:

        c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] ⇒ add(store = "Active Directory", types = ("<Groups Claim Name>"), query = ";tokenGroups;{0}", param = c.Value);

      • Store Groups rule example:

        c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] ⇒ add(store = "Active Directory", types = ("groups"), query = ";tokenGroups;{0}", param = c.Value);

        • "groups" is the name of the resulting claim that you enter into the Groups Claim Name field on the Identity Provider Details page in the Advanced Identity Cloud.

    9. Click Finish.

    10. Click Add Rule.

    11. To include active directory attributes of the users that are accessing Advanced Identity Cloud, in the Claim rule template drop-down field, select Send Claims Using a Custom Rule.

    12. In the Custom rule field, enter the rule definition for the Issue Groups rule.

      • Issue Groups rule template:

        c:[Type == "<Groups Claim Name>", Value =~ "^<Group Name Prefix>-.+"] ⇒ issue(claim = c);

      • Issue Groups rule example:

        c:[Type == "groups", Value =~ "^aic-.+"] ⇒ issue(claim = c);

        • "groups" is the name of the resulting claim that you enter into the Groups Claim Name field on the Identity Provider Details page in the Advanced Identity Cloud.

        • "aic" is the prefix you chose for the group names.

    13. Click Finish.

Set up Microsoft Entra ID as a federation IdP

To use Microsoft Entra ID (Entra ID) as a federation IdP for a PingOne Advanced Identity Cloud tenant environment, you need to create a new app registration.

Microsoft Entra ID used to be known by the name Microsoft Azure AD. Learn more in New name for Azure Active Directory.

Step 1: Configure Entra ID as a federation IdP

  1. In a browser, navigate to the Microsoft Entra admin center.

  2. Create a new application:

    1. Click Applications, then click App registrations.

    2. In the top toolbar, click add New registration.

    3. On the Register an application page:

      1. Enter the application Name. For example, "Advanced Identity Cloud administrators".

      2. Select Accounts in this organizational directory only (Me only - Single tenant) from the Supported account types list.

      3. In the Redirect URI (optional) section:

        1. In the left-hand field, select Web.

        2. In the right-hand field, enter the redirect URI for an Advanced Identity Cloud environment using the following URL format:

          https://<tenant-env-fqdn>/login/admin

          For example, if your tenant environment FQDN is openam-mycompany-ew2.id.forgerock.io, use https://openam-mycompany-ew2.id.forgerock.io/login/admin.

      4. Click Register to create the application.

  3. Find the application ID:

    1. In the application menu, click Overview.

    2. Note the Application (client) ID of the application. For example, 6b05a314-c721-4aa6-baad-7f533cbd25b0.

      In Advanced Identity Cloud, enter this value in an application’s Application ID field (or set in an ESV mapped to that field).

  4. Find the application’s well-known endpoint:

    1. In the top toolbar, click Endpoints.

    2. Note the OpenID Connect metadata document endpoint of the application. For example, https://login.microsoftonline.com/0e076864-135f-4914-9b72-80efaa4c3dcf/v2.0/.well-known/openid-configuration.

      In Advanced Identity Cloud, enter this value in an application’s Well-known Endpoint field (or set in an ESV mapped to that field).

  5. Add the email claim to the application’s token configuration:

    1. In the application menu, click Token configuration.

    2. Click add Add optional claim.

    3. In the Add optional claim modal:

      1. Select the ID token type.

      2. Select the email claim checkbox.

      3. Click Add.

      4. The first time you add the email claim, the UI displays an Add optional claim dialog box to let you grant the appropriate API permissions:

        entra id add optional claim email

        1. Select the Turn on the Microsoft Graph profile permission checkbox.

        2. Click Add.

  6. Add an application secret:

    1. In the application menu, click Certificates & secrets.

    2. Click add New client secret.

    3. In the Add a client secret modal:

      1. (Optional) Enter a Description.

      2. Select an option from the Expires list (or accept the default selection of 180 days).

      3. Click Add to create the secret.

    4. Note the Value of the new secret. Do this immediately, as it can only be viewed for a short time after creation.

      In Advanced Identity Cloud, enter this value in an application’s Application Secret field (or set in an ESV mapped to that field).

Step 2: Use group membership to enable federation in Entra ID

Groups let you add and remove sets of administrators based on their group membership in your IdP. You can also specify the level of administrator access (super administrator[4] or tenant administrator) for groups of users.

If you modify group membership in Entra ID, it can take a few minutes for those changes to take effect in Advanced Identity Cloud.

  1. In a browser, navigate to the Microsoft Entra admin center.

  2. Create one or more groups:

    1. Create a group for super administrators[4]:

      1. Click Groups, then click All groups.

      2. In the top toolbar, click New group.

      3. In the New Group page:

        1. Select Microsoft 365 from the Group type list.

        2. Enter the super administrator Group name. For example, Super administrators.

        3. Click Create.

      4. In the All groups page, in the top toolbar, click Refresh.

      5. Click the new group you just created.

      6. Note the Object ID of the group. For example, 8c578f67-cac4-49eb-8f28-8e4f2c22945e.

        In Advanced Identity Cloud, enter this value in an application’s Group Identifiers field (or set in an ESV mapped to that field).

    2. (Optional) Repeat step 2a to create a group for tenant administrators.

  3. Set up the application to acquire claims from the identity token instead of the user info endpoint:

    1. Click Applications, then click App registrations.

    2. Click All applications, then click your application.

    3. In the application menu, click Token configuration.

    4. Click add Add optional claim.

    5. In the Add optional claim modal:

      1. Select the ID token type.

      2. Select the email, family_name, and given_name claim checkboxes.

      3. Click Add.

      4. The first time you add these new claims, the UI displays an Add optional claim dialog box to let you grant the appropriate API permissions:

        entra id add optional claim additional

        1. Select the Turn on the Microsoft Graph profile permission checkbox.

        2. Click Add.

    6. Click add Add groups claim.

    7. In the Edit groups claim modal:

      1. Select Groups assigned to the application.

      2. Click Add.

    8. Confirm the name of the groups claim you added is groups.

      In Advanced Identity Cloud, enter this value in an application’s Group Claim Name field (or set in an ESV mapped to that field).

Set up an OIDC-compliant IdP as a federation IdP

To use an OIDC-compliant IdP as a federation IdP for a PingOne Advanced Identity Cloud tenant environment, you need to create a new OIDC client.

Step 1: Configure OIDC-compliant IdP as a federation IdP

  1. Read your IdP vendor’s documentation on configuring an OIDC client.

  2. Configure an OIDC client profile:

    1. Choose a client ID or note the automatically generated client ID. Some OIDC IdPs let you choose the client ID while others autogenerate it for you.

      In Advanced Identity Cloud, use this in an application’s Application ID field.

    2. Choose a client secret or note the automatically generated client secret. Some OIDC IdPs let you choose the client secret while others autogenerate it for you.

      In Advanced Identity Cloud, enter this value in an application’s Application Secret field (or set in an ESV mapped to that field).

    3. Configure the allowed scopes. Recommended scopes: openid, profile, and email.

    4. Configure the client authentication method. Supported authentication methods: client_secret_post, client_secret_basic, or none.

  3. Obtain the well-known URL from the OIDC-compliant IdP. You will enter this URL when you enable the IdP in Advanced Identity Cloud.

    In Advanced Identity Cloud, enter this value in an application’s Well-known Endpoint field (or set in an ESV mapped to that field).

Step 2: Use group membership to enable federation in an OIDC-compliant IdP

Groups let you add and remove sets of administrators based on their group membership in your IdP. You can also specify the level of administrator access (super administrator[4] or tenant administrator) for groups of users.

  1. Read your IdP vendor’s documentation on configuring groups in your OIDC client.

  2. Obtain the name of the groups claim from the OIDC-compliant IdP.

    In Advanced Identity Cloud, enter this value in an application’s Group Claim Name field (or set in an ESV mapped to that field).

  3. Set up super administrators[4] groups:

    1. Set up one or more groups for users that need to be super administrators[4] when they access the tenant using your IdP.

    2. Note the group ID (or group IDs).

      In Advanced Identity Cloud, enter the group ID (or group IDs) in an application’s Group Identifiers field to the left of Super Admins (or set in an ESV mapped to that field).

  4. (Optional) Set up tenant administrators groups:

    1. Set up one or more groups for users that need to be tenant administrators when they access the tenant using your IdP.

    2. Note the group ID (or group IDs).

      In Advanced Identity Cloud, enter the group ID (or group IDs) in an application’s Group Identifiers field to the left of Tenant Admins (or set in an ESV mapped to that field).

Manage tenant configuration

PingOne Advanced Identity Cloud provides the following ways to let you manage the static configuration shared by your tenant environments:

Configuration item Description

Environment secrets and variables (ESVs)

Use environment secrets and variables (ESVs) to:

  • Create secrets to set values that need encrypting. The values may or may not need to be different for each tenant environment.

    For example, an MFA push notification node might need an authorization password to use an external SMS service.

  • Create variables to set values that need to be different for each tenant environment.

    For example, an authentication node might need one URL in your development environment, but a different URL in your production environment.

Configure placeholders

Create placeholders to use the value of the variable you set instead of using a static value. Use placeholders in conjunction with Environment secrets and variables (ESVs).

Promote your configuration

Promote configuration between sequential environments (development → staging or staging → production).

ESVs

Environment secrets and variables (ESVs) let you individually configure your sandbox[2], development, UAT[3], staging, and production tenant environments in PingOne Advanced Identity Cloud.

Use variables to set values that need to be different for each tenant environment. For example, an authentication node might need one URL in your development environment, but a different URL in your production environment.

Use secrets to set values that need encrypting. The values may or may not need to be different for each tenant environment. For example, an MFA push notification node might need an authorization password to use an external SMS service.

ESVs are an Advanced Identity Cloud only feature. In particular, ESV secrets should not be confused with secrets in the self-managed PingAM or PingIDM products.

Variables

Use ESV variables to set configuration values that need to be different for each tenant environment.

Variables are simple key-value pairs. Unlike secrets, they are not versioned. They should not contain sensitive values. The value of a variable must not exceed a maximum length of 65535 bytes (just under 64KiB).

You can reference ESV variables from configuration placeholders or scripts after you have:

The following table shows how to reference an ESV variable with the name esv-my-variable:

Context How to reference Access as soon as set

Configuration placeholders

&{esv.my.variable}

Learn more in Configure placeholders to use with ESVs.


(requires restart)

Scripts

systemEnv.getProperty("esv.my.variable") (AM)
identityServer.getProperty("esv.my.variable") (IDM)

Learn more in Use ESVs in scripts.


(requires restart)

Variable expression types

You must use the expressionType parameter to set an expression type when you create an ESV variable. This lets Advanced Identity Cloud correctly transform the value of the ESV variable to match the configuration property expression type when substituting it into configuration.

The expression type is set when the ESV variable is created, and it cannot be modified.

Before the expressionType parameter was introduced, it was only possible to set expression types from within configuration, using expression level syntax; for example, {"$int": "&{esv.journey.ldap.port|1389}"}. The expressionType parameter supplements this expression level syntax and allows the ESV type to be identified without inspecting configuration.

Make sure the expression type that you set in configuration matches the expression type that you set in the ESV expressionType parameter.
Expression type Description Examples

string

String value (default)

Name

esv-email-provider-from-email

Placeholder

{"string": "&{esv.email.provider.from.email}"}
or
&{esv.email.provider.from.email}

Value

example@forgerock.com

array

JSON array

Name

esv-cors-accepted-origins

Placeholder

{"$array": "&{esv.cors.accepted.origins}"}

Value

["http://example.org", "http://example.com"]

Name

esv-provisioner-base-contexts

Placeholder

{"$array": "&{esv.provisioner.base.contexts}"}

Value

["dc=example,dc=com"]

object

JSON object

Name

esv-journey-welcome-description

Placeholder

{"$object": "&{esv.journey.welcome.description}"}

Value

{"en":"Example description","fr":"Exemple de description"}

bool

Boolean value

Name

esv-email-provider-use-ssl

Placeholder

{"$bool": "&{esv.email.provider.use.ssl}"}

Value

true

int

Integer value

Name

esv-email-provider-port

Placeholder

{"$int": "&{esv.email.provider.port}"}

Value

465

number

This type can transform any number value (integers, doubles, longs, and floats).

list

Comma-separated list

Name

esv-journey-ldap-servers

Placeholder

{"$list": "&{esv.journey.ldap.servers}"}

Value

userstore-0.userstore:1389,userstore-1.userstore:1389,userstore-2.userstore:1389
Ping Identity recommends using array type variables instead of list type variables. The two types are functionally equivalent, but the array type is more compatible with the UI.
Existing ESVs will be migrated to use the expressionType parameter. If any existing ESVs contain combined types, they will be split into separate ESVs by the migration process.

ESV variables in Advanced Identity Cloud global configuration

Ping Identity manages Advanced Identity Cloud global configuration on your behalf; however, the global configuration contains a single static ESV placeholder to let you override the default maximum size for SAML requests (20480 bytes). To override the default value of the static placeholder in any environment, create a new ESV variable with a corresponding name and a custom value:

Static placeholder

&{esv.global.saml.max.content.length|20480}

Default value

20480

ESV name to create

esv-global-saml-max-content-length

Possible values

Specify an integer

Learn more in https://backstage.forgerock.com/knowledge/kb/article/a37324869.

Secrets

Use ESV secrets to set configuration values that need encrypting. The values may or may not need to be different for each tenant environment.

You can reference ESV secrets from configuration placeholders or scripts after you have:

You can reference secrets that are signing and encryption keys by mapping them to secret labels. Secrets referenced by secret label mappings can be accessed as soon as the ESV is set; restarting Advanced Identity Cloud services is not required.

The following table shows how to reference an ESV secret with the name esv-my-secret:

Context How to reference Access as soon as set

Configuration placeholders

&{esv.my.secret}

Learn more in Configure placeholders to use with ESVs.


(requires restart)

Scripts

systemEnv.getProperty("esv.my.secret") (AM)
identityServer.getProperty("esv.my.secret") (IDM)

Learn more in Use ESVs in scripts.


(requires restart)

Signing and encryption keys

Map to secret label

Secret versions

Instead of having a single value, ESV secrets have one or more secret versions, each containing their own value. By design, the value of a secret version cannot be read back after it has been created. The value of a secret version must not exceed a maximum length of 65535 bytes (just under 64KiB). To create a new secret version, its value must be different to the value of the latest secret version.

You can enable or disable secret versions by setting their status field to ENABLED or DISABLED. The latest version of a secret must be enabled for it to be used in your configuration.

The following rules ensure that a secret always has at least one enabled version:

  • When you create a secret, the first version of the secret is automatically created and is enabled.

  • You cannot disable the latest version of a secret.

  • You cannot delete the latest version of a secret if the previous version is disabled.

Secret versions are an important feature of key rotation. Learn more in Rotate keys in mapped ESV secrets.

Encoding format

You can use the encoding parameter to set an encoding format when you create an ESV secret:

Encoding format Description

generic

Use this format for secrets that are not keys, such as passwords.

pem

Use this format for asymmetric keys; for example, a public and private RSA key pair. Learn more in Generate an RSA key pair.

base64aes

Use this format for AES keys; for example, an AES-256 key. Learn more in Generate an AES or HMAC key.

base64hmac

Use this format for HMAC keys; for example, a HMAC-SHA-512 key. Learn more in Generate an AES or HMAC key.
You can only choose an encoding format using the API. The UI currently creates secrets only with the generic encoding format.

Control access to secrets

There are 3 contexts where you can access an ESV secret:

  1. From configuration placeholders; learn more in Configure placeholders to use with ESVs.

  2. From scripts; learn more in Use ESVs in scripts.

  3. From mapped secret labels (for signing and encryption keys); learn more in Use ESVs for signing and encryption keys.

However, if the secret contains a signing and encryption key, you may want to restrict access from configuration placeholder and script contexts. To do this, you can use the useInPlaceholders boolean parameter when you create the secret:

Context Unrestricted access Restricted access

useInPlaceholders = true

useInPlaceholders = false

Configuration placeholders

  • Secret accessible

  • Uses latest secret version

  • Restart of Advanced Identity Cloud services required

  • Secret not accessible

Scripts

  • Secret accessible

  • Uses latest secret version

  • Restart of Advanced Identity Cloud services not required

Mapped secret labels

  • Secret accessible

  • Uses all enabled secret versions

  • Restart of Advanced Identity Cloud services not required
You can only set restricted access using the API. The UI currently creates secrets only with unrestricted access.

Comparison of secrets and variables

esv variable secret comparison

Preconditions to delete an ESV

Before you delete an ESV, you may need to remove references to it from your environment:

  • You cannot delete an ESV if it is referenced in a configuration placeholder. You must first remove the placeholder from configuration. Learn more in Delete an ESV referenced by a configuration placeholder.

  • You cannot delete an ESV if it is referenced in a script. You must first remove any scripts that reference the ESV.

  • You cannot delete an ESV if it is referenced in an orphaned script[6]. You must first remove any orphaned scripts. You can do this by running a self-service promotion (which automatically cleans up orphaned scripts).

ESV naming

ESV API naming convention

The names of secrets and variables need to be prefixed with esv- and can only contain alphanumeric characters, hyphens, and underscores; for example, esv-mysecret-1 or esv-myvariable_1. The maximum length, including prefix, is 124 characters.

ESV legacy naming convention and API compatibility

Before the introduction of the ESV API endpoints, if ESVs were defined on your behalf as part of the promotion process, they were prefixed with byos-. Advanced Identity Cloud uses compatibility behavior to let you still use these legacy ESVs. The compatibility behavior depends on how far the legacy ESVs were promoted through your development, staging, and production tenant environments:

Development, staging, and production environments

If you promoted a legacy ESV to all your tenant environments, it will have been duplicated during the ESV migration process, so will be available in the API using the new esv- prefix.

For example, byos-myvariable123 will appear as esv-myvariable123. Scripts that reference the legacy ESV will still work; both byos-myvariable123 and esv-myvariable123 resolve to the same ESV.

Development and staging environments only

If you never promoted a legacy ESV to your production environment, it will have been ignored during the ESV migration process. However, you can still use the ESV API to create it in your production environment, as the compatibility behaviour looks for new ESVs that have a naming format like a legacy ESV (byos-<hash>-<name>). So any ESVs that are created with a naming format of esv-<hash>-<name> will also automatically create a byos-<hash>-<name> duplicate.

For example, creating a new ESV called esv-7765622105-myvariable will automatically create another ESV called byos-7765622105-myvariable. Scripts that reference the legacy ESV will still work; both byos-7765622105-myvariable and esv-7765622105-myvariable resolve to the same ESV.

ESV descriptions

ESVs have a description field. This lets you provide further information on how and where to use an ESV.

Manage ESVs using the API

You can find background information on ESVs in PingOne Advanced Identity Cloud in ESVs.

ESV API endpoints

Advanced Identity Cloud provides these API endpoints for ESVs:

To authenticate to the API, learn more in Authenticate to ESV API endpoints.

If you plan to delete an ESV using the variables or secrets API endpoints, you may first need to remove references to it from your environment. Learn more in Preconditions to delete an ESV.

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.

Manage ESVs using the admin console

You can find background information on ESVs in PingOne Advanced Identity Cloud in ESVs.

Create variables

  1. In the Advanced Identity Cloud admin console, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Variables tab.

  3. Click + Add Variable.

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

    Name

    Enter a variable name. Learn more in ESV naming.

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

    Type

    Select a variable expression type.

    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 Advanced Identity Cloud admin console, 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 + Update 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.

    • Below that, you will see the read-only Type field. The variable type cannot be modified.

  5. Click Done to close the modal.

Delete variables

Before you delete a variable, you may need to remove references to it from your environment. Learn more in Preconditions to delete an ESV.

  1. In the Advanced Identity Cloud admin console, 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 Delete Variable icon on the right-hand side.

  4. In the Delete Variable? modal window, click Delete.

Create secrets

  1. In the Advanced Identity Cloud admin console, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Secrets tab.

  3. Click + Add Secret.

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

    Name

    Enter a secret name. Learn more in 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 Advanced Identity Cloud admin console, 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 + Update or Updated 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

      Learn more about the rules for enabling, disabling, and deleting secret versions in 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.

Delete secrets

Before you delete a secret, you may need to remove references to it from your environment. Learn more in Preconditions to delete an ESV.

  1. In the Advanced Identity Cloud admin console, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Secrets tab.

  3. Find a secret in the paginated list of variables, then click the Delete Secret icon on the right-hand side.

  4. In the Delete Secret? modal window, click Delete.

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 ESV management in the admin console 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 View Updates.

  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 Apply Now.

  4. The banner will change color from blue to orange while the updates are applied, and ESV management in the admin console 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 ESV management in the admin console will be enabled again.

Use ESVs in scripts

PingOne Advanced Identity Cloud lets scripts access ESVs directly, without the need for you to restart Advanced Identity Cloud services or request a promotion first.

Ensure that your scripts use the full reference for ESVs; for example esv.my.variable not my.variable. Scripts with an incorrect reference can cause promotions to fail.

Referencing a non-existent ESV in a script, even within comments, can lead to system errors. Ensure that all ESVs mentioned in the script are valid and exist.

Ping Identity recommends that you establish a review and testing process for all scripts.

AM scripts

To access an ESV with the name esv-my-variable in an AM script, use:

systemEnv.getProperty("esv.my.variable")

Learn more about using the systemEnv binding in ESVs in scripts.

IDM scripts

To access an ESV with the name esv-my-variable in an IDM script, use:

identityServer.getProperty("esv.my.variable")

Learn more about using the identityServer variable in The identityServer variable.

Use ESVs for signing and encryption keys

PingOne Advanced Identity Cloud lets you store signing and encryption keys in ESV secrets, then map them to secret labels. Each secret label represents an authentication feature in Advanced Identity Cloud, such as signing OAuth 2.0 client access tokens.

Advanced Identity Cloud can directly access keys stored in a mapped ESV secret, there is no need to restart Advanced Identity Cloud services.

You can rotate keys stored in a mapped ESV secret by adding new secret versions to the ESV. The key in the latest secret version is used to sign new access tokens, then subsequently validate them. Keys in older secret versions (that are still enabled) are still used to validate existing access tokens.

You can also rotate SAML 2.0 certificates using ESV secrets. Learn more in Rotate SAML 2.0 certificates using ESVs

Secret labels

Secret labels (also known as secret IDs or purposes) represent authentication features in Advanced Identity Cloud that need a signing or encryption key. For example, to sign an OAuth 2.0 client access token with an HMAC key, you would use the secret label am.services.oauth2.stateless.signing.HMAC.

For a full list of secret labels, learn more in Secret labels.

Secret labels with fixed names

Most secret labels represent an authentication feature that requires only a single secret per realm. These secret labels have fixed names as they require only a single mapping per realm to override them. An example of a secret label with a fixed name is am.services.oauth2.stateless.token.encryption, the label for the secret used to encrypt client-side access tokens issued in the realm.

Secret labels with identifiers

Some secret labels represent an authentication feature that could require multiple instances per realm, such as OAuth 2.0 clients. The names of these secret labels contain a configurable portion, known as the identifier, to support multiple override mappings per realm. An example of a secret label with an identifier is am.applications.oauth2.client.<identifier>.secret.

Authentication features that support secret labels with identifiers provide a Secret Label Identifier field that lets you define the identifier value. The value of the identifier must be alphanumeric, can also contain periods (but not at the start or end), and must not contain spaces. When you create an instance of the authentication feature and define a Secret Label Identifier, Advanced Identity Cloud creates a new secret label; for example, if you create a new OAuth 2.0 client and define the Secret Label Identifier as "salesforce", Advanced Identity Cloud creates the secret label am.applications.oauth2.client.salesforce.secret.

You can then map the secret label to an ESV secret. If you don’t create a mapping, the authentication feature falls back to a manually entered password.

In the case of OAuth 2.0 clients, Advanced Identity Cloud defines four secret labels for each client. In the example above, Advanced Identity Cloud creates the following secret labels:

  • am.applications.oauth2.client.salesforce.secret

  • am.applications.oauth2.client.salesforce.jwt.public.key

  • am.applications.oauth2.client.salesforce.id.token.enc.public.key

  • am.applications.oauth2.client.salesforce.mtls.trusted.cert

Continuing the example, Advanced Identity Cloud tries to find a mapping for any of the four secret labels, before falling back to a manually entered password.

Learn more in Authenticate OAuth 2.0 clients.

Map ESV secrets to secret labels

In each realm, each secret label is mapped to a default secret key. You cannot access these default secret keys. However, you can override the default key mappings. To do this, map a secret label to an ESV secret in a realm’s ESV secret store.

To store a key in an ESV secret, then map it to a secret label:

  1. Create an ESV secret, containing the value of your new signing or encryption key:

    You can only create secrets that contain keys using the API. The UI currently does not support the encoding and useInPlaceholders parameters.

    For examples of how to generate asymmetric and symmetric keys, learn more in:

    1. Create an access token for the appropriate realm. Learn more in Get an access token.

    2. Create the ESV secret:

      Show request 
      $ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/secrets/<secret-name>' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: protocol=1.0;resource=1.0' \
--data-raw '{
    "encoding": "<encoding-format>",(3)
    "useInPlaceholders": false,(4)
    "valueBase64": "<base64-encoded-key>"(5)
}'
      1 Replace <secret-name> with an appropriate secret name; for example, esv-oauth2-signing-key. Learn more in ESV naming.
      2 Replace <access-token> with the access token.
      3 Replace <encoding-format> with pem for asymmetric keys or base64hmac for symmetric keys. Learn more in Encoding format.
      4 Ensure that useInPlaceholders is set to false. Learn more in Control access to secrets.
      5 Replace <base64-encoded-key> with your new signing or encryption key, encoded as a Base64 string.
      Show response 
      {
    "_id": "esv-oauth2-signing-key",
    "activeVersion": "",
    "description": "",
    "encoding": "base64hmac",
    "lastChangeDate": "2022-01-28T13:25:40.515Z",
    "lastChangedBy": "23b299e8-90d4-406e-9431-80faf25bc7c0",
    "loaded": true,
    "loadedVersion": "",
    "useInPlaceholders": false
}

  2. In the Advanced Identity Cloud admin console, click Native Consoles > Access Management.

  3. In the AM native admin console, go to Realm > Secret Stores.

  4. Click the ESV secret store, then click Mappings.

  5. Click + Add Mapping, then enter the following information:

    Secret Label

    Select a secret label; for example am.services.oauth2.stateless.signing.HMAC.

    aliases

    Enter the name of the ESV secret you created in step 1, including the esv- prefix; for example, esv-oauth2-signing-key. Then click Add.

    Only add a single ESV alias. The UI lets you add additional aliases, but this is a legacy mechanism for key rotation. Instead, rotate ESV keys by adding new secret versions to the ESV. Learn more in Rotate keys in mapped ESV secrets.

  6. Click Create.

Rotate keys in mapped ESV secrets

You can rotate keys stored in a mapped ESV secret by manipulating the enabled status of its secret versions:

idcloudui esv secrets manage versions rotation

Version 4

This is the latest secret version. It is enabled and cannot be disabled. It is used to sign new tokens. Existing tokens signed by this key are still valid.

Version 3 and version 2

These are older secret versions. They are still enabled. Existing tokens signed by these keys are still valid.

Version 1

This is an older secret version. It is disabled. Existing tokens signed by this key are not valid.

Rotate SAML 2.0 certificates using ESVs

Generate an RSA key pair

To generate an RSA key pair to use in an ESV:

  1. Run the following command to generate a private key:

    $ openssl genrsa -out private-key.pem

  2. Then, generate a public key using the private key:

    $ openssl req -new -x509 -key private-key.pem -out public-key.pem -days 365 -subj /CN=idcloud

  3. Combine the private key and public key into a key pair:

    $ cat private-key.pem public-key.pem > key-pair.pem

  4. If you intend to use an API request to create the ESV:

    1. Encode the key pair into base64:

      $ openssl enc -base64 -A -in key-pair.pem -out key-pair-base64.pem

      The file key-pair-base64.pem now contains a base64 encoded key pair value.

    2. You can now use this value in the valueBase64 property of the JSON body of the API request. Refer to step 1b in Map ESV secrets to secret labels for an example.

Generate an AES or HMAC key

To generate an AES or HMAC key to use in an ESV:

  1. Run the following command:

    $ head -c<bytes> /dev/urandom | openssl enc -base64 -A -out key.txt(1)
    1 Replace <bytes> with your required key length; for example, 512.

    Summary of command:

    • Generates a random number using /dev/urandom

    • Truncates the random number to your required key length using head

    • Encodes the truncated random number into base64 using openssl

  2. If you intend to use an API request to create the ESV:

    1. Encode the key into base64 again:

      $ openssl enc -base64 -A -in key.txt -out key-base64.txt

      The file key-base64.txt now contains a base64 encoded key value.

    2. You can now use this value in the valueBase64 property of the JSON body of the API request. Refer to step 1b in Map ESV secrets to secret labels for an example.

Configure placeholders to use with ESVs

PingOne Advanced Identity Cloud lets you reference ESVs from configuration placeholders. This lets you use different configuration values for the development, staging, and production environments at runtime.

For example, suppose you wanted to set a different email sender for each environment. You would set the configuration value of the email sender to an ESV with different values in each environment; for example, dev-mycompany@example.com (development), staging-mycompany@example.com (staging), and mycompany@example.com (production). Then, you would insert the ESV configuration placeholder into your configuration instead of a literal value.

Configuration placeholders that reference an undefined ESV cause promotions to fail. Learn more in Configuration integrity checks.

Set up configuration placeholders to reference an ESV

  1. In your development environment:

    1. Create the ESV using one of the following:

    2. Restart Advanced Identity Cloud services.

    3. Insert the ESV configuration placeholder into your configuration. Learn more in:

  2. In your staging environment:

    1. Repeat step 1a for your staging environment. Ensure the ESV name is the same as you set up in the development environment.

    2. Run a promotion to move the configuration change from your development environment to your staging environment. Learn more in:

  3. In your production environment:

    1. Repeat step 1a for your production environment. Ensure the ESV name is the same as you set up in the development environment.

    2. Run a further promotion to move the configuration change from your staging environment to your production environment.

If you want to add more ESVs later, repeat the steps above and use a further series of promotions.

Configuration placeholders can only be inserted into static configuration. You can find more information on what static configuration is and which areas of configuration are classified as static in the promotion FAQs.

Update an ESV referenced by a configuration placeholder

  1. Update the ESV using one of the following:

  2. Next, Restart Advanced Identity Cloud services.

Restart Advanced Identity Cloud services

If you update an ESV referenced by a configuration placeholder, you also need to restart Advanced Identity Cloud services. This substitutes the updated secret or variable into the corresponding configuration placeholder.

  1. Restart Advanced Identity Cloud services using one of the following:

Delete an ESV referenced by a configuration placeholder

  1. Remove the ESV configuration placeholder from your configuration in the development environment. Refer to:

  2. Run a promotion to move the configuration change from the development environment to the staging environment. Refer to:

  3. Run a further promotion to move the configuration change from the staging environment to the production environment.

  4. Delete the ESV in each of the development, staging, and production environments using one of the following:

Define and promote an ESV

An example of using a variable would be to define a URL that a user is redirected to after logging in. In each environment, the URL would need a different value; for example, dev-www.example.com (development), staging-www.example.com (staging), and www.example.com (production).

To define and promote the variable:

  1. Decide on a variable name; for example, esv-myurl. Learn more in ESV naming.

  2. Set an ESV variable in each of the development, staging, and production environments. To do this, choose one of the following options:

  3. Insert the ESV configuration placeholder into your configuration in the development environment. For the example variable esv-myurl from step 1, the placeholder would be called &{esv.myurl}. Refer to:

    Configuration placeholders can only be inserted into static configuration. Learn more in promotion FAQs.

  4. Run a promotion to move the configuration change from the development environment to the staging environment. Refer to:

  5. Run a promotion to move the configuration change from the staging environment to the production environment.

The following illustration demonstrates the process:

image$esv set variable

Manage configuration placeholders using the API

PingOne Advanced Identity Cloud lets you add placeholders to your configuration so you can reference the value of an ESV variable or an ESV secret instead of defining a static value.

For example, if you created an ESV variable named esv-email-provider-port, you could reference its value by adding a placeholder of {"$int" : "&{esv.email.provider.port}"} to your configuration.

To set a default value in a configuration placeholder, include it after a vertical bar. For example, the following expression sets a default email provider port of 465: {"$int" : "&{esv.email.provider.port|465}"}. If no ESV is set, the default value of 465 is used instead.

If you add a placeholder to your configuration and do not set a corresponding ESV or specify a default value, you will not be able to complete a successful promotion.

A configuration property can include a mix of static values and placeholders. For example, if you set esv-hostname to id, then &{esv.hostname}.example.com evaluates to id.example.com.

Examples

Insert ESV placeholders into tenant email provider configuration

This example shows how to configure placeholders in your tenant email provider configuration. Learn more in Email provider.

  1. Get an access token.

  2. Get the email provider configuration:

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/config/external.email' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token created in step 1.
    Show response 
    {
    "_id": "external.email",
    "auth": {
        "enable": true,
        "password": "changeit",
        "username": "example.user"
    },
    "connectiontimeout": 30000,
    "debug": false,
    "from": "\"Example User\" <example.user@example.com>",
    "host": "localhost",
    "port": 465,
    "smtpProperties": [],
    "ssl": {
        "enable": true
    },
    "starttls": {
        "enable": false
    },
    "threadPoolSize": 21,
    "timeout": 30000,
    "writetimeout": 30000
}

  3. Create a local copy of the email provider configuration from step 2, then substitute in ESV placeholders:

    {
    "auth": {
        "enable": true,
        "password": "&{esv.email.provider.password}", (1)
        "username": "&{esv.email.provider.username}" (2)
    },
    "connectiontimeout": 30000,
    "debug": false,
    "from": "\"Example User\" <&{esv.email.provider.from.email}>", (3)
    "host": "localhost",
    "port": {
        "$int": "&{esv.email.provider.port}" (4)
    },
    "smtpProperties": [],
    "ssl": {
        "enable": {
            "$bool": "&{esv.email.provider.use.ssl}" (5)
        }
    },
    "starttls": {
        "enable": false
    },
    "threadPoolSize": 21,
    "timeout": 30000,
    "writetimeout": 30000
}
    1 Substitution for ESV placeholder &{esv.email.provider.password}.
    2 Substitution for ESV placeholder &{esv.email.provider.username}.
    3 Substitution for ESV placeholder &{esv.email.provider.from.email}.
    4 Substitution for ESV placeholder &{esv.email.provider.port}.
    5 Substitution for ESV placeholder &{esv.email.provider.use.ssl}.

    The following table summarizes the ESVs that correspond with the above placeholders:

    ESV name ESV type Expression type Example value

    esv-email-provider-password

    Secret

    n/a

    esv-email-provider-username

    Variable

    String

    example.user

    esv-email-provider-from-email

    Variable

    String

    example.user@example.com

    esv-email-provider-port

    Variable

    Integer

    465

    esv-email-provider-use-ssl

    Variable

    Boolean

    true

  4. Update the email provider configuration:

    Show request 
    $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/external.email' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(2)
--data-raw '<email-provider-configuration>'(3)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token created in step 1.
    3 Replace <email-provider-configuration> with the local copy of the email-provider configuration modified in step 3.
    Show response 
    {
    "_id": "external.email",
    "auth": {
        "enable": true,
        "password": "&{esv.email.provider.password}",
        "username": "&{esv.email.provider.username}"
    },
    "connectiontimeout": 30000,
    "debug": false,
    "from": "\"Example User\" <&{esv.email.provider.from.email}>",
    "host": "localhost",
    "port": {
        "$int": "&{esv.email.provider.port}"
    },
    "smtpProperties": [],
    "ssl": {
        "enable": {
            "$bool": "&{esv.email.provider.use.ssl}"
        }
    },
    "starttls": {
        "enable": false
    },
    "threadPoolSize": 20,
    "timeout": 30000,
    "writetimeout": 30000
}

Insert ESV placeholders into CORS configuration

This example shows how to configure placeholders in your tenant CORS configuration. Learn more in Configure cross-origin resource sharing.

  1. Get an access token.

  2. Get the CORS configuration:

    Show request 
    $ curl \
--request POST 'https://<tenant-env-fqdn>/am/json/global-config/services/CorsService/?_action=nextdescendents' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token created in step 1.
    Show response 
    {
    "result": [
        {
            "maxAge": 600,
            "exposedHeaders": [],
            "acceptedHeaders": [
                "accept-api-version",
                "x-requested-with"
            ],
            "allowCredentials": true,
            "acceptedMethods": [
                "GET",
                "POST",
                "PUT",
                "DELETE"
            ],
            "acceptedOrigins": [
                "https://example.org",
                "https://example.com",
                "https://openam-example.forgeblocks.com"
            ],
            "enabled": true,
            "_id": "example-cors-config", (1)
            "_type": {
                "_id": "configuration",
                "name": "Cors Configuration",
                "collection": true
            }
        }
    ]
}
    1 The ID of the CORS configuration; in this example it is example-cors-config.

  3. Create a local copy of the CORS configuration from step 2, then substitute in an ESV placeholder:

    {
    "maxAge": 600,
    "exposedHeaders": [],
    "acceptedHeaders": [
        "accept-api-version",
        "x-requested-with"
    ],
    "allowCredentials": true,
    "acceptedMethods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
    ],
    "acceptedOrigins": {
        "$array": "&{esv.cors.accepted.origins}" (1)
    },
    "enabled": true,
    "_id": "example-cors-config",
    "_type": {
        "_id": "configuration",
        "name": "Cors Configuration",
        "collection": true
    }
}
    1 Substitution for ESV placeholder &{esv.cors.accepted.origins}.

    The following table summarizes the ESV that corresponds with the above placeholder:

    ESV name ESV type Expression type Example value

    esv-cors-accepted-origins

    Variable

    Array

    ["https://example.org","https://example.com","https://openam-example.forgeblocks.com"]

  4. Update the CORS configuration:

    Show request 
    $ curl \
--request PUT 'https://<tenant-env-fqdn>/am/json/global-config/services/CorsService/configuration/<cors-id>' \(1)(2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(3)
--data-raw '<cors-configuration>'(4)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <cors-id> with the CORS configuration ID you found in step 2. For example, example-cors-config.
    3 Replace <access-token> with the access token created in step 1.
    4 Replace <cors-configuration> with the local copy of the CORS configuration modified in step 3.
    Show response 
    {
    "_id": "example-cors-settings",
    "_rev": "1594160724",
    "maxAge": 600,
    "exposedHeaders": [],
    "acceptedHeaders": [
        "accept-api-version",
        "x-requested-with"
    ],
    "allowCredentials": true,
    "acceptedMethods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
    ],
    "acceptedOrigins": {
        "$array": "&{esv.cors.accepted.origins}"
    },
    "enabled": true,
    "_type": {
        "_id": "configuration",
        "name": "Cors Configuration",
        "collection": true
    }
}

Insert ESV placeholders into journey node configuration

This example shows how to configure placeholders in an LDAP decision node, but the approach can be adapted to configure placeholders in any journey node.

  1. Get an access token.

  2. Get the configuration of the journey that contains the LDAP decision node so you can extract the ID of the node:

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realms/<realm>/realm-config/authentication/authenticationtrees/trees/<journey-name>' \(1)(2)(3)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(4)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <realm> with the realm that contains the journey that contains the LDAP decision node. For example, alpha.
    3 Replace <journey-name> with the name of the journey that contains the LDAP decision node. For example, UpdatePassword.
    4 Replace <access-token> with the access token created in step 1.
    Show response 
    {
    "_id": "ldapJourney",
    "_rev": "1341035508",
    "identityResource": "managed/alpha_user",
    "uiConfig": {
        "categories": "[]"
    },
    "entryNodeId": "76e74888-73e1-46e2-aa33-5e4c8b07ccec",
    "nodes": {
        "76e74888-73e1-46e2-aa33-5e4c8b07ccec": {
            "x": 249,
            "y": 171.015625,
            "connections": {
                "outcome": "c12abfe7-ae71-42e6-a6b3-e8f4d4d05549"
            },
            "nodeType": "PageNode",
            "displayName": "Page Node"
        },
        "2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3": { (1)
            "x": 510,
            "y": 181.015625,
            "connections": {
                "CANCELLED": "e301438c-0bd0-429c-ab0c-66126501069a",
                "EXPIRED": "e301438c-0bd0-429c-ab0c-66126501069a",
                "FALSE": "e301438c-0bd0-429c-ab0c-66126501069a",
                "LOCKED": "e301438c-0bd0-429c-ab0c-66126501069a",
                "TRUE": "70e691a5-1e33-4ac3-a356-e7b6d60d92e0"
            },
            "nodeType": "LdapDecisionNode",
            "displayName": "LDAP Decision"
        }
    },
    "staticNodes": {
        "startNode": {
            "x": 50,
            "y": 250
        },
        "70e691a5-1e33-4ac3-a356-e7b6d60d92e0": {
            "x": 792,
            "y": 181
        },
        "e301438c-0bd0-429c-ab0c-66126501069a": {
            "x": 795,
            "y": 307
        }
    },
    "enabled": true
}
    1 The ID of the LdapDecisionNode node; in this example, it is 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.

  3. Get the configuration of the LDAP decision node:

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realms/<realm>/realm-config/authentication/authenticationtrees/nodes/LdapDecisionNode/<node-id>' \(1)(2)(3)(4)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(5)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <realm> with the realm that contains the journey that contains the LDAP decision node. For example, alpha.
    3 The node name specified is LdapDecisionNode.
    4 Replace <node-id> with the node ID you found in step 2. For example, 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.
    5 Replace <access-token> with the access token created in step 1.
    Show response 
    {
    "_id": "2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3",
    "_rev": "-752122233",
    "searchFilterAttributes": [
        "mail"
    ],
    "userProfileAttribute": "uid",
    "primaryServers": [
        "userstore-0.userstore:1389",
        "userstore-1.userstore:1389",
        "userstore-2.userstore:1389"
    ],
    "ldapConnectionMode": "LDAP",
    "trustAllServerCertificates": false,
    "heartbeatInterval": 10,
    "returnUserDn": true,
    "searchScope": "SUBTREE",
    "heartbeatTimeUnit": "SECONDS",
    "secondaryServers": [],
    "ldapOperationsTimeout": 0,
    "userCreationAttrs": [],
    "minimumPasswordLength": 8,
    "accountSearchBaseDn": [
        "o=example"
    ],
    "adminPassword": null,
    "adminDn": "uid=admin",
    "beheraEnabled": true,
    "_type": {
        "_id": "LdapDecisionNode",
        "name": "LDAP Decision",
        "collection": true
    },
    "_outcomes": [
        {
            "id": "TRUE",
            "displayName": "True"
        },
        {
            "id": "FALSE",
            "displayName": "False"
        },
        {
            "id": "LOCKED",
            "displayName": "Locked"
        },
        {
            "id": "CANCELLED",
            "displayName": "Cancelled"
        },
        {
            "id": "EXPIRED",
            "displayName": "Expired"
        }
    ]
}

  4. Create a local copy of the node configuration from step 3, then substitute in ESV placeholders:

    {
    "searchFilterAttributes": [
        "mail"
    ],
    "userProfileAttribute": "uid",
    "primaryServers" : {
        "$list": "&{esv.journey.ldap.primary.servers}" (1)
    },
    "ldapConnectionMode": "LDAP",
    "trustAllServerCertificates": false,
    "heartbeatInterval": {
        "$int": "&{esv.journey.ldap.heartbeat.interval}" (2)
    },
    "returnUserDn": true,
    "searchScope": "SUBTREE",
    "heartbeatTimeUnit": "&{esv.journey.ldap.heartbeat.unit}", (3)
    "secondaryServers": [],
    "ldapOperationsTimeout": 0,
    "userCreationAttrs": [],
    "minimumPasswordLength": 8,
    "accountSearchBaseDn": [
        "o=example"
    ],
    "adminPassword": {
        "$string": "&{esv.journey.ldap.password}" (4)
    },
    "adminDn": "&{esv.journey.ldap.username}", (5)
    "beheraEnabled": {
        "$bool": "&{esv.journey.ldap.behera.enabled}" (6)
    },
    "_type": {
        "_id": "LdapDecisionNode",
        "name": "LDAP Decision",
        "collection": true
    },
    "_outcomes": [
        {
            "id": "TRUE",
            "displayName": "True"
        },
        {
            "id": "FALSE",
            "displayName": "False"
        },
        {
            "id": "LOCKED",
            "displayName": "Locked"
        },
        {
            "id": "CANCELLED",
            "displayName": "Cancelled"
        },
        {
            "id": "EXPIRED",
            "displayName": "Expired"
        }
    ]
}
    1 Substitution for ESV placeholder &{esv.journey.ldap.primary.servers}.
    2 Substitution for ESV placeholder &{esv.journey.ldap.heartbeat.interval}.
    3 Substitution for ESV placeholder &{esv.journey.ldap.heartbeat.unit}.
    4 Substitution for ESV placeholder &{esv.journey.ldap.password}.
    5 Substitution for ESV placeholder &{esv.journey.ldap.username}.
    6 Substitution for ESV placeholder &{esv.journey.ldap.behera.enabled}.

    The following table summarizes the ESVs that correspond with the above placeholders:

    ESV name ESV type Expression type Example value

    esv-journey-ldap-primary-servers

    Variable

    List

    userstore-0.userstore:1389,userstore-1.userstore:1389,userstore-2.userstore:1389

    esv-journey-ldap-heartbeat-interval

    Variable

    Integer

    10

    esv-journey-ldap-heartbeat-unit

    Variable

    String

    SECONDS

    esv-journey-ldap-password

    Secret

    n/a

    changeit

    esv-journey-ldap-username

    Variable

    String

    uid=myadmin

    esv-journey-ldap-behera-enabled

    Variable

    Boolean

    false

  5. Update the configuration of the LDAP decision node:

    Show request 
    $ curl \
--request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realms/<realm>/realm-config/authentication/authenticationtrees/nodes/LdapDecisionNode/<node-id>' \(1)(2)(3)(4)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(5)
--data-raw '<node-configuration>'(6)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <realm> with the realm that contains the journey that contains the LDAP decision node. For example, alpha.
    3 The node name specified is LdapDecisionNode.
    4 Replace <node-id> with the node ID you found in step 2. For example, 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.
    5 Replace <access-token> with the access token created in step 1.
    6 Replace <node-configuration> with the local copy of the node configuration modified in step 4.
    Show response 
    {
    "_id": "2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3",
    "_rev": "1359037709",
    "searchFilterAttributes": [
        "mail"
    ],
    "userProfileAttribute": "uid",
    "primaryServers": {
        "$list": "&{esv.journey.ldap.servers}"
    },
    "ldapConnectionMode": "LDAP",
    "trustAllServerCertificates": false,
    "heartbeatInterval": {
        "$int": "&{esv.journey.ldap.heartbeat.interval}"
    },
    "returnUserDn": true,
    "searchScope": "SUBTREE",
    "heartbeatTimeUnit": "&{esv.journey.ldap.heartbeat.unit}",
    "secondaryServers": [],
    "ldapOperationsTimeout": 0,
    "userCreationAttrs": [],
    "minimumPasswordLength": 8,
    "accountSearchBaseDn": [
        "o=example"
    ],
    "adminPassword": {
        "$string": "&{esv.journey.ldap.password}"
    },
    "adminDn": "&{esv.journey.ldap.username}",
    "beheraEnabled": {
        "$bool": "&{esv.journey.ldap.behera.enabled}"
    },
    "_type": {
        "_id": "LdapDecisionNode",
        "name": "LDAP Decision",
        "collection": true
    },
    "_outcomes": [
        {
            "id": "TRUE",
            "displayName": "True"
        },
        {
            "id": "FALSE",
            "displayName": "False"
        },
        {
            "id": "LOCKED",
            "displayName": "Locked"
        },
        {
            "id": "CANCELLED",
            "displayName": "Cancelled"
        },
        {
            "id": "EXPIRED",
            "displayName": "Expired"
        }
    ]
}

Insert ESV placeholders into federation IdP configuration

This example shows how to configure placeholders for a federation IdP.

  1. Get an access token.

  2. Get the configuration of the federation IdP:

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realm-config/services/SocialIdentityProviders/oidcConfig/<idp-name>' \(1)(2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(3)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <idp-name> with the name of your federation IdP. For example, ms-entra-id.
    3 Replace <access-token> with the access token created in step 1.
    Show response 
    {
    "_id": "ms-entra-id",
    "_rev": "-704142225",
    "pkceMethod": "S256",
    "clientId": "6b05a314-c721-4aa6-baad-7f533cbd25b0",
    "wellKnownEndpoint": "https://login.microsoftonline.com/0e076864-135f-4914-9b72-80efaa4c3dcf/v2.0/.well-known/openid-configuration",
    "authorizationEndpoint": "https://login.microsoftonline.com/0e076864-135f-4914-9b72-80efaa4c3dcf/oauth2/v2.0/authorize",
    "issuerComparisonCheckType": "EXACT",
    "clientSecret": null,
    "encryptJwtRequestParameter": false,
    "scopeDelimiter": " ",
    "scopes": [
        "User.Read",
        "openid",
        "profile"
    ],
    "issuer": "https://login.microsoftonline.com/0e076864-135f-4914-9b72-80efaa4c3dcf/v2.0",
    "userInfoResponseType": "JSON",
    "acrValues": [],
    "enabled": true,
    "jwtRequestParameterOption": "NONE",
    "authenticationIdKey": "id",
    "uiConfig": {
        "buttonDisplayName": "Azure",
        "buttonImage": "img/azure-logo.bcd266f1.svg",
        "iconFontColor": "white",
        "providerKey": "azure",
        "buttonCustomStyle": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "iconBackground": "#0078d7",
        "buttonCustomStyleHover": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;"
    },
    "privateKeyJwtExpTime": 600,
    "revocationCheckOptions": [],
    "enableNativeNonce": true,
    "transform": "dc0c9905-4a58-4f61-8562-337514e610a7",
    "jwtSigningAlgorithm": "NONE",
    "redirectURI": "https://&{fqdn}/login/admin",
    "clientAuthenticationMethod": "CLIENT_SECRET_POST",
    "responseMode": "DEFAULT",
    "useCustomTrustStore": false,
    "tokenEndpoint": "https://login.microsoftonline.com/0e076864-135f-4914-9b72-80efaa4c3dcf/oauth2/v2.0/token",
    "_type": {
        "_id": "oidcConfig",
        "name": "Client configuration for providers that implement the OpenID Connect specification.",
        "collection": true
    }
}

  3. Create a local copy of the federation IdP configuration from step 2, then substitute in ESV placeholders:

    {
    "_id": "ms-entra-id",
    "_rev": "-704142225",
    "pkceMethod": "S256",
    "clientId": "&{esv.idp.client.id}", (1)
    "wellKnownEndpoint": "&{esv.idp.well.known.endpoint}", (2)
    "authorizationEndpoint": "&{esv.idp.authorization.endpoint}", (3)
    "issuerComparisonCheckType": "EXACT",
    "clientSecret": {
        "$string": "&{esv.idp.client.secret}" (4)
    },
    "encryptJwtRequestParameter": false,
    "scopeDelimiter": " ",
    "scopes": [
        "User.Read",
        "openid",
        "profile"
    ],
    "issuer": "&{esv.idp.issuer}", (5)
    "userInfoResponseType": "JSON",
    "acrValues": [],
    "enabled": true,
    "jwtRequestParameterOption": "NONE",
    "authenticationIdKey": "id",
    "uiConfig": {
        "buttonDisplayName": "Azure",
        "buttonImage": "img/azure-logo.bcd266f1.svg",
        "iconFontColor": "white",
        "providerKey": "azure",
        "buttonCustomStyle": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "iconBackground": "#0078d7",
        "buttonCustomStyleHover": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;"
    },
    "privateKeyJwtExpTime": 600,
    "revocationCheckOptions": [],
    "enableNativeNonce": true,
    "transform": "dc0c9905-4a58-4f61-8562-337514e610a7",
    "jwtSigningAlgorithm": "NONE",
    "redirectURI": "&{esv.idp.redirect.uri}", (6)
    "clientAuthenticationMethod": "CLIENT_SECRET_POST",
    "responseMode": "DEFAULT",
    "useCustomTrustStore": false,
    "tokenEndpoint": "&{esv.idp.token.endpoint}", (7)
    "_type": {
        "_id": "oidcConfig",
        "name": "Client configuration for providers that implement the OpenID Connect specification.",
        "collection": true
    }
}
    1 Substitution for ESV placeholder &{esv.idp.client.id}.
    2 Substitution for ESV placeholder &{esv.idp.well.known.endpoint}.
    3 Substitution for ESV placeholder &{esv.idp.authorization.endpoint}.
    4 Substitution for ESV placeholder &{esv.idp.client.secret}.
    5 Substitution for ESV placeholder &{esv.idp.issuer}.
    6 Substitution for ESV placeholder &{esv.idp.redirect.uri}.
    7 Substitution for ESV placeholder &{esv.idp.token.endpoint}.

    The following table summarizes the ESVs that correspond with the above placeholders:

    ESV name ESV type Expression type Example value

    esv-idp-client-id

    Variable

    String

    6b05a314-c721-4aa6-baad-7f533cbd25b0

    esv-idp-well-known-endpoint

    Variable

    String

    https://login.microsoftonline.com/0e076864-135f-4914-9b72-80efaa4c3dcf/v2.0/.well-known/openid-configuration

    esv-idp-authorization-endpoint

    Variable

    String

    https://login.microsoftonline.com/0e076864-135f-4914-9b72-80efaa4c3dcf/oauth2/v2.0/authorize

    esv-idp-client-secret

    Secret

    String

    changeit

    esv-idp-issuer

    Variable

    String

    https://login.microsoftonline.com/0e076753-135f-4914-9b72-80efaa4c3dcf/v2.0

    esv-idp-redirect-uri

    Variable

    String

    https://openam-federation-preview.forgeblocks.com/login/admin

    esv-idp-token-endpoint

    Variable

    String

    https://login.microsoftonline.com/0e076864-135f-4914-9b72-80efaa4c3dcf/oauth2/v2.0/token

  4. Update the federation IdP configuration:

    Show request 
    $ curl \
--request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realm-config/services/SocialIdentityProviders/oidcConfig/<idp-name>' \(1)(2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(3)
--data-raw '<idp-configuration>'(4)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <idp-name> with the name of your federation IdP. For example, ms-entra-id.
    3 Replace <access-token> with the access token created in step 1.
    4 Replace <idp-configuration> with the local copy of the federation IdP configuration modified in step 3.
    Show response 
    {
    "_id": "ms-entra-id",
    "_rev": "-704142225",
    "pkceMethod": "S256",
    "clientId": "&{esv.idp.client.id}",
    "wellKnownEndpoint": "&{esv.idp.well.known.endpoint}",
    "authorizationEndpoint": "&{esv.idp.authorization.endpoint}",
    "issuerComparisonCheckType": "EXACT",
    "clientSecret": {
        "$string": "&{esv.idp.client.secret}"
    },
    "encryptJwtRequestParameter": false,
    "scopeDelimiter": " ",
    "scopes": [
        "User.Read",
        "openid",
        "profile"
    ],
    "issuer": "&{esv.idp.issuer}",
    "userInfoResponseType": "JSON",
    "acrValues": [],
    "enabled": true,
    "jwtRequestParameterOption": "NONE",
    "authenticationIdKey": "id",
    "uiConfig": {
        "buttonDisplayName": "Azure",
        "buttonImage": "img/azure-logo.bcd266f1.svg",
        "iconFontColor": "white",
        "providerKey": "azure",
        "buttonCustomStyle": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "iconBackground": "#0078d7",
        "buttonCustomStyleHover": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;"
    },
    "privateKeyJwtExpTime": 600,
    "revocationCheckOptions": [],
    "enableNativeNonce": true,
    "transform": "dc0c9905-4a58-4f61-8562-337514e610a7",
    "jwtSigningAlgorithm": "NONE",
    "redirectURI": "&{esv.idp.redirect.uri}",
    "clientAuthenticationMethod": "CLIENT_SECRET_POST",
    "responseMode": "DEFAULT",
    "useCustomTrustStore": false,
    "tokenEndpoint": "&{esv.idp.token.endpoint}",
    "_type": {
        "_id": "oidcConfig",
        "name": "Client configuration for providers that implement the OpenID Connect specification.",
        "collection": true
    }
}

Insert ESV placeholders into federation IdP groups configuration

This example shows how to configure placeholders for federation IdP groups.

  1. Get an access token.

  2. Get the configuration of the federation IdP groups:

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/config/fidc/federation-<idp-name>' \(1)(2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(3)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <idp-name> with the name of your federation IdP. For example, ms-entra-id.
    3 Replace <access-token> with the access token created in step 1.
    Show response 
    {
    "_id": "fidc/federation-ms-entra-id",
    "groups": {
        "claim": "groups",
        "mappings": {
            "super-admins": [
                "8c578f67-cac4-49eb-8f28-8e4f2c22945e"
            ],
            "tenant-admins": [
                "3623050d-3604-45a2-942e-f6be9ec9f9ed"
            ]
        }
    }
}

  3. Create a local copy of the federation IdP groups configuration from step 2, then substitute in ESV placeholders:

    {
    "_id": "fidc/federation-ms-entra-id",
    "groups": {
        "claim": "groups",
        "mappings": {
            "super-admins": [
                "&{esv.idp.super.admins.group}" (1)
            ],
            "tenant-admins": [
                "&{esv.idp.tenant.admins.group}" (2)
            ]
        }
    }
}
    1 Substitution for ESV placeholder &{esv.idp.super-admins-group}.
    2 Substitution for ESV placeholder &{esv.idp.tenant-admins-group}.

    The following table summarizes the ESVs that correspond with the above placeholders:

    ESV name ESV type Expression type Example value

    esv-idp-super-admins-group

    Variable

    String

    8c578f67-cac4-49eb-8f28-8e4f2c22945e

    esv-idp-tenant-admins-group

    Variable

    String

    3623050d-3604-45a2-942e-f6be9ec9f9ed

  4. Update the federation IdP groups configuration:

    Show request 
    $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/fidc/federation-<idp-name>' \(1)(2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(3)
--data-raw '<idp-groups-configuration>'(4)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <idp-name> with the name of your federation IdP. For example, ms-entra-id.
    3 Replace <access-token> with the access token created in step 1.
    4 Replace <idp-groups-configuration> with the local copy of the federation IdP groups configuration modified in step 3.
    Show response 
    {
    "_id": "fidc/federation-ms-entra-id",
    "groups": {
        "claim": "groups",
        "mappings": {
            "super-admins": [
                "&{esv.idp.super.admins.group}"
            ],
            "tenant-admins": [
                "&{esv.idp.tenant.admins.group}"
            ]
        }
    }
}

Insert an ESV placeholder into an LDAP connector

This example shows how to configure a placeholder for an LDAP connector configured with the password for an LDAP server.

When a connector is created, Advanced Identity Cloud stores any secret or password in the connector’s configuration as an encrypted object. If the encrypted object is promoted, it cannot be unencrypted in an upper environment because the encryption keys are different in each environment. Therefore, the encrypted object must be stored in an ESV secret and replaced in the configuration with an ESV placeholder.

  1. Get an access token.

  2. Get the configuration of the LDAP connector:

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/<connector-id>' \(1)(2)
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>'(3)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <connector-id> with the name of your connector. For example, myldapconnector.
    3 Replace <access-token> with the access token created in step 1.
    Show response 
    {
  "_id": "provisioner.openicf/myldapconnector",
  "configurationProperties": {
    "accountObjectClasses": [
      "top",
      "person",
      "organizationalPerson",
      "inetOrgPerson"
    ],
    "accountSearchFilter": null,
    "accountSynchronizationFilter": null,
    "accountUserNameAttributes": [
      "uid"
    ],
    "attributesToSynchronize": [],
    "baseContexts": [
      "ou=identities"
    ],
    "baseContextsToSynchronize": [
      "ou=identities"
    ],
    "blockSize": "100",
    "changeLogBlockSize": "100",
    "changeNumberAttribute": "changeNumber",
    "credentials": { (1)
      "$crypto": {
        "type": "x-simple-encryption",
        "value": {
          "cipher": "AES/CBC/PKCS5Padding",
          "data": "hfJKTFhe+c6wozK/OEKMEw==",
          "iv": "G/1aF6oKS5/bzlkEzsmK0A==",
          "keySize": 16,
          "mac": "QSp/OAIEPWp9vkDhyZtK5Q==",
          "purpose": "idm.config.encryption",
          "salt": "6gSguT4PDQdKsPOrcItx7Q==",
          "stableId": "openidm-sym-default"
        }
      } (2)
    },
    "failover": [],
    "filterWithOrInsteadOfAnd": false,
    "groupMemberAttribute": "uniqueMember",
    "groupObjectClasses": [],
    "groupSearchFilter": null,
    ...
    },
  ...
}
    1 Opening bracket of the encrypted object containing the connector’s password.
    2 Closing bracket of the encrypted object containing the connector’s password.

  3. Create a local copy of the connector configuration from step 2, then substitute in an ESV placeholder for the encrypted object:

    {
  "_id": "provisioner.openicf/myldapconnector",
  "configurationProperties": {
    "accountObjectClasses": [
      "top",
      "person",
      "organizationalPerson",
      "inetOrgPerson"
    ],
    "accountSearchFilter": null,
    "accountSynchronizationFilter": null,
    "accountUserNameAttributes": [
      "uid"
    ],
    "attributesToSynchronize": [],
    "baseContexts": [
      "ou=identities"
    ],
    "baseContextsToSynchronize": [
      "ou=identities"
    ],
    "blockSize": "100",
    "changeLogBlockSize": "100",
    "changeNumberAttribute": "changeNumber",
    "credentials": "&{esv.connector.ldap.password}", (1)
    "failover": [],
    "filterWithOrInsteadOfAnd": false,
    "groupMemberAttribute": "uniqueMember",
    "groupObjectClasses": [],
    "groupSearchFilter": null,
    ...
    },
  ...
}
    1 Substitution of ESV placeholder &{esv.connector.ldap.password} for the encrypted object.

    The following table summarizes the ESV that corresponds with the above placeholder and contains the encrypted object from the connector configuration returned in step 2:

    ESV name ESV type Expression type Example value

    esv-connector-ldap-password

    Secret

    n/a

    {"$crypto": {"type": "x-simple-encryption", "value": {"cipher": "AES/CBC/PKCS5Padding", "data": "hfJKTFhe+c6wozK/OEKMEw==", "iv": "G/1aF6oKS5/bzlkEzsmK0A==", "keySize": 16, "mac": "QSp/OAIEPWp9vkDhyZtK5Q==", "purpose": "idm.config.encryption", "salt": "6gSguT4PDQdKsPOrcItx7Q==", "stableId": "openidm-sym-default"}}}

  4. Update the connector configuration:

    Show request 
    $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/<connector-id>' \(1)(2)
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access-token>'\(3)
--data-raw '<connector-configuration>'(4)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <connector-id> with the name of your connector. For example, myldapconnector.
    3 Replace <access-token> with the access token created in step 1.
    4 Replace <connector-configuration> with the local copy of the connector configuration modified in step 3.
    Show response 
    {
  "_id": "provisioner.openicf/myldapconnector",
  "configurationProperties": {
    "accountObjectClasses": [
      "top",
      "person",
      "organizationalPerson",
      "inetOrgPerson"
    ],
    "accountSearchFilter": null,
    "accountSynchronizationFilter": null,
    "accountUserNameAttributes": [
      "uid"
    ],
    "attributesToSynchronize": [],
    "baseContexts": [
      "ou=identities"
    ],
    "baseContextsToSynchronize": [
      "ou=identities"
    ],
    "blockSize": "100",
    "changeLogBlockSize": "100",
    "changeNumberAttribute": "changeNumber",
    "credentials": "&{esv.connector.ldap.password}",
    "failover": [],
    "filterWithOrInsteadOfAnd": false,
    "groupMemberAttribute": "uniqueMember",
    "groupObjectClasses": [],
    "groupSearchFilter": null,
    ...
    },
  ...
}

Manage configuration placeholders using the admin console

PingOne Advanced Identity Cloud lets you add placeholders to your configuration so you can reference the value of an ESV variable or an ESV secret instead of defining a static value.

For example, if you created an ESV variable named esv-ldap-minimum-password-length, you could reference its value in a journey by adding the placeholder &{esv.ldap.minimum.password.length} to the Minimum Password Length field of an LDAP Decision node.

Admin console support for configuration placeholders

The Advanced Identity Cloud admin console has full support for viewing and removing placeholders; however, it supports adding placeholders only to journey configuration. To add placeholders to configuration outside the journey editor, use the API. Learn more in Manage configuration placeholders using the API.

The following table summarizes the Advanced Identity Cloud admin console support for placeholders:

Admin console action Journey configuration Non-journey configuration

Add placeholder

Yes

No (use API)

View placeholder

Yes

Yes

Remove placeholder

Yes

Yes
Even if you enter a placeholder in non-journey configuration in the admin console and the UI renders it as a read-only field, it is not valid and won’t work as expected.

Add a configuration placeholder to a field

If you create a new ESV in a separate tab or window, you may also need to reload the page you are working on to display the new ESV in a field’s variable list.

  1. (Optional) Create a new ESV by following steps 1a and 1b in Set up configuration placeholders to reference an ESV.

  2. In the Advanced Identity Cloud admin console, identify the insertable placeholder field to which you want to add a placeholder.

  3. Click on the field’s token icon (token).

  4. The UI displays a list of ESVs with a compatible variable expression type for the field; for example, for a field that expects a boolean value, the list contains only ESV variables with a bool expression type:

    image$ui esv insertable placeholder list
    The UI combines ESV secrets and ESV variables of expression type string into one list. This combined list displays for password fields and for text fields that expect a string value.

  5. (Optional) To filter the ESVs displayed in the list, enter a value in the field with a search icon (search).

  6. Select an ESV from the list.

  7. The UI displays the selected placeholder and changes the field to a read-only placeholder field.

  8. (Optional) To edit the placeholder:

    1. Click on the field’s clear icon (close).

    2. The UI reverts the field to an insertable placeholder field.

    3. Repeat steps 2–7 above.

  9. Save the page that contains the field. This adds the placeholder to your configuration.

Delete a configuration placeholder for a field

  1. In the Advanced Identity Cloud admin console, identify the read-only placeholder field for which you want to delete a placeholder.

  2. Click on the field’s clear icon (close).

  3. The UI reverts the field to an insertable placeholder field.

  4. (Optional) Set a new regular input value for the field.

  5. Save the page that contains the field. This removes the placeholder from your configuration and replaces it with a regular input value.

Placeholder field states

Insertable

Fields into which you can add a placeholder are insertable. If a field is insertable, a token icon (token) displays when you hover your cursor over the field or when you focus on the field:

  • For text, password, select, and tag fields, the icon is displayed inside the field on the right-hand side:

    image$ui esv insertable placeholder input text

  • For checkboxes, the icon is displayed outside the field to the right-hand side:

    image$ui esv insertable placeholder input checkbox

  • For key-value fields, the icon is displayed to the right-hand side of the key-value field name:

    image$ui esv insertable placeholder input key value

Until you add a configuration placeholder, insertable placeholder fields behave the same as regular input fields.

Read-only

When you add a configuration placeholder to a placeholder field, it becomes read-only:

  • For text, password, select, and tag fields, the placeholder displays inside the field, the field is grayed out, and the field value cannot be edited. The only part of the field that is interactive is the field’s clear icon (close) on the right-hand side:

    image$ui esv read only placeholder input text

  • For checkboxes, the checkbox is replaced with a read-only text field below the checkbox label:

    image$ui esv read only placeholder input checkbox

  • For key-value fields, the field name, controls, and summary are replaced entirely with a read-only text field. The read-only text field includes the key-value field name above the placeholder:

    image$ui esv read only placeholder input key value

Key-value field conversion example

An example of a key-value field is the Page Header field in the Page Node.

The following screenshot shows the Page Header field populated with en and fr keys containing locale-specific messages:

image$ui journeys page node page header modal

To convert this data to an ESV, use the object type ESV variable and set the value as a JSON object:

{
    "en":"Sign in",
    "fr":"Se connecter"
}

Introduction to self-service promotions

PingOne Advanced Identity Cloud lets you run self-service promotions to move static 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.

If you promote configuration that accidentally causes instability or errors, Advanced Identity Cloud lets you run a self-service rollback to restore an upper environment to its previous configuration.

You can run a promotion or a rollback using the following options:

The Advanced Identity Cloud configuration model

The following video summarizes the concepts of the Advanced Identity Cloud configuration model:

Static and dynamic configuration

Learn about the difference between static and dynamic configuration in these FAQs:

Lower and upper environments

In a sequential pair of environments, we refer to 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 which environment you are promoting to.

Standard promotion group of environments

For a standard promotion group of development, staging, and production tenant environments, the lower and upper environments are:

Development
environment		 Staging
environment		 Production
environment

Staging promotion

south lower

north upper

Production promotion

south lower

north upper

Key:

  • south lower = lower environment (configuration source)

  • north upper = upper environment (configuration destination)

Additional UAT environments

If you add any UAT environments to your promotion group of environments, they are inserted into the promotion process before the staging environment:

  • If you add one UAT environment, the revised lower and upper environments are:

    Development
    environment    		 UAT
    environment    		 Staging
    environment    		 Production
    environment

    UAT promotion

    south lower

    north upper

    Staging promotion

    south lower

    north upper

    Production promotion

    south lower

    north upper

  • If you add a second UAT environment, the revised lower and upper environments are:

    Development
    environment    		 UAT
    environment    		 UAT2
    environment    		 Staging
    environment    		 Production
    environment

    UAT promotion

    south lower

    north upper

    UAT2 promotion

    south lower

    north upper

    Staging promotion

    south lower

    north upper

    Production promotion

    south lower

    north upper

  • The lower and upper environments are revised in the same way for each additional UAT environment you add.

Environment locking

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

Before you run a promotion or a rollback, you must lock the lower and upper environments. This prevents anyone else from locking either of those environments, which ensures only one promotion or rollback 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 a promotion or rollback by manipulating ESV configuration values. If the lower environment is also the development environment, then most Advanced Identity Cloud API endpoints are also restricted.

When a promotion or a rollback 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 or a rollback, Advanced Identity Cloud performs integrity checks on your static configuration to protect the stability of the upper environment.

Integrity check for missing ESVs

Promotion Rollback

Checked?

Yes

Yes

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

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

Integrity check for encrypted secrets

Promotion Rollback

Checked?

Yes

No

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.

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

Manage self-service promotions using the API

You can find background information on self-service promotions in PingOne Advanced Identity Cloud in Introduction to self-service promotions.

Lower and upper environments

Before you run any promotions API requests, you must know which tenant environment is the lower environment and which is the upper environment. Learn more in Lower and upper environments.

The API uses a pull model to promote configuration, so most API commands must be run against the upper environment.

Dry-run promotions

When you are ready to run a promotion, perform a dry run first. A dry run lets you identify any problems with missing ESVs or encrypted secrets, before you run a full promotion.

Reports

Header 1 Header 2

Dry-run promotion report

A promotion report generated after a dry-run promotion. It provides a full list of configuration changes that will be promoted between a lower and an upper environment.

Promotion report

A promotion report generated after a promotion. It provides a full list of configuration changes that were promoted between a lower and an upper environment.

Provisional rollback report

A rollback report generated before rollback. It provides a full list of configuration changes that will be reverted from the upper environment.

Rollback report

A rollback report generated after a rollback. It provides a full list of configuration changes that were reverted from the upper environment.

Promotions API endpoints

Advanced Identity Cloud provides these API endpoints for promotions:

To authenticate to promotions API endpoints, use an access token created with the fr:idc:promotion:* scope.

The following diagram summarizes how promotions API commands are used to run a promotion. Learn more in Run a promotion.

self service promotions api states

Monitor progress when you lock or unlock environments, start a promotion, or start a rollback

When you use API commands to lock environments, unlock environments, start a promotion, or start a rollback, you trigger asynchronous processes in your environments. You can monitor the progress of these asynchronous processes by checking their state or status until they have completed. You do this by running further API commands and analyzing their responses.

Check the lock state

To check the lock state, use the /environment/promotion/lock/state endpoint:

curl \
--request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/lock/state' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
2 Replace <access-token> with an access token for the upper environment (learn more in Get an access token).

Learn how to analyze the response from this endpoint in Lock environments.

Check the promotion status

To check the promotion status, use the /environment/promotion/promote endpoint:

curl \
--request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/promote' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
2 Replace <access-token> with an access token for the upper environment (learn more in Get an access token).

Learn how to analyze the response from this endpoint during a promotion in Run a promotion.

Check the rollback status

To check the rollback status, use the /environment/promotion/promote endpoint, as described in Check the promotion status.

Learn how to analyze the response from this endpoint during a rollback in Run a rollback.

Lock environments

Before you run a promotion or a rollback, you must lock the upper and lower environments.

Step 1: Check that the environments are unlocked

  1. Check the lock state to confirm that both environments are unlocked. This is indicated in the response when result has a value of unlocked:

    {
    "description": "Environment unlocked",
    "lowerEnv": {
        "state": "unlocked"
    },
    "result": "unlocked",
    "upperEnv": {
        "state": "unlocked"
    }
}

Step 2: Lock the environments

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

  1. To lock the environments, use the /environment/promotion/lock endpoint to create a lock request:

    curl \
--request POST 'https://<tenant-env-upper-fqdn>/environment/promotion/lock' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
    1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
    2 Replace <access-token> with an access token for the upper environment (learn more in Get an access token).

    1. If the lock request is successful, the response result has a value of locking:

      {
    "description": "Environment lock in progress",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "result": "locking"
}

    2. If the lock request is rejected, the response code has a value of 409.

      • In the example below the lock request was rejected because a lock already exists:

        {
    "code": 409,
    "message": "Environment is already locked for promotion 791eb03a-7ec1-42ae-ae84-ed142cf52688"
}

        To resolve this:

        1. If another member of your team is already running a promotion:

          1. Wait until the team member has completed their promotion and has released the lock.

          2. Start the promotion steps again.

        2. If the lock has accidentally been left in place, and no one else is running a promotion:

          1. Unlock the environments using the promotion ID stated in the error message.

          2. Start the promotion steps again.

      • In the example below the lock request was rejected because Ping Identity locked the environment:

        {
    "code": 409,
    "message": "Environment is locked by {forgerock_name} for maintenance. Retry later."
}

        Ping Identity typically locks an environment so that Ping Identity support engineers can investigate an issue or perform maintenance. To resolve this, wait until Ping Identity releases the lock.

    3. If the lock request causes an unexpected error, the response code has a value of 500.

      {
    "code": 500,
    "message": "<internal-error-message>"
}

      To resolve this, open a support case with Ping Identity support. Learn more in Resolve environment errors that are preventing a promotion or a rollback.

  2. Check the lock state to confirm that the lock is in progress. This is indicated in the response when result has a value of locking:

    {
    "description": "Environment lock in progress",
    "lowerEnv": {
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "state": "locking"
    },
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "result": "locking",
    "upperEnv": {
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "state": "locking"
    }
}

  3. Check the lock state as many times as you need until both environments are locked. This is indicated in the response when result has a value of locked:

    {
    "description": "Environment locked",
    "lowerEnv": {
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "state": "locked"
    },
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "result": "locked",
    "upperEnv": {
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "state": "locked"
    }
}

Run a promotion

Step 1: Lock the environments

Follow the instructions in Lock environments.

Step 2: Check that a promotion is not already running

Check the promotion status to confirm that a promotion is not already running. This is indicated in the response when status has a value of READY:

{
    "status": "READY",
    "message": "Environment ready for promotion",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:12:32Z",
    "type": "promotion"
}

Step 3: Run a dry-run promotion

To run a dry-run promotion, follow the steps in Step 4: Run the promotion; however, in step 4.1, set the dryRun flag to true:

--data-raw '{
    "dryRun": true
}'

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.

Step 4: Run the promotion

  1. To run a promotion, use the /environment/promotion/promote endpoint:

    curl \
--request POST 'https://<tenant-env-upper-fqdn>/environment/promotion/promote' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(2)
--data-raw '{
    "dryRun": false (3)
}'
    1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
    2 Replace <access-token> with an access token for the upper environment (learn more in Get an access token).
    3 The dryRun flag is set to false in the request body. 
    {
    "result": "Promotion process initiated successfully"
}

  2. Check the promotion status to confirm that the promotion is in progress. This is indicated in the response when status has a value of RUNNING:

    {
    "status": "RUNNING",
    "message": "Prepare config",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:14:13Z",
    "type": "promotion"
}

  3. Check the promotion status as many times as you need until the promotion is complete.

    1. If the promotion is still running, the response status has a value of RUNNING:

      {
    "status": "RUNNING",
    "message": "Promote configuration",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:15:51Z",
    "type": "promotion"
}

    2. If the promotion failed but is recoverable, the response status has a value of ERROR, and the response blockingError has a value of false.

      1. In the example below, the promotion failed an integrity check for missing ESVs.

        {
    "status": "ERROR",
    "message": "Missing ESVs",
    "blockingError": false,
    "missingESVs": [
        "email.from"
    ],
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:19:31Z",
    "type": "promotion"
}

        To resolve this:

        1. Unlock the environments.

        2. For each ESV in missingESVs, add an ESV into the upper environment.

        3. Start the promotion steps again.

      2. In the example below, the promotion failed an integrity check for encrypted secrets.

        {
    "status": "ERROR",
    "message": "Found encrypted values in the AM/IDM configuration",
    "blockingError": false,
    "globalLock": "LOCKED",
    "encryptedSecrets": [
        "* am/services/realm/root-alpha/persistentcookiedecisionnode/1.0/organizationconfig/default/dd35c42f-177e-4633-9107-373214858fa7.json:10"
    ],
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:19:31Z",
    "type": "promotion"
}

        To resolve this:

        1. If the encrypted secret is in your configuration by accident:

          1. Unlock the environments.

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

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

          4. Start the promotion steps again.

        2. If the encrypted secret is in your configuration deliberately, you can bypass this check:

          1. Follow the steps in Step 4: Run the promotion; however, in step 4.1, set the ignoreEncryptedSecrets flag to true:

            --data-raw '{
    "dryRun": false,
    "ignoreEncryptedSecrets": true
}'

    3. If the promotion failed and is not recoverable, the response status has a value of ERROR, and the response blockingError has a value of true:

      {
    "status": "ERROR",
    "message": "Failed to promote config",
    "blockingError": true,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:19:31Z",
    "type": "promotion"
}

      If you run the promotion again after a blocking error, the following response displays:

      {
    "code": 409,
    "message": "Environment is blocked from a previous failed promotion or rollback"
}

      To resolve this, open a support case with Ping Identity support. Learn more in Resolve environment errors that are preventing a promotion or a rollback.

    4. If Advanced Identity Cloud services are restarting, the response status has a value of RUNNING, and the response message has a value of Waiting for workloads to restart:

      {
    "status": "RUNNING",
    "message": "Waiting for workloads to restart",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:32:06Z",
    "type": "promotion"
}

      This part of the promotion can take several minutes. It does not apply to dry-run promotions, where Advanced Identity Cloud services do not need to be restarted.

    5. If the promotion is complete, the response status has a value of READY, and the response message has a value of Promotion completed:

      {
    "status": "READY",
    "message": "Promotion completed",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:40:29Z",
    "type": "promotion"
}

      If no changes have been promoted, the message has a value of Promotion completed (no change).

Step 5: View the promotion report

  1. To view a report for the most recent promotion, use the /environment/promotion/report endpoint.

    curl \
--request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/report' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(2)
    1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
    2 Replace <access-token> with an access token for the upper environment (learn more in Get an access token). 
    {
    "createdDate": "2024-06-12T17:32:05Z",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "report": {
        "IDMConfig": [
            {
                "configChange": {
                    "added": [
                        "Forgotten Username"
                    ]
                },
                "configItem": "Email > Templates",
                "fileDestinationPattern": "idm/conf/emailTemplate-*.json",
                "fileName": "displayName",
                "type": "single"
            }
        ]
    },
    "reportId": "c41286bb-30cd-4109-ba9d-dc4788b6a75c",
    "reportName": "Report_2024-06-12T17-32+00Z_dryrun=false_8acd3a87-2272-450f-a3b3-1eb222108740",
    "type": "promotion"
}

    In the example above, the promotion report shows that email template configuration was promoted.

  2. To view a report from before the most recent promotion, learn more in View previous promotion or rollback reports.

Step 6: Unlock the environments

Follow the instructions in Unlock environments.

Run a rollback

Step 1: Lock the environments

Follow the instructions in Lock environments.

Step 2: Check that a promotion is not already running

Check the promotion status to confirm that a promotion is not already running. This is indicated in the response when status has a value of READY:

{
    "status": "READY",
    "message": "Environment ready for promotion",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:12:32Z",
    "type": "promotion"
}

Step 3: Get a provisional rollback report

To get a provisional rollback report, use the /environment/promotion/report/provisional-rollback endpoint:

curl \
--request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/report/provisional-rollback' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
2 Replace <access-token> with an access token for the upper environment (learn more in Get an access token). 
{
    "createdDate": "2024-06-12T17:32:05Z",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "report": {
        "IDMConfig": [
            {
                "configChange": {
                    "added": [
                        "Forgotten Username"
                    ]
                },
                "configItem": "Email > Templates",
                "fileDestinationPattern": "idm/conf/emailTemplate-*.json",
                "fileName": "displayName",
                "type": "single"
            }
        ]
    },
    "reportId": "c41286bb-30cd-4109-ba9d-dc4788b6a75c",
    "reportName": "Report_2024-06-12T17-32+00Z_dryrun=false_8acd3a87-2272-450f-a3b3-1eb222108740",
    "type": "provisional-rollback"
}

Step 4: Run the rollback

  1. To run a rollback, use the /environment/promotion/rollback endpoint:

    curl \
--request POST 'https://<tenant-env-upper-fqdn>/environment/promotion/rollback' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(2)
--data-raw '{}'
    1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
    2 Replace <access-token> with an access token for the upper environment (learn more in Get an access token). 
    {
    "result": "Rollback process initiated successfully"
}

  2. Check the rollback status to confirm that the rollback is in progress. This is indicated in the response when status has a value of RUNNING:

    {
    "status": "RUNNING",
    "message": "Prepare config",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:14:13Z",
    "type": "rollback"
}

  3. Check the rollback status as many times as you need until the rollback is complete.

    1. If the rollback is still running, the response status has a value of RUNNING:

      {
    "status": "RUNNING",
    "message": "Rollback configuration",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:15:51Z",
    "type": "rollback"
}

    2. If the rollback failed but is recoverable, the response status has a value of ERROR, and the response blockingError has a value of false.

      1. In the example below, the rollback failed an integrity check for missing ESVs.

        {
    "status": "ERROR",
    "message": "Missing ESVs",
    "blockingError": false,
    "missingESVs": [
        "email.from"
    ],
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:19:31Z",
    "type": "rollback"
}

        To resolve this:

        1. Unlock the environments.

        2. For each ESV in missingESVs, re-add the ESV into the upper environment.

        3. Start the rollback steps again.

    3. If the rollback failed and is not recoverable, the response status has a value of ERROR, and the response blockingError has a value of true:

      {
    "status": "ERROR",
    "message": "Failed to rollback config",
    "blockingError": true,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:19:31Z",
    "type": "rollback"
}

      If you run the rollback again after a blocking error, the following response displays:

      {
    "code": 409,
    "message": "Environment is blocked from a previous failed promotion or rollback"
}

      To resolve this, open a support case with Ping Identity support. Learn more in Resolve environment errors that are preventing a promotion or a rollback.

    4. If Advanced Identity Cloud services are restarting, the response status has a value of RUNNING, and the response message has a value of Waiting for workloads to restart:

      {
    "status": "RUNNING",
    "message": "Waiting for workloads to restart",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:32:06Z",
    "type": "rollback"
}

      This part of the rollback can take several minutes.

    5. If the rollback is complete, the response status has a value of READY, and the response message has a value of Promotion completed:

      {
    "status": "READY",
    "message": "Rollback completed",
    "blockingError": false,
    "globalLock": "LOCKED",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "timeStamp": "2024-06-12T17:40:29Z",
    "type": "rollback"
}

Step 5: Unlock the environments

Follow the instructions in Unlock environments.

Unlock environments

After you run a promotion or a rollback, you must unlock the upper and lower environments.

  1. To unlock the environments, use the /environment/promotion/lock endpoint:

    curl \
--request DELETE 'https://<tenant-env-upper-fqdn>/environment/promotion/lock/<promotion-id>' \(1) (2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(3)
    1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
    2 Replace <promotion-id> with the promotionId created when you initially locked the environments.
    3 Replace <access-token> with an access token for the upper environment (learn more in Get an access token). 
    {
    "description": "Environment unlock in progress",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "result": "unlocking"
}

  2. Check the lock state as many times as you need until both environments are unlocked. This is indicated in the response when result has a value of unlocked:

    {
    "description": "Environment locked",
    "lowerEnv": {
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "state": "locked"
    },
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "result": "locked",
    "upperEnv": {
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "state": "locked"
    }
}

View previous promotion or rollback reports

  1. To view a list of previous promotion or rollback reports, use the /environment/promotion/reports endpoint:

    curl \
--request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/reports' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(2)
    1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
    2 Replace <access-token> with an access token for the upper environment (learn more in Get an access token). 
    [
    {
        "createdDate": "2024-06-12T12:00:29Z",
        "dryRun": true,
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "reportId": "57aabe7d-4e8c-4fbb-8a13-2fc7d1cb4d52",
        "type": "promotion"
    },
    {
        "createdDate": "2024-06-12T17:32:05Z",
        "dryRun": false,
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "reportId": "c41286bb-30cd-4109-ba9d-dc4788b6a75c",
        "type": "promotion"
    },
    {
        "createdDate": "2024-06-12T13:56:10Z",
        "dryRun": true,
        "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
        "reportId": "df893dee-e952-489c-b94d-8c9ebf36e9a5",
        "type": "promotion"
    }
]

  2. To view individual reports, use the /environment/promotion/report endpoint and supply a reportId from the response in the previous step:

    curl \
--request GET 'https://<tenant-env-upper-fqdn>/environment/promotion/report/<report-id>' \(1) (2)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>'(3)
    1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
    2 Replace <report-id> with a reportId; for example, c41286bb-30cd-4109-ba9d-dc4788b6a75c.
    3 Replace <access-token> with an access token for the upper environment (learn more in Get an access token). 
    {
    "createdDate": "2024-06-12T17:32:05Z",
    "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
    "report": {
        "IDMConfig": [
            {
                "configChange": {
                    "added": [
                        "Forgotten Username"
                    ]
                },
                "configItem": "Email > Templates",
                "fileDestinationPattern": "idm/conf/emailTemplate-*.json",
                "fileName": "displayName",
                "type": "single"
            }
        ]
    },
    "reportId": "c41286bb-30cd-4109-ba9d-dc4788b6a75c",
    "reportName": "Report_2024-06-12T17-32+00Z_dryrun=false_8acd3a87-2272-450f-a3b3-1eb222108740",
    "type": "promotion"
}

Resolve environment errors that are preventing a promotion or a rollback

To resolve environment errors that are preventing a promotion or a rollback, open a support case:

  1. Go to https://support.pingidentity.com.

  2. Click Create a case.

  3. Follow the steps in the case submission wizard by selecting your account and contract and answering questions about your tenant environments.

  4. On the Please answer the following questions to help us understand the issue you’re facing page, enter the following details, and then click Next:

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Tenant Settings

    What version of the product are you using?

    Select NA

    Which component is affected?

    Select Self-Service Promotion

  5. On the Tell us about the issue page, enter the following details, and then click Next:

    Field Value

    Provide a descriptive title for your issue

    Enter one of the following:

    • Resolve environment errors preventing a self-service promotion

    • Resolve environment errors preventing a self-service rollback

    Describe the issue below

    Enter the following details:

    • The error type, either:

      • 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

    • The error code and message (API users only).

  6. Click Submit.

Revert configuration in your development environment

To revert configuration in your development environment, open a support case:

  1. Go to https://support.pingidentity.com.

  2. Click Create a case.

  3. Follow the steps in the case submission wizard by selecting your account and contract and answering questions about your tenant environments.

  4. On the Please answer the following questions to help us understand the issue you’re facing page, enter the following details, and then click Next:

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Configuration

    What version of the product are you using?

    Select NA

  5. On the Tell us about the issue page, enter the following details, and then click Next:

    Field Value

    Provide a descriptive title for your issue

    Enter Select Restore from backup

    Describe the issue below

    Enter the following details:

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

    • The environment name (Dev).

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

  6. Click Submit.

Manage self-service promotions using the admin console

You can find background information on self-service promotions in PingOne Advanced Identity Cloud in Introduction to self-service promotions.

Lower and upper environments

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

The admin console uses a push model to promote configuration, so you need to run a promotion from the admin console in the lower environment. However, you also need to have a tenant administrator account in the upper environment, as the admin console 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 functionality in the lower environment

In the lower environment, the admin console 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 console 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[3] 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 admin console 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 admin console in the lower environment shows a sign-in screen for the upper environment. This lets the admin console 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[3] 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 console 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 admin console 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 admin console 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 admin console 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 console of the lower environment, open the TENANT menu (upper right)

  2. Click Promote configuration.

  3. Click View promotion history.

  4. If the admin console 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 functionality in the upper environment

In the upper environment, the admin console 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 console 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 admin console restricts some functionality under Tenant Settings > Promotion until the environments are unlocked.

Restricted functionality in the lower environment

In the lower environment, the admin console 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 admin console 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 admin console 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 admin console 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 admin console 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 admin console 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, open a support case:

  1. Go to https://support.pingidentity.com.

  2. Click Create a case.

  3. Follow the steps in the case submission wizard by selecting your account and contract and answering questions about your tenant environments.

  4. On the Please answer the following questions to help us understand the issue you’re facing page, enter the following details, and then click Next:

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Tenant Settings

    What version of the product are you using?

    Select NA

    Which component is affected?

    Select Self-Service Promotion

  5. On the Tell us about the issue page, enter the following details, and then click Next:

    Field Value

    Provide a descriptive title for your issue

    Enter one of the following:

    • Resolve environment errors preventing a self-service promotion

    • Resolve environment errors preventing a self-service rollback

    Describe the issue below

    Enter the following details:

    • The error type, either:

      • 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

    • The error code and message (API users only).

  6. 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, open a support case:

  1. Go to https://support.pingidentity.com.

  2. Click Create a case.

  3. Follow the steps in the case submission wizard by selecting your account and contract and answering questions about your tenant environments.

  4. On the Please answer the following questions to help us understand the issue you’re facing page, enter the following details, and then click Next:

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Configuration

    What version of the product are you using?

    Select NA

  5. On the Tell us about the issue page, enter the following details, and then click Next:

    Field Value

    Provide a descriptive title for your issue

    Enter Select Restore from backup

    Describe the issue below

    Enter the following details:

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

    • The environment name (Dev).

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

  6. Click Submit.

Service accounts

PingOne Advanced Identity Cloud provides service accounts to let you request access tokens for most REST API endpoints; for example, you may need an access token to use the REST API endpoint /openidm/managed/alpha_user to get a list of identities.

You create a new service account in the Advanced Identity Cloud admin console, which provides you with credentials (a service account ID and a private key). You use the credentials to obtain an access token from a built-in OAuth 2.0 public client using the JWT profile for OAuth 2.0 authorization grant flow. You can then use the access token as a bearer token in the Authorization HTTP header for each API request.

Manage service accounts

A tenant administrator can manage service accounts in these ways:

Only a tenant administrator account has the privileges to create, modify, or delete service accounts.

You create service accounts in each environment; they are not promotable.

Service account scopes

When you create a service account, you choose which scopes it can grant to the access tokens it creates. You should always choose the minimum number of scopes needed.

Scopes for AM and IDM APIs in Advanced Identity Cloud

Scope Purpose Reference

fr:am:*  

Access to /am/* API endpoints

PingAM REST API reference

fr:idm:*      

Access to /openidm/* and ESV API endpoints

PingIDM REST API reference
Service account access tokens granted the fr:idm:* scope also have access to API endpoints under the fr:idc:esv:* scope.

Scopes for Advanced Identity Cloud environment APIs

Scope Purpose Reference

fr:idc:certificate:*  

Access to certificate API endpoints

Manage SSL certificates using the API

      fr:idc:certificate:read

Read-only access to certificate API endpoints. Use this scope if you only need to list certificates.

fr:idc:content-security-policy:*  

Access to Content Security Policy API endpoints

Content Security Policy API endpoint

fr:idc:cookie-domain:*  

Full access to cookie domain API endpoints.

Manage cookie domains using the API

fr:idc:custom-domain:*  

Access to custom domain endpoints

Custom domains API endpoint

fr:idc:esv:*      

Access to ESV API endpoints

Manage ESVs using the API

      fr:idc:esv:read

Read-only access to ESV API endpoints. Use this scope if you only need to list ESVs.

      fr:idc:esv:update

Create, update, and delete access to ESV API endpoints

      fr:idc:esv:restart

Access to ESV API endpoint to restart Advanced Identity Cloud services

fr:idc:promotion:*  

Access to promotions API endpoints

Manage self-service promotions using the API

fr:idc:release:*  

Access to release management API endpoints

Release management API endpoint

fr:idc:sso-cookie:*  

Access to SSO cookie API endpoints

SSO cookie API endpoint

Scopes for Advanced Identity Cloud APIs under development

The following scopes grant access to API endpoints that are under development and will imminently be released to the rapid channel.

Scope Purpose Reference

fr:idc:analytics:*  

Access to analytics API endpoints

fr:idc:dataset:*  

Access to dataset deletion API endpoints

fr:idc:mtls:*  

Access to mTLS (mutual TLS) API endpoints

Scopes for add-on capability APIs

The following scopes grant access to API endpoints in Add-on capabilities.

Scope Purpose Reference

fr:idc:proxy-connect:*  

Full access to Proxy Connect API endpoints. Use this scope to view, create, activate, deactivate, or delete rules.

Manage Proxy Connect using the API

      fr:idc:proxy-connect:read

Read-only access to Proxy Connect API endpoints. Use this scope if you only need to view rules.

      fr:idc:proxy-connect:write

Write access to Proxy Connect API endpoints. Use this scope to create, activate, deactivate, or delete rules.

fr:iga:*  

Access to IGA API endpoints

Identity Governance REST API reference

Restricted scopes

The following scopes are restricted, so the API endpoints under them are not accessible using a service account access token. Learn how to access API endpoints using a tenant administrator access token in the article A scripted approach for creating and using service accounts in PingOne Advanced Identity Cloud.

Scope Purpose Reference

fr:idc:federation:*  

Access to federation API endpoints

Federation API endpoint

Get an access token using a service account

To get an access token using a service account, learn more in Authenticate to Advanced Identity Cloud REST API with access token.

You can also create a script to get a service account access token within your journeys. This approach lets you use the access token in API calls in a Scripted Decision node in Advanced Identity Cloud. Learn more in Get an access token in a journey for an example.

Manage service accounts using the admin console

View service accounts

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

    150

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts. The page displays existing service accounts for your tenant.

Create a new service account

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

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts.

  5. Click New Service Account.

  6. Enter a Name and optional Description for the service account.

  7. In the Scopes section, select the scopes that the service application can grant to an access token. Learn more in Service account scopes.

  8. Click Save.

  9. When the 'Service account successfully created!' message shows:

    1. Make a note of the service account ID, found in the ID field.

    2. Click Download Key to download the service account private key.

      You must download the private key at this point as it will not be available again.

  10. Click Done.

To get an access token using a service account, learn more in Authenticate to Advanced Identity Cloud REST API with access token.

Modify a service account

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

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts.

  5. Click the ellipsis on the right of a service account and select Edit.

  6. You can change the Name or optional Description.

  7. In the Scopes section, you can change the scopes that the service application can grant to an access token. Learn more in Service account scopes.

    Before removing scopes that the service application can grant to an access token, make sure you identify which of your integrations are dependent upon those scopes; otherwise those integrations will fail the next time they request an access token.

  8. Click Save.

Regenerate a key for a service account

Before regenerating a key, make sure you identify which of your integrations are dependent upon it to sign JWTs, as all those integrations need to be updated with the new key.

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

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts.

  5. Click the ellipsis on the right of a service account and select Regenerate Key.

  6. On the Regenerate Key dialog box, click Regenerate Key.

  7. When the 'Key successfully created!' message is shown:

    1. Click Download Key to download the new service account private key.

      You must download the private key at this point as it will not be available again.

  8. Click Done.

Delete a service account

Before deleting a service account, make sure none of your integrations are dependent upon its key to sign JWTs; otherwise those integrations will fail the next time they request an access token.

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

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts.

  5. Click the ellipsis on the right of a service account and select Delete.

  6. On the Delete Service Account page, click Delete Service Account.

Monitor your tenant

PingOne Advanced Identity Cloud lets you monitor uptime status and system performance.

Advanced Identity Cloud also provides APIs for extracting log data. Learn more in View audit and debug logs.

Monitor uptime status

Tenant status page

Use your tenant status page to monitor uptime and historical trends for your production and staging tenant environments.

If you don’t have access to this page, follow the instructions in Get status page access credentials for additional tenant administrators.
Production environment

For the production environment, the tenant status page shows individual statuses for these services:

  • Access Management

  • Identity Management

  • End User UI

  • Login UI

  • Registration UI

  • Administrator UI

  • Logs

    400

Staging environment

For the staging environment, the tenant status page combines the individual service statuses into a single status.

Manage access to your tenant status page

Get status page access credentials for the initial tenant administrator

If you are the initial tenant administrator, you should have received status page credentials when your tenant was set up.

If you have lost or forgotten those credentials, follow the instructions in Get status page access credentials for additional tenant administrators.

Get status page access credentials for additional tenant administrators

If monitoring Advanced Identity Cloud uptime status is part of a tenant administrator’s role, create a support case in the Ping Identity Support Portal to request that the administrator receive access to the tenant status page.

  • You can request access on behalf of one or more tenant administrators, including yourself.

  • In the request, provide the email address of each tenant administrator you want to have status page access.

Remove status page access for tenant administrators

If you want to remove status page access for one or more tenant administrators, create a support case in the Ping Identity Support Portal. In the request, provide the email address of each tenant administrator from which you want to remove access.

Access your tenant status page

If you don’t have access to this page, follow the instructions in Get status page access credentials for additional tenant administrators.

  1. Identify your tenant domain name by removing the protocol and any trailing slash from your tenant FQDN.

    Example: openam-mycompany-mytenant-usw1.id.forgerock.io

  2. Obtain your tenant status page URL by appending your tenant domain name to the Advanced Identity Cloud status page URL, https://status.id.forgerock.io.

    Example: https://status.id.forgerock.io/openam-mycompany-mytenant-usw1.id.forgerock.io

  3. Open your tenant status page URL in a browser.

  4. On the sign-on page, enter your status page credentials.

  5. Click Authenticate.

    Your tenant status page displays, showing real-time status information for your staging and production tenant environments:

    400

View incident reports in your production tenant environment

Filter your status page to show service incidents in your production tenant environment:

  1. Click View historical uptime.

  2. Select the Incidents tab.

  3. For the production environment, click Filter Components, then select one or more Advanced Identity Cloud services.

    400

  4. Click Filter Components again to view the incident reports.

Monitor system performance

Monitor using health check endpoint

Use the HTTP response codes from the /monitoring/health endpoint to integrate your tenant environment with external monitoring tools such as Pingdom.

$ curl 'https://<tenant-env-fqdn>/monitoring/health'

This endpoint returns the following HTTP response status codes:

200

Indicates all critical services in an environment are healthy. This status code also shows the informational message OK.

503

Indicates one or more critical services in an environment are not healthy. This status code also shows the informational message Service Unavailable.

Monitor using Prometheus endpoints

Advanced Identity Cloud provides monitoring endpoints you can use with Prometheus.

Endpoint Description

/monitoring/prometheus/am

Produces Prometheus-formatted metrics for Access Management.

Learn which AM metrics are available in the self-managed documentation:

/monitoring/prometheus/idm

Produces Prometheus-formatted metrics for Identity Management

Learn which IDM metrics are available in the self-managed documentation:

Advanced Identity Cloud adds a kubernetes_pod_name label to each metric to allow your monitoring to distinguish between the Kubernetes pods within a tenant environment:

 # TYPE am_authentication summary
 am_authentication_total{kubernetes_pod_name="am-75b55d85c8-gqw9l",outcome="failure",} 0.0
 am_authentication_count{kubernetes_pod_name="am-75b55d85c8-gqw9l",outcome="failure",} 0.0
 am_authentication_total{kubernetes_pod_name="am-75b55d85c8-gqw9l",outcome="success",} 7016.0
 am_authentication_count{kubernetes_pod_name="am-75b55d85c8-gqw9l",outcome="success",} 7016.0

You must obtain API credentials to authenticate to the /monitoring/prometheus/am and /monitoring/prometheus/idm endpoints. Learn more in Authenticate to Advanced Identity Cloud REST API with API key and secret.

You can download and run a Docker-based example of a Grafana dashboard. The demo requires that you have Docker Desktop installed, and requires macOS.

To try the demo:

  1. Download and extract the PingOne Advanced Identity Cloud Monitoring Demo ZIP file.

  2. Edit the setup_monitoring_config.sh file:

    1. In the TENANT_DOMAIN variable, enter the domain name of your tenant.

      Do not include the protocol, and do not add a trailing slash.

      For example:

      TENANT_DOMAIN="openam-mycompany-mytenant-usw1.id.forgerock.io"

    2. In the API_KEY_ID and API_KEY_SECRET variables, enter the API credentials you obtained earlier.

      For example:

      API_KEY_ID="b977d5724ef...562e4c57"
API_KEY_SECRET="d3628be865ce152f49...870e5fd3506c4"

    3. Save your changes.

  3. Run the setup_monitoring_config.sh script.

    The Shell script will set up the following config files:

    Config File Description

    prometheus/prometheus.yml

    The script populates the tenant domain and API credentials.

    docker/docker-compose.yml

    The script populates the working directory path.

  4. Run the following Docker command:

    docker-compose -f docker/docker-compose.yml up

    The command downloads a Prometheus Docker image and configures it for your tenant. It also downloads a Grafana Docker image, and configures it to use the Prometheus image as a data source.

  5. When the command output for the "grafana_1" container displays a message that contains "HTTP Server Listen", open http://localhost:3000 in a web browser.

  6. Log in with username admin, password admin.

  7. Enter a new password to use for the administrator, or click Skip.

  8. On the Grafana Home page, select Dashboards in the left-side hamburger menu.

    The Dashboards page appears.

  9. Select AM Overview to view the AM overview dashboard:

    Sample AM Grafana Dashboard

  10. Select IDM Sample Dashboard to view the IDM sample dashboard.

  11. Go to http://localhost:9090 to view the Prometheus dashboard.

Get audit and debug logs

PingOne Advanced Identity Cloud provides audit and debug logs to help you manage your tenant:

  • Use audit logs to investigate user and system behavior.

  • Use debug logs to investigate any issues that can arise in production.

Advanced Identity Cloud stores logs for 30 days. Use the /monitoring/logs endpoint to access the stored data.

You need to get an API key and secret before you can authenticate to the endpoints.

Sources

Advanced Identity Cloud makes browsing the logs easier by storing them in various sources.

View sources

To view a list of the available sources, use the /monitoring/logs/sources endpoint.

Example request:

$ curl \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs/sources' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>'

Example response:

{
  "result": [
    "am-access",
    "am-activity",
    "am-authentication",
    "am-config",
    "am-core",
    "am-everything",
    "idm-access",
    "idm-activity",
    "idm-authentication",
    "idm-config",
    "idm-core",
    "idm-everything",
    "idm-recon",
    "idm-sync"
  ],
  "resultCount": 14,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": 1,
  "remainingPagedResults": 0
}

Advanced Identity Cloud returns the available sources in the result array.

Source descriptions

The following table lists the available sources and describes their purpose:

Source Type Description

am-access

Audit

Captures all incoming Advanced Identity Cloud access calls as audit events. This includes who, what, when, and the output for every access request.

Audit events:

  • AM-ACCESS-ATTEMPT

  • AM-ACCESS-OUTCOME

Show example 
{
  "payload": {
    "_id": "92c9b6a4-f36f-438a-b1d4-c6e6bd909da6-783933",
    "client": {
      "ip": "198.51.101.0"
    },
    "component": "OAuth",
    "eventName": "AM-ACCESS-ATTEMPT",
    "http": {
      "request": {
        "headers": {
          "content-type": [
            "application/x-www-form-urlencoded"
          ],
          "host": [
            "<tenant-env-fqdn>"
          ],
          "user-agent": [
            "Apache-HttpClient/4.5.13 (Java/11.0.11)"
          ],
          "x-forwarded-for": [
            "198.51.101.0, 203.0.116.0, 192.0.3.255"
          ],
          "x-forwarded-proto": [
            "https"
          ]
        },
        "method": "POST",
        "path": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token",
        "secure": true
      }
    },
    "level": "INFO",
    "realm": "/alpha",
    "request": {
      "detail": {
        "client_id": "RCSClient",
        "grant_type": "client_credentials",
        "scope": "fr:idm:*"
      }
    },
    "source": "audit",
    "timestamp": "<dateTime>",
    "topic": "access",
    "transactionId": "1634116808645-2e50ecbf0df5407a6870-226587/0"
  },
  "timestamp": "<dateTime>",
  "type": "application/json"
}
Access log format
_id

A universally unique identifier (UUID) for the message object, such as a568d4fe-d655-49a8-8290-bfc02095bec9-491.

timestamp

The timestamp when Advanced Identity Cloud logged the message, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ. For example: 2015-11-14T00:16:04.653Z

eventName

The name of the audit event. For example, AM-ACCESS-ATTEMPT and AM-ACCESS-OUTCOME.

transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling that request are assigned that transaction ID, so you could see the same transaction ID for different audit event topics. For example, 9c9e8d5c-2941-4e61-9c3c-8a990088e801.

userId

The universal identifier for authenticated users. For example, id=scarter,ou=user,o=shop,ou=services,dc=example,dc=com.

trackingIds

A unique random string generated as an alias for each Advanced Identity Cloud session ID and OAuth 2.0 token.

When Advanced Identity Cloud generates an access or grant token, it also generates a unique random value and logs it as an alias. In this way, you can trace an access token back to its originating grant token, trace the grant token back to the session in which it was created, and then trace how the session was authenticated. An example of a trackingIds property in an OAuth 2.0/OpenID Connect 1.0 environment is:

[ "1979edf68543ead001", "8878e51a-f2aa-464f-b1cc-b12fd6daa415", "3df9a5c3-8d1e-4ee3-93d6-b9bbe58163bc" ]
client.host

The client hostname. This field is populated only if reverse DNS lookup is enabled.

client.ip

The client IP address.

client.port

The client port number.

request.protocol

The protocol associated with the request operation.

Possible values: CREST, PLL, SAML2.

request.operation

The request operation. For common REST operations, possible values are: READ, ACTION, QUERY.

For PLL operations, possible values are: LoginIndex, SubmitRequirements, GetSession, REQUEST_ADD_POLICY_LISTENER.

request.detail

Detailed information about the request operation. For example:

  • {"action":"idFromSession"}

  • {"action":"validateGoto"}

  • {"action":"validate"}

  • {"action":"logout"}

  • {"action":"schema"}

  • {"action":"template"}

Example values for an OAuth 2.0 app tree flow:

{
    "oAuth2Client":"myClient",
    "configuredService":"oauth2Tree"
}

Example values for a SAML 2.0 app tree flow:

{
    "spEntity":"serviceprovider1",
    "idpEntity":"identityprovider1",
    "configuredService":"samlTree"
}
http.method

The HTTP method requested by the client. For example, GET, POST, PUT.

http.path

The path of the HTTP request; for example, https://<tenant-env-fqdn>//am/json/realms/root/realms/alpha/authenticate.

http.queryParameters

The HTTP query parameter string. For example:

  • { "_action": [ "idFromSession" ] }

  • { "_queryFilter": [ "true" ] }

  • { "_action": [ "validate" ] }

  • { "_action": [ "logout" ] }

  • { "realm": [ "/shop" ] }

  • { "_action": [ "validateGoto" ] }

http.request.headers

The HTTP header for the request.

Example 
{
    "accept": [
        "application/json"
    ],
    "accept-api-version": [
        "protocol=1.0,resource=2.1"
    ],
    "content-type": [
        "application/json"
    ],
    "host": [
        "example.forgeblocks.com"
    ],
    "origin": [
        "https://example.forgeblocks.com"
    ],
    "user-agent": [
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:120.0) Gecko/20100101 Firefox/120.0"
    ],
    "x-forwarded-for": [
        "188.39.235.130, 34.117.102.58, 10.154.0.3"
    ],
    "x-forwarded-proto": [
        "https"
    ],
    "x-requested-with": [
        "forgerock-sdk"
    ]
}
http.request.cookies

A JSON map of key-value pairs and appears as its own property to allow for denylisting fields or values.

http.response.cookies

Not used in Advanced Identity Cloud.

response.status

The response status of the request. For example, SUCCESS, FAILURE, or null.

response.statusCode

The response status code, depending on the protocol. For common REST, HTTP failure codes are displayed but HTTP success codes aren’t. For PLL endpoints, PLL error codes are displayed.

response.detail

The message associated with response.statusCode. For example, the response.statusCode of 401 has a response.detail of { "reason": "Unauthorized" }.

response.elapsedTime

The time to execute the access event, usually in millisecond precision.

response.elapsedTimeUnits

The elapsed time units of the response. For example, MILLISECONDS.

component

The Advanced Identity Cloud service utilized; for example, Server Info, Users, Config, Session, Authentication, Policy, OAuth, SAML2, Web Policy Agent, or Java Policy Agent.

realm

The realm where the operation occurred. For example, ("/alpha").

am-activity

Audit

Captures state changes to objects that were created, updated, or deleted by Advanced Identity Cloud end users. This includes session, user profile, and device profile changes.

Audit events:

  • AM-SELFSERVICE-REGISTRATION-COMPLETED

  • AM-SELFSERVICE-PASSWORDCHANGE-COMPLETED

  • AM-SESSION-CREATED

  • AM-SESSION-IDLE_TIME_OUT

  • AM-SESSION-MAX_TIMED_OUT

  • AM-SESSION-LOGGED_OUT

  • AM-SESSION-DESTROYED

  • AM-SESSION-PROPERTY_CHANGED

  • AM-IDENTITY-CHANGE

  • AM-GROUP-CHANGE

Show example 
{
  "timestamp": "<dateTime>",
  "payload": {
    "_id": "3fc956b8-00a1-4e10-b8aa-72295d003bfb-195032",
    "objectId": "3fc956b8-00a1-4e10-b8aa-72295d003bfb-195023",
    "transactionId": "cf2a721c-9cec-4224-bdd1-3a33e1f8ed56/4",
    "level": "INFO",
    "eventName": "AM-SESSION-CREATED",
    "timestamp": "<dateTime>",
    "component": "Session",
    "source": "audit",
    "topic": "activity",
    "trackingIds": [
      "3fc956b8-00a1-4e10-b8aa-72295d003bfb-195023"
    ],
    "realm": "/",
    "userId": "id=amadmin,ou=user,ou=am-config",
    "runAs": "id=amadmin,ou=user,ou=am-config",
    "operation": "CREATE"
  },
  "type": "application/json"
}
Activity log format
_id

A universally unique identifier (UUID) for the message object, such as a568d4fe-d655-49a8-8290-bfc02095bec9-487.

changedFields

Not used.

component

The Advanced Identity Cloud service utilized. For example, Session or ID Repo.

eventName

The name of the audit event. For example, AM-SESSION_CREATED, AM-SESSION-LOGGED_OUT, AM-NEW-CONNECTION-FACTORY.

level

The activity log level, INFO by default.

objectId

The unique identifier of the object that was created, updated, or deleted. For logging sessions, the session trackingId is used in this field.

operation

The stage change operation performed on the object. For example, CREATE or UPDATE.

runAs

The user to run the activity as, used in delegated administration.

transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling that request are assigned that transaction ID, so you could see the same transaction ID for different audit event topics. For example, 9c9e8d5c-2941-4e61-9c3c-8a990088e801.

trackingIds

An array containing the following:

  • A random context ID that identifies the session

  • A random string generated from an OAuth 2.0/OIDC 1.0 flow that could track an access token ID or a grant token ID.

For example, [ "c120669f-f636-467d-8da0-590d72aeaf08-181706" ].

userId

The universal identifier for authenticated users. For example, id=fe32c8fe-38a2-4159-a220-9385350f3aca,ou=user,ou=am-config.

timestamp

The timestamp when Advanced Identity Cloud} logged the message, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ. For example: 2015-11-14T00:16:04.652Z

type

The data type,application/json by default.

source`

The source of these logs, am-activity.

am-authentication

Audit

Captures when and how a user authenticated and related audit events.

Advanced Identity Cloud records an authentication audit event for each authentication node and the journey outcome. A node can provide extra data in the standard audit event, which is logged when an authentication node completes.

Audit events:

  • AM-BACK-CHANNEL-INITIALIZE

  • AM-LOGOUT

  • AM-LOGIN-COMPLETED

  • AM-LOGIN-MODULE-COMPLETED

  • AM-NODE-LOGIN-COMPLETED

    Advanced Identity Cloud logs this audit event each time an authentication node completes.

    Show example 
    {
  "type": "application/json",
  "timestamp": "<dateTime>",
  "payload": {
    "topic": "authentication",
    "eventName": "AM-NODE-LOGIN-COMPLETED",
    "transactionId": "ad56bedd-7dab-45d1-84d9-505b0b64fd6d/6",
    "principal": [
      "amadmin"
    ],
    "timestamp": "<dateTime>",
    "component": "Authentication",
    "source": "audit",
    "realm": "/",
    "entries": [
      {
        "info": {
          "authLevel": "0",
          "displayName": "Page Node",
          "nodeId": "83a9d86e-d6f5-11ea-87d0-0242ac130003",
          "nodeOutcome": "outcome",
          "treeName": "FRLogin",
          "nodeType": "PageNode"
        }
      }
    ],
    "level": "INFO",
    "trackingIds": [
      "3fc956b8-00a1-4e10-b8aa-72295d003bfb-184020"
    ],
    "_id": "3fc956b8-00a1-4e10-b8aa-72295d003bfb-184022"
  }
}

  • AM-TREE-LOGIN-STARTED

    • Disabled by default in Advanced Identity Cloud.

  • AM-TREE-LOGIN-COMPLETED

    • If authentication completes successfully, the event has a result of SUCCESS.

    • If authentication fails, the event has a result of FAILED.

    • If the authentication ends in an exception, the event has a result of FAILED with the following additional field:

      exception: "An exception occurred during the authentication process"

      These exceptions let you troubleshoot authentication journeys that failed due to misconfiguration.

Learn more about am-authentication properties in Authentication log format.

Authentication log format
_id

A universally unique identifier (UUID) for the message object, such as a568d4fe-d655-49a8-8290-bfc02095bec9-487.

changedFields

Not used.

component

The Advanced Identity Cloud service utilized. For example, Session or ID Repo.

eventName

The name of the audit event. For example, AM-SESSION_CREATED, AM-SESSION-LOGGED_OUT, AM-NEW-CONNECTION-FACTORY.

level

The activity log level, INFO by default.

objectId

The unique identifier of the object that was created, updated, or deleted. For logging sessions, the session trackingId is used in this field.

operation

The stage change operation performed on the object. For example, CREATE or UPDATE.

runAs

The user to run the activity as, used in delegated administration.

transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling that request are assigned that transaction ID, so you could see the same transaction ID for different audit event topics. For example, 9c9e8d5c-2941-4e61-9c3c-8a990088e801.

trackingIds

An array containing the following:

  • A random context ID that identifies the session

  • A random string generated from an OAuth 2.0/OIDC 1.0 flow that could track an access token ID or a grant token ID.

For example, [ "c120669f-f636-467d-8da0-590d72aeaf08-181706" ].

userId

The universal identifier for authenticated users. For example, id=fe32c8fe-38a2-4159-a220-9385350f3aca,ou=user,ou=am-config.

timestamp

The timestamp when Advanced Identity Cloud} logged the message, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ. For example: 2015-11-14T00:16:04.652Z

type

The data type,application/json by default.

source`

The source of these logs, am-activity.

am-config

Audit

Captures access management configuration changes for Advanced Identity Cloud with a timestamp and by whom.

Configuration changes can only be performed in development environments, so these logs are empty in staging and production environments.

Audit events:

  • AM-CONFIG-CHANGE

Show example 
{
  "payload": {
    "_id": "92c9b6a4-f36f-438a-b1d4-c6e6bd909da6-822860",
    "eventName": "AM-CONFIG-CHANGE",
    "level": "INFO",
    "objectId": "ou=Office365,ou=dashboardApp,ou=default,ou=GlobalConfig,ou=1.0,ou=dashboardService,ou=services,ou=am-config",
    "operation": "CREATE",
    "runAs": "id=bd220328-9762-458b-b05a-982ac3c7fc54,ou=user,ou=am-config",
    "source": "audit",
    "timestamp": "<dateTime>",
    "topic": "config",
    "trackingIds": [
      "92c9b6a4-f36f-438a-b1d4-c6e6bd909da6-821644"
    ],
    "transactionId": "1634122041174-2e50ecbf0df5407a6870-229391/0",
    "userId": "id=bd220328-9762-458b-b05a-982ac3c7fc54,ou=user,ou=am-config"
  },
  "timestamp": "<dateTime>",
  "type": "application/json"
}
Config log format
_id

A universally unique identifier (UUID) for the message object. For example, 6a568d4fe-d655-49a8-8290-bfc02095bec9-843.

timestamp

The timestamp when Advanced Identity Cloud logged the message, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ. For example, 2015-11-14T00:21:03.490Z

eventName

The name of the audit event. For example, AM-CONFIG-CHANGE.

transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling the request will be assigned that transaction ID, so you could see the same transaction ID for different audit event topics. For example, 301d1a6e-67f9-4e45-bfeb-5e4047a8b432.

user.id

Not used.

You can determine the value for this field by linking to the access event using the same transactionId.

trackingIds

Not used.

runAs

The user to run the activity as. Can be used in delegated administration.

objectId

The identifier of a system object that has been created, modified, or deleted. For example, ou=SamuelTwo,ou=default,ou=OrganizationConfig,ou=1.0, ou=iPlanetAMAuthSAML2Service,ou=services,o=shop,ou=services,dc=example,dc=com.

operation

The state change operation invoked: CREATE, MODIFY, or DELETE.

before

The JSON representation of the object prior to the activity.

Example:

{
   "sunsmspriority":[
      "0"
   ],
   "objectclass":[
      "top",
      "sunServiceComponent",
      "organizationalUnit"
   ],
   "ou":[
      "SamuelTwo"
   ],
   "sunserviceID":[
      "serverconfig"
   ]
}
after

The JSON representation of the object after the activity.

Example:

{
 "sunKeyValue":[
      "forgerock-am-auth-saml2-auth-level=0",
      "forgerock-am-auth-saml2-meta-alias=/sp",
      "forgerock-am-auth-saml2-entity-name=http://",
      "forgerock-am-auth-saml2-authn-context-decl-ref=",
      "forgerock-am-auth-saml2-force-authn=none",
      "forgerock-am-auth-saml2-is-passive=none",
      "forgerock-am-auth-saml2-login-chain=",
      "forgerock-am-auth-saml2-auth-comparison=none",
      "forgerock-am-auth-saml2-req-binding= urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
      "forgerock-am-auth-saml2-binding= urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact",
      "forgerock-am-auth-saml2-authn-context-class-ref=",
      "forgerock-am-auth-saml2-slo-relay=http://",
      "forgerock-am-auth-saml2-allow-create=false",
      "forgerock-am-auth-saml2-name-id-format= urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
   ]
}
changedFields

The fields that were changed. For example, [ "sunKeyValue" ].

revision

Not used.

component

Not used.

realm

The realm where the operation occurred. For example, ("/alpha").

am-core

Debug

Captures access management debug logs for Advanced Identity Cloud. Use am-core when debugging anything in access management without capturing audit events. am-core also captures logging in authentication scripts.

Development and sandbox environments provide DEBUG level logs, with logs in several areas tuned to INFO or WARNING.

To reduce log volumes, staging and production environments only provide WARNING level logs and above.

To troubleshoot and view the latest entries in the stored logs, you can tail am-core source. Learn more in Tail logs.

am-everything

Audit, Debug

Captures all access management audit and debug logs for Advanced Identity Cloud.

This includes all the logs captured in am-access, am-activity, am-authentication, am-config, and am-core.

idm-access

Audit

Captures messages for the identity management REST endpoints and the invocation of scheduled tasks. This is the who, what, and output for every identity management access request in Advanced Identity Cloud.

Audit events:

  • access

Show example 
{
  "payload": {
    "_id": "32c02w2f-bafe-4bdf-a8e1-1ce94813c46b-123717",
    "client": {
      "ip": "198.51.101.0",
      "port": 60572
    },
    "eventName": "access",
    "http": {
      "request": {
        "headers": {
          "host": [
            "<tenant-env-fqdn>:443"
          ],
          "user-agent": [
            "Blackbox Exporter/0.25.0"
          ],
          "x-forwarded-for": [
            "34.102.86.57, 34.97.113.137, 120.211.3.20"
          ],
          "x-forwarded-proto": [
            "https"
          ],
          "x-real-ip": [
            "34.102.86.57"
          ]
        },
        "method": "GET",
        "path": "https://<tenant-env-fqdn>/openidm/info/ping",
        "secure": true
      }
    },
    "level": "INFO",
    "request": {
      "operation": "READ",
      "protocol": "CREST"
    },
    "response": {
      "elapsedTime": 10,
      "elapsedTimeUnits": "MILLISECONDS",
      "status": "SUCCESSFUL",
      "statusCode": "200"
    },
    "roles": [
      "internal/role/openidm-reg"
    ],
    "server": {
      "ip": "10.68.2.21",
      "port": 8080
    },
    "source": "audit",
    "timestamp": "dateTime",
    "topic": "access",
    "transactionId": "6b3a1cbb-523d-48ae-bd11-1aca4b65c294/0",
    "userId": "anonymous"
  },
  "source": "idm-access",
  "timestamp": "<dateTime>",
  "type": "application/json"
}

Learn more about idm-access properties in Access event topic properties.

idm-activity

Audit

Captures operations on internal (managed) and external (system) objects in Advanced Identity Cloud. idm-activity logs the changes to identity content, such as adding or updating users and changing passwords.

Audit events:

  • activity

Show example 
{
  "timestamp": "<dateTime>",
  "type": "application/json",
  "payload": {
    "_id": "eebf2abb-e4f1-428f-8fbb-8c18ed3f9559-218925",
    "transactionId": "1630077288251-f5190abcb8c2d0d42c31-136380/0",
    "message": "",
    "timestamp": "<dateTime>",
    "eventName": "activity",
    "userId": "bd220328-9762-458b-b05a-982ac3c7fc54",
    "revision": "00000000478fd92b",
    "operation": "PATCH",
    "changedFields": [],
    "runAs": "bd220328-9762-458b-b05a-982ac3c7fc54",
    "passwordChanged": true,
    "status": "SUCCESS",
    "objectId": "managed/alpha_user/e70c4476-1305-408a-9246-ac76c64ba039"
  }
}

Learn more about idm-activity properties in Activity event topic properties.

idm-authentication

Audit

Captures the results when authenticating to an /openidm endpoint to complete certain actions on an object.

If an authentication session already exists in access management, authentication to identity management is not required. In this instance, the authentication logs would appear for am-authentication, with identity management logs in idm-access and idm-activity.

Audit events:

  • authentication

Learn more about idm-authentication properties in Authentication event topic properties.

idm-config

Audit

Captures identity management configuration changes for Advanced Identity Cloud with a timestamp and by whom.

Configuration changes can only be performed in development environments, so these logs are empty in staging and production environments.

Audit events:

  • CONFIG

Show example 
{
  "payload": {
    "_id": "f6a3a7b2-aaf3-426d-a998-a970f84bdf4b-1519486",
    "changedFields": [
      "/mappings"
    ],
    "eventName": "CONFIG",
    "objectId": "sync",
    "operation": "UPDATE",
    "revision": null,
    "runAs": "bd220328-9762-458b-b05a-982ac3c7fc54",
    "timestamp": "<dateTime>",
    "transactionId": "1634054726312-2e50ecbf0df5407a6870-202437/0",
    "userId": "bd220328-9762-458b-b05a-982ac3c7fc54"
  }
}

Learn more about idm-config properties in Configuration event topic properties.

idm-core

Debug

Captures identity management debug logs for Advanced Identity Cloud. Use idm-core when debugging anything in identity management without capturing audit events.

Development and sandbox environments provide FINE level logs, with logs in several areas tuned to INFO, WARNING and SEVERE.

To reduce log volumes, staging and production environments only provide INFO and WARNING level logs and above.

To troubleshoot and view the latest entries in the stored logs, you can tail idm-core source. Learn more in Tail logs.

idm-everything

Audit, Debug

Captures identity management audit and debug logs for Advanced Identity Cloud.

This includes all the logs captured in idm-access, idm-activity, idm-authentication, idm-config, idm-recon, idm-sync, and idm-core.

idm-recon

Audit

Captures reconciliation events for Advanced Identity Cloud.

The corresponding audit topic for idm-recon is disabled by default in Advanced Identity Cloud. For reconciliation events to appear in the audit logs, you must enable the recon event handler.

Learn more about idm-recon event properties in Reconciliation event topic properties.

idm-sync

Audit

Captures any changes to an object resulting in automatic sync (live sync and implicit sync) when a repository is mapped to Advanced Identity Cloud. This includes situations and the actions taken on each object, by account. The idm-activity log contains additional details about each action.

Learn more about idm-sync event properties in Synchronization event topic properties.

Retrieve log entries

To retrieve the stored log entries for a source, use the /monitoring/logs endpoint, specifying the source as a parameter.

Example request:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication'

Example response:

{
  "result": [{
    "payload": "<payload>",
    "timestamp": "<dateTime>",
    "type": "application/json",
    "source": "am-authentication"
  }, {
    "...": "..."
  }],
  "resultCount": "1000",
  "pagedResultsCookie": "<pagedResultsCookie>",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Advanced Identity Cloud returns the available log entries in the result array. Results are in JSON format or plaintext, depending on the source you request.

To reduce the size of the output, log query results are by default restricted to the last 24 hours, unless you add beginTime and/or endTime query parameters. Learn more in Get log results for a time period.

Get log results for a time period

Use the beginTime and endTime query parameters to return entries created between two ISO 8601 formatted times.

Example request:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication' \
--data 'beginTime=2023-03-01T12:45:00Z' \
--data 'endTime=2023-03-01T12:50:00Z'

The beginTime and endTime query parameters are subject to these rules:

  1. If endTime is not specified, it defaults to the current time.

  2. If beginTime is not specified, it defaults to 24 hours before endTime.

  3. If beginTime is specified, it must be 24 hours or less before endTime.

Tail logs

To tail, or get the latest entries in the stored logs for a source, use the /monitoring/logs/tail endpoint with the source as a parameter.

The first call to the tail endpoint returns log entries from the last 15 seconds. Subsequent calls return log entries in a range that starts from the last returned log entry in the previous result (inclusive) and ends with the latest log entry but one. If calls to the tail endpoint are not frequent enough to match the rate at which the log entries are produced, the result may not include all available log entries.

The format of the log results depends on the source or sources specified in your request. Some sources return only JSON formatted log entries and some sources return only plaintext log entries. Some sources, such as am-everything, can return log entries in both formats.

Example request:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs/tail' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-everything'

Example response:

{
  "result": [{
    "payload": "<payload>",
    "timestamp": "<dateTime>",
    "type": "<type>",
    "source": "am-core"
  }, {
    "...": "..."
  }],
  "resultCount": "100",
  "pagedResultsCookie": "<pagedResultsCookie>",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

You can specify multiple sources in a single call. Example request:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs/tail' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-access,idm-access,idm-sync,idm-activity'

To keep tailing, pass the pagedResultsCookie value from the previous response in your request. This retrieves new records since your request.

Example request:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs/tail' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-access,idm-access,idm-sync,idm-activity' \
--data '_pagedResultsCookie=<pagedResultsCookie>'

View logs for a specific request

All log events for an external request into Advanced Identity Cloud are assigned the same unique transaction ID. The x-forgerock-transactionid response header holds the transaction ID:

$ curl \
--request POST 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate' \
--include \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Passw0rd!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
...
x-forgerock-transactionid: <transaction-id>
...

To filter the logs for a specific transaction ID, add the transactionId parameter to your API request; for example:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication' \
--data 'transactionId=<transaction-id>'

Example response:

{
  "result": [{
    "payload": "<payload>",
    "timestamp": "<dateTime>",
    "type": "application/json",
    "source": "am-authentication"
  }, {
    "...": "..."
  }],
  "resultCount": "8",
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Filter log results

Use the _queryFilter parameter to filter log results on any field or combination of fields in a payload. You can add the parameter to the /monitoring/logs and /monitoring/logs/tail endpoints.

The benefits of the _queryFilter parameter are:

  • Lets you iteratively refine queries to remove extraneous results and find the specific log entries you are interested in. This is useful when searching logs to debug a production issue.

    Use the /monitoring/logs endpoint for iterative searching as the /monitoring/logs/tail endpoint only returns results from the last 15 seconds.

  • Lets you tune queries to reduce Advanced Identity Cloud log volume, making integration with external log tools such as Splunk or Elastic Stack more efficient and potentially reducing storage costs.

The _queryFilter parameter takes a URL-encoded filter expression:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=<source>' \
--data-urlencode '_queryFilter=<filter-expression>'

Learn more about constructing a filter expression in the filter expression rules for _queryFilter. Here are some basic examples:

Example filter expression Description

/payload co "WARNING"

Search plaintext results for a particular string.

/payload/client/ip co "10.104.1.5"

Search for JSON results containing a particular client IP address.

/payload/level eq "DEBUG"

Search for JSON results with a particular log level.

/payload/eventName eq "access"

Search for JSON results with a particular event name.

/payload/eventName co "AM-ACCESS-ATTEMPT"

Search for JSON results containing a particular event name.

/payload/timestamp eq "2023-05-16T08:21:34.632Z"

Search for JSON results with a particular timestamp.

/payload/timestamp sw "2023-05-14T16:34:34"

Search for JSON results with a timestamp that starts with a particular datetime.

/payload/client/ip co "10.104.1.5" and /payload/level eq "ERROR"

Search for JSON results containing a particular client IP address and also containing a particular log level.

/payload/entries/info/nodeType pr

Search for JSON results where an authentication node type is present.

Filter array items in log results

To filter on array items, do not include an array index in your filter expression.

For example, to search for JSON results where the authentication node type is ScriptedDecisionNode:

  • Wrong: /payload/entries/0/info/nodeType eq "ScriptedDecisionNode"

  • Right: /payload/entries/info/nodeType eq "ScriptedDecisionNode"

where a log entry for an authentication node looks like this:

    {
      "payload": {
        "_id": "7ae37a4b-f22b-4c5e-8621-2130d5bc603c-9310858",
        "component": "Authentication",
        "entries": [
          {
            "info": {
              "authLevel": "0",
              "displayName": "Using Invite?",
              "nodeId": "15edd2f7-22f1-4f32-bf0a-8ca3f98af850",
              "nodeOutcome": "False",
              "nodeType": "ScriptedDecisionNode",
              "treeName": "Login"
            }
          }
        ],
        "eventName": "AM-NODE-LOGIN-COMPLETED",
        ...
    }

Filter log results between two dates

To filter log results between two dates, use the beginTime and endTime query parameters with ISO 8601 datetime values:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=<source>' \
--data 'beginTime=<begin-datetime>' \
--data 'endTime=<end-datetime>' \
--data-urlencode '_queryFilter=<filter-expression>'

For example, to filter log results between two specific dates for a specific user :

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication' \
--data 'beginTime=2023-05-24T12:40:00.00Z' \
--data 'endTime=2023-05-24T12:45:00.00Z' \
--data-urlencode '_queryFilter=/payload/principal eq "user.name@example.com"'

Add response fields

Authentication events

You can use a script to add extra information to log entries for authentication events. Learn more in Add information to authentication audit log entries.

Identity object events

You can configure audit log results to include additional identity object events. For example, you may want to log the before and after values of specific activities, such as changes to a user’s last name or email address.

To include additional identity object event fields, add them to the includeIf property in the audit configuration. Make these changes in your development environment and then promote them.

By default, Advanced Identity Cloud audits identity object event fields that are safe to log. When adding audit event fields, be mindful of the type of information that you intend to expose in the logs. For example, you may need to keep personally identifiable information (PII) out of the logs.
Add identity object event fields to audit logging

  1. Get the current audit configuration.

    Example request:

    $ curl \
--request GET \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
'https://<tenant-env-fqdn>/openidm/config/audit'

    Learn more in the IDM REST API reference.

    Show response 
    {
  "_id": "audit",
  "auditServiceConfig": {
    "availableAuditEventHandlers": [
      "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
      "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
      "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
      "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
      "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
      "org.forgerock.openidm.audit.impl.RouterAuditEventHandler",
      "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler",
      "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler"
    ],
    "caseInsensitiveFields": [
      "/access/http/request/headers",
      "/access/http/response/headers"
    ],
    "filterPolicies": {
      "value": {
        "excludeIf": [
          "/access/http/request/cookies/&{com.iplanet.am.cookie.name}",
          "/access/http/request/cookies/session-jwt",
          "/access/http/request/headers/&{com.sun.identity.auth.cookieName}",
          "/access/http/request/headers/&{com.iplanet.am.cookie.name}",
          "/access/http/request/headers/accept-encoding",
          "/access/http/request/headers/accept-language",
          "/access/http/request/headers/Authorization",
          "/access/http/request/headers/cache-control",
          "/access/http/request/headers/connection",
          "/access/http/request/headers/content-length",
          "/access/http/request/headers/content-type",
          "/access/http/request/headers/proxy-authorization",
          "/access/http/request/headers/X-OpenAM-Password",
          "/access/http/request/headers/X-OpenIDM-Password",
          "/access/http/request/queryParameters/access_token",
          "/access/http/request/queryParameters/IDToken1",
          "/access/http/request/queryParameters/id_token_hint",
          "/access/http/request/queryParameters/Login.Token1",
          "/access/http/request/queryParameters/redirect_uri",
          "/access/http/request/queryParameters/requester",
          "/access/http/request/queryParameters/sessionUpgradeSSOTokenId",
          "/access/http/request/queryParameters/tokenId",
          "/access/http/response/headers/Authorization",
          "/access/http/response/headers/Set-Cookie",
          "/access/http/response/headers/X-OpenIDM-Password"
        ],
        "includeIf": []
      }
    },
    "handlerForQueries": "json"
  },
  "eventHandlers": [
    {
      "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
      "config": {
        "name": "json",
        "topics": [
          "access",
          "activity",
          "sync",
          "authentication",
          "config"
        ]
      }
    }
  ],
  "eventTopics": {
    "activity": {
      "filter": {
        "actions": [
          "create",
          "update",
          "delete",
          "patch",
          "action"
        ]
      },
      "passwordFields": [
        "password"
      ],
      "watchedFields": []
    },
    "config": {
      "filter": {
        "actions": [
          "create",
          "update",
          "delete",
          "patch",
          "action"
        ]
      }
    }
  },
  "exceptionFormatter": {
    "file": "bin/defaults/script/audit/stacktraceFormatter.js",
    "type": "text/javascript"
  }
}

  2. Make a backup of the audit configuration.

  3. Update the includeIf property (under filterPolicies) in the audit configuration to include the fields you want to add.

    The following example updates the audit configuration to include before and after values of a user’s last name and email address:

    $ curl \
--request PUT \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "_id": "audit",
  ...
   "filterPolicies": {
     "value": {
       "excludeIf": [
          "/access/http/request/cookies/&{com.iplanet.am.cookie.name}",
          "/access/http/request/cookies/session-jwt",
        ...
        ],
        "includeIf": [
           "/activity/before/sn", (1)
           "/activity/after/sn", (2)
           "/activity/before/mail", (3)
           "/activity/after/mail" (4)
        ]
      }
   },
  ...
}' \
'https://<tenant-env-fqdn>/openidm/config/audit'

    Fields added:

    1 Logs the user’s last name before change.
    2 Logs the user’s last name after change.
    3 Logs the user’s email address before change.
    4 Logs user’s email address after change.

Once updated, idm-activity and idm-everything audit logs will include the fields you have added.

For example, the following entry in a sample idm-activity log shows before and after values for changes to a user’s last name and email address from "Brown" to "Granger":

{
    "payload": {
        "message": "",
        "runAs": "bd220328-9762-458b-b05a-982ac3c7fc54",
        "transactionId": "1630683558570-abec9e9304c84ad368ba-28676/0",
        "before": {
            "sn": "Brown",
            "mail": "jbrown@example.com"
        },
        "operation": "PATCH",
        "passwordChanged": false,
        "_id": "52f7cea0-285d-4ef6-bda3-83256dda71c5-1300250",
        "revision": "00000000412cae36",
        "eventName": "activity",
        "userId": "bd220328-9762-458b-b05a-982ac3c7fc54",
        "status": "SUCCESS",
        "objectId": "managed/alpha_user/ce7492dc-8759-47b3-b4ee-eda8d4de4ab1",
        "timestamp": "2023-09-03T15:39:42.862Z",
        "changedFields": [],
        "after": {
            "sn": "Granger",
            "mail": "jgranger@example.com"
        }
    "type": "application/json",
    "timestamp": "<date-time>"
}

You can also exclude fields from audit logging by adding them to the excludeIf property in the audit configuration.

For example, to prevent audit logs from showing target object attributes for synchronization and reconciliation events, add the following entries to the excludeIf property in the audit configuration:

"/sync/targetObject/<attribute-name>",
"/recon/targetObject/<attribute-name>"

Rate limiting

Logs endpoint

To reduce unwanted stresses on the system, Advanced Identity Cloud limits the number of requests you can make to the /monitoring/logs endpoint in a certain timeframe:

  • The page-size limit is 1000 logs per request.

    Ping Identity recommends you do not override the page-size limit with a greater value as it could increase request throttling and reduce the overall number of logs you can request per minute.

  • The request limit is 60 requests per minute.

  • The theoretical upper rate limit is therefore 60,000 logs per minute.

These limits apply per environment, so your development, staging, and production environments each have their own quota.

The following rate limit notification response headers are sent for each request to the /monitoring/logs endpoint:

X-RateLimit-Limit

The maximum number of requests allowed in the current rate limit window.

X-RateLimit-Remaining

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

The time in seconds since Jan. 1, 1970, UTC when the rate limit window resets.

A 429 HTTP status code on the /monitoring/logs endpoint indicates that the rate limit has been exceeded, and no results are returned.

Logs tail endpoint

The /monitoring/logs/tail endpoint has the same limits and response headers as the /monitoring/logs endpoint described above. However, the endpoint also has a limit of 15,000 lines per request, which supersedes the page-size limit of 1000 logs per request.

Because calls to the /monitoring/logs/tail endpoint do not always fetch all logs, use this endpoint for debugging only. Use the /monitoring/logs endpoint when you need to fetch all logs.

Troubleshooting

Update audit configuration

Sometimes a log source is shown in the available sources in Advanced Identity Cloud but returns no results when you query the Advanced Identity Cloud logging endpoints. In this case, check the underlying IDM audit configuration to ensure that the corresponding audit topic for the source is enabled.

The following example shows how to enable the recon event handler so that reconciliation events appear in the audit logs:

  1. Get the current audit configuration.

    Example request:

    $ curl \
--request GET \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
'https://<tenant-env-fqdn>/openidm/config/audit'

    Learn more in IDM REST API reference.

  2. Update the audit configuration as needed. The following example enables the reconciliation audit event handler.

    Example update:

    $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/audit' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "_id": "audit",
  ...
  "eventHandlers": [
    {
      "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
      "config": {
        "elasticsearchCompatible": false,
        "enabled": true,
        "name": "json",
        "topics": [
          "access",
          "activity",
          "sync",
          "authentication",
          "config",
          "recon"
        ]
      }
    }
  ],
  ...
}' \
'https://<tenant-env-fqdn>/openidm/config/audit'

Include large log entries in filter log results

Some Advanced Identity Cloud log output is too large to be stored as a single log entry, so is stored across two log entries instead. When this happens, any log output in JSON format is stored as two plaintext log entries rather than a single JSON log entry. Consequently, any filter expression that filters on a specific JSON field will not find any of these plaintext log entries.

To work around this, you can combine a specific field filter with a plaintext filter. For example, if you were searching for log results containing a particular transaction ID using the filter expression:

/payload/transactionId co "<transaction-id>"

you could add a plaintext filter as follows:

/payload/transactionId co "<transaction-id>" or /payload co "<transaction-id>"

to include both JSON and plaintext log entries in the log results.

Import cURL commands into Postman

If you use Postman’s import cURL commands feature to convert cURL commands into Postman requests, you might have problems with the example commands on this page that use a GET request and include a --data parameter, such as this one:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs'
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication'

When you import the above command into Postman and run the request, it produces this error:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>400 Bad Request</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Bad Request</h1>
<h2>Your client has issued a malformed or illegal request.</h2>
<h2></h2>
</body></html>

This occurs because Postman adds the value of --data parameter twice—as a query string but also incorrectly as a message body. The equivalent incorrect cURL query of the import would be:

curl \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs?source=am-authentication' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=am-authentication'

To resolve, convert any --data parameters into a query string before importing into Postman:

$ curl \
--request 'https://<tenant-env-fqdn>/monitoring/logs?source=am-authentication'
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>'

Configure emails for your users

Email provider

PingOne Advanced Identity Cloud uses email provider configuration to support email-dependent end-user journeys. For example, registration and password reset end-user journeys usually include an email component.

By default, Advanced Identity Cloud configures the email provider with default values to connect to a built-in SMTP server. This lets you quickly create and test email-dependent journeys in your tenant development environment using the ready-to-use email templates. No rate limiting is applied to password reset emails or any emails sent by the built-in SMTP server. This means an attacker can potentially spam a known user account with an infinite number of emails, filling that user’s inbox. In the case of password reset, the spam attack can obscure an actual password reset attempt.

In your staging and production tenant environments, you must update the email provider configuration with values to connect to something other than the built-in SMTP server.

Additionally, the built-in SMTP server does not support:

Setup process

Email provider configuration changes made in one realm are applied to both realms.

  1. Create a new email template.

  2. In your tenant development environment, create and test a journey that uses an email node. By default, the email provider uses the built-in SMTP server to test the email node.

  3. When you’re satisfied with your test results:

    1. Edit the email provider configuration to use your own external email provider.

    2. Verify that your email templates work with the external provider.

  4. Promote your configuration changes to your tenant staging environment.

  5. Optionally, you can revert the email provider to use the built-in SMTP server for testing purposes. Be sure to reconfigure the email provider to use your own external service before promoting configuration changes to your tenant staging environment.

Do not use the email provider with the built-in SMTP server in a tenant production environment. Advanced Identity Cloud provides this ready-to-use server for testing purposes only.

Email service configuration types

Advanced Identity Cloud supports two email service configuration types:

  • SMTP - Email service that uses the Simple Mail Transfer Protocol. Can be configured using the admin console or API.

  • MS Graph API - Email service that uses the MS Graph API sendMail endpoint. Can only be configured using the API.

International email addresses

To use international email addresses, you must:

  • Use SMTP as the provider type.

  • The SMTP provider must support international email addresses.

  • Configure mail.mime.allowutf8=true using the REST API or the UI.

    Learn more in smtpProperties sub-properties.

MS Graph API requirements

Use of the MS Graph API email client requires a properly configured Microsoft Azure tenant. The steps for configuring an Azure tenant should be used as an outline, as the specific options, menus, and features may have changed.

Microsoft Sandbox

If you need a sandbox for testing only, check out the Microsoft developer sandbox subscription. Although the sandbox accepts sendMail requests, the Microsoft Exchange service prevents messages from being delivered. The messages do show up in the sender’s "sent" box, which should be sufficient for manual testing purposes.

Configure Azure for MS Graph API email client

  1. Navigate to Azure Active Directory | App registrations.

  2. Create the Advanced Identity Cloud client application:

    1. From the menu bar, click + New Registration.

    2. On the Register an application page, enter the application Name, such as my-email-client.

    3. For Supported account types, select the applicable option for your organization.

    4. Click Register.

    5. On the my-email-client page, from the main Essentials area, record the Application (client) ID.

      This is the value for clientId in the auth settings of the email configuration. Learn more in oauth2 properties.

  3. Add a client secret:

    1. On the my-email-client page, in the main Essentials area, click Add a certificate or secret.

      Show Me
      Azure app - add a secret link

    2. On the Certificates & secrets page, select the Client secrets tab, and click + New client secret.

      Show Me
      Azure app - add a new client secret

    3. In the Add a client secret window, enter the details, and click Add.

    4. Copy the Value and Secret ID to a secure place before leaving the Certificates & secrets page.

      Use the secret Value for clientSecret in the auth settings of the email configuration. Learn more in oauth2 properties.

  4. Add API permissions:

    1. From the side menu, click API permissions.

    2. On the API permissions page, click + Add a permission.

    3. In the Request API permissions windows, select the Microsft APIs tab, and click Microsoft Graph.

    4. In the What type of permissions…​ area, click Application permissions.

    5. In the Select permissions search bar, type send.

    6. Expand the Mail node, and select Mail.Send.

    7. Click Add permissions.

      Show Me
      Azure app - Request API permissions

Configure the email provider

Email provider configuration changes made in one realm are applied to both realms.

In your staging and production tenant environments, configure the email provider to use your own external service:

  • For SMTP, you can use the UI or API.

  • For MS Graph API, you can only use the API.

Using the admin console

  1. In the Advanced Identity Cloud admin console, go to Email > Provider.

  2. On the Email Provider page, enable Use my own email provider.

  3. Enter details in the following fields:

    From Address

    Email address of the organization or individual sending the email.

    Example: mycompany@example.com.

    Not set by default.

    Although from is optional in the email configuration, the email service requires this property to send email. If you do not specify a from address in the email configuration, you must provide one in another way, for example:

    • From an email template.

    • As a parameter in the email service request (from or _from).

    From Name

    Name of sending organization.

    Host

    Hostname or IP address of your SMTP server.

    When no hostname is specified, Advanced Identity Cloud uses the built-in SMTP server.

    Port

    Port number of your SMTP server.

    Many SMTP servers require the use of a secure port such as 465 or 587. Many ISPs flag email from port 25 as spam.

    Default value is 587.

    Username

    Username for your SMTP server account.

    Password

    Password for your SMTP server account.

  4. Click Show advanced settings, and edit the options and fields:

    Socket Connection Timeout (ms)

    Elapsed time before Advanced Identity Cloud times out due to unsuccessful socket connection to the SMTP server. A setting of 0 disables this timeout.

    The default is 300000 ms (5 minutes).

    Socket Write Timeout (ms)

    Elapsed time before Advanced Identity Cloud times out because client can’t write to the SMTP server. A setting of 0 disables this timeout.

    The default is 300000 (5 minutes).

    Socket Timeout (ms)

    Elapsed time before Advanced Identity Cloud times out due to inactivity. A setting of 0 disables this timeout.

    The default is 300000 (5 minutes).

    Use STARTTLS

    • If enabled, and if the SMTP server supports the STARTTLS command, then Advanced Identity Cloud switches to a TLS-protected connection before issuing any login commands.

    • If the SMTP server does not support STARTTLS, the connection continues without the use of TLS.

    Enabled by default.

    Use SSL

    If enabled, Advanced Identity Cloud uses SSL to connect to the SMTP server.

    Disabled by default.

    Allow UTF-8

    If enabled, adds support for UTF-8 (Non-ASCII) characters in the local part of email addresses (everything before the @ character).

    Disabled by default.

    Do not set this property unless your SMTP provider supports UTF-8 characters. Learn more in International email addresses.

  5. To test your configuration, click Send Test Email.

    1. In the Send Test Email dialog box, enter your own email address.

    2. Click Send.

    If the test is successful, you’ll get a test email in your email inbox.

  6. To save the email provider configuration, click Save.

Using the API

You can edit the email service over REST at the openidm/config/external.email endpoint. The following example submits an email configuration over REST:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
    "host" : "smtp.gmail.com",
    "port" : 587,
    "debug" : false,
    "auth" : {
        "enable" : true,
        "username" : "admin",
        "password" : "Passw0rd"
    },
    "from" : "admin@example.com",
    "timeout" : 300000,
    "writetimeout" : 300000,
    "connectiontimeout" : 300000,
    "starttls" : {
        "enable" : true
    },
    "ssl" : {
        "enable" : false
    },
    "smtpProperties" : [
        "mail.smtp.ssl.protocols=TLSv1.2",
        "mail.smtps.ssl.protocols=TLSv1.2",
        "mail.mime.allowutf8=true"
    ],
    "threadPoolSize" : 20
}' \
"https://<tenant-env-fqdn>/openidm/config/external.email"

Sample email configuration

This sample email configuration sets up the email provider:

  • SMTP

  • MS Graph API

{
    "host" : "smtp.gmail.com",
    "port" : 587,
    "debug" : false,
    "auth" : {
        "enable" : true,
        "username" : "xxxxxxxx",
        "password" : "xxxxxxxx"
    },
    "timeout" : 300000,
    "writetimeout" : 300000,
    "connectiontimeout" : 300000,
    "starttls" : {
        "enable" : true
    },
    "ssl" : {
        "enable" : false
    },
    "smtpProperties" : [
        "mail.smtp.ssl.protocols=TLSv1.2",
        "mail.smtps.ssl.protocols=TLSv1.2",
        "mail.mime.allowutf8=true"
    ],
    "threadPoolSize" : 20
}
{
    "type" : "msgraph",
    "mailEndpoint" : "https://graph.microsoft.com/v1.0/users/example@myTenant.onmicrosoft.com/sendMail",
    "from" : "example@myTenant.onmicrosoft.com",
    "auth" : {
        "enable" : true,
        "type" : "oauth2",
        "clientId" : "clientId",
        "clientSecret" : "clientSecret",
        "tokenEndpoint" : "https://login.microsoftonline.com/myTenant.onmicrosoft.com/oauth2/v2.0/token",
        "scope" : [
            "https://graph.microsoft.com/.default"
        ]
    },
    "timeout" : 300000,
    "writetimeout" : 300000,
    "connectiontimeout" : 300000,
    "threadPoolSize" : 20
}

Email provider configuration properties

The msgraph type also supports the External REST configuration properties.

Table 1. Properties
Property Description Required? /
Type Support

type

The email service configuration type, smtp or msgraph. When no type is specified, the default value is smtp.

No

mailEndpoint

The URI for the MS Graph API sendMail endpoint.

Typical format:

https://graph.microsoft.com/v1.0/users/{user}@{tenant}.onmicrosoft.com/sendMail

Yes

Only for msgraph type.

host

The hostname or IP address of the SMTP server.

Yes

Only for smtp type.

port

SMTP server port number, such as 25, 465, or 587.

Many SMTP servers require the use of a secure port such as 465 or 587. Many ISPs flag email from port 25 as spam.

Yes

Only for smtp type.

debug

When set to true, this option outputs diagnostic messages from the JavaMail library. Debug mode can be useful if you are having difficulty configuring the external email endpoint with your email server.

No

Only for smtp type.

from

Specifies a default From: address which displays when users receive emails from Advanced Identity Cloud.

Although from is optional in the email configuration, the email service requires this property to send email. If you do not specify a from address in the email configuration, you must provide one in another way, for example:

  • From an email template.

  • As a parameter in the email service request (from or _from).

No

auth

Contains authentication detail sub-properties. Learn more about authentication sub-properties.

Yes

Required sub-properties vary based on type.

starttls

If "enable" : true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. If the server does not support STARTTLS, the connection continues without the use of TLS.

No

Only for smtp type.

ssl

Set "enable" : true to use SSL to connect, and use the SSL port by default.

No

Only for smtp type.

smtpProperties

SMTP options. Learn more about SMTP sub-properties.

No

Only for smtp type.

threadPoolSize

Emails are sent in separate threads managed by a thread pool. This property sets the number of concurrent emails that can be handled at a specific time. The default thread pool size (if none is specified) is 20.

No

connectiontimeout

The socket connection timeout, in milliseconds. The default connection timeout (if none is specified) is 300000 milliseconds, or five minutes. A setting of 0 disables this timeout.

No

timeout

The socket read timeout, in milliseconds. The default read timeout (if none is specified) is 300000 milliseconds, or five minutes. A setting of 0 disables this timeout.

No

Only for smtp type.

writetimeout

The socket write timeout, in milliseconds. The default write timeout (if none is specified) is 300000 milliseconds, or five minutes. A setting of 0 disables this timeout.

No

Only for smtp type.
Table 2. auth sub-properties
Property Description Required? /
Type Support

enable

Whether you need login credentials to connect to the server/API.

If "enable" : false,, you can leave the entries for "username" and "password" empty:

"enable" : false,
"username" : "",
"password" : ""

Yes

username

Account used to connect to the server/API.

No

password

Password used to connect to the server/API.

No

type

Authentication type used to connect to the server/API:

  • basic—basic authentication using a username and password. Default value.

  • oauth2—OAuth2 authentication. Requires additional oauth2 properties. The msgraph configuration type only supports oauth2.

Yes
Table 3. oauth2 properties
Property Description Required? /
Type Support

The following properties are only applicable when the auth/type is oauth2.

clientId

clientId used to request an access token from the token endpoint. Obtained during Azure application creation.

Yes

clientSecret

clientSecret used to request an access token from the token endpoint. Obtained during Azure application creation.

Yes

tokenEndpoint

OAuth2 token endpoint.

Typical format:

https://login.microsoftonline.com/{tenant}.onmicrosoft.com/oauth2/v2.0/token

Yes

scope

Requested OAuth2 scopes in a JSON array of strings.

Yes

scopeDelimiter

Scope delimiter to use. Defaults to space.

No

grantType

The only supported grant type is client_credentials.

No
Table 4. smtpProperties sub-properties
Property Description Required? /
Type Support

mail.smtp.ssl.protocols

The enabled SMTP SSL connection protocols. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

No

Only for smtp type.

mail.smtps.ssl.protocols

The enabled SMTPS SSL connection protocols. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

No

Only for smtp type.

mail.mime.allowutf8

Adds support for UTF-8 (Non-ASCII) characters in the local part of email addresses (everything before the @ character) if set to true.

Do not set this property unless your SMTP provider supports UTF-8 characters. Learn more in International email addresses.

No

Only for smtp type.

Revert the email provider to use the built-in SMTP server

Email provider configuration changes made in one realm are applied to both realms.

If you need to revert the email provider to use the built-in SMTP server:

  1. In the Advanced Identity Cloud admin console, go to Email > Provider.

  2. On the Email Provider page, disable Use my own email provider.

  3. Click Save.

The built-in SMTP server does not support:

Email templates

PingOne Advanced Identity Cloud provides preconfigured email templates for common end-user journeys.

You can customize email templates using Markdown language. Advanced Identity Cloud uses a parser to let you preview your markup.

Email templates utilize Handlebar expressions to reference object data dynamically. For example, to reference the userName of an object:

{{object.userName}}

Create a new email template

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click + New Template.

  3. Provide the following details:

    • Template Name: Display name for the template.

    • From Address: Enter an email address for the group or individual sending the email.

    • From Name: Enter a name for the group or individual sending the email.

    • Description: A brief description of the template.

  4. Click Save. The new email opens in the email editor.

  5. Learn more in Edit an email template.

When you reference an email template, such as in a node or script, you must use the correct format. You can find the correct format for the email template name in the Advanced Identity Cloud admin console URL when editing the template.

For example, the Forgotten Username email template’s name is forgottenUsername:

https://<tenant-env-fqdn>/?realm=alpha#/email/templates/edit/forgottenUsername

Edit an email template

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. To change the wording in the email template, edit the Markdown text in the left window on the page. You can also:

  4. Add, modify, or delete locales to suit your end-user audience. Learn more in Manage email template locales.

  5. Repeat step 3 for each template locale.

  6. To edit the template styles, click Styles, and edit the CSS style code.

  7. To view available variables that you can use in the template, click Variables, and view the content on the Available Properties page. Click Done.

  8. To edit the template settings, click the More () icon at the top right of the page, and select Settings.

  9. Provide the following details:

    • Template Name: Display name for the template.

    • From Address: Enter an email address for the group or individual sending the email.

    • From Name: Enter a name for the group or individual sending the email.

    • Description: Enter a brief description of the template.

  10. Click Update.

  11. Click Save. This saves content changes in all template locales.

Add an image to an email template

  1. Upload your image to a hosted service, such as a content delivery network (CDN), so it is available over HTTPS. Local image paths are not permitted.

  2. In the Advanced Identity Cloud admin console, go to Email > Templates.

  3. On the Email Templates page, click a template name to open the email editor.

  4. Edit the Markdown text to reference your image:

    • To add an image at full size:

      ![alt text](<image url>)

      For example, the Markdown would look like this for an image hosted at https://example.com/image.ext where the alt text is this is an example image:

      ![this is an example image](<https://example.com/image.ext>)

    • To add an image and resize it in pixels:

      ![this is an example image](<https://example.com/image.ext> =100x100)

    • To add an image and resize it as a percentage:

      ![this is an example image](<https://example.com/image.ext> =50%x50%)

  5. Click Save.

Use HTML formatting in an email template

Although you can’t see HTML formatting in the editor, you can use inline HTML to format your email. Learn more in Markdown Syntax: Inline HTML.

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. Edit the Markdown text:

    • Specify HTML tags to format your content. For example:

      <h1>Reset Password</h1>

    • To add a table, include both the <thead> and <tbody> tags; otherwise the table will not convert correctly to Markdown when saved. For example:

      <table>
  <thead>
    <tr>
     <th>Header 1</th>
     <th>Header 2</th>
     <th>Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell Text 1</td>
      <td>Cell Text 2</td>
      <td>Cell Text 3</td>
    </tr>
  </tbody>
</table>

  4. Click Styles, and add CSS styles for the tag to format it as required. For example:

    h1 {
    font-family: Arial, Helvetica, sans-serif;
    color: #f96700;
    background-color: #032b75;
    font-size: 25px;
    padding: 10px;
}

  5. Click Save.

After saving your changes, the inline HTML tags are converted to Markdown, but the CSS styles for the tags persist. The CSS styles apply to all locales.

Alternatively, you can click Advanced Editor and modify the template in HTML. However, if you swap to the Advanced Editor, you cannot change back to Markdown.

Use ESV variables in an email template

You can use ESV variables in email templates to dynamically present different text, images, or links depending on the specific tenant environment.

You can find background information on ESVs in PingOne Advanced Identity Cloud in ESVs.

To add ESV variables to an email template, you must use the Advanced Editor. After you have swapped to the Advanced Editor, you cannot change back to Markdown.
Add ESV variables to an email template

  1. Create the ESV variables to use in the email template:

    1. Create the variables using the Advanced Identity Cloud admin console or variables APIs.

    2. Restart Advanced Identity Cloud services by applying updates in the Advanced Identity Cloud admin console or using the restart API.

  2. In the Advanced Identity Cloud admin console, go to Email > Templates.

  3. On the Email Templates page, click a template name to open the email editor.

  4. Click Advanced Editor.

  5. Add the placeholder for one or more ESV variables. For example:

    &{esv.my.variable}

  6. Click Save.

Example

  1. In step 1, add these two ESV variables:

  2. In step 5, add the link and image:

    • Add the link using the ESV placeholder, where the link text is the URL, for example:

      <p>For more information, go to our website: &{esv.test.link}</p>
      You can also add the link using the <a> tag with the href attribute. This is useful if you want to display different link text.

    • Add the image using the ESV placeholder, for example:

      <p>
<img src="&{esv.test.image}">
</p>

    The preview in the left window shows the ESV placeholder and an image placeholder rather than the actual link and image as these are only resolved when the email is sent.

Manage email template locales

You can create email content for different locales. When an email is sent during an end-user journey, Advanced Identity Cloud automatically selects the appropriate email template based on the value of the accept-language header, typically derived from the language set in the end user’s browser.

You can use the browser’s developer tools to check the value set in the accept-language header.

The locale selector in the top left of the email template editor displays the current template’s locale in the format Locale: code, where code is a ISO-639-1 language code, for example, en or de. Some preconfigured email templates, such as the registration template, already include content for the en (default) and fr locales.

To manage email template locales:

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. Switch, add, modify, or delete a locale:

    • To switch locale:

      1. Click Locale: code.

      2. Select a locale.

    • To add a locale:

      1. Click Locale: code.

      2. Click add Add Locale to open the Add Locale modal.

      3. Enter a ISO-639-1 language code in the Code field.

      4. (Optional) Select Make Default to make the new locale the default for this template.

      5. Click Save to add the new locale to the template, populated with a copy of the content from the default locale. The changes apply immediately without saving the main template.

    • To modify a locale:

      1. Click Locale: code.

      2. Click the locale’s edit icon (edit) to open the Edit Locale modal.

      3. To change the locale, enter a ISO-639-1 language code in the Code field.

      4. To make the locale the default locale for the template, select Make Default.

      5. Click Save to close the modal window. Any changes apply immediately without saving the main template.

    • To delete a locale:

      1. Click Locale: code.

      2. Click the locale’s edit icon (edit) to open the Edit Locale modal.

      3. Click Delete Locale to delete the locale and its content. The deletion applies immediately without saving the main template.

Delete an email template

Deleting an email template cannot be undone.

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click the More () icon adjacent to any template.

  3. Select Delete.

  4. In the dialog box, click Delete.

Manage email templates

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click the More () icon adjacent to any template, and do any of the following:

    • To disable a template, click Deactivate.

    • To enable a template, click Activate.

    • To duplicate a template, click Duplicate.

      1. In the Duplicate Template window, enter the following details:

        • Template Name: Display name for the template.

        • From Address: Enter an email address for the group or individual sending the email.

        • From Name: Enter a name for the group or individual sending the email.

        • Description: A brief description of the template.

      2. Click Save.

More information

Send email

Typically, PingOne Advanced Identity Cloud sends emails from journeys, scripts, or other backend processes. You can also send test emails using the REST API.

Send email using the API

To test your configuration, use the REST API, sending an HTTP POST to /openidm/external/email. Pass the message parameters as part of the POST payload, URL encoding the content, as necessary.

The following example sends a test email using the REST API:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "from":"openidm@example.com",
  "to":"your_email@example.com",
  "subject":"Test",
  "body":"Test"}' \
"https://<tenant-env-fqdn>/openidm/external/email?_action=send"
{
  "status": "OK",
  "message": "Email sent"
}

By default, a response is returned only when the email relay has completed. To return a response immediately, without waiting for the email relay to finish, include the parameter waitForCompletion=false in the REST call. Use this option only if you do not need to verify that the email was accepted by the SMTP server. For example:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "from":"openidm@example.com",
  "to":"your_email@example.com",
  "subject":"Test",
  "body":"Test"}' \
"https://<tenant-env-fqdn>/openidm/external/email?_action=send&waitForCompletion=false"
{
  "status": "OK",
  "message": "Email submitted"
}

Send email templates using the API

You can send an email template using the sendTemplate action. For example:

curl \
--header "Authorization: Bearer <access-token>" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "templateName":"welcome",
  "to":"your_email@example.com",
  "cc":"alt_email@example.com",
  "bcc":"bigBoss_email@example.com"}' \
"https://<tenant-env-fqdn>/openidm/external/email?_action=sendTemplate"
{
  "status": "OK",
  "message": "Email sent"
}

Send email using a script

You can send email using the resource API functions, with the external/email context. Learn more about these functions in openidm.action. In the following example, params is an object that contains the POST parameters:

var params =  new Object();
params.from = "openidm@example.com";
params.to = "your_email@example.com";
params.cc = "bjensen@example.com,scarter@example.com";
params.subject = "OpenIDM recon report";
params.type = "text/html";
params.body = "<html><body><p>Recon report follows...</p></body></html>";

openidm.action("external/email", "send", params);

Send email templates using a script

You can send an email template using the sendTemplate action. For example:

Example 1
var params =  new Object();
params.templateName = "welcome";
params.to = "your_email@example.com";
params.cc = "bjensen@example.com,scarter@example.com";
params.bcc = "bigBoss@example.com";

openidm.action("external/email", "sendTemplate", params);
Example 2
var params = new Object();
params.templateName = "myTemplate";
params.to = "hgale815@example.com";
params.object = { "givenName": newObject.givenName, "sn": newObject.sn, "mail": newObject.mail, "country": newObject.country };

openidm.action("external/email", "sendTemplate", params);

Email templates utilize Handlebar expressions to reference object data dynamically. For example, to reference the userName of an object:

{{object.userName}}

Configure cross-origin resource sharing

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. In PingOne Advanced Identity Cloud, you can configure CORS to allow browsers from trusted domains to access Advanced Identity Cloud protected resources. For example, you might want a custom web application running on your own domain to get an end-user’s profile information using the Advanced Identity Cloud REST API.

By default, CORS is configured to let the Ping SDKs access Advanced Identity Cloud. You can add additional CORS configurations that let other APIs or SDKs access Advanced Identity Cloud.

cors config

Configure CORS using ESVs

  1. In your development environment:

    1. Use the Advanced Identity Cloud admin console to set up one or more CORS configurations for your environment:

      You can create as many configurations as you need. The active configurations are combined to form the entire set of rules for resource sharing in your environment.

    2. For each CORS configuration:

      • If the acceptedOrigins field contains hard-coded configuration, use the Advanced Identity Cloud REST API to replace the value of the acceptedOrigins field with an ESV array. Learn more in Insert ESV placeholders into CORS configuration.

      • If the acceptedOrigins field already contains an ESV array, no action is needed.

    3. Check that the CORS configuration is working as expected in your development environment.

  2. In your staging environment:

    1. If you created any new ESV arrays in step 1b, create corresponding ESVs with the same names in your staging environment.

    2. Run a promotion to move the configuration change from your development environment to your staging environment. Refer to:

    3. Check that the CORS configuration is working as expected in your staging environment.

  3. In your production environment:

    1. If you created any new ESV arrays in step 1b, create corresponding ESVs with the same names in your production environment.

    2. Run a promotion to move the configuration change from your staging environment to your production environment.

    3. Check that the CORS configuration is working as expected in your production environment.

Create a new CORS configuration

  1. In your development environment, open the TENANT menu (upper right), and choose Tenant settings.

  2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

  3. Click + New CORS Configuration.

  4. On the New CORS Configuration dialog box, choose a configuration type.

    Ping SDKs

    Choose this option when you want to work with the Ping SDKs.
    Advanced Identity Cloud pre-configures accepted origins, methods, and headers for you. You can modify the configuration in the next step.

    Custom

    Choose this option when you want to use your own SDK, APIs, or other software components.

  5. Click Next.

  6. In the New CORS Configuration dialog box, provide CORS details.

    Name

    Enter a display name. Use only numerals, letters, and hyphens (-).

    Accepted Origins

    Required. Accepted origins that will be allowed to make requests to Advanced Identity Cloud from your application in a cross-origin context. Wildcards are not supported. Each value should be identical to the origin of the CORS request.
    Example: https://myapp.example.com:443

    Accepted Methods

    Defaults are POST and GET. The set of (non-simple) accepted HTTP methods allowed when making CORS requests to Advanced Identity Cloud. Use only uppercase characters.

    Accepted Headers (optional)

    Accepted header names when making requests from the above specified trusted domains.
    Header names are case-insensitive. By default, the following simple headers are explicitly accepted: Cache-Control, Content-Language, ExpiresLast-Modified, Pragma.
    If you don’t specify values for this element, then the presence of any header in the CORS request, other than the simple headers listed above, will cause the request to be rejected.

  7. (Optional) Click Show advanced settings to display further CORS configuration settings:

    Exposed Headers (optional)

    Add the response header names that Advanced Identity Cloud returns.
    The header names are case-insensitive. User agents can make use of any headers that are listed in this property, as well as these simple response headers: Cache-Control, Content-Language, Expires, Last-Modified, Pragma, and Content-Type. User agents must filter out all other response headers.

    Enable Caching

    Max age is the maximum length of time, in seconds, that the browser is allowed to cache the pre-flight response. The value is included in pre-flight responses, in the Access-Control-Max-Age header.

    Allow Credentials

    Enable this property if you send Authorization headers as part of the CORS requests, or need to include information in cookies when making requests.

    When enabled, AM sets the Access-Control-Allow-Credentials: true header.

  8. Click Save CORS Configuration.

Activate or deactivate a CORS configuration

  • To activate or deactivate all CORS configurations:

    1. In your development environment, open the TENANT menu (upper right), and choose Tenant settings.

    2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

    3. On the CORS Configurations page, in the upper right side, click Activate or Deactivate.

  • To deactivate an individual CORS configuration:

    1. In your development environment, open the TENANT menu (upper right), and choose Tenant settings.

    2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

    3. On the CORS Configurations page, find the name of the configuration you want to deactivate.

    4. Click its More () menu, and choose Deactivate.

Edit a CORS configuration

  1. In your development environment, open the TENANT menu (upper right), and choose Tenant settings.

  2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

  3. On the CORS Configurations page, find the name of the configuration you want to edit.

  4. Click its More () menu, and choose Edit.

View CORS configurations

  1. Open the TENANT menu (upper right), and choose Tenant settings.

  2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

TLS, secrets, signing, trust, and encryption

PingOne Advanced Identity Cloud was built with security in mind:

This page describes the default implementations for each of these security factors. It also describes customization options, if they’re available.

TLS encryption

By default, your Advanced Identity Cloud tenant uses a Google-managed SSL certificate for TLS encryption.

If you prefer, Advanced Identity Cloud lets you use your own, self-managed SSL certificate instead of using the Google-managed SSL certificate.

Learn more about configuring your tenant to use a self-managed certificate in Self-managed SSL certificates.

Secrets

When you configure Advanced Identity Cloud, the secrets you provide in your development environment normally do not change when you promote your environment to staging and production. But, in some situations, you might want the three environments to use different secrets.

For example, you might want Advanced Identity Cloud to log in to an external system, such as an OTP provider. But you need Advanced Identity Cloud to use different credentials depending on whether it’s accessing the OTP provider from the development, staging, or production environment.

Environment secrets and variables (ESVs) let you configure different secrets in your Advanced Identity Cloud development, staging, and production environments. In the preceding example, instead of hard-coding a single set of credentials for the OTP provider in the Advanced Identity Cloud admin console, you could configure ESVs that hold the credentials. Then, the desired credentials to the OTP provider would be used depending on which Advanced Identity Cloud environment was running.

Learn more in Define and promote ESVs.

Signing keys and certificates

By default, Advanced Identity Cloud generates a set of secret labels in each Advanced Identity Cloud realm. Each secret label corresponds to functionality in Advanced Identity Cloud that requires a signing key or certificate. For a full list of secret labels, learn more in Secret labels.

Advanced Identity Cloud lets you override the generated secret labels. First, create an ESV secret that holds the key or certificate. Then, map the secret in the secret store of the desired realm.

Learn more in Use ESVs for signing and encryption keys.

Trust relationships with SAML 2.0 providers

If your Advanced Identity Cloud tenant has trust relationships with one or more SAML 2.0 providers, the tenant might receive SAML assertions signed by a certificate. The certificate might itself be signed by a certificate authority (CA). For Advanced Identity Cloud to trust this type of SAML assertion, the CA’s public certificate must be installed in Advanced Identity Cloud.

You can add a CA’s public certificate to your Advanced Identity Cloud configuration by creating a support case in the Ping Identity Support Portal.

Encrypted data at rest

In Advanced Identity Cloud, your tenant includes a unique data encryption key. All Advanced Identity Cloud data that’s stored at rest is encrypted with this key.

You cannot use your own encryption key to encrypt Advanced Identity Cloud data.

Create private network connections with Secure Connect

Advanced Identity Cloud add-on capability

Contact your Ping Identity representative if you want to add Secure Connect to your PingOne Advanced Identity Cloud subscription. Learn more in Add-on capabilities.

Secure Connect is currently also a limited availability feature.

You can use Secure Connect to provide dedicated, direct, and secure communication between your PingOne Advanced Identity Cloud network and your private network, such as an on-premises data center or IaaS provider. Secure Connect bypasses the public internet, improving latency, throughput, and security.

secure connect network

Secure Connect is only available in development, UAT[3], staging, and production environments; it is not available in a sandbox[2] environment.

Use cases

The following are examples of how you might use Secure Connect:

  • Call an API endpoint in your private network from a journey script or journey authentication node in Advanced Identity Cloud.

  • Send Advanced Identity Cloud emails from an internal MX/SMTP server not exposed to the public internet.

  • Resolve an internal DNS name using a private DNS server; for example, an internal DNS name using the .company domain extension.

  • Access PII/classified data which cannot be sent over public internet.

Supported services

Ping Identity supports the following services using Secure Connect:

  • DNS for internal domain names (53/udp)

  • HTTP outbound (Advanced Identity Cloud → private network service) (80/tcp & 8080/tcp)

  • HTTPS outbound (Advanced Identity Cloud → private network service) (443/tcp)

  • HTTPS inbound (private network service → Advanced Identity Cloud) (443/tcp)

  • SMTP outbound (Advanced Identity Cloud → private network service) (25/tcp)

  • SMTPS outbound (Advanced Identity Cloud → private network service) (587/tcp)

This list represents the use cases Ping Identity explicitly tests against; however, you may test and use additional services to support your own private network use cases.

Configure DNS

To support Secure Connect, configure your company’s DNS to avoid collisions. Collisions can occur when the same IP address is allocated to resources inside different private networks and one or both private networks advertise the address publicly. This can cause traffic destined for one network to be incorrectly routed to the other network.

To avoid collisions, separate your company’s DNS configuration into public and private zones. The private zone can advertise resources reachable using public and private addresses, but the public zone should only advertise resources reachable using public addresses and should not advertise private addresses.

Learn more in RFC 1918.

FAQs

Can I still access Advanced Identity Cloud API endpoints over the public internet?

Yes, Advanced Identity Cloud API endpoints are still available over the public internet; however, Secure Connect also exposes the same API endpoints privately to let you communicate between your private network and Advanced Identity Cloud:

  • Communicate inbound by calling API endpoints in your Advanced Identity Cloud tenant environments from your private network.

  • Communicate outbound by calling API endpoints in your private network from your Advanced Identity Cloud tenant environments.

Can I still access the Advanced Identity Cloud admin console over the public internet?

Yes, the Advanced Identity Cloud admin console is still available over the public internet and cannot be made private.

How do I communicate securely with my tenant environments?

When you provision Secure Connect, you provide Ping Identity with CIDR ranges for each tenant environment. Ping Identity uses your CIDR ranges to create an internal endpoint for each Advanced Identity Cloud tenant environment. You then create private DNS records for these Advanced Identity Cloud endpoints and then create a self-managed SSL certificate.

How do I communicate securely to my private network?

For services like SMTP, Ping Identity can add your CA certificate into the trust store of your tenant environments. For assistance with this, learn more in Send Ping Identity a CA or TLS certificate.

Can I connect Google Cloud to another cloud provider? For example, AWS?

Yes, you can connect Google Cloud to another cloud provider. In the example of AWS, you separately implement AWS Direct Connect, then set up virtual routing in your private network between Google Cloud and AWS. Learn more in Partner Interconnect with multi-cloud enabled partners.

Google Cloud Interconnect

Secure Connect uses Google Cloud Interconnect to implement private network connections between your Advanced Identity Cloud tenant environments and your private network:

To implement this, Ping Identity creates VLAN attachments that are associated with a cloud router in your Advanced Identity Cloud network. The cloud router creates a BGP session for the VLAN attachments and your corresponding private network router. The cloud router receives the routes your private network router advertises. These routes are added as custom dynamic routes in your Advanced Identity Cloud network. The cloud router also advertises routes for your tenant environments, using CIDR blocks you specify during provisioning.

Availability

You can configure Google Cloud Interconnect to support three-nines availability or four-nines availability. The following table summarizes the different approaches:

Availability Guidance Requirements

Three-nines (99.9%)

Recommended only for non-critical applications where downtime can be tolerated.

At least two Interconnect connections. The connections must be located in the same metropolitan area, but in different edge availability domains (metropolitan availability zones).

Four-nines (99.99%)

Recommended for most production applications.

At least four Interconnect connections, two connections in one metropolitan area and two connections in another. Interconnect connections that are in the same metropolitan area must be placed in different edge availability domains (metropolitan availability zones).

Partner Interconnect service providers

Equinix Fabric

Secure Connect uses the Partner Interconnect service for Equinix Fabric to provide private network connections between your Advanced Identity Cloud tenant environments and an Equinix private network.

To set up Partner Interconnect and Equinix in Advanced Identity Cloud, learn more in Configure Secure Connect with Equinix.

Configure Secure Connect with Equinix

You can find background information on Secure Connect in PingOne Advanced Identity Cloud in Create private network connections with Secure Connect.

You must complete three steps to configure Secure Connect with Equinix:

Each step requires you to co-ordinate with Ping Identity support using a support case.

Step 1: Set up Equinix Interconnect service

  1. Request Google Cloud pairing keys from Ping Identity support:

    1. Go to https://support.pingidentity.com.

    2. Click Create a case.

    3. Follow the steps in the case submission wizard by selecting your account and contract and answering questions about your tenant environments.

    4. On the Please answer the following questions to help us understand the issue you’re facing page, enter the following details, and then click Next:

      Field Value

      What product family is experiencing the issue?

      Select PingOne Advanced Identity Cloud

      What specific product is experiencing the issue?

      Select Configuration

      What version of the product are you using?

      Select NA

    5. On the Tell us about the issue page, enter the following details, and then click Next:

      Field Value

      Provide a descriptive title for your issue

      Enter Set up Equinix Interconnect service

      Describe the issue below

      Enter a comma-separated list of FQDNs for your development, UAT[3], staging, and production tenant environments.

    6. Click Submit.

    7. Ping Identity support provides you with the Google Cloud pairing keys for the appropriate region and availability zone.

  2. Set up the Equinix Interconnect service in the Equinix Fabric portal:

    1. Open the Equinix instructions for setting up Google Cloud Interconnect in your browser.

    2. Follow the steps under the heading Create Connection in the Equinix Fabric Portal, using the Google Cloud pairing keys from step 1.1.

  3. Confirm to Ping Identity support that you have set up the Equinix Interconnect service:

    1. Update the support case you created in step 1.1 to let Ping Identity support know you have completed the instructions in step 1.2.

    2. Ping Identity support activates a BGP configuration in GCP.

Step 2: Provision Equinix Interconnect connection

  • The minimum lead time for a provisioning request is one week.

  • During the provisioning process there will be approximately one hour of downtime for your environments. Ping Identity support will work with you on timeframes in the support case.

  1. Send Ping Identity support details of your Interconnect connection, including a preferred date and time window for the provisioning process:

    1. Go to https://support.pingidentity.com.

    2. Click Create a case.

    3. Follow the steps in the case submission wizard by selecting your account and contract and answering questions about your tenant environments.

    4. On the Please answer the following questions to help us understand the issue you’re facing page, enter the following details, and then click Next:

      Field Value

      What product family is experiencing the issue?

      Select PingOne Advanced Identity Cloud

      What specific product is experiencing the issue?

      Select Configuration

      What version of the product are you using?

      Select NA

    5. On the Tell us about the issue page, enter the following details, and then click Next:

      Field Value

      Provide a descriptive title for your issue

      Enter Provision Equinix Interconnect connection

      Describe the issue below

      Enter the following details:

      • A comma-separated list of FQDNs for your development, UAT[7], staging, and production tenant environments.

      • An ASN (Autonomous System Number) value for your private network router.

      • An MTU (Maximum Transmission Unit) value for the Interconnect connection.

      • Development environment information:

        • A CIDR block for the development environment.

        • IP addresses or domain names for testing the development environment.

      • Staging environment information:

        • A CIDR block for the staging environment.

        • An IP addresses or domain names for testing the staging environment.

      • Production environment information:

        • A CIDR block for the production environment.

        • An IP addresses or domain names for testing the production environment.

      • Your use case for this implementation.

      • Your preferred date/time for provisioning the Interconnect connection.

    6. Click Submit.

    7. Ping Identity support works with you in the support case to agree a suitable date and time window for the provisioning process.

  2. Pre-provisioning steps:

    1. Before the provisioning process, Ping Identity support provides you with pairing keys and BGP IP addresses for all tenant environments. The number of pairing keys is dependent on the level of availability you require.

    2. In the Equinix portal, use the pairing keys to create direct connections to the BGP IP addresses, using the BGP ASN of 16550.

    3. Ping Identity accepts the connections.

  3. Provisioning steps:

    1. During the provisioning process, Ping Identity support establishes BGP sessions.

    2. After provisioning is complete, the routes advertised by each party are validated and bidirectional network connectivity is tested. Ping Identity support provides nodes in each tenant environment that should respond to queries from the private network.

      The routes Ping Identity advertises with BGP are as follows:

      • The chosen CIDR block for the tenant environment.

      • 35.199.192.0/19 (Google Cloud DNS)

      Ping Identity allows all traffic from the advertised subnets via BGP. You are responsible for configuring your firewall in your private network to allow traffic from Advanced Identity Cloud.

Step 3: Send internal certificates

For services like SMTP, Ping Identity can add your internal certificate or CA into the trust store of your tenant environments. For assistance with this, learn more in Send Ping Identity a CA or TLS certificate.

1. Backing up data to a different region is a limited availability feature. Learn more in Regions for details about the availability of backup in specific data regions. In the future, Ping Identity will add more regions with backup regions.
2. A sandbox environment is an add-on capability.
3. A user acceptance testing (UAT) environment is an add-on capability.
4. A super administrator is a tenant administrator with elevated permissions for configuring tenant administrators and federated tenant access. Learn more in Tenant administrator groups.
5. Microsoft Entra ID used to be known by the name Microsoft Azure AD. Learn more in New name for Azure Active Directory.
6. Orphaned scripts are a legacy problem that can affect tenants that received support-assisted promotions before the introduction of self-service promotions.