PingOne Advanced Identity Cloud

PingOne Advanced Identity Cloud documentation

Single-page edition

All PingOne Advanced Identity Cloud docs on a single HTML page. Use this for text searches, or to make a PDF.

PingOne Advanced Identity Cloud

PingOne Advanced Identity Cloud (formerly ForgeRock Identity Cloud) is a comprehensive IAM service. Our service lets you deploy applications anywhere: on-premises, in your own private cloud, or in your choice of public cloud.

With PingOne Advanced Identity Cloud, you can manage the complete lifecycle of identities including:

And much more...

Support and customer success

Ping Identity is here to help you with your identity journey. You’ll have a dedicated team to help you achieve your goals. Find all the resources you need Backstage.

Our dedicated cloud engineering team monitors and manages your environment. We’ll help you with moving configuration, and with secrets management, between environments. Learn about moving configuration between environments.

power_settings_new
Getting Started

Steps for
first-timers
format_list_numbered
How-Tos

Cookbook instructions
library_books
Deep Dives

How things work & other concepts
launch
Beyond the Docs

Recommended resources

Getting started with PingOne Advanced Identity Cloud

Step 1: Register your Advanced Identity Cloud tenant

After your organization purchases PingOne Advanced Identity Cloud and requests a tenant, Ping Identity prepares the tenant for initial use. Afterward, Ping Identity sends a registration email to the person from your organization that is designated as the tenant administrator.

If you are the designated tenant administrator and received the registration email, click on the registration link and perform the sign up steps in the next section.

Step 2: Sign in to Advanced Identity Cloud

If you haven’t received a confirmation email, contact your Ping Identity representative.

You receive an email for each environment.

  1. In a supported web browser, enter your first name, last name, and password.

  2. Accept the privacy policy.

  3. Set up Multi-factor authentication (MFA).

Step 3: Know your tenant

  1. Take 5 minutes to read about Advanced Identity Cloud and its capabilities.

  2. Take 5 minutes to read about your tenant.

Step 4: Take a test drive

Here are some things you can try in your development environment:

  1. Create a user profile.

  2. Create an external role for your user.

  3. Add an application to your identity platform.

  4. Set up a basic login end-user journey.

  5. Sign out of your tenant administrator session, then be the end-user:

    1. Using a browser, go to your tenant URL.

    2. Sign in as the test user you created.

Step 5: Get going

Once you’re ready to stage real users and applications in your tenant, start with these steps:

  1. Take some time to read up on how your engineering environments work.

  2. To provision your tenant, import identity profiles to your tenant.

  3. Invite others to be tenant administrators.

  4. Add an application to your tenant.

  5. Sync your application users with users in your tenant.

  6. Use the ForgeRock SDKs to set up authentication.

  7. Set up a login end-user journey.

Admin UIs

PingOne Advanced Identity Cloud provides three user interfaces (UIs) to help you manage your tenant:

idcloudui admin consoles

① Advanced Identity Cloud admin UI
② AM admin UI (native console)
③ IDM admin UI (native console)

Advanced Identity Cloud admin UI

This is the primary UI, designed to handle most of the day-to-day tasks associated with managing your tenant. To get started, take a test drive.

AM admin UI and IDM admin UI (native consoles)

These are secondary UIs, intended for specialist tasks when configuring AM and IDM in Advanced Identity Cloud. They let you access functionality not yet available in the Advanced Identity Cloud admin UI.

You don’t need separate credentials to access these UIs. If you are signed into the Advanced Identity Cloud admin UI, you can seamlessly switch from one UI to another.

AM admin UI

Use to register SAML 2.0 applications, for example.

To open, in the Advanced Identity Cloud admin UI, click Native Consoles > Access Management.

IDM admin UI

Use to set up a built-in connector, for example, or map your identities to identities stored in an external resource.

In the Advanced Identity Cloud admin UI, click Native Consoles > Identity Management.

Advanced Identity Cloud analytics dashboard

PingOne Advanced Identity Cloud analytics dashboard provides a comprehensive snapshot of your Advanced Identity Cloud system usage. You can use the dashboard to gain valuable insights on your tenants:

Analytics Dashboard

Monitor the number of users and engagements

At the top of the Identity Cloud analytics dashboard, there is a summary of total number of users, applications, and organizations in your realm. These realm usage totals are summarized as follows:

  • Total Users. Displays the total count of active and inactive users in this realm.

  • Applications. Displays the total number of current applications in this realm.

  • Organizations. Displays the total number of organizations in this realm.

Analytics Dashboard Summary page

Below the realm usage totals, Identity Cloud analytics dashboard displays three trendline charts: user engagements, total users, and new users. These trendline charts are updated every two to three hours and are summarized as follows:

  • User Engagement. Displays the trendline of the number of user engagements within a given time period; by default, the last 30 days. A user engagement is counted when a user is involved in an identity operation within the given time period. An identity operation can be any of the following:

    • Sign-in/authentication

    • Token refresh (for example, token issuance, validation, and refresh)

    • Password creation or change

      A user who has multiple user engagements within a given time period is counted once.

  • Total Users Trend. Displays the trendline for total users (active and inactive) during the time period in this realm.

    The total users trend number may differ from the Total Users number at the top of the page as the data depends on the selected time period and the update frequency. For example, new users who have been added to the system within the last hour may not appear yet on the page.

  • Sign Ups. Displays the trendline for new user sign-ups during the time period in this realm.

Filter timelines

Each chart displays the usage numbers for the current time period, expressed as solid lines; the dotted lines display the numbers for the previous time period. For example, if the time period is Last 30 days, the solid line displays the numbers over the last 30 days from today’s date; the dotted line displays the previous 30-day numbers.

To compare the numbers for a specific date, hover over a point on either line to display the numbers for the current and the previous time periods.

Analytics Dashboard Trends page

By default, the Identity Cloud analytics dashboard displays the number of engagements, total users, and new user sign-ups for a 30-day period, you can filter the output by changing the time period.

Change the time period for the trendline charts

  1. Click Last 30 days, and select one of the following time periods:

    • Today. Displays the numbers for today, 12:00 a.m. to the current time.

    • Yesterday. Displays the numbers for yesterday, 12:00 a.m. to 12:00 p.m. on the previous day.

    • Last 7 Days. Displays the numbers for the last seven days from today’s date.

    • Last 30 Days. Displays the last 30 days from today’s date. This is the default time period.

      All dates and time periods are based on UTC time.

  2. Click Apply to save your changes.

Analytics Dashboard Trends time periods filtering

Monitor journeys

You can refer to a chart on the number of successful and failed journey outcomes within your realm on the Identity Cloud analytics dashboard. Scroll down the Identity Cloud analytics dashboard page to refer to the Journeys graph.

By default, the Identity Cloud analytics dashboard displays the aggregation of all successful and failed journeys on the Advanced Identity Cloud. These aggregations express four different types of information:

  • Blue lines indicate successful journey outcomes.

  • Red lines indicate failed journey outcomes.

  • Solid lines indicate the journey outcomes that occurred within the current selected time period.

  • Dotted lines indicate the journey outcomes in the previous time period.

The journey usage is not counted if the journey is used as a node in another journey.

Analytics Dashboard Journeys section

The Identity Cloud analytics dashboard also lets you filter the chart by journey type. The available journeys are listed on the Advanced Identity Cloud Journeys page and includes any custom journeys that you may have configured. For example:

  • EvaluateRisk

  • ForgottenUsername

  • Login (default)

  • PasswordGrant

  • ProgressiveProfile

  • Registration

  • ResetPassword

  • Sample Tree

  • UpdatePassword

The categories are:

  • Authentication

  • Password Reset

  • Progressive Profile

  • Registration

  • Username Reset

The journeys and categories options come from any tag that you have selected.

Filter journeys

  1. On the Journeys chart, click All journeys.

  2. On the Filter Journeys dialog box, select one or more journeys on the drop-down list to include in your chart.

  3. Click Apply to update your journeys chart. The changes appear immediately.

Access journey pass/fail details

The Journeys chart also lets you drill down at specific points on a trendline to access its details, or metric breakdown. Red lines indicate failed journeys. Blue lines indicate successful journeys.

For example, you can use the Metric Breakdown page to review the journeys for the selected date, sorted by a ranking of percentage failures (default). The percentage is calculated for each journey as the total outcomes passed or failed, and then sorted in descending order from the highest failed journey by percentage to the lowest failed journey by percentage.

Analytics Dashboard Metric Breakdown page sorted by percentage success or failures

The Metric Breakdown page also lets you sort the journeys by number ranking. Number indicates the actual number of successful or failed outcomes for each journey.

The following table provides an example of how the analytics dashboard ranks by percentage and by number:

Table 1. Metric Breakdown Example of How Percentage Rank and Number Rank and Determined
Journey Total Outcomes Passed Failed Percentage Rank Number Rank

A

900

630

270 (30%)

2

1

B

100

50

50 (50%)

1

2

C

100

80

20 (20%)

3

3
Timeouts are not displayed in the Journey outcomes.

Access the metric breakdown page

  1. On the Journeys chart, hover anywhere over a trendline to view the successful or failed outcomes for that date, and then click View detail. The Metric Breakdown page appears with more insights on the individual journeys. By default, All Journeys and Percentage are selected.

  2. On the Metric Breakdown page, click Number to display the number of failed and successful journeys sorted by rank.

    Click to show how to access the metric breakdown page
    How to access the Metric Breakdown page

Top Five Journeys by Outcome and Top Five Journeys by Usage widgets

The Identity Cloud analytics dashboard displays two additional widgets providing trendlines into your journeys: Top Five Journeys by Outcome and Top Five Journeys by Usage. The Top Five Journeys by Outcome widget displays the top five journeys ranked by percentage failed or successful. The default selection is Fail. You can change the selection to Success to display top five successful journeys.

The Top Five Journeys by Usage widget displays the top five most or least used journeys. By default, the most used journeys are selected. Each bar chart provides the percentage usage of the journey in the given time period based on the outcomes only. For each journey, the calculation is based on the total number of outcomes for the journey divided by the total number of all journey outcomes in the time period.

The widgets only display the journey outcomes for the selected time period. The x-axis denotes the percentage outcomes in the journey.
Analytics Dashboard Top Five Journeys by Outcome and Top Five Journeys by Usage Widgets

Access top five journeys by outcome and top five journeys by usage

  1. On the Top Five Journeys by Outcome widget, the widget displays the top five failed journeys by default. Click Success to display the top five successful journeys.

  2. On the Top Five Journeys by Usage widget, the widget displays the most used journeys by default. Click Least to display the least used journeys.

Notice

The analytics dashboard service provides key insights and trends with respect to successful or failed journey outcomes, number of users, user engagement, number of new users (sign-ons), applications, and organizations. By leveraging this functionality, Ping Identity customers can better understand their usage of the Advanced Identity Cloud. This functionality also allows Ping Identity to maintain accurate billing information with respect to such use.

All data Ping Identity collects for the purposes of providing the analytics dashboard service is anonymized using industry standard practices. The purpose is to ensure that the data does not contain any personally identifiable information, and further, so it cannot be re-identified. This includes, but is not limited to, a one-way SHA-256 hashing function that returns a hexadecimal representation of a UUID. This ensures that no personally identifiable information is used by Ping Identity, or any other third-party or system.

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

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. You can extract any configuration from your sandbox environment using the REST APIs, then post it to your development environment.

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)

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 UAT (user acceptance testing) 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).

A UAT environment is inserted into the self-service promotion process between the development and staging environments:

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

    environments with uat

  • If you have two UAT environments, the revised promotion order is development → UAT → UAT2 → staging → production:

    environments with uat and uat2
You can only add up to two UAT environments to your promotion group of environments.

Set up tenant administrators

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

You can set up additional tenant administrators 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.

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. Open an Advanced Identity Cloud: Config request with Backstage Support.

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

    Field Value

    Hostname(s)

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

    What would you like to do?

    Select Enable outbound static IP addresses.

    Do you give permission for ForgeRock to access and make changes to your environment?

    Select Yes to allow Backstage Support to access your environments

  3. Click Submit to create the support ticket.

  4. Backstage 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 UI 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 UI, 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 UI, 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.

    • Region
      The region where your data resides.

Invite and view 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 UI, open the TENANT menu (upper right).

  2. Click Tenant Settings.

  3. Click Global Settings.

Tenant administrator settings

Types of administrators

There are two types of administrator in Advanced Identity Cloud:

  • Tenant administrator: An administrator that 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: A tenant administrator with the following elevated permissions:

    • Invite tenant administrators.

    • Grant or revoke super administrator privileges to and from tenant administrators.

    • Enable federation for a tenant.

    • Enforce federation for some or all administrators in a tenant.

The tenant provisioning process initially creates a single super administrator.

Register as an administrator

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

If you are added as an 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 the ForgeRock 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 ForgeRock’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 ForgeRock’s privacy policy, and click Next. The Advanced Identity Cloud dashboard should now display.

Tenant administrator sign-in

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

Tenant administrators access their sign-in page 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, a tenant administrator is automatically switched to the Alpha realm.

Multiple failed authentication attempts cause Advanced Identity Cloud to lock out a tenant administrator. For information about how to unlock an administrator’s account, learn more in Unlock a tenant administrator’s account.

Edit your own tenant administrator profile

Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

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

150

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 Account 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 manage settings for your tenant.

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

  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 the invitee completes the instructions in the invitation email, the invitee becomes an administrator.

View the tenant administrators list

Tenant administrators Super administrators[4]

Action allowed?

No

Yes

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

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

  2. Click Tenant Settings > Admins.

    • To invite a new tenant administrator:

    • To deactivate a tenant administrator:

      • Find an 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 tenant administrators list.

      When you delete a tenant administrator, their username is removed from the tenant administrators list, and tenant administrator 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.

If your organization has multiple tenant administrators, another tenant administrator can unlock the account:

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

  2. Click Tenant Settings > Admins.

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

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

If your organization does not have multiple tenant administrators, submit a Backstage Support ticket.

Grant or revoke super administrator access

Tenant administrators Super administrators[4]

Action allowed?

No

Yes

To grant or revoke super administrator privileges:

  1. Go to Tenant Settings > Admins.

  2. Click an 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 in as a tenant administrator by asking for a second factor of authentication.

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

Register for 2-step verification

You can register for 2-step verification when you sign in as a tenant administrator 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.

  • Alternatively, click Skip for now to temporarily skip registration for 2-step verification.

    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. Open your tenant administrator user profile.
    In the Advanced Identity Cloud admin UI, open the TENANT menu (upper right) and choose your tenant administrator username.

  2. On your tenant administrator user 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 out and attempt to sign back in again, you will be asked if you want to set up a second factor.

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 AM or IDM 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 types

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

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

Before the expressionType parameter was introduced, it was only possible to set 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 type that you set in configuration matches the 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[5]. 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

For background on ESVs in PingOne Advanced Identity Cloud, learn more 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 UI

For background on ESVs in PingOne Advanced Identity Cloud, learn more in ESVs.

Create variables

  1. In the Advanced Identity Cloud admin UI, 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 type. Learn more in variable types.

    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 UI, 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 UI, 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 UI, 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 UI, 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 UI, 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 the ESV UI 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 the ESV UI 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 the ESV UI 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.

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.

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 UI, click Native Consoles > Access Management.

  3. In the AM admin UI (native 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

The following knowledge base article describes how to rotate SAML 2.0 certificates using ESVs: https://backstage.forgerock.com/knowledge/kb/article/a47544526.

Generate keys to use in 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

Configure tenant email provider

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

  1. Get an access token. Learn more in Get an access token.

  2. Get the email provider configuration:

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/config/external.email' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' (1)
    1 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 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' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(1)
--data-raw '<email-provider-configuration>'(2)
    1 Replace <access-token> with the access token created in step 1.
    2 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
}

Configure CORS

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. Learn more in 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' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' (1)
    1 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 ESV placeholders:

    {
    "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 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)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(2)
--data-raw '<cors-configuration>'(3)
    1 Replace <cors-id> with the CORS configuration ID you found in step 2; for example, example-cors-config.
    2 Replace <access-token> with the access token created in step 1.
    3 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
    }
}

Configure a journey node

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. Learn more in 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)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' (3)
    1 Replace <realm> with the realm that contains the journey that contains the LDAP decision node; for example, alpha.
    2 Replace <journey-name> with the name of the journey that contains the LDAP decision node; for example, UpdatePassword.
    3 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)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' (4)
    1 Replace <realm> with the realm that contains the journey that contains the LDAP decision node; for example, alpha.
    2 The node name specified is LdapDecisionNode.
    3 Replace <node-id> with the node ID you found in step 2; for example, 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.
    4 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 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)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(4)
--data-raw '<node-configuration>'(5)
    1 Replace <realm> with the realm that contains the journey that contains the LDAP decision node; for example, alpha.
    2 The node name specified is LdapDecisionNode.
    3 Replace <node-id> with the node ID you found in step 2; for example, 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.
    4 Replace <access-token> with the access token created in step 1.
    5 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"
        }
    ]
}

Configure a federation provider secret

This example shows how to configure a placeholder for a federation provider secret.

  1. Get an access token. Learn more in Get an access token.

  2. Get the configuration of the federation provider:

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realm-config/services/SocialIdentityProviders/oidcConfig/<provider-id>' \(1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' (2)
    1 Replace <provider-id> with the name of your federation provider; for example, ms-azure-provider.
    2 Replace <access-token> with the access token created in step 1.
    Show response 
    {
    "clientId": "my-client-id",
    "pkceMethod": "S256",
    "wellKnownEndpoint": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
    "authorizationEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "clientSecret": null,
    "issuerComparisonCheckType": "EXACT",
    "encryptJwtRequestParameter": false,
    "scopeDelimiter": " ",
    "scopes": [
        "User.Read",
        "openid"
    ],
    "issuer": "ForgeRock",
    "userInfoResponseType": "JSON",
    "acrValues": [],
    "encryptedIdTokens": false,
    "enabled": true,
    "jwtRequestParameterOption": "NONE",
    "authenticationIdKey": "id",
    "uiConfig": {
        "buttonCustomStyle": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "buttonCustomStyleHover": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "buttonDisplayName": "Azure",
        "buttonImage": "img/azure-logo.6be3c5e8.svg",
        "iconBackground": "#0078d7",
        "iconFontColor": "white"
    },
    "privateKeyJwtExpTime": 600,
    "revocationCheckOptions": [],
    "enableNativeNonce": true,
    "userInfoEndpoint": "https://graph.microsoft.com/oidc/userinfo",
    "jwtSigningAlgorithm": "NONE",
    "redirectURI": "https://openam-federation-preview.forgeblocks.com/login/admins",
    "clientAuthenticationMethod": "CLIENT_SECRET_POST",
    "responseMode": "DEFAULT",
    "useCustomTrustStore": false,
    "tokenEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "_id": "ms-azure-provider",
    "_type": {
        "_id": "oidcConfig",
        "name": "Client configuration for providers that implement the OpenID Connect specification.",
        "collection": true
    }
}

  3. Create a local copy of the federation provider configuration from step 2, then substitute an ESV placeholder for the application secret:

    {
    "clientId": "my-client-id",
    "pkceMethod": "S256",
    "wellKnownEndpoint": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
    "authorizationEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "clientSecret": {
        "$string":"&{esv.ms.azure.provider}" (1)
    },
    "issuerComparisonCheckType": "EXACT",
    "encryptJwtRequestParameter": false,
    "scopeDelimiter": " ",
    "scopes": [
        "User.Read",
        "openid"
    ],
    "issuer": "ForgeRock",
    "userInfoResponseType": "JSON",
    "acrValues": [],
    "encryptedIdTokens": false,
    "enabled": true,
    "jwtRequestParameterOption": "NONE",
    "authenticationIdKey": "id",
    "uiConfig": {
        "buttonCustomStyle": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "buttonCustomStyleHover": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "buttonDisplayName": "Azure",
        "buttonImage": "img/azure-logo.6be3c5e8.svg",
        "iconBackground": "#0078d7",
        "iconFontColor": "white"
    },
    "privateKeyJwtExpTime": 600,
    "revocationCheckOptions": [],
    "enableNativeNonce": true,
    "userInfoEndpoint": "https://graph.microsoft.com/oidc/userinfo",
    "jwtSigningAlgorithm": "NONE",
    "redirectURI": "https://openam-federation-preview.forgeblocks.com/login/admins",
    "clientAuthenticationMethod": "CLIENT_SECRET_POST",
    "responseMode": "DEFAULT",
    "useCustomTrustStore": false,
    "tokenEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "_id": "ms-azure-provider",
    "_type": {
        "_id": "oidcConfig",
        "name": "Client configuration for providers that implement the OpenID Connect specification.",
        "collection": true
    }
}
    1 Substitution for ESV placeholder &{esv.ms.azure.provider}.

  4. Update the federation provider configuration:

    Show request 
    curl \
--request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realm-config/services/SocialIdentityProviders/oidcConfig/<provider-id>' \ (1)
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: resource=1.0' \
--header 'Authorization: Bearer <access-token>' \(2)
--data-raw '<provider-configuration>' (3)
    1 Replace <provider-id> with the name of your federation provider; for example, ms-azure-provider.
    2 Replace <access-token> with the access token created in step 1.
    3 Replace <provider-configuration> with the local copy of the provider configuration modified in step 3.
    Show response 
    {
    "clientId": "my-client-id",
    "pkceMethod": "S256",
    "wellKnownEndpoint": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
    "authorizationEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "clientSecret": {
        "$string":"&{esv.ms.azure.provider}"
    },
    "issuerComparisonCheckType": "EXACT",
    "encryptJwtRequestParameter": false,
    "scopeDelimiter": " ",
    "scopes": [
        "User.Read",
        "openid"
    ],
    "issuer": "ForgeRock",
    "userInfoResponseType": "JSON",
    "acrValues": [],
    "encryptedIdTokens": false,
    "enabled": true,
    "jwtRequestParameterOption": "NONE",
    "authenticationIdKey": "id",
    "uiConfig": {
        "buttonCustomStyle": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "buttonCustomStyleHover": "background-color: #fff; border-color: #8b8b8b; color: #8b8b8b;",
        "buttonDisplayName": "Azure",
        "buttonImage": "img/azure-logo.6be3c5e8.svg",
        "iconBackground": "#0078d7",
        "iconFontColor": "white"
    },
    "privateKeyJwtExpTime": 600,
    "revocationCheckOptions": [],
    "enableNativeNonce": true,
    "userInfoEndpoint": "https://graph.microsoft.com/oidc/userinfo",
    "jwtSigningAlgorithm": "NONE",
    "redirectURI": "https://openam-federation-preview.forgeblocks.com/login/admins",
    "clientAuthenticationMethod": "CLIENT_SECRET_POST",
    "responseMode": "DEFAULT",
    "useCustomTrustStore": false,
    "tokenEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "_id": "ms-azure-provider",
    "_type": {
        "_id": "oidcConfig",
        "name": "Client configuration for providers that implement the OpenID Connect specification.",
        "collection": true
    }
}

Manage configuration placeholders using the UI

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.

UI support for configuration placeholders

The Advanced Identity Cloud admin UI 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 UI support for placeholders:

UI 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 UI 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 UI, 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 type for the field; for example, for a field that expects a boolean value, the list contains only ESVs with a bool type:

    image$ui esv insertable placeholder list
    The UI combines secrets and string type variables 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 UI, 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:

Lower and upper environments

The environments in a sequential pair of environments are referred to as the lower environment (the configuration source), and the upper environment (the configuration destination); the terms lower environment and upper environment therefore refer to different environments, depending on 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

output lower

input upper

Production promotion

output lower

input upper

Key:

  • output lower = lower environment (configuration source)

  • input upper = upper environment (configuration destination)

Additional UAT environments

If you also have a UAT[3] environment in your promotion group of environments, it is inserted into the promotion process between the development and staging environments:

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

    Development
    environment    		 UAT
    environment    		 Staging
    environment    		 Production
    environment

    UAT promotion

    output lower

    input upper

    Staging promotion

    output lower

    input upper

    Production promotion

    output lower

    input upper

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

    Development
    environment    		 UAT
    environment    		 UAT2
    environment    		 Staging
    environment    		 Production
    environment

    UAT promotion

    output lower

    input upper

    UAT2 promotion

    output lower

    input upper

    Staging promotion

    output lower

    input upper

    Production promotion

    output lower

    input upper

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

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

Lower and upper environments

Before you run 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 for maintenance. Retry later."
}

        Ping Identity typically locks an environment so that Backstage 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, submit a Backstage Support ticket. 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, submit a Backstage Support ticket. 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, submit a Backstage Support ticket. 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 submit a support ticket:

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

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

    Field Value

    Product

    Select the following from the lists:

    • PingOne Advanced Identity Cloud

    • Tenant Settings

    • Self-Service Promotion

    What are you trying to achieve?

    Enter one of the following:

    • Resolve environment errors preventing a self-service promotion

    • Resolve environment errors preventing a self-service rollback

    Please provide a short description

    Enter one of the following:

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

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

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

  3. Click Submit.

Revert configuration in your development environment

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

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

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

    Field Value

    Hostname

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

    What would you like to do?

    Select Restore from backup

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

    Field Value

    What is the environment name?

    Select Dev.

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

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

  4. Click Submit.

Manage self-service promotions using the UI

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

Lower and upper environments

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

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

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

Promotions UI functionality in the lower environment

In the lower environment, the promotions UI lets you:

  • View changes awaiting promotion to the upper environment

  • Promote changes to the upper environment

  • View history of promotions sent to the upper environment

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

View changes awaiting promotion to the upper environment

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

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

  3. The Promotion tab shows the following information:

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

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

        idcloudui promotion summary development

        If you have a UAT[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 UI indicates that two configuration changes have been made—one to a journey and one to an email template:

      idcloudui promotion view changes development

Sign in to the upper environment

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

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

idcloudui promotion screen title sign in development

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

idcloudui promotion screen title sign in staging

If you have a UAT[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 UI of the lower environment, open the TENANT menu (upper right)

  2. Click Promote configuration.

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

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

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

  4. Click Promote n Changes.

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

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

    idcloudui promotion lock tenants development

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

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

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

    • If you want to cancel the promotion:

      1. Click Cancel Promotion.

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

    • If you want to proceed with the promotion:

      1. Click Start Promotion

      2. In the Start Promotion? modal window:

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

        2. Click Start Promotion again.

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

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

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

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

    • Click Done to return to the Promotion tab.

      idcloudui promotion success

View history of promotions sent to the upper environment

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

  2. Click Promote configuration.

  3. Click View promotion history.

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

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

idcloudui promotion history development

Promotions UI functionality in the upper environment

In the upper environment, the promotions UI lets you:

  • View a history of promotions received from the lower environment

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

View history of promotions received from the lower environment

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

  2. Click Tenant settings.

  3. Click the Details tab.

  4. Click View updates.

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

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

Restricted functionality

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

Restricted functionality in the lower environment

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

  • The left menu is hidden.

  • The page header shows Tenant Locked on the left.

  • The page header shows a restricted dropdown menu on the right.

idcloudui promotion review development

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

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

Restricted functionality in the upper environment

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

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

idcloudui promotion summary tenant locked staging

Troubleshooting

Resolve failed integrity check for missing ESVs

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

idcloudui promotion error esvs

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

To resolve this:

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

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

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

  4. Start the promotion steps again.

Resolve failed integrity check for encrypted secrets

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

idcloudui promotion error encrypted secrets

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

To resolve this:

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

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

  3. For each encrypted secret in the report:

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

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

  4. Start the promotion steps again.

Resolve tenant locked errors

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

idcloudui promotion error tenant locked

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

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

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

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

    Field Value

    Product

    Select the following from the lists:

    • PingOne Advanced Identity Cloud

    • Tenant Settings

    • Self-Service Promotion

    What are you trying to achieve?

    Enter one of the following:

    • Resolve environment errors preventing a self-service promotion

    • Resolve environment errors preventing a self-service rollback

    Please provide a short description

    Enter one of the following:

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

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

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

  3. Click Submit.

Revert a promotion

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

Revert configuration in your development environment

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

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

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

    Field Value

    Hostname

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

    What would you like to do?

    Select Restore from backup

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

    Field Value

    What is the environment name?

    Select Dev.

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

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

  4. Click Submit.

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 UI, 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: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:advanced-gateway:*  

Access to web application firewall (WAF) API endpoints

      fr:idc:advanced-gateway:read

Read-only access to WAF API endpoints. Use this scope if you only need to list WAFs.

      fr:idc:advanced-gateway:write

Create, update, and delete access to WAF API endpoints

fr:idc:analytics:*  

Access to analytics API endpoints

fr:idc:cookie-domain:*  

Access to cookie domain endpoints

Scopes for add-on capability APIs

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

Scope Purpose Reference

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 UI

View service accounts

  1. In the Advanced Identity Cloud admin UI, 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 UI, 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 UI, 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 UI, 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 UI, 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, submit a Backstage Support ticket.
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 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 access credentials for additional tenant administrators.

Get access credentials for additional tenant administrators

If monitoring Advanced Identity Cloud uptime status is part of a tenant administrator’s role, submit a Backstage Support ticket 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 access for tenant administrators

If you want to remove status page access for one or more tenant administrators, submit a Backstage Support ticket. 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, submit a Backstage Support ticket.

  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 Purpose

/monitoring/prometheus/am

Produces Prometheus-formatted metrics for Access Management

/monitoring/prometheus/idm

Produces Prometheus-formatted metrics for Identity Management

You must obtain API credentials to authenticate to these endpoints. Learn more in Obtaining API Credentials.

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"
}

Learn more about am-access properties in Access log format.

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"
}

Learn more about am-activity properties in Activity log format.

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-LOGOUT

  • AM-LOGIN-COMPLETED

  • AM-LOGIN-MODULE-COMPLETED

  • AM-NODE-LOGIN-COMPLETED

  • AM-TREE-LOGIN-COMPLETED

Advanced Identity Cloud logs an AM-NODE-LOGIN-COMPLETED 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"
  }
}

Learn more about am-authentication properties in Authentication log format.

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"
}

Learn more about am-config properties in Config log format.

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

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>'

To understand how to construct a filter expression, learn more 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/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 debug 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 'https://<tenant-env-fqdn>/openidm/config/audit' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json'

    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.RepositoryAuditEventHandler",
      "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.JsonAuditEventHandler",
      "config": {
        "buffering": {
          "maxSize": 100000,
          "writeInterval": "100 millis"
        },
        "logDirectory": "&{idm.data.dir}/audit",
        "name": "json",
        "topics": [
          "access",
          "activity",
          "sync",
          "authentication",
          "config"
        ]
      }
    },
    {
      "class": "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler",
      "config": {
        "enabled": false,
        "name": "repo",
        "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 'https://<tenant-env-fqdn>/openidm/config/audit' \
--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)
        ]
      }
   },
  ...
}'

    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.

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 20,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 'https://<tenant-env-fqdn>/openidm/config/audit' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json'

    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"
        ]
      }
    },
    {
      "class": "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler",
      "config": {
        "enabled": false,
        "name": "repo",
        "topics": [
          "access",
          "activity",
          "sync",
          "authentication",
          "config",
          "recon"
        ]
      }
    }
  ],
...
}'

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 may 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>'

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 UI 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 UI

  1. In the Advanced Identity Cloud admin UI, 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 2. 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 3. 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 4. 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 5. 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 UI, 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 UI, 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.

Edit an email template

  1. In the Advanced Identity Cloud admin UI, 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 UI, 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 UI, 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.

For background on ESVs in PingOne Advanced Identity Cloud, learn more in ESVs.

To add ESV variables to an email template, you must use the Advanced Editor. Once 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 UI or variables APIs.

    2. Restart Advanced Identity Cloud services by applying updates in the Advanced Identity Cloud admin UI or using the restart API.

  2. In the Advanced Identity Cloud admin UI, 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

The locale selector in the top left of the email template editor displays the current template locale in the format Locale: code, where code is a ISO-639-1 language codes (for example en or de).

  • 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 window.

    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 close the modal window and 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 window.

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

    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 UI, 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 UI, 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

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 ForgeRock 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 UI 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 the Configure CORS section of Manage configuration placeholders using the API.

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

    ForgeRock SDK

    Choose this option when you want to work with the ForgeRock SDK.
    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 ForgeRock 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 ForgeRock. 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 ForgeRock 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 UI, 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 submitting a ticket to Backstage Support.

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.

Realm settings

Realms are administrative units that group configurations and identities together so that you can manage different sets of identities and applications within the same PingOne Advanced Identity Cloud tenant.

Each realm is fully self-contained and operates independently of other realms within a tenant; the identities and applications in one realm can’t access those in another realm.

A typical example of realm management is when a company divides its identities into two realms: one for employees and one for customers, each having a distinct set of identities and registered applications.

Manage realm settings

  1. In the Advanced Identity Cloud admin UI (upper left), open the Realm menu.

  2. Go to Realm Settings > Details.

  3. On the Details page:

    • The Status bar indicates whether the realm is Active or Inactive.

    • To take the realm out of service, click Deactivate.
      When a realm is deactivated, users and devices contained in the realm will not be able to access its applications. Identity and app information is still registered to your identity platform.

    • Name: The realm name is non-configurable.

    • (Optional) DNS Aliases: Alternative display names for the realm’s URL.

    • Use Client-based Sessions: Enable this option to allow signing and encryption of the JWT in the global session service.

  4. To configure a custom domain name, click Custom Domains. Learn more in Custom domains.

When you’re satisfied with your changes, click Save.

Override realm authentication attributes

It’s useful to override realm authentication attributes when you want to adjust the core authentication properties of a realm. For example, you may want to extend the time limit for responding to an authentication verification email.

Under Native Consoles > Access Management, go to Authentication > Settings.

For detailed property information, learn more in Core authentication attributes.

Switch realms

Switch realms when you want to access identities or applications registered to a realm other than the current realm.

  1. In the Advanced Identity Cloud admin UI, open the Realm menu (upper left).

  2. Click Switch realm.

  3. In the Switch Realm dialog box, click Switch.

Alpha and Bravo realms

The Alpha and Bravo realms are the two default realms that are included as part of an PingOne Advanced Identity Cloud tenant. These realms are configurable, unlike the top-level realm that Advanced Identity Cloud configures for tenant administrator identities.

Advanced Identity Cloud does not support more than two realms in the same tenant.

The Alpha and Bravo realms are nearly identical, with the exception of delegated administration.

End-user sign-in

End users access their sign-in page using a URL that specifies the realm they belong to. For example:

  • Alpha realm end users: https://<tenant-env-fqdn>/am/XUI/?realm=alpha&authIndexType=service&authIndexValue=Login

  • Bravo realm end users: https://<tenant-env-fqdn>/am/XUI/?realm=bravo&authIndexType=service&authIndexValue=Login

Tenant administrators cannot authenticate using these realm-specific login URLs, learn more in Tenant administrator sign-in.

Delegated administration

In the Alpha realm, you can set up internal roles for delegated administration using a custom set of privilege attributes.You can then assign those internal roles to users so that Alpha realm users can act as delegated administrators and perform actions on the custom set of attributes specified by the role.

The Bravo realm does not support delegated administration.

Assign internal roles

You can assign the internal roles in two different ways using the Advanced Identity Cloud admin UI:

  • To add an internal role to a user, go to Identities > Manage > Realm - Users. Select a user, then select the Authorization Roles tab, then click + Add Authorization Roles.

  • To add a user to an internal role, go to Identities > Manage > Internal Roles. Select a role, then select the Members tab, then click + Add Members.

In the Bravo realm, while you can set up internal roles for delegated administration, you cannot use them. Also, you cannot add a user to an internal role, and even though it appears possible to add an internal role to a user, this will not correctly link the user to the role. If you attempt this, the user will not be listed in the internal role Members tab.

The following table summarizes these differences:

Action Alpha Realm Bravo Realm

Create internal role for the purposes of delegated administration

Add user to internal role

Add internal role to user


appears possible but will not work

Custom domains

Access PingOne Advanced Identity Cloud through a customer-friendly URL by configuring a custom domain name. For example, replace the default forgerock.io domain with your own company name or brand.

Consider the following points when you customize a domain name:

  • You can set a custom domain name only at the realm level.

  • You can set multiple custom domain names per realm.

  • The Advanced Identity Cloud admin UI continues to display the default tenant environment URL.

  • Don’t use your top-level domain name.

    • Wrong: mycompany.com

    • Right: id.mycompany.com

  • Changing your custom domain name affects your end-user UIs and REST APIs.

Set up a custom domain in Advanced Identity Cloud

Configure a custom domain using the UI

  1. Choose one of these options:

  2. In the Advanced Identity Cloud admin UI, go to Realm > Realm Settings > Custom Domain.

  3. Click + Add a Custom Domain.

  4. In the Add a Custom Domain dialog box, enter your domain name, then click Next.
    The domain name must be unique, and must contain at least one period (dot).
    Example: id.mycompany.com.

  5. Choose one of these options:

    • If your custom domain relies on public DNS:

      1. In the Verify Domain Name Ownership dialog box, Advanced Identity Cloud provides the Host and Data information that you’ll use in the next step to prove that you own the domain you’ve named.

      2. Create a CNAME record with your domain name registrar.

      3. Return to the Verify the Domain Ownership dialog box, and click Verify.

    • If your custom domain relies on private DNS or you route your HTTP traffic through a WAF service:

      1. In the Verify Domain Name Ownership dialog box, click Verify.

  6. Configure the base URL source for the realm where the custom domain is to be used.

  7. The custom domain should now be successfully configured:

    • If your custom domain relies on public DNS and you do not have a self-managed SSL certificate, Advanced Identity Cloud generates a Google-managed SSL certificate.

      If your custom domain already has CAA records, you must add additional CAA records to ensure that Advanced Identity Cloud can generate Google-managed SSL certificates. Learn more in Specify the CAs that can issue your Google-managed certificate.

    • The custom domain name is added to the realm settings.

    • The FDQN for your custom domain name is mapped to server defaults.

    • The custom domain name is added to the Redirection URIs field of the end-user-ui OAuth 2.0 client. Learn more in Configure OAuth clients.

    • Both tenant domain and custom domain URL paths work; however, this does not apply to the OIDC configuration discovery endpoint.

      Examples:

      • For AM endpoint:
         https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate
         you can use:
         https://id.mycompany.com/am/json/realms/root/realms/alpha/authenticate

      • For IDM endpoint:
         https://<tenant-env-fqdn>/openidm/managed/alpha_user/<uuid>
         you can use:
         https://id.mycompany.com/openidm/managed/alpha_user/<uuid>

  8. Confirm that the custom domain is working as expected. Learn more in Check that a custom domain is working in your browser.

Configure a custom domain using ESVs

The option to configure a custom domain using ESVs has been removed from Advanced Identity Cloud. Instead, you can Configure a custom domain using the UI in any environment without needing to configure ESVs and promote configuration.

If you previously used ESVs to configure a custom domain, the ESV values have been migrated to normal UI input values and the custom domain still works as normal.

Add a CNAME record to your custom domain

If your custom domain relies on public DNS, add a CNAME record to it so Advanced Identity Cloud can validate that you are the domain owner.

  1. Sign in to the website for your domain name registrar.

  2. Find the CNAME record for your domain. If you don’t already have a CNAME record for your domain, then follow the domain name provider’s instructions to create one.

  3. In the CNAME record for your domain, enter the following values to create an alias from your custom domain to your Advanced Identity Cloud tenant domain:

    • In the host field, enter your custom domain FQDN; for example, id.mycompany.com.

    • In the data field, enter your Advanced Identity Cloud tenant FQDN; for example, openam-mycompany.forgerock.io.

  4. Follow the domain name provider’s instructions to complete the operation.

  5. It may take up to 48 hours for domain name changes to propagate. Learn more in Check when CNAME domain name changes propagate.

Check when CNAME domain name changes propagate

If you add a CNAME record to your custom domain, you can use the following ways to check when the changes propagate:

  • Use a DNS checker website; for example https://dnschecker.org/all-dns-records-of-domain.php.

  • Use the nslookup command-line tool:

    If you do not have nslookup installed, refer to https://command-not-found.com/nslookup to find installation instructions for your particular package manager. 
    $ nslookup -q=cname id.mycompany.com(1)
Server:     fe80::ced4:2eff:fec3:40e%8
Address:    fe80::ced4:2eff:fec3:40e%8#53
id.mycompany.com     canonical name = openam-mycompany.forgeblocks.com.(2)
    1 Replace id.mycompany.com with your custom domain FQDN.
    2 The output shows that the domain id.mycompany.com is an alias for the canonical name openam-mycompany.forgeblocks.com.

Deactivate CNAME record verification for your custom domain

If your custom domain relies on private DNS, or you route your HTTP traffic through a WAF service, raise a ticket to deactivate CNAME record verification.

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

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

    Field Value

    Product

    Select the following from the lists:

    • PingOne Advanced Identity Cloud

    • Tenant Settings

    • Realms - Custom Domains

    What are you trying to achieve?

    Enter "Disable CNAME record verification for a custom domain".

    Please provide a short description

    Enter your custom domain FQDN.

  3. Click Submit.

Configure the base URL source for a realm to support a custom domain

To support HTTP requests from a custom domain, the base URL source of the associated realm needs to be configured to retrieve the hostname, the server name, and the port number from incoming HTTP requests.

  1. Go to Native Consoles > Access Management.

  2. From the Realms menu, choose the realm that contains the custom domain name.

  3. On the Services page, click Base URL Source to edit its configuration.

  4. On the Base URL Source page, change the Base URL Source option to
    Host/protocol from incoming request.

  5. Click Save Changes.

Check that a custom domain is working in your browser

  • To confirm that Advanced Identity Cloud is serving traffic over HTTPS (TLS) for your custom domain name, in a browser, go to your custom domain location. For example, go to https://id.mycompany.com.

  • To test hosted pages, use an incognito or private browser window to access an end-user URL. For example, access https://id.mycompany.com/login/?authIndexType=service&authIndexValue=mytreename#/.

  • If your custom domain relies on public DNS, it may take up to 48 hours for domain name changes to propagate. If you try to use the new domain name to access your website, error messages may display until the changes take effect. If error messages still display after 48 hours, make sure your Advanced Identity Cloud domain name settings are correct and match your CNAME record. Learn more in Check when CNAME domain name changes propagate.

Verify a custom domain in Google

If you use Google as a social login IDP, you must use your domain to configure the redirect URL fields of your OAuth 2.0 apps. This might create prompts from Google to verify your domain with your domain provider. For information about how to verify your domain, learn more in Verify your site ownership on the Google Search Console.

Access OIDC configuration discovery endpoint

When you configure a custom domain, the OIDC configuration discovery endpoint URL changes:

Domain context Endpoint URL

Default domain

  • https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/<realm>/.well-known/openid-configuration

Custom domain

  • Incorrect:
    https://<custom-domain-fqdn>/am/oauth2/realms/root/realms/<realm>/.well-known/openid-configuration

  • Correct:
    https://<custom-domain-fqdn>/.well-known/openid-configuration

Using the incorrect endpoint URL can result in an OIDC discovery failure due to an issuer mismatch.

You can configure the cookie domain in Advanced Identity Cloud to control which applications have access to the cookies you create.

Advanced Identity Cloud supports two cookie domain configurations:

Custom domain level

The cookie domain matches the custom domain; for example, for the custom domain id.mycompany.co.uk, the cookie domain would also be id.mycompany.co.uk.

You may need to use the custom domain level to ensure that a session cookie can only be set or modified by applications running on a single subdomain (for example, sso.mycompany.co.uk).

Custom domain level configuration is enabled by default if your tenant environments were created on or after June 17, 2022.
Domain level

The cookie domain is determined from the custom domain using eTLD+1; for example, for the custom domain id.mycompany.co.uk, the cookie domain would be mycompany.co.uk as the eTLD is .co.uk and therefore the eTLD+1 is mycompany.co.uk.

You may need to use the domain level for the following reasons:

  • You want to set a session cookie on one subdomain (for example, sso.mycompany.co.uk) but make it available to an application running on a different subdomain (for example, banking.mycompany.co.uk).

  • You want to set a shadow session cookie at the domain level (for example, mycompany.co.uk) to make it available to legacy applications that are yet to be migrated to Advanced Identity Cloud.

Domain level configuration is enabled by default if your tenant environments were created before June 17, 2022.

To change the cookie domain configuration, raise a support ticket:

  1. Go to Backstage Support, and click PingOne Advanced Identity Cloud.

  2. Click Advanced Identity Cloud: Config Request from the PingOne Advanced Identity Cloud options.

  3. In the Request Type section, provide values for the following fields:

    Field Value

    Hostname(s)

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

    What would you like to do?

    Select Change cookie domain configuration.

    Do you give permission for ForgeRock to access and make changes to your environment?

    Select Yes to allow ForgeRock Support to access your environments.

  4. In the Cookie domain configuration section, provide a value for the following field:

    Field Value

    What level do you want the cookie domain to be?

    Select Custom domain level or Domain level.

    To determine the default setting for your tenant environments, learn more in Supported cookie domain configurations.

  5. Click Submit to create the support ticket.

  6. ForgeRock support confirms when the configuration has been changed.

Application management (legacy)

The topics in this section are for tenants created before January 12, 2023. Learn more in Application management migration FAQ.

Your applications act as clients to PingOne Advanced Identity Cloud. Ping Identity uses both OAuth 2.0 and OpenID Connect protocols to protect your applications. When you register a supported application or service, Advanced Identity Cloud sets the OAuth 2.0 grant type based on the type of application you’re registering. Advanced Identity Cloud also sets OpenID Connect default options for you. You can customize configuration in the application’s client profile.

To get started, first register your application or service to your tenant. Then, create a client profile for the application or service.

You can view and manage all your applications on the Applications page of the Advanced Identity Cloud admin UI.

The Advanced Identity Cloud admin UI supports a maximum of 500 applications.

Register an application or service

  1. In the Advanced Identity Cloud admin UI, go to Applications, and click + Add Application.

  2. In the New Consumer App dialog box, choose the application type you want to register:

  3. In the Web Application Credentials dialog box, enter a Client ID to be displayed in the Applications list, and if shown, enter a Client Secret.

  4. Click Create Application.

Create a client profile

  1. In the Advanced Identity Cloud admin UI, click Applications.

  2. In the Applications list, find the application name, then click More (), and choose Edit.

  3. Review read-only Client Credentials:

    Client Credentials

    Discovery URI

    AM URL base for OpenID Provider Configuration.
    Default: http://openam.example.com:8088/openam/oauth2

    Client ID

    Identifier used to register your client with AM’s authorization server, and then used when your client must authenticate to AM.

    Client Secret

    Password used to register your client with AM’s authorization server, and then used when your client must authenticate to AM.

  4. Edit General Settings:

    General Settings

    Name

    Specify a client name to display to the resource owner when the resource owner is asked to authorize client access to protected resources.

    App Logo URI

    Specify the location of your custom logo image file.

    Description

    Specify a client description to display to the resource owner when the resource owner is asked to authorize client access to protected resources.

    Sign-in URLs

    Custom URL for handling login. Overrides the default OpenAM login page.

    Sign-out URLs

    Custom URL for handling logout. Example: http://client.example.com:8080/openam/XUI/?realm=/#logout.

    Grant Types

    Specify the set of OAuth 2.0 grant types, also known as grant flows, allowed for this client:

    Authorization Code

    (default) Instead of requesting authorization directly from the user, your client application or service directs the user to an authorization server (Advanced Identity Cloud).

    Back Channel Request

     

    Implicit

    The client is issued an access token directly. No intermediate credentials (such as an authorization code) are issued. This grant type can potentially pose a security risk. Learn more in Implicit grant.

    Resource Owner Password Credentials

    Username and password can be used directly as an authorization grant to obtain an access token. The credentials should only be used when there is a high degree of trust between the user and the client application or service.

    Client Credentials

    Used when the client acts on its own behalf or requests access to protected resources based on previously-arranged authorization.

    Refresh Token

    Credentials used to obtain access tokens.

    Device Code

    Authorizes a client device, such as a smarthome thermostat, to access its service on an end user’s behalf. For example, the end user could log in to the thermostat service using a cell phone to enter a code displayed on the thermostat.

    SAML 2.0

    Leverages the REST-based services provided by AM’s OAuth 2.0 support. Maintains existing SAML 2.0 federation implementation.

    Scopes

    Specify scopes that display to the resource owner when they authorize client access to protected resources.

    The openid scope is required.

  5. Edit Advanced Settings:

    Access

    Add Default Scopes

    Scopes to be set automatically when tokens are issued. The openid scope is required.

    Add Response types

    Specify the response types that the client uses. The response type value specifies the flow that determines how the ID token and access token are returned to the client. By default, the following response types are available:

    • ︎code. Specifies that the client application requests an authorization code grant.

    • token. Specifies that the client application requests an implicit grant type and requests a token from the API.

    • id_token. Specifies that the client application requests an ID token.

    • code token. Specifies that the client application requests an access token, access token type, and an authorization code.

    • token id_token. Specifies that the client application requests an access token, access token type, and an ID token.

    • code id_token. Specifies that the client application requests an authorization code and an ID token.

    • code token id_token. Specifies that the client application requests an authorization code, access token, access token type, and an ID token.

    Add Claims

    Claims can be entered as simple strings, such as name, email, profile, or sub. Or, as a pipe-separated string in the format: scope|locale|localized description. For example, name|en|Full name of user.

    Allow wildcard ports in redirect URLs

    Specify whether AM allows the use of wildcards (* characters) in the redirection URI port to match one or more ports.

    The URL configured in the redirection URI must be either localhost, 127.0.01, or ::1. For example, http://localhost:*/, https://127.0.0.1:80*/, or https://[::1]:*443/.

    Enable this setting, for example, for desktop applications that start a web server on a random free port during the OAuth 2.0 flow.
    Authentication

    Token Endpoint
    Authentication Method

    Authentication method client uses to authenticate to AM.
    Choose one:

    • client_secret_basic. Clients authenticate using the HTTP Basic authentication scheme after receiving a client_secret value.

    • client_secret_post. Clients authenticate by including the client credentials in the request body after receiving a client_secret value.

    • private_key_jwt. Clients sign a JSON web token (JWT) with a registered public key.

    Token Endpoint Authentication Method (Client Type)

    • Confidential clients can maintain the confidentiality of their credentials. For example, a web application runs on a server where its credentials are protected.

    • Public clients run the risk of exposing their passwords to a host or user agent. For example, a JavaScript client running in a browser may be accessible to the public.

    Implied Consent

    When enabled, the resource owner will not be asked for consent during authorization flows. The OAuth2 Provider must also be configured to allow clients to skip consent.

    OAuth 2.0 Mix-Up Mitigation active

    Enable this setting only if this OAuth 2.0 client supports the OAuth 2.0 Mix-Up Mitigation draft; otherwise AM will fail to validate access token requests received from this client.

    Add Default ACR values

    Default Authentication Context Class Reference values. Specify strings that will be requested as Voluntary Claims by default in all incoming requests.

    Add Request URIs

    Specify request_uri values that a dynamic client would pre-register.

    Client JWT Bearer
    Public Key

    A base64-encoded X509 certificate in PEM format used to obtain the client’s JWT bearer public key. The client uses the private key to sign client authentication and access token request JWTs, while AM uses the public key for verification.

    Subject Type

    Default value is public.

    • Choose pairwise if you want each client to receive a different subject value. This prevents correlation between clients.

    • Choose public if you want each client to receive the same subject value.

    Default Max Age

    Enable this option to enforce a default maximum age of ten minutes. If the user session is not currently active, and if more than ten minutes have passed since the user last authenticated, then the user must be authenticated again.

    Use Certificate-Bound Access Tokens

    Enable this option if you want access tokens issued to this client to be bound to an X.509 certificate. When enabled, access tokens will use the X.509 certificate to authenticate to the access_token endpoint.
    Token Lifetimes

    Authorization code lifetime (seconds)

    The time an authorization code is valid for.
    Default value: 120

    Access token lifetime (seconds)

    The time an access token is valid for, in seconds
    If you set the value to 0, the access token will not be valid. A maximum lifetime of 600 seconds is recommended. Default value: 3600

    Refresh token lifetime (seconds)

    The time a refresh token is valid for.
    If this field is set to -1, the refresh token will never expire. Default value: 604800

    JWT token lifetime (seconds)

    The amount of time the JWT is valid for. Default value: 3600
    Consent Screen

    Add Display Name

    Custom user-facing title. In this example, MyClient.

    Add Display Description

    User-facing instruction text. In this example, "This application is requesting the following information:"

    Add Privacy Policy URI

    URI containing the client’s privacy policy documentation. The URI is displayed as a link in the consent page.

    200
    Client Management

    Access Token

    Specify the registration_access_token value that you provide when registering the client, and then subsequently, when reading or updating the client profile.
    Session Management

    Client Session URI

    Specify the relying party (client) URI to which the OpenID Connect Provider sends "session changed" notification. Message is sent using the HTML 5 postMessage API.
    Endpoint Response Formats

    User info response format

    Specify the output format from the userinfo endpoint.
    The supported output formats are:

    • (default) User info JSON response format.

    • User info encrypted JWT response format.

    • User info signed JWT response format.

    • ︎ User info signed then encrypted response format.

    Token introspection response format

    Specifies the format of the token introspection response. The possible values for this property are:

    • JSON response format

    • Signed JWT response format

    • Signed then encrypted JWT response format
    Signing and Encryption

    Public key selector

    Select the public key for this client, which comes from the JWKs_URI, manual JWKs, or X.509 field.

    JSON Web Key URI

    The URI that contains the client public keys in JSON web key format.

    JSON Web Key

    Raw JSON web key value containing the client public keys.

    ID Token Encryption Public Key

    Base64-encoded public key for encrypting ID tokens.

    Enable ID Token Encryption

    When enabled, encryption uses the algorithm with which the ID token must be encrypted. Default algorithm value is RSA1_5 (RSAES-PKCS1-V1_5).

  6. Click Save.

Supported application types

When you register an application or service, Advanced Identity Cloud automatically sets the optimal configuration for you. To change the default settings, edit the client profile.

Native / SPA

Native applications are developed for specific platforms or devices. Examples include the applications on mobile phones and applications dedicated to the macOS platform.

Single-page applications (SPAs) are OAuth 2.0 clients that run in a user’s web browser. SPAs use PKCE to verify the client because SPAs do not have a way to secure the client_secret value. PKCE stands for Proof Key Code Exchange; a security standard explained in the IETF specification Proof Key for Code Exchange by OAuth Public Clients.

For a deep dive on how ForgeRock implements PKCE for native and SPA applications, learn more in Authorization code grant with PKCE.

Web

Web applications are OAuth 2.0 clients that run on a web server. End users (resource owners) access web applications using a web browser. The application makes API calls using a server-side programming language. The end user has no access to the OAuth 2.0 client secret or any access tokens issued by the authorization server.

Service

Machine-to-machine (M2M) applications interact with an API and no user involvement is necessary. The application can ask for an access token without involving a user in the process. A smart meter that tracks your utility usage and wearable devices that gather and communicate health data use services and M2M applications.

OAuth 2.0 and OpenID Connect

Advanced Identity Cloud uses OAuth 2.0 and OpenID Connect to protect your applications.

OAuth 2.0

Advanced Identity Cloud provides an authorization service in the OAuth 2.0 authorization flow. OAuth 2.0 lets you set up access to your resources without sharing end-user account information. For a deep dive, learn more in RFC6749.

You may encounter domain validation prompts when using forgeblocks.com and id.forgerock.io domains as redirect URLs in your Google OAuth 2.0 applications. To resolve this, you must use a custom domain, and then set up domain verification with Google.

You could encounter No provider found errors when using forgeblocks.com and id.forgerock.io domains as redirect URLs in your OAuth 2.0 applications. To resolve this, either modify the redirect URL to include a realm identifier, or use a custom domain:

  • Incorrect:
    https://<tenant-env-fqdn>/am/oauth2/client/form_post/...

  • Correct:
    https://<tenant-env-fqdn>/am/oauth2/<realm>/client/form_post/...
    or
    https://<custom-domain-fqdn>/am/oauth2/client/form_post/...

A custom domain acts as a realm DNS alias, so when it is used as a redirect URL, Advanced Identity Cloud implicitly knows which realm to use.

OpenID Connect

OpenID Connect (OIDC) provides an identity layer on top of OAuth 2.0. OIDC lets a client make assertions about the user’s identity and their means of authentication. For a deep dive, learn more in OIDC grant flows.

What’s in the client profile

Changing the client profile settings requires a working knowledge of OAuth 2.0, its grant types, and its components. If no one has given you direction on how to configure the client profile, you’ll want to read up on some basic concepts.

Scopes

Scopes limit your client application’s access to end users' resources. For a deep dive on how scopes work, learn more in Scopes.

Grant types

Grant types, also known as grant flows, describe how your application or service access gets an access token. Learn more about grant types in OAuth 2.0 grant flows.

Claims

Claims convey information about the end user to your client application or service. For a deep dive on claims, learn more in the Claims.

Access tokens

Your applications and services use access tokens when making requests on behalf of a user. Tokens provide proof that your application or service is authorized to access the end user’s data. For a deep dive on access tokens, learn more in Advanced Identity Cloud as authorization server.

Keys

Keys protect sensitive information that Advanced Identity Cloud needs to both send and receive. You can store keys in ESV secrets, then use them in OAuth 2.0 authentication flows by mapping the ESVs to secret labels.

Test SAML 2.0 SSO using JSP flows

The topics in this section are for tenants created before January 12, 2023. Learn more in Application management migration FAQ.

SAML 2.0 helps organizations to share(or federate) identities and services without having to manage the identities or credentials themselves.

These instructions describe how to launch an SP-initiated JSP flow to test SAML 2.0 SSO. PingOne Advanced Identity Cloud acts as the authentication service provider (SP) in a circle of trust (CoT). For this test, a self-managed AM instance acts as the identity provider (IDP).

Before identities can be federated in a CoT, an AM module named Federation must be present in the SP configuration.

In self-managed AM instances, by default the Federation module is ready-to-use.

In Advanced Identity Cloud AM instances, you must manually create a module named Federation when you create an SP circle of trust.

Step 1: Set up an SP and an IDP

  1. Set up the Advanced Identity Cloud AM instance as a service provider:

    1. In the AM admin UI (native console), go to
      Realm Name > Applications > Federation > Entity Providers.

    2. Click + Add Entity Provider > Hosted, and add a hosted entity provider:

      • Entity ID: Enter a unique identifier. Example: Cloud-SP.

      • Service Provider Meta Alias: Provide an SP alias. Example: cloud-sp.

    3. Export the SP metadata to an XML file. Example export metadata URL:
      https://<tenant-FQDN>/am/saml2/jsp/exportmetadata.jsp?entityid=<SP-Entity-ID>&realm=/alpha.

  2. Set up the self-managed AM instance as an identity provider:

    1. In the AM admin UI (self managed), go to
      Top Level Realm > Applications > Federation > Entity Providers.

    2. Click + Add Entity Provider > Hosted, and add a hosted entity provider:

      • Entity ID: Enter a unique identifier. Example: AM-IDP.

      • Meta Alias: Provide an IDP alias. Example: am-idp.

    3. Export the IDP metadata to an XML file. Example export metadata URL:
      https://<IDP-host-FQDN>/openam/saml2/jsp/exportmetadata.jsp?entityid=<IDP-Entity-ID>.

  3. In the Advanced Identity Cloud AM instance, add a remote entity provider by importing the IDP metadata:

    1. In the AM admin UI (native console), go to
      Realm Name > Authentication > Federation > Entity Providers.

    2. Click + Add Entity Provider > Remote.

    3. Import the IDP metadata.

  4. In the self-managed AM instance, add a remote entity provider by importing the SP metadata:

    1. In the AM admin UI (self managed), go to:
      Top Level Realm > Authentication > Federation > Entity Providers.

    2. Click + Add Entity Provider > Remote.

    3. Import the SP metadata.

  5. Create a user profile on the SP and IDP:

    1. SP: In the AM admin UI (native console), go to Identities and add a user identity.

    2. IDP: In the AM admin UI (self managed), go to Identities and add a user identity.

Step 2: Create an SP circle of trust

  1. In the Advanced Identity Cloud AM instance, create a circle of trust:

    1. In the AM admin UI (native console), go to
      Realm Name > Applications > Federation > Circles of Trust.

    2. Click + Add Circle of Trust.

    3. On the New Circle of Trust page, provide a name, then click Create.

    4. On the CoT page, provide CoT details.

      CoT details:

      • Description: Enter a unique identifier.

      • Entity Providers: Choose the entity IDs for the SP and IDP.
        Examples: Cloud-SP AM-IDP

    5. Click Save Changes.

  2. In the Advanced Identity Cloud AM instance, create a federation module:

    1. In the AM admin UI (native console), go to
      Realm Name > Authentication > Modules.

    2. On the Modules page, click Add Module. Enter module details:

      • Name: Must be named Federation.

      • Type: Must be type Federation.

    3. Click Save Changes.

  3. In the Advanced Identity Cloud AM instance, configure the page the browser displays upon successful SSO:

    1. In the AM admin UI (native console), go to
      Realm Name > Applications > Federation > Entity Providers.

    2. In the Cloud-SP entity provider page, select the Advanced tab.

    3. In the Relay State URL List field, add the target URL for the SP end-user sign-in page.
      Example: https://<tenant-FDQN>/enduser/?realm=alpha#/dashboard.

    4. Click Save Changes.

Step 3: Create an IDP circle of trust

  1. In the AM admin UI (self managed), go to
    Top Level Realm > Applications > Circles of Trust.

  2. Click + Add Circle of Trust.

  3. On the New Circle of Trust page, provide a name, then click Create.

  4. On the CoT page, provide CoT details.

    CoT details:

    • Description: Enter a unique identifier.

    • Entity Providers: Choose the entity IDs for the SP and IDP.
      Examples: Cloud-SP AM-IDP.

  5. Click Save Changes.

Step 4: Test SAML 2.0 SSO

  1. In a browser, go the JSP URL to launch an SP-initiated JSP flow. Example:
    https://<tenant-FQDN>/am/saml2/jsp/spSSOInit.jsp?realm=/alpha/&metaAlias=/alpha/cloud-sp&idpEntityID=AM-IDP&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST&NameIDformat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent&RelayState=https://<tenant-FQDN>/enduser/?realm=alpha#/dashboard.

  2. On the IDP sign-in page, enter the user’s credentials:

    Keep this session open. The IDP authenticates the user, then the browser redirects the user back to the SP sign-in page.

  3. On the SP sign-in page, enter the user’s credentials:

    After this second successful authentication, the user’s SP identity is linked to, or federated with, the user’s IDP identity.

    The browser redirects to the SP end-user page.

  4. Sign the user out of both the SP and IDP.

  5. Go to the IDP end-user sign-in page, and enter the user’s credentials.

    When the user is successfully authenticated, the browser redirects to the SP end-user page specified in Relay State URL List.

More Information

For deep dives, learn more in:

Gateways & agents

Integrate PingOne Advanced Identity Cloud with PingGateway and policy agents to secure access to your web resources.

PingGateway

PingGateway integrates your web applications, APIs, and microservices with Advanced Identity Cloud. ${ig.abbr} enforces security and access control without modifying your applications or the containers where they run—whether on premises, in a public cloud, or in a private cloud.

Based on reverse proxy architecture, ${ig.abbr} intercepts client requests and server responses. In this process, ${ig.abbr} enforces user or service authentication and authorization to HTTP traffic. Advanced Identity Cloud acts as the authentication and authorization provider.

${ig.abbr} can also conduct deep analysis, then throttle and transform requests and responses when necessary.

Learn more in the PingGateway Guide for Advanced Identity Cloud. In particular, refer to these detailed instructions and examples:

Policy agents

Policy agents are PingAM add-on components. They operate as policy enforcement points (PEPs) for websites and applications.

Policy agents natively plug into web or applications servers. The agents intercept inbound requests to websites, and interact with AM to:

  • Ensure that clients provide appropriate authentication.

  • Enforce AM resource-based policies.

Use Web Agents to protect services and web resources hosted on a web or proxy server. Use Java Agents to protect resources hosted on application or portal servers.

Although both agents enforce authentication and authorization to protected resources, they differ in the way they derive policy decisions and enforce them.

For examples of how to transition from on-premises access management to Advanced Identity Cloud without changing the architecture of the agent-based model, learn more in these guides:

Web Agent Example

Web Agent Guide for Advanced Identity Cloud

Java Agent Example

Java Agent Guide for Advanced Identity Cloud

Password policy

Configure a password policy in PingOne Advanced Identity Cloud when you want a customized rule for creating valid sign-in passwords. The password policy applies to end users who sign in to your registered apps within a realm.

You can configure only one password policy per realm.

By default, Advanced Identity Cloud password policy is set to the minimum security requirements established by the National Institute of Standards and Technology (NIST). Any changes you make to the password policy must conform to requirements contained in their guidelines. Learn more in NIST Digital Identity Guidelines.

Configure a password policy

  1. In the Advanced Identity Cloud admin UI, go to Security > Password Policy.

  2. Choose the realm the password policy will apply to.

  3. Edit password policy details.

    Password length

    When enabled, the policy requires a password with the specified minimum number of characters. No maximum.

    Cannot include

    Options to restrict the use of any of the following in the policy:

    • More than two consecutive characters (Example: aaaaaa)

    • Commonly-used passwords (Examples: qwerty or 12345678)

    • Values in certain user attributes. From the drop-down list, specify user attributes that cannot be used.

    Must contain

    When enabled, the policy requires the use of a specified 1–4 of the following:

    • Upper case letter

    • Lower case letter

    • Number

    • Space, pipe, or special character:
      ( ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { } ~ ) .

    Cannot reuse

    When enabled, the policy restricts the end user from reusing the specified number of previously set passwords.

    Force password change

    When enabled, the policy forcibly expires each end-user password after the specified number of days, months, or years have elapsed from when the password was set.

    To handle expired passwords in an end-user journey, use the Expired outcome in the Identity Store Decision node.

    Refer to the considerations in Force end-user password changes before using this policy setting.

  4. Click Save.

Force end-user password changes

You can combine a password policy and the Identity Store Decision node to expire end-user passwords in a journey; the Force password change policy setting lets you define an expiry time interval, which is measured for each end user from when their password was last set.

If you are introducing such a policy for the first time, you may want to process your end users in batches in order to improve messaging about the changes. The following sections describe two high-level strategies to achieve this.

If you are considering forcing your end users to change their passwords, review the NIST Digital Identity Guidelines. In particular, NIST no longer recommends scheduled password changes; learn more in Usability Considerations by Authenticator Type.

The NIST guidelines are continually refined, so you should keep them in mind when setting password policy.

Strategy 1: Target segments of end users

Adapt the end-user login journey to use dynamic groups or user properties to target a segment of end users to reset their password.

Advantage: You can segment users any way you like. For example, you may have a set of end users who could struggle with a password reset. You could add a property to each end user in the set and initially exclude end users with that property from a password reset. Then, at a later time, remove the exclusion when support is available for those end users.

Disadvantage: Creating new dynamic groups with large numbers of end users can incur a significant performance cost.

Strategy 2: Target oldest passwords first

Adapt the end-user login journey to target all end users to reset their password, but initially set a very long expiry time interval to target the oldest passwords first. Then periodically reduce the expiry time interval to eventually target all passwords.

Advantage: This strategy segments end users by the date of their last password reset. Additionally, end users with the oldest passwords are targeted first.

Password timestamps

Password timestamps let you view or query when a user password was last changed and when it is set to expire.

If you have this feature enabled, the following timestamp fields and properties are available:

Field name on the user page Property name in the managed object configuration

Password Last Changed Time

passwordLastChangedTime

Password Expiration Time

passwordExpirationTime [6]

To enable or check the status of the feature, learn more in Feature enablement.

Example query on passwordLastChangedTime
curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=passwordLastChangedTime%20ge%20%222024-01-01T21:22:06.274Z%22&_fields=_id"
{
  "result": [
    {
      "_id": "453a73a9-3f50-4b04-8115-f3915fd1dd89",
      "_rev": "fa876a46-82e6-4a11-a3f4-6b4919815ea4-5851"
    }
  ],
  ...
}

Journeys

PingOne Advanced Identity Cloud comes with pre-configured end-user journeys. A journey is an end-to-end workflow invoked by an end user or device. Advanced Identity Cloud provides templates for common end-user journeys; for example, account registration and sign-in.

You can use the Advanced Identity Cloud hosted pages theme editor to configure or modify the layout and appearance of journeys.

You can use the drag-and-drop journey editor to configure or modify the journey templates:

Authentication template

Use the Login authentication template to configure sign-in journeys.

User self-service templates

Use a self-service template to let end users manage their accounts or resolve simple password issues without having to engage a tenant administrator.

Custom journey

Start with a blank canvas when you want to build a custom journey, and drag and drop nodes from the nodes list.

Default end-user journey

The journey Advanced Identity Cloud displays to end users when they access a default webpage URL. For example, application webpages commonly display a sign-in link. When the end user clicks the link, the Login journey is invoked by default.

Set a default end-user journey as follows:

  • Set a new journey as the default:

    • In the Advanced Identity Cloud admin UI, click Journeys and New Journey.

    • On the New Journey page, enable the option Default journey for end users.

  • Set an existing journey as the default:

    • In the Advanced Identity Cloud admin UI, click Journeys to view the list of journeys.

    • Select a journey, and click and Set as default.

Device profiling support

Use the ForgeRock SDKs to create authentication journeys based on device context. Learn more in Configure device profiling authentication.

Scripting

Add JavaScript to a Scripted Decision node to customize the outcome of an authentication journey.

Use the auth scripting editor to do the following:

Authentication templates

Login

Create a basic Login journey for end users to authenticate and sign in to an app or service with a username and password.

  1. In the Advanced Identity Cloud admin UI, go to Journeys > Login.

  2. Hover over the journey schematic, and click Edit.

  3. Enter information for each node in the journey:

    Learn about all available nodes in Nodes for journeys.

  4. To test the journey, copy the Preview URL, and paste the URL into a browser using Incognito mode.

  5. When you’re satisfied with your journey, click Save.

Learn more about the Login journey in Login with self-service.

If you implement account lockout using the Account Lockout node, it creates a persistent lockout on user accounts. User accounts can be unlocked by a tenant administrator.

Advanced Identity Cloud also supports configurable persistent and duration account lockout. Learn more in Account lockout.

Device profiling

Use the ForgeRock SDK to create journeys that let inanimate objects authenticate based on device context. Cell phones and smartwatches are examples of devices that have their own identities. Device context provides Advanced Identity Cloud with information about how or where a device is used to authenticate.

For detailed instructions, learn more in Configure device profiling authentication.

User self-service templates

Registration

Create a registration journey to let end users create their own account for an app or service.

  1. In the Advanced Identity Cloud admin UI, go to Journeys > Registration.

  2. Hover over the journey schematic, and click Edit.

  3. Enter information for each node in the journey:

    Learn about all available nodes in Nodes for journeys.

  4. To test the journey, copy the Preview URL, and paste the URL into a browser using Incognito mode.

  5. When you’re satisfied with your journey, click Save.

Learn more about the Registration journey in User self-registration.

Progressive profile

Create a Progressive Profile journey to trigger a conditional event in the journey.

The default journey triggers a reminder to set preferences for receiving news and special offers. The reminder is displayed only if the end user logs in three times without selecting preferences. If the end user makes no selection, the reminder expires and is not displayed again. If the end user selects one or more options, the preferences get set in the end user’s profile.

  1. In the Advanced Identity Cloud admin UI, go to Journeys > Progressive Profile.

  2. Hover over the journey schematic, and click Edit.

  3. Enter information for each node in the journey:

    Learn about all available nodes in Nodes for journeys.

  4. To test the journey, copy the Preview URL, and paste the URL into a browser using Incognito mode.

  5. When you’re satisfied with your journey, click Save.

Learn more about the Progressive Profile journey in Progressive profile.

Update password

Create an Update Password journey to let end users change their passwords. End users may be required to change passwords at regular intervals or if a password is compromised.

  1. In the Advanced Identity Cloud admin UI, go to Journeys > Update Password.

  2. Hover over the journey schematic, and click Edit.

  3. Enter information for each node in the journey:

    Learn about all available nodes in Nodes for journeys.

  4. To test the journey, copy the Preview URL, and paste the URL into a browser using Incognito mode.

  5. When you’re satisfied with your journey, click Save.

Learn more about the Update Password journey in Password updates.

Reset password

Create a Reset Password journey to let end users change their existing passwords. End users typically reset their passwords when they’ve forgotten the password they set.

  1. In the Advanced Identity Cloud admin UI, go to Journeys > Reset Password.

  2. Hover over the journey schematic, and click Edit.

  3. Enter information for each node in the journey:

    Learn about all available nodes in Nodes for journeys.

  4. To test the journey, copy the Preview URL, and paste the URL into a browser using Incognito mode.

  5. When you’re satisfied with your journey, click Save.

Learn more about the Reset Password journey in Password reset.

Forgotten username

Create a Forgotten Username journey to let end users retrieve their username from their user account data.

  1. In the Advanced Identity Cloud admin UI, go to Journeys > Forgotten Username.

  2. Hover over the journey schematic, and click Edit.

  3. Enter information for each node in the journey:

    Learn about all available nodes in Nodes for journeys.

  4. To test the journey, copy the Preview URL, and paste the URL into a browser using Incognito mode.

  5. When you’re satisfied with your journey, click Save.

Learn more about the Forgotten Username journey in Username recovery.

Custom journeys

Create a custom journey when none of the ready-to-use templates suits your needs.

  1. In the Advanced Identity Cloud admin UI, click Journeys.

  2. Click + New Journey.

  3. Enter journey details:

    • Name: Name to display in the Journeys list.

    • Identity Object: Identifier for the user or device to authenticate.

    • (Optional) Description: Summarize end user interaction.

    • (Optional) Tags: For organizing journeys to make them easier to find.

  4. Click Create journey.

  5. Use the journey editor to create your custom journey.
    Drag nodes from the palette and arrange them on the blank canvas.

  6. Provide information for each node, and connect nodes.

    Learn about all available nodes in Nodes for journeys.

  7. To test the journey, copy the Preview URL, and paste the URL into a browser using Incognito mode.

  8. When you’re satisfied with your journey, click Save.

Deactivate journeys

Deactivate a journey to prevent end users using it to authenticate. If you deactivate it, you can reactivate it at any time.

For example, if you are building a new journey in your development environment and you need to run a promotion, you can deactivate the journey prior to the promotion so that there’s no risk of the journey being discovered and used by end users in your upper environments and potentially allowing insecure access. You can activate the journey in your development environment again after a promotion.

Ping Identity recommends you deactivate any default journeys not in use. Learn more in Deactivate unused or insecure journeys.

  1. In the Advanced Identity Cloud admin UI, go to Journeys to view the existing journeys list.

  2. Find the journey.

  3. Click its More () menu:

    • To deactivate the journey, choose Deactivate, then in the Deactivate Journey dialog, click Deactivate.

    • To activate the journey, choose Activate.

You can also deactivate and activate a journey using the More () menu in the journey editor.

Duplicate journeys

Duplicate a journey to preserve a template for future use. For example, if you are testing a journey, start with a duplicate. Give the duplicate journey a unique name.

Create a duplicate journey in the following ways:

  • Click Journeys to view the existing journeys list. Find the template name. Then, click its More () menu, and choose Duplicate.

  • In the Journey editor, click More (), and choose Duplicate.

Export journeys

You can export journeys, including all dependencies like nodes, inner journeys, and scripts of any type apart from library scripts.

Use this feature to export journeys from one environment, such as a development environment, to another.

  1. In the Advanced Identity Cloud admin UI, go to Journeys.

  2. Check the checkbox beside one more journeys.

  3. Click Export.

  4. View the information on the Export Journeys page.

  5. Click Export.

Import journeys

You can import journeys, including all dependencies such as nodes, inner journeys, and scripts, and scripts of any type apart from library scripts.

Use this feature to import a journey from one environment, such as a development environment, to another.

  1. In the Advanced Identity Cloud admin UI, go to Journeys, and click Import.

  2. Download or skip back up:

    • Download a backup of your existing journeys so that you can restore them in case of error or unexpected behavior during or after import:

      1. To view the backup summary, click Show backup summary.

      2. Click Download Backup.

    • Skip the download:

      1. Click Skip Backup.

      2. In the dialog box, click Skip Backup again.

  3. Configure the import:

    1. On the Import Journeys page, browse to and select a JSON file that contains the journey’s configurations to import.

    2. Select the identity object that the journey authenticates.

    3. In the Conflict Resolution section, choose how the system resolves import conflicts:

      • Overwrite all conflicts (default)

      • Manually pick conflict resolution

    4. Click Next.

    5. Review the information on the Import Summary page.

    6. Click Start Import.

    7. On the Import Complete page, click Done.

More information

Debug Advanced Identity Cloud end-user journeys

You can debug end-user journeys in your PingOne Advanced Identity Cloud development environment as you create them. By setting a journey to debug mode, you can view information stored in shared, transient, and secure state, as you navigate the journey. This lets you confirm that information is being passed correctly from node to node in the journey.

Enable debug mode

Enable debug mode to log debug information as you navigate a journey.

  1. In the Advanced Identity Cloud admin UI, go to Journeys, and select a journey.

  2. Hover over the journey schematic, and click Edit.

  3. In the journey editor, click the debug button idcloudui journeys buttons debug (on the top right of the toolbar). The Debug panel opens.

  4. In the Debug panel, enable Debug mode.

  5. Select Enable Debug Popup to display debug logs as you navigate the journey. Learn more in view debug information in a popup window.

  6. Click Save to save your journey with debug mode enabled.

  • Use debug mode only in your development environment.

  • Before promoting a journey to your staging environment, ensure that you have deactivated debug mode and saved the journey. Journeys that are in debug mode are clearly marked with a Debug label in the journey list view.

View debug information in a pop-up window

View debug log output in a separate pop-up window, as you navigate a journey.

  1. In the Advanced Identity Cloud admin UI:

    1. Enable debug mode.

    2. In the journey editor, copy the end-user journey URL from the Preview URL field (on the right, above the top toolbar).

  2. In a new incognito browser window (or a separate browser):

    1. Go to the end-user journey URL that you copied in the previous step.

    2. The browser window displays an initial debug step.

    3. If the browser blocks the pop-up window, unblock it:

    4. Refresh the browser window. The pop-up window should now appear.

    5. Arrange the windows so that they are both clearly visible.

    6. Navigate the journey in the browser window, and monitor the debug output for each step in the pop-up window.

Shared, transient, and secure state

Shared state

Used by nodes to store non-sensitive information required during the authentication flow.

Transient state

Used by nodes to store sensitive information that Advanced Identity Cloud encrypts on round trips to the client.

Secure state

Used by nodes to store decrypted transient state.

When debug mode is enabled, debug nodes are temporarily inserted between each journey node. Because debug nodes can change the state of node information, inserting them between journey nodes can cause a problems if a journey node expects to access node information in a specific state.

For example, if a journey node adds a password to secure state, and the following debug node reads that password from secure state, the password is moved to transient state. Then, if the next journey node expects the password to be in secure state, and tries to read it from there, an error occurs.

Advanced Identity Cloud identity schema

PingOne Advanced Identity Cloud uses a default identity schema to organize users, roles, assignments, groups, organizations, and applications. The following diagram shows the identity schema relationships:

idcloud identity schema

Learn more about the Advanced Identity Cloud identity schema in Summary of the identity schema.

You can customize the default identity schema to your business needs in the following ways:

  • Create custom attributes to store identity information specific to your business.

  • Create indexable custom attributes that let you search your identities and create customized segments.

  • Create organizations to structure your identities in a flexible and performant way.

For examples of customizing the Advanced Identity Cloud identity schema, learn more in Use cases for customizing the identity schema.

Summary of the identity schema

  • Users, roles, assignments, groups, organizations, and applications form the default identity schema. Their relationships are also part of the default schema.

  • Users are hybrid identity objects:

    • Their default attributes are explicitly defined in the schema, with indexes also explicitly defined for certain attributes.

    • You can add custom attributes to them. However, the attributes are stored in an unindexed JSON data structure.

    • If you need a custom attribute for a user to be searchable, use an indexed general purpose extension attribute instead of a custom attribute.

  • Roles, assignments, groups, and organizations are generic identity objects:

    • None of their attributes are explicitly defined in the schema, and instead they are entirely stored in an indexed JSON data structure.

    • You can add custom attributes to them, and they will also be indexed.

  • You can create custom identity objects. These custom identity objects are also generic. This means that they are entirely stored in an indexed JSON data structure.

  • Applications are also generic identity objects. However, you should not alter these in any way as they are reserved for modification by Ping Identity to support workforce use cases. You should not add custom attributes to them, repurpose their default attributes, or reconcile data into them.

  • Advanced Identity Cloud does not support adding additional relationships to the default schema. Instead, you can use organizations to create flexible, performant identity structures.

  • Advanced Identity Cloud does not support adding relationships to custom identity objects.

  • Advanced Identity Cloud does not support the modification of application identity objects.

  • Ping Identity recommends that you add no more than 12 custom attributes each to roles, assignments, groups, and organizations, as this can impact the performance of your tenant environments.

The following table summarizes the identity schema:

Identity object Type Indexes on default attributes? Indexes on custom attributes?

Users

Hybrid

Yes (where defined)

No

Roles
Assignments
Groups
Organizations

Generic

Yes (all)

Yes (all)

Applications

Generic

Yes (all)

n/a (customer modifications not supported)

Custom

Generic

n/a

Yes (all)

Use cases for customizing the identity schema

The following are examples of how you might customize the default schema to support a media service:

  • Add a custom attribute for membership level to user identities to support subscription-level access or rate limiting. For example, the membership levels might be "gold", "silver", and "bronze".

  • Add a custom attribute for registration level to user identities to support access to premium content or to support progressive profiling in journeys. For example, the registration levels might be "guest", "pending", and "registered".

  • Adapt a general purpose extension attribute to be a searchable user attribute for date of birth to support age-restricted access. Use the attribute to support delegated administration for different age segments, allowing separate users to administrate adults and children.

  • Create organizations to structure user relationships between family members to support parental control.

The following are examples of how you might customize the default schema to support workforce:

  • Add custom attributes for job code, department number, or cost center to user identities to support the automatic provisioning of birthright roles.

  • Add custom attributes for external ID and metadata to user identities to support synchronisation using System for Cross-domain Identity Management (SCIM).

Customize user identities

You can customize user identities by adding your own attributes. This lets you store more useful information about each user such as the user’s department, cost centers, application preferences, device lists, and so on.

Advanced Identity Cloud offers the following strategies to customize user identities:

Customize user identities using custom attributes

You can create new custom attributes directly on user identities. Custom attributes on user identities must be prefixed with custom_; for example, custom_department.

Advanced Identity Cloud does not support searching on user identity custom attributes, which can sometimes render an environment unresponsive. Instead, if you need to make a particular user identity attribute searchable, use an indexed extension attribute. Learn more in Customize user identities using general purpose extension attributes.

To create a user identity custom attribute:

  1. In the Advanced Identity Cloud admin UI, click Native Consoles > Identity Management.

  2. In the IDM admin UI, go to Configure > Managed Objects.

  3. Click Alpha_user or Bravo_user.

  4. Click + Add a Property. This scrolls the page to the bottom and automatically focuses on the Name input field.

  5. In the Name input field, enter a new attribute name prefixed with custom_; for example, enter custom_department.

  6. In the Label input field, optionally enter a display name for the new attribute.

  7. Click Save.

Customize user identities using general purpose extension attributes

You can use the general purpose extension attributes that already exist on user identities. These attributes are predefined as part of the default identity schema. The following extension attributes are indexed, so you can use them as searchable attributes:

  • Generic Indexed String 1–5

  • Generic Indexed Multivalue 1–5

  • Generic Indexed Date 1–5

  • Generic Indexed Integer 1–5

To use an extension attribute:

  1. In the Advanced Identity Cloud admin UI, click Native Consoles > Identity Management.

  2. In the IDM admin UI, go to Configure > Managed Objects.

  3. Click Alpha_user or Bravo_user.

  4. Find an extension attribute that has one of the following default labels:

    • Generic Indexed String 1–5 or Generic Unindexed String 1–5

    • Generic Indexed Multivalue 1–5 or Generic Multivalue String 1–5

    • Generic Indexed Date 1–5 or Generic Date String 1–5

    • Generic Indexed Integer 1–5 or Generic Integer String 1–5

      If you need to make the attribute searchable, make sure you use an indexed extension attribute.

  5. Click the pen icon () to edit the attribute.

  6. In the Readable Title input field, enter a custom label. For example, Department.

  7. Click Save.

Roles and assignments

Roles and assignments let you create an entitlements structure that fits the needs of each realm in PingOne Advanced Identity Cloud.

Identity architects usually build the entitlements structure, and may also use the native AM and IDM consoles to put more complex entitlements in place.

Once your entitlements structure is in place, you can use the Advanced Identity Cloud admin UI to:

  • Add new user profiles, device profiles, or roles

  • Add assignments to roles

  • Make changes to existing user profiles, device profiles, roles, or assignments

  • Provision identities with role-based permissions

Roles

Roles define privileges for user and device identities. Roles let you automatically update privileges in numerous identity profiles. All role members receive the same permissions you’ve defined for the role. When you change the privileges for that role, you change the permissions for all role members.

When you add a role to an identity profile, the user or device becomes a member of the role. A user or device can belong to many roles.

A role won’t work until you link it to at least one assignment. During the authorization process, Advanced Identity Cloud evaluates permissions based on:

  • Roles a user or device belongs to

  • Assignments attached to their roles

binaandsam2

Internal roles

Internal roles, also called authorization roles, control access to your identity platform. You use internal roles to authorize administrators to manage your tenant or identities contained in it.

External roles

External roles, also called provisioning roles, give users and devices the permissions they need to access apps and services. You use external roles to let employees access intranet applications. You can also use external roles to let your customers and their end users access web services and mobile apps in your tenant.

Assignments

You create an assignment when you want to give a user or device permission to access a resource they need to do a job. A resource might be any application or service, data contained in a document or a database, or a device such as a printer or cell phone.

An assignment won’t work without a role. A role-assignment relationship is not fully formed until you do two things:

Assignment linked to role

Link an assignment to a role. Advanced Identity Cloud grants the permissions defined in the assignment to all members of the linked role.

Assignment mapped to attribute

Map your tenant assignment to an attribute stored in an external system. An external system can be, for example, an intranet Reporting App with its own database of user accounts.

map2app2

In this illustration, Bina’s Accountant II role links to three assignments. During data store sync, Advanced Identity Cloud provisions her Reporting App user account based on assignment-attribute mappings:

Mapping From Assignment Attribute Mapping To Reporting App Description and Provisioning Outcome

Assignments: Reporting App

UserName

The mapping sets the value of Bina’s Name ("Bina Raman") in the UserName attribute in the Reporting App.

This gives Bina access to the app itself.

Assignments: Operations Reports

Reports: Operations

The mapping adds the value "Operations" to the Reports attribute in the Reporting App.

This gives Bina access to Operations reports in the Reporting App.

Assignments: Sales Reports

Reports: Sales

The mapping adds the value "Sales" to the Reports attribute in the Reporting App.

This gives Bina access to Sales reports.

You can create any number of assignments in your tenant. You can link an assignment to one or more external roles. You cannot link assignments to internal roles.

How provisioning works

When you add a user or device to a role, Advanced Identity Cloud updates the user or device profile with the role information. The update gives, or provisions, the user or device with the permissions that come with the role and its assignments.

Here’s a simple entitlement schema example:

Roles

Accountant-I
Accountant-II

Accountant-I Assignments

Reporting App
Operations Reports

Accountant-II Assignments

Reporting App
Operations Reports
Sales Reports

Sam and Bina are co-workers. Their identity profiles are provisioned with permissions based on the entitlements schema example.

  • Sam is a member of the Accountant I role.
    The Accountant I role assignments give Sam permission to use the Reporting app to access only Operations Reports.

  • Bina is a member of the Accountant II role.
    The Accountant II role assignments give Bina permission to use the Reporting app to access both Operations Reports and Sales Reports.

For a deep dive, learn more in the following documents:

Organizations

Create organizations in PingOne Advanced Identity Cloud when you want to group identities to suit your business needs.

For example, you can build an organization structure modeled after your brand hierarchy. This lets you control access to business applications with tailored login experiences. You can also use organizations to delegate user administration.

Organization use case

Here’s an example to help explain organization concepts. MightyBank is a conglomeration of independently-operated banks. MightyBank organizes its business units into two locales based on banking regulations associated with each locale. Within a business unit, each bank brand is a self-contained organization.

This diagram depicts MightyBank’s hierarchy of realms and organizations for identity management:

idcloudui concepts organizations hierarchy

MightyBank organized their Advanced Identity Cloud tenant similarly to their business units. The Alpha realm contains MightyBank identities in the Americas. The Bravo realm contains MightyBank identities in Europe, the Middle East, and Africa (EMEA). Identities represent all employees, contractors, partners, vendors, customers—anyone who conducts business for or with MightyBank.

Each organization in the hierarchy has a designated owner. An owner can create child organizations, or sub-organizations. Owners can also add administrators to their organizations and sub-organizations.

Organization administrators manage user identities within organizations. Administrators also delegate administration to individual users through roles and assignments.

Users who belong to an organization are known as members of the organization.

Top-level organizations

Only Advanced Identity Cloud tenant administrators can create top-level organizations. In this example, Sam Carter is an Advanced Identity Cloud tenant administrator. Sam has created a top-level organization in each realm.

Sam can view and manage all identities within both the Alpha and Bravo realms:

idcloudui concepts orgs sam alpha bravo realms

Sam delegates organization administration by setting up organization owners, who in turn set up organization administrators.

Owners

The main job of organization owners is to create organizations and sub-organizations. They also designate users, within the organizations they own, as administrators. Users who are authorized to manage identities within organizations are called organization administrators.

In this example, Sam designated Alma as owner of the top-level organization in the Alpha realm. Alma grouped identities into sub-organizations. One sub-organization contains Acme Bank identities. A second sub-organization contains MexBanco identities.

Alma is authorized to manage the MightyBank Americas organization, and all its sub-organizations.

idcloudui concepts orgs aspreckles realm

Organization owners can do the following, but only within the organizations and sub-organizations they own:

In this example, before Alma can add a user profile to the Acme Bank organization, the user must belong to MightyBank Americas, the parent organization. If a user doesn’t belong to the parent organization, then Alma can open the Acme Bank organization, and create a new user profile directly in the organization.

Administrators

The main job of organization administrators is to manage user identities within an organization or sub-organization.

In this example, Alma designated Barbara as the administrator for MightyAmericas. Barbara is authorized to manage all identities in the MightyAmericas organization, and in all of its sub-organizations.

Barbara then delegated administration to two employees in the Acme Bank organization, and two employees in the MexBanco organization. These delegated administrators share responsibility for managing identities.

idcloudui concepts orgs bjensen admin

Organization administrators can do the following, but only within the organizations they are authorized to manage:

In this example, before an administrator can add a user profile to the Acme Bank organization, the user profile must already belong to MightyBank Americas, the parent organization. If a user profile does not already belong in MightyBank Americas, then the administrator can open the Acme Bank organization and create a new user profile directly in the organization.

Each organization administrator can manage user profiles, but in only the organization they’re authorized to manage.

More information

Manage identities

A PingOne Advanced Identity Cloud tenant can contain data about people (such as employees, customers, or vendors) and devices (such as cell phones or printers), each of which has a unique combination of defining attributes. Advanced Identity Cloud stores these attributes in identity profiles.

In an identity profile, roles and assignments define the type and extent of access permissions given to users and devices. Advanced Identity Cloud uses roles and assignments to provision identity profiles with permissions.

For quick takes, learn more in About roles and assignments and How provisioning works. To view a list of tenant administrators, learn more in View the administrators list. To view realm settings, learn more in Realm settings.

Note that identity resources are grouped by realm. If you can’t find a resource, make sure that you’re looking in the right realm.

Users

A user is a person, such as a customer, employee, or vendor, whose identity profile is stored in a tenant. A user identity profile is also called a user profile.

For a deep dive into Advanced Identity Cloud user identities, learn more in Manage identities.

Create a user profile

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Users and New Alpha realm - User.

  3. On the New Alpha realm - User page, enter information for the user, and then click Save. For a list of user attributes, learn more in User identity attributes and properties reference.

Edit a user profile

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Users, and click on a username.

  3. Edit information for the user, and then click Save. For a list of user attributes, learn more in User identity attributes and properties reference.

Reset a user password

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Users, and click on a username.

  3. Click Reset Password.

  4. Enter a new password, and click Reset Password to save the new password.

Delete a user

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Users, and click on a username.

  3. At the bottom of the page, click Delete Alpha realm - User. The Delete operation cannot be undone.

Add an application to a user

When you add an application to a user, Advanced Identity Cloud automatically provisions an account for them in the target application.

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Users, and click a username.

  3. Click the Applications tab.

  4. Click + Add Application.

  5. On the Account Details page, in the Application drop-down field, select an application.

  6. Click Assign. Afterward, in the Users & Roles tab, the Assignment column shows the user has a Direct assignment to the application.

Manage trusted devices

To populate the Trusted Devices tab, add the Device Profile Collector node to your authentication journeys to collect end-user device information.

You can view and delete the list of trusted devices on a user account.

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Users, and click a username.

  3. Click the Trusted Devices tab to view a list of devices that the end user has used to log in to their account.

  4. Click a device from the list to open its Device Details modal window. The modal displays device information such as operating system and browser. The modal may also display location information for the device if the Device Profile Collector node is configured to collect it and if the end user consented to the information being collected by their browser.

  5. Choose one of the following options:

    • To close the modal, click Done.

    • To remove the device from the list of trusted devices:

      1. Click Remove device.

      2. In the Delete Device? modal window, click Delete.

Roles

For a quick take, learn more in Roles in this guide. For a deeper dive, learn more in Roles.

Create an external role

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha Realm - Roles and New Alpha realm - Role.

  3. On the role page, enter the following information for the role, and then click Next:

    • Name: Unique identifier to display in the roles list.

    • Description: String to describe the role, such as Sales.

  4. (Optional) Assign the role only to identities with specified attributes:

    1. On the Dynamic Alpha realm - role Assignment page, use the slider to create a conditional filter for the role.

    2. Use the choosers to specify conditions that an identity must meet.

    3. (Optional) Click Advanced Editor to create a query-based condition.

    4. Click Next.

  5. (Optional) Assign the role only at specified times:

    1. On the Time Constraint page, use the slider to enable a start and end date during which the role is active.

    2. Use the calendar, clock choosers, and time zone offset.

    3. Click Save.

Edit an external role

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha Realm - Roles, and click on a role name.

  3. Add managed assignments to the role:

    1. On the role page, click Managed Assignments and Add Managed Assignments.

    2. Select a managed assignment from the drop-down list, and click Save.

  4. Add members to the role:

    1. On the role page, click Role Members and Add Role Members.

    2. Select an identity from the members list.

    3. (Optional) Use the slider to assign the role only at specified times, and then add the dates, times, and timezone offset.

  5. Change the time constraints or conditions of a role.

    1. On the Internal Role page, click Settings.

    2. In Time Constraint or Condition, click Set Up to edit the parameters, and then click Save.

Add an application to a role

When you add an application to a role and then assign a user to the role, Advanced Identity Cloud automatically provisions the user in the target application.

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha Realm - Roles, and click on a role name.

  3. Click the Applications tab.

  4. Click + Add Application.

  5. On the Account Details page, in the Application drop-down field, select an application.

  6. Click Assign. Afterward, in the Users & Roles tab, the Assignment column shows the user has a Role-based assignment to the application.

Create an internal role

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. Click Internal Roles.

  3. Click + New Internal Role.

  4. In the New Internal role screen, enter role details:

    • Name: Unique identifier to display in the Roles list.

    • Description (optional): String that’s meaningful to your organization.
      Examples: Employee, Customers, Sales Department, and Europe.

  5. Click Next.

  6. To choose an identity object that the role should grant permissions to, on the Internal role Permissions dialog, choose an identity object.

  7. To add the identity, click Add.

  8. Set the permission for the identity:

    • View: Grant the identity object view access.

    • Create: Grant the identity object create access.

    • Update: Grant the identity object update access.

    • Delete: Grant the identity object delete access.

  9. To add another identity, repeat the above three steps.

  10. Click Next.

  11. To optionally assign a user to a role based on specific attributes, on the Dynamic Internal role Assignment screen:

    1. Enable A conditional filter for this role.

    2. Use the choosers and drop-down lists to specify conditions for assigning a user to a role.

    3. To create a query-based condition, click Advanced Editor, and edit the query code.

    4. Click Next.

  12. To assign a role on a temporary basis, on the Time Constraint screen:

    1. Enable Set a start and end date during which this role will be active.

    2. Use the calendar and date pickers to define when the role is in effect:

      • Specify the time zone to be used for the start date/time and end/date you specified. Choose a time zone relative to Greenwich Mean Time (GMT). GMT is the same as Universal Time Coordinated (UTC).

      • To view a worldwide list of offset times, click Time zones chart to calculate the offset time.

  13. Click Save.

Edit an internal role

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Internal Roles, and click on a role name.

    • To edit role details:

      1. Click the Details tab.

      2. Edit the Name field and possibly the Description field.

      3. Click Save.

    • To edit a privilege:

      1. Click the Privileges tab.

      2. Click a privilege.

      3. Edit the privilege details.

      4. Click Save.

    • To add a privilege:

      1. Click the Privileges tab.

      2. Click + Add Privileges.

      3. To choose an identity that this role should grant administration privileges to, use the drop-down list field to choose an identity object.

      4. To add the identity, click Add.

      5. Set the permission for the identity:

        • View: Grant the identity object view access.

        • Create: Grant the identity object create access.

        • Update: Grant the identity object update access.

        • Delete: Grant the identity object delete access.

      6. To add another identity, repeat the above three steps.

      7. Click Save.

    • To edit a member:

      1. Click the Members tab.

      2. Click a member.

      3. Edit the member’s information.

      4. Click Save.

    • To add a member:

      1. Click the Members tab.

      2. Click + Add Members.

      3. Use the drop-down field to choose a member.

      4. Click Save.

    • To set a start and end date for when the role is active:

      1. On the Internal Role page, click Settings.

      2. In the Time Constraint section, click Set Up.

      3. Enable Set a start and end date during which this role will be active.

      4. Set the time parameter fields.

      5. Click Save.

    • To set a conditional filter for the role:

      1. On the Internal Role page, click Settings.

      2. In the Condition section, click Set Up.

      3. Enable A conditional filter for this role.

      4. Set the condition fields.

      5. Click Save.

    • To use JSON to configure internal role details, privileges, and other information:

      1. On the Internal Role page, click Raw JSON.

      2. Edit the JSON sample.

For a deep dive into roles, learn more in Roles.

Assignments

For a quick take, learn more in Assignments. For a deep dive into roles and assignments, learn more in Use assignments to provision users.

Create a mapping

Before you create an assignment, make sure that you have a mapping, or create a mapping as described in this section.

A mapping specifies a relationship between an object and its attributes, in two data stores. Learn more in Resource mapping.

  1. In the Advanced Identity Cloud admin UI, go to Native Consoles > Identity Management. The Identity Management console is displayed.

  2. Click Create Mapping, and add a mapping using information from Configure mappings using the admin UI.

Create an assignment

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Assignments and New Alpha realm - Assignments.

  3. On the assignment page, enter the following information for the assignment, and then click Next:

    • Name: Unique identifier to display in the assignments list.

    • Description: String to describe the assignment, such as Sales reporting.

    • Mapping: Select a mapping to which the assignment applies.

  4. (Optional) Add an attribute to map to the target system. Learn more in provision an attribute in the target data store.

    1. On the Assignment Attributes page, click Add an Attribute.

    2. Select an attribute from the drop-down list, and enter a value for the attribute. The attribute-value pair is synchronized with user accounts in the target data store.

    3. (Optional) Click , and in the Assignment Operation window specify how Advanced Identity Cloud synchronizes assignment attributes on the target data store:

      • On assignment

        • Merge with target: The attribute value is added to any existing values for that attribute.

        • Replace target: The attribute value overwrites any existing values for that attribute. The value from the assignment becomes the authoritative source for the attribute.

      • On unassignment

        • Remove from target: The attribute value is removed from the system object when the user is no longer a member of the role, or when the assignment itself is removed from the role definition.

        • No operation: Removing the assignment from the user’s effectiveAssignments has no effect on the current state of the attribute in the system object.

  5. Click to add the assignment, and then click Save.

  6. (Optional) Add an event script.

    Groovy scripts are not supported.

    1. One the Alpha realm - Assignment page, click Add an event script.

    2. Choose whether to trigger the script on assignment or unassignment.

    3. Enter the script in the text box or upload it.

    4. (Optional) Define custom variables to pass to your script. To enter variables in JSON format, use the JSON slider.

    5. Click Save.

  7. (Optional) Add managed roles to the assignment

    1. On the Alpha realm - Assignment page, click the Manage Roles tab, and click Add Manage Roles.

    2. Select a managed role from the drop-down list, and click Save.

Edit an assignment

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Assignments and click on an assignment name.

  3. In the Details tab and Manage Roles tab, edit the assignment settings.

Organizations

For a quick take, learn more in Organizations.

Organizations can be managed in the following ways:

  • By tenant administrators, using the REST APIs:

    Before you can use the IDM REST APIs, you’ll have to get an access token and authenticate to the IDM API server. Learn more in Accessing the IDM REST APIs.

    For examples of API calls for organizations, learn more in Manage Organizations Over REST.

  • By tenant administrators, using the Advanced Identity Cloud admin UI as described on this page.

  • By organization owners and organization administrators, using the Advanced Identity Cloud end-user UI as described on this page.

Import identities into an organization

You can build organizations in different ways. For example, you can start with a parent organization that contains all user identities, and then build your organization hierarchy. Alternatively, you can start with a hierarchy of empty organizations, and then add users. Whatever approach you take, at some point you’ll have to import identities into an organization.

Tenant administrators Organization owners Organization administrators

Only tenant administrators can import identities into an organization.

For this example, it is assumed that the following items already exist:

  • A .csv file containing 100 user identities

  • A parent organization with no members

  1. In the Advanced Identity Cloud admin UI, go to Identities > Import.

  2. On the Bulk Import page, click New Import.

  3. On the Upload CSV page, select Alpha realm - Users, and then click Next.

  4. In the Upload CSV page, Enter the following information and then click Next:

    • CSV File: Browse to your file

    • Match Using: Add a property name to use for a unique record match

  5. When the Import Complete dialog box is displayed, and you can confirm that the import was successful, click Done.

    You can confirm the import in the following ways:

    • Go to Identities > Manage > Alpha realm - Users, and open any user profile. Click Organizations to which I Belong, and make sure that the organization you created is displayed.

    • Go to Identities > Manage > Alpha realm - Organizations, and make sure that the organization you created is displayed.

    • Click the name of the organization you created, click Members, and then make sure that all the imported user identities are displayed.

Create a parent organization

Tenant administrators Organization owners Organization administrators

Only tenant administrators can create a parent organization.

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Organizations and New Alpha realm - Organizations.

  3. On the New Alpha realm - Organizations page, enter a name for the organization. Uppercase, lowercase, alphanumeric, special characters, and white spaces are allowed.

  4. Click Save.

  5. In the organization page, change the name, add a description, or assign a parent organization. To designate this organization as the parent, leave the Parent Organization field blank.

  6. Click Save.

Create an organization owner

Tenant administrators Organization owners Organization administrators

Only tenant administrators can create an organization owner.

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  3. Click Owner and Add Owner.

  4. In the Add Owner page, select an identity from the drop-down list.

    Make sure that the organization owner is not also an organization member. This can result in giving the organization administrator greater control of the organization than its owner.

  5. Click Save.

Create an organization administrator

Tenant administrators Organization owners Organization administrators

  • Tenant administrators can create an organization administrator in any organization.

  • Organization owners can create organization administrators only within organizations or sub-organization where they are owner.

  • Organization administrators cannot create other organization administrators.

  1. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  2. Click Administrators and Add Administrators.

  3. In the Add Administrators page, select a user from the drop-down list. The user must already belong to the organization.

  4. Click Add Administrators. The username is displayed in the members list.

Create a sub-organization

Tenant administrators Organization owners Organization administrators

  • Tenant administrators can create sub-organizations within any organization.

  • Organization owners can create sub-organizations only within organizations or sub-organizations where they are owner.

  • Organization administrators can create sub-organizations only within organizations or sub-organizations where they are administrator.

Tenant administrators
Tenant administrators can view all organizations.

Follow the steps in to create a parent organization, and then set a parent organization that is:

  • An existing organization

  • One level of hierarchy higher than this child organization

Organization owners and organization administrators
Organization owners and organization administrators can view only the organizations and sub-organizations that they own or administrate.

  1. In the Advanced Identity Cloud end-user UI, go to Alpha realm - Organizations and New Alpha realm - Organizations.

  2. On the New Alpha realm - Organizations, page enter a name for the organization. Uppercase, lowercase, alphanumeric, special characters, and white spaces are allowed.

  3. Click Save.

  4. In the organization page, optionally change the name, and add a description.

  5. Assign a parent organization that is One level of hierarchy higher than this child organization.

  6. Click Save.

While privileges for default attributes are automatically included when setting up a sub-organization, custom attributes need to be manually added to your privileges configuration before creating the sub-organization.

Do this by adding the custom attribute to the accessFlags section of the owner-view-update-delete-orgs and owner-create-orgs privileges. These are accessed through the REST API at the /openidm/config/alphaOrgPrivileges or /openidm/config/bravoOrgPrivileges endpoints (depending on the realm you are updating).

Edit an organization or sub-organization

Tenant administrators Organization owners Organization administrators

  • Tenant administrators can edit any organization or sub-organization.

  • Organization owners can edit only organizations or sub-organization where they are owner.

  • Organization administrators can edit only organizations or sub-organizations where they are administrator.

Tenant administrators

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  3. In the organization page, change the name, add a description, or assign a parent organization.

    Uppercase, lowercase, alphanumeric, special characters, and white spaces are allowed in the organization name.

    To designate this organization as the parent, leave the Parent Organization field blank.

  4. Click Save.

Organization owners and organization administrators

  1. In the Advanced Identity Cloud end-user UI, go to Alpha realm - Organizations, and click on an organization name.

  2. In the organization page, change the name, add a description, or assign a parent organization.

    Uppercase, lowercase, alphanumeric, special characters, and white spaces are allowed in the organization name.

    To designate this organization as the parent, leave the Parent Organization field blank.

  3. Click Save.

Add or create organization members

Tenant administrators Organization owners Organization administrators

  • Tenant administrators can access all members of all organizations.

  • Organization owners can access only members of organizations they own.

  • Organization administrators can access only members in their administrative area.

Add a member to an organization
Tenant administrators

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  3. On the organization page, click Members and Add Members.

  4. Select an identity from the members list, and then click Save. The username or usernames you added are now displayed in the members list.

Organization owners and organization administrators

  1. In the Advanced Identity Cloud end-user UI, go to Alpha realm - Organizations.

  2. Follow steps in the tenant administrator instructions.

Create a new user profile in an organization
Tenant administrators

  1. Add a user profile, as described in Create a user profile.

  2. In the user profile, click Organizations to which I Belong and Add Organizations to which I Belong.

  3. In the add organization dialog box, choose one or more organizations from the drop-down list, and click Save.

Organization owners and organization administrators

  1. In the Advanced Identity Cloud end-user UI, go to Alpha realm - Users.

  2. Follow steps in the tenant administrator instructions.

Delete an organization

Tenant administrators Organization owners Organization administrators

  • Tenant administrators can delete any organization or sub-organization.

  • Organization owners can delete only organizations or sub-organizations where they are owner.

  • Organization administrators can delete only organizations or sub-organization where they are administrator.

Tenant administrators

  1. In the Advanced Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  3. On the organization page, click Delete Alpha realm - Organization.

    This operation cannot be undone.
Organization owners and organization administrators

  1. In the Advanced Identity Cloud end-user UI, go to Manage.

  2. Follow steps in the tenant administrator instructions.

Sync identities

Before you can sync identities with a remote server or use load balancing and failover in PingOne Advanced Identity Cloud, you must register a remote server with your tenant.

Connectors can read data in your tenant and in external resources (an app or service that runs on a server outside your tenant). Use connectors to convert your identity profiles, as well as user accounts in a resource server, into a format that both data stores can use.

Advanced Identity Cloud provides built-in connectors for synchronization with data stores in other cloud services.

Process overview

Before you can make a connection, you must register a remote connector server with your tenant. You also need to have a connector service up and running.

To configure connectors that aren’t built in to Advanced Identity Cloud, complete this list of tasks in order:

  1. Register a remote server.

  2. Change the client secret by resetting it.

  3. Download a remote server from Backstage.

  4. Install and configure a connector, if needed.

    You can also create a connector configuration over REST.

  5. Configure the remote server to connect to Advanced Identity Cloud (optional).

  6. Create a mapping between identities in Advanced Identity Cloud and identities in your identity resource server.

  7. If you plan to set up load balancing or failover, then register a remote server cluster (optional).

For troubleshooting advice, learn more in the knowledge base article How do I troubleshoot the Java Remote Connector Service (RCS)?.

Tasks

Task 1: Register a remote server

  1. To create a connector server in your development or sandbox[2] environments:

    1. In the Advanced Identity Cloud admin UI, go to Identities > Connect > Connector Servers.

    2. Click + New Connector Server.

    3. In the New Connector Server dialog box, provide the remote server details:

      • Name: This name is displayed in the Connector Servers list.
        Use only lowercase letters and numerals. No special characters or spaces are allowed.

    4. Click Save.

  2. To create a connector server in your UAT[3], staging, or production environments:

    1. Follow the instructions in step 1 to create a connector server in your development environment.

    2. Run a series of promotions to promote the connector server configuration from your development environment to your upper environments.

Task 2: Reset the client secret

RCSClient is a built-in OAuth 2.0 client shared by all connector servers in Advanced Identity Cloud. If you reset its client secret, you must update the configuration of all remote connectors configured to connect to the tenant environment.

  1. If you already know the client secret of the RCSClient, skip to Task 3: Download a remote server.

  2. In the Advanced Identity Cloud admin UI, go to web_asset OAuth2 Clients.

  3. Click RCSClient.

  4. Click Reset to change the client secret

  5. In the Reset Client Secret dialog box, enter a strong password.

  6. Read the warning, and then click Save.

Task 3: Download a remote server

You’re directed to the IDM Cloud Connectors download page. You must sign in to Backstage to view this page and download the connectors.

  1. Download the Remote Connector Server to the host that will run the connector server.

    Ping Identity recommends using the Java version of the Remote Connector Server. Only download the .NET version if you need to use a PowerShell connector. Learn about the differences between the RCS types in Install a Remote Connector Server (RCS).

    You can run the connector server on the same host as the identity resource server or you can run it on a different host. For example, you could run the connector server on a host that’s dedicated to only connectors.

  2. Configure the remote server.

Task 4: Install and configure a connector

If the connector you want to use is not bundled with the remote server you downloaded in Task 2, you’ll need these instructions. Follow the instructions in the ICF documentation to download and install the remote connector you need.

After you complete the Next Steps, click Done in the Next Steps window.

Task 5: Configure a remote server

  1. Unpack the OpenICF package you downloaded from the IDM Connectors download page.

  2. Edit the ConnectorServer.properties file.

    ConnectorServer.properties details:

    1. Add the OAuth2 Client credentials used to obtain an OAuth2 token. The client uses the Client Credentials grant type.

      • connectorserver.clientId=RCSClient
        Advanced Identity Cloud created this OAuth 2 client for you.

      • connectorserver.clientSecret=<client-secret>
        Use the OAuth 2 client secret you entered for RCSClient.

    2. Uncomment these settings and edit them for your tenant:

      • connectorserver.url
        This is the Advanced Identity Cloud OpenICF endpoint.
        Use wss over HTTPS so the client can obtain a bearer token through OpenID.

        • In staging and production environments, use three URLs in a space-delimited list. Example:
          connectorserver.url=wss://<tenant-env-fqdn>/openicf/0 wss://<tenant-env-fqdn>/openicf/1 wss://<tenant-env-fqdn>/openicf/2

        • In a development environment, use only one URL. Example:
          connectorserver.url=wss://<tenant-env-fqdn>/openicf/0

      • connectorserver.connectorServerName=<remote-server-name>
        This is the remote server name you set through the Advanced Identity Cloud admin UI. Be sure the name includes only lowercase letters and numerals. No special characters or spaces are allowed.

      • connectorserver.pingPongInterval=60
        The WebSocket Ping/Pong interval (seconds).

      • connectorserver.housekeepingInterval=20
        The WebSocket connections housekeeping interval (seconds).

      • connectorserver.groupCheckInterval=60
        WebSocket groups check interval, in seconds.

      • connectorserver.webSocketConnections=3
        Specifies the number of sockets the connector server establishes and maintains to each Advanced Identity Cloud (IDM) backend instance.

      • connectorserver.connectionTtl=300
        WebSocket connection’s time to live (seconds).

      • connectorserver.newConnectionsInterval=10
        Time between new connections (seconds).

      • connectorserver.tokenEndpoint=https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token
        Token endpoint to retrieve access token.

      • connectorserver.scope=fr:idm:*
        OAuth2 token scope.

      • connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog

      You don’t need to set the connectorserver.usessl property; the remote server determines connection security from the value of the connectorserver.url property.

  3. When you’re satisfied with your changes, save the file.

  4. Start the remote server on the OAuth 2.0 client:

    • Windows

    • Linux

    bin\ConnectorServer.bat /run
    bin/ConnectorServer.sh /run

  5. To verify the connection is working, view the remote server status in the Remote Servers list.

Task 6: Create a mapping

Create a mapping between identities in Advanced Identity Cloud and identities in your identity resource server.

  1. In the Advanced Identity Cloud admin UI, go to Native Consoles > Identity Management.

  2. In the IDM admin UI, click Create Mapping.
    For detailed information and instructions, learn more in Configure a resource mapping.

After you’ve tested your mapping configuration per the instructions, you can make connections for synchronizing and provisioning user profiles.

Task 7: Register a server cluster

This is optional. Use a cluster of remote servers when you want to set up load balancing or failover among multiple resource servers.

  1. In the Advanced Identity Cloud admin UI, go to Identities > Connect > Server Clusters.

  2. Click + New Server Cluster.

  3. Provide Server Cluster Details:

    • Name: Identifier to display in the Server Clusters list.

    • Algorithm:

      • Choose Failover if you want requests to be redirected to a designated server only when the primary server fails.

      • Choose Round Robin if you want to continuously load-balance among two or more servers regardless of service status.

  4. Click Next.

  5. In the Choose Servers dialog box, enable the connectors you want to include in the server cluster.

    Every connector associated with a server cluster must have an identical set of JAR files and scripts in its /path/to/openicf/lib directory. All JAR files must be at the same version. If you make any changes to the JAR files and scripts in this directory, you must propagate the changes to all the other connectors in the server cluster.

  6. Click Create Cluster.

Synchronize passwords

You can synchronize hashed user passwords from your PingDS deployment into Advanced Identity Cloud.

Password synchronization relies on an LDAP connector configured to synchronize accounts from your DS servers. Advanced Identity Cloud password synchronization does not use a password synchronization plugin. Instead, it synchronizes hashed passwords as strings in the same way it synchronizes other LDAP attributes.

This feature depends on having compatible one-way hash password storage schemes in Advanced Identity Cloud and in your DS password policies. DS servers in Advanced Identity Cloud verify user-provided plaintext passwords against the password hash, just as the DS servers in your deployment.

  1. Verify that your DS service stores the passwords you want to synchronize only with DS password storage schemes that are also enabled in Advanced Identity Cloud.

    The following DS password storage schemes are enabled in Advanced Identity Cloud:

    • Bcrypt

    • PBKDF2

    • PBKDF2-HMAC-SHA256

    • PBKDF2-HMAC-SHA512

    • Salted SHA-256

    • Salted SHA-512

    • SCRAM-SHA-256

    • SCRAM-SHA-512

  2. Verify that account synchronization works properly from your DS service to Advanced Identity Cloud.

    For example, modify a test user’s entry in your DS server and check that the corresponding account in Advanced Identity Cloud is updated correctly after reconciliation runs.

  3. In the native IDM admin UI, configure the LDAP connector to synchronize userPassword attributes as strings:

    1. Delete __PASSWORD__ from the list of LDAP connector properties.

    2. Add userPassword with Native type: string and Run as User enabled.

  4. In the native IDM admin UI, configure the mapping from your remote DS system resource to Advanced Identity Cloud managed users:

    1. Map userPassword in your remote DS system resource to password in managed users.

    2. Set the transformation script for the synchronization to the following inline script:

      // Set the text of DS userPassword as the value of the password:
if (source != null) {
  var base64 = Packages.org.forgerock.util.encode.Base64url;
  decodedTarget = new Packages.java.lang.String(base64.decode(source));
  target = decodedTarget;
}

  5. Verify that password synchronization is working correctly.

    For example, modify a test user’s password in your DS server, and check that the user can authenticate in Advanced Identity Cloud after reconciliation runs.

About Advanced Identity Cloud connectors

Apps and services that run and store data outside your tenant exist as external resources relative to Advanced Identity Cloud.

Advanced Identity Cloud provides connectors to synchronize your identity profiles with data stored in your resource servers.

Connectors work differently based on the capabilities of the connected resource server. For a summary of supported connectors and their capabilities, learn more in ICF documentation.

Syncing and provisioning

Here’s how Advanced Identity Cloud synchronizes user data. In this diagram, an identity resource server hosts an app and a data store containing user accounts. The resource server also hosts a connector server. The connector server runs a connector.

When you edit a user’s account on the resource server, the connector makes the change in the user’s profile in your tenant.

idcloud connector server

The opposite also happens. When you edit a user’s profile in your tenant, the connector makes the change in the user’s account in your resource server. For a quick take on Advanced Identity Cloud syncing and provisioning, refer to a related example in "Assignments".

Data reconciliation

Advanced Identity Cloud reconciles data when changes occur in your identity profiles or in user accounts stored in resource servers.

An Advanced Identity Cloud connector first compares an identity profile to its corresponding user account in the resource server. If conflicting information exists, Advanced Identity Cloud resolves the conflicts based on your preferences. Then Advanced Identity Cloud updates both the identity profile and the user account.

Load balancing and failover

Use a connector server cluster (a cluster of connector servers) when you want to set up load balancing or failover. A connector server cluster connects to multiple resource servers.

When you configure the connector server cluster for load balancing, Advanced Identity Cloud distributes incoming authentication or authorization requests among the clustered servers. The connector service determines where a request is directed. Request traffic flows evenly, and no single connector works faster or more slowly than others in the server cluster. This ensures requests are handled with the greatest efficiency.

When you configure connector servers for failover, if one resource server stops, then your Advanced Identity Cloud redirects requests to a standby resource server. This ensures your end users don’t experience a loss of service. When the stopped resource server restarts, Advanced Identity Cloud directs requests to the restarted server.

Deactivate the RCS OAuth 2.0 client

The RCS OAuth 2.0 client is activated by default. If you do not need to synchronize your tenant data using a connector, you can deactivate the client:

  1. In the Advanced Identity Cloud admin UI, go to OAuth2 Clients.

  2. Click RCSClient.

  3. Click check_circle Active, then select power_settings_new Inactive.

  4. The client is immediately deactivated.

If you deactivate the RCS OAuth 2.0 client, you can reactivate it at any time.

More information

For a deep dive, learn more in the following documents:

Bulk import identities

You can use a CSV file to bulk import identities into PingOne Advanced Identity Cloud. This is useful when you want to add a large number of identities to a role or assignment in a single operation.

Import identities in bulk

Before you begin:
You’ll need a CSV file containing the identity profiles you want to import. The file must comply with this CSV template example:

CSV template example 
{
  "_id": "template",
  "header": "\"userName\",\"givenName\",\"sn\",\"mail\",\"description\",\"accountStatus\",\"telephoneNumber\",
 \"postalAddress\",\"address2\",\"city\",\"postalCode\",\"country\",\"stateProvince\",\"preferences/updates\",
 \"preferences/marketing\""
}

Be sure to use commas as separators. Any other separator may cause errors.

Learn more about generating this file in Import bulk data.

  1. In the Advanced Identity Cloud admin UI, go to Identities > Import.

  2. On the Import Identities page, click + New Import.

  3. On the New Import dialog box, select the realm-target you want to import to.

    Tell me more

    The target can be any managed object such as a user, role, or assignment defined within a realm. For example, you could import ten user profiles to the Bravo realm - Roles target. The imported roles are added to the bravo_role managed object in Advanced Identity Cloud.

  4. Click Next.

  5. (Optional) If you haven’t already generated a CSV file, click CSV Template. to download an example file.

    If you use this file:

    • Replace the attributes in this file with attributes in your identity resource server.

    • Delete all unused attributes.

  6. Enter the name of the CSV file to upload.

  7. Choose a property Advanced Identity Cloud can use to match an entry in the CSV file to an identity profile in your realm-target.

    Tell me more

    For example, you could choose the username property. If username bjensen exists in your CSV file, Advanced Identity Cloud tries to verify that a user profile with the username bjensen also exists in your tenant. If verified, then Advanced Identity Cloud updates the entire bjensen user profile. If no match is found, then Advanced Identity Cloud creates a user profile for bjensen.

  8. Click Next.

    The Import Complete dialog box indicates real-time import progress. When the import is complete, Advanced Identity Cloud displays the number of new, updated, unchanged, and failed imports.

  9. (Optional) To download a CSV file containing a list of identity profiles that failed to import, click Download CSV.

  10. Click Done.

View or delete a CSV file

  1. In the Advanced Identity Cloud admin UI, go to Identities > Import.

  2. On the Import Identities list, find the filename.
    In the same row, click More ().

  3. Choose View Details or Delete.

Constrain identity queries in the UI

PingOne Advanced Identity Cloud lets you constrain queries in two ways when managing identities with the Advanced Identity Cloud admin UI:

Constraining how the Advanced Identity Cloud admin UI can be used can improve overall Advanced Identity Cloud performance because the constraints forbid queries that might inadvertently use a large amount of computing resources.

If you encounter slow or failed searches when searching for users in the IDM admin UI, refer to the knowledge base article Searching for users in the UI is very slow in Identity Cloud for troubleshooting ideas.

Require a minimum length search string

You can require Advanced Identity Cloud administrators to enter a minimum length string when querying identities using the Advanced Identity Cloud admin UI. This setting also disables sorting search results unless a minimum length string has been specified in the search box.

Applying this setting can speed up the time it takes to retrieve records from large identity data sets.

This setting only affects queries performed in the Advanced Identity Cloud admin UI. It does not affect Advanced Identity Cloud REST API queries.

To apply the setting:

  1. In the Advanced Identity Cloud admin UI, go to Identities > Configure to access the Configure Identities page.

  2. Click on an identity profile. For example, if you want to configure the UI for managing identities in the Alpha realm, click Alpha realm - User.

  3. Enter a number greater than zero in the Minimum Characters field.

  4. Click Save.

To verify that the setting is in effect:

  1. Go to Identities > Manage.

  2. Select the identity profile that corresponds to the one you configured when you applied the setting.

  3. Click one of the column titles at the top of the search results to attempt to sort the results.

    You should not be able to sort the results. Sorting by column should have been disabled.

  4. Specify a string in the Search field that has fewer characters than the minimum number of characters you specified in the profile’s configuration. Then, press Enter.

    The search operation should not be permitted.

  5. Specify a string in the Search field that has the minimum number of characters you specified in the profile’s configuration. Then, press Enter.

    The search operation should be permitted.

  6. Click one of the column titles at the top of the search results to sort the results.

    Sorting the search results should now be permitted.

Forbid sorting or searching resource collections

A resource collection is a set of identities that has a relationship with another identity. For example:

  • All the users with a particular role assignment

  • All the users who are members of an organization

You can forbid Advanced Identity Cloud delegated administrators from sorting resource collections and performing searches within resource collections in the Advanced Identity Cloud admin UI.

This setting only affects delegated administrators using the Advanced Identity Cloud end-user UI. It does not affect tenant administrators using the Advanced Identity Cloud admin UI.

To apply the setting:

  1. In the Advanced Identity Cloud admin UI, go to Identities > Configure to access the Configure Identities page.

  2. Click on an identity profile. For example, if you want to configure the UI for managing identities in the Alpha realm, click Alpha realm - User.

  3. Click the Disable sorting and searching on grids that use this object as a resource collection toggle.

  4. Click Save.

To verify that the setting is in effect:

  1. Log out of Advanced Identity Cloud.

  2. Log in to Advanced Identity Cloud as a delegated administrator.

  3. Select an identity profile that has a relationship with the profile you configured when you applied the setting.

    For example, if you disabled sorting and search for Alpha realm - User grids, then you could select Alpha realm - organization because organizations have members (which are users).

  4. Find the name of an organization for which you’re the delegated administrator.

  5. Click its More () menu, and choose Edit.

  6. Click Members to bring up the collection of users that are members of your organization.

  7. Click First Name to attempt to sort the identities by first name.

    Sorting the search results should not be permitted.

User identity attributes and properties reference

You may need to work with user identity attributes in PingOne Advanced Identity Cloud for the following reasons:

  • To customize the identity attribute display names shown in the user profile in the UI

  • To reference the identity attributes in scripts and API calls

The attribute and property names are not consistent between the underlying AM and IDM services. To address this, the reference tables depict the equivalent attribute.

Using the reference tables

  • If you write scripts for AM that access user profiles, then use AM attribute names. User profile script examples: OAuth2 access token modification; OIDC claims; decision node scripts for authentication journeys (trees).

  • If you write scripts for IDM that access managed objects, then use IDM property names. Managed object script examples: onUpdate, onCreate, onDelete, and so forth.

  • If you use APIs to access managed objects or user profiles:

    • Calls to /am APIs must use AM attribute names.

    • Calls to /openidm APIs must use IDM property names.

If you use the IDM admin UI to change the display name of a property, the change is reflected in both the IDM admin UI and the Advanced Identity Cloud admin UI; however, on the API side and in scripts, the generic names remain unchanged.

Reference tables

Basic user attributes

Display Name IDM Property AM Attribute

Username

userName

uid

Common Name

cn

cn

Display Name

displayName

displayName

Password

password

userPassword

Status

accountStatus

inetUserStatus

First Name

givenName

givenName

Last Name

sn

sn

Email Address

mail

mail

Description

description

description

Telephone Number

telephoneNumber

telephoneNumber

Address 1

postalAddress

street

City

city

l

State/Province

stateProvince

st

Postal Code

postalCode

postalCode

Country

country

co

Additional user attributes

Description IDM Property AM Attribute

Alias list

aliasList

iplanet-am-user-alias-list

Applications

applications

fr-idm-managed-application-member

Applications I Own

ownerOfApp

fr-idm-managed-application-owner

Assigned dashboard

assignedDashboard

assignedDashboard

Assignments

assignments

fr-idm-managed-assignment-member

Consented Mappings

consentedMappings

fr-idm-consentedMapping

Direct Reports

reports

manager

Manager

manager

fr-idm-managed-user-manager

Authorization Roles

authzRoles

not available[7]

Effective Assignments

effectiveAssignments

fr-idm-effectiveAssignment

Effective Applications

effectiveApplications

fr-idm-effectiveApplications

Effective Groups

effectiveGroups

fr-idm-effectiveGroup

Effective Roles

effectiveRoles

fr-idm-effectiveRole

Groups

groups

fr-idm-managed-user-groups

Last Sync timestamp

lastSync

fr-idm-lastSync

KBA

kbaInfo

fr-idm-kbaInfo

Preferences

preferences

fr-idm-preferences

Profile image

profileImage

labeledURI

Provisioning Roles

roles

fr-idm-managed-user-roles

Organizations I Administer

adminOfOrg

fr-idm-managed-organization-admin

Organizations I Own

ownerOfOrg

fr-idm-managed-organization-owner

Organizations to which I Belong

  • memberOfOrg

  • memberOfOrgIDs

  • fr-idm-managed-organization-member

  • fr-idm-managed-user-memberoforgid

Password Last Changed Time

passwordLastChangedTime

pwdChangedTime

Password Expiration Time

passwordExpirationTime

pwdExpirationTime

Task Proxies[8]

taskProxies

n/a

Task Principals[8]

taskPrincipals

fr-idm-managed-user-task-principals
Description IDM Property AM Attribute

Notifications

_notifications

fr-idm-managed-user-notifications

Revision

_rev

etag

User Metadata

_meta

fr-idm-managed-user-meta

UUID

_id

fr-idm-uuid

General purpose extension attributes

Strings
Display Name IDM Property AM Attribute

Generic Indexed String 1

frIndexedString1

fr-attr-istr1

Generic Indexed String 2

frIndexedString2

fr-attr-istr2

Generic Indexed String 3

frIndexedString3

fr-attr-istr3

Generic Indexed String 4

frIndexedString4

fr-attr-istr4

Generic Indexed String 5

frIndexedString5

fr-attr-istr5

Generic Unindexed String 1

frUnindexedString1

fr-attr-str1

Generic Unindexed String 2

frUnindexedString2

fr-attr-str2

Generic Unindexed String 3

frUnindexedString3

fr-attr-str3

Generic Unindexed String 4

frUnindexedString4

fr-attr-str4

Generic Unindexed String 5

frUnindexedString5

fr-attr-str5
Multivalues
Display Name IDM Property AM Attribute

Generic Indexed Multivalue 1

frIndexedMultivalued1

fr-attr-imulti1

Generic Indexed Multivalue 2

frIndexedMultivalued2

fr-attr-imulti2

Generic Indexed Multivalue 3

frIndexedMultivalued3

fr-attr-imulti3

Generic Indexed Multivalue 4

frIndexedMultivalued4

fr-attr-imulti4

Generic Indexed Multivalue 5

frIndexedMultivalued5

fr-attr-imulti5

Generic Unindexed Multivalue 1

frUnindexedMultivalued1

fr-attr-multi1

Generic Unindexed Multivalue 2

frUnindexedMultivalued2

fr-attr-multi2

Generic Unindexed Multivalue 3

frUnindexedMultivalued3

fr-attr-multi3

Generic Unindexed Multivalue 4

frUnindexedMultivalued4

fr-attr-multi4

Generic Unindexed Multivalue 5

frUnindexedMultivalued5

fr-attr-multi5
Dates
Display Name IDM Property AM Attribute

Generic Indexed Date 1

frIndexedDate1

fr-attr-idate1

Generic Indexed Date 2

frIndexedDate2

fr-attr-idate2

Generic Indexed Date 3

frIndexedDate3

fr-attr-idate3

Generic Indexed Date 4

frIndexedDate4

fr-attr-idate4

Generic Indexed Date 5

frIndexedDate5

fr-attr-idate5

Generic Unindexed Date 1

frUnindexedDate1

fr-attr-date1

Generic Unindexed Date 2

frUnindexedDate2

fr-attr-date2

Generic Unindexed Date 3

frUnindexedDate3

fr-attr-date3

Generic Unindexed Date 4

frUnindexedDate4

fr-attr-date4

Generic Unindexed Date 5

frUnindexedDate5

fr-attr-date5
Integers
Display Name IDM Property AM Attribute

Generic Indexed Integer 1

frIndexedInteger1

fr-attr-iint1

Generic Indexed Integer 2

frIndexedInteger2

fr-attr-iint2

Generic Indexed Integer 3

frIndexedInteger3

fr-attr-iint3

Generic Indexed Integer 4

frIndexedInteger4

fr-attr-iint4

Generic Indexed Integer 5

frIndexedInteger5

fr-attr-iint5

Generic Unindexed Integer 1

frUnindexedInteger1

fr-attr-int1

Generic Unindexed Integer 2

frUnindexedInteger2

fr-attr-int2

Generic Unindexed Integer 3

frUnindexedInteger3

fr-attr-int3

Generic Unindexed Integer 4

frUnindexedInteger4

fr-attr-int4

Generic Unindexed Integer 5

frUnindexedInteger5

fr-attr-int5

Overview

PingOne Advanced Identity Cloud end users experience and regularly interact with user interfaces (UIs) and user self-service capabilities.

Advanced Identity Cloud provides different UI customization options depending on the needs of your organization.

Advanced Identity Cloud end users can manage their own data, reset their password, retrieve their username, and more. The robust capabilities of Advanced Identity Cloud allows you to customize the end user screens, the applications they have access to, and the data they have access to. Configure user self-service journeys by defining journeys and configuring the information end users can access, manage, and the actions they can take.

End-user UX options for authentication journeys and account management

When you integrate your applications with PingOne Advanced Identity Cloud, you must provide your end users with a UX (user experience) that handles authentication journeys and account management.

Advanced Identity Cloud provides these end-user UX options:

wysiwyg
Advanced Identity Cloud hosted pages

Use Advanced Identity Cloud’s built-in and fully-featured UIs with no development work.
widgets
ForgeRock Login Widget

Use a widget to integrate authentication journeys easily into your client-side JavaScript web applications.
developer_mode
ForgeRock SDKs

Use SDKs for web, Android, or iOS applications. Integrate the SDK into Advanced Identity Cloud using the REST API.
api
Advanced Identity Cloud REST API

Build your own custom UIs without any Ping Identity prebuilt components and integrate with Advanced Identity Cloud REST API.

The options are not mutually exclusive, and you may need a combination of them to meet your company’s requirements. For a quick take on which option is most suitable for you, learn more in Compare end-user UX options.

UX options

Advanced Identity Cloud hosted pages

Advanced Identity Cloud hosted pages provide OOTB UIs for the following:

  • End-user authentication journeys, such as login, registration, and password reset

  • End-user account activities, such as managing profile information, viewing application access, and viewing roles and entitlements

This is the most straightforward end-user UX option since all the necessary capabilities are readily available.

The UI layouts are fixed but can be themed per realm. You can add company logos and change button, link, and background colors. The UIs support web applications but not native applications.

Hosted pages are useful if you have limited theming needs or want to quickly try new registration or authentication flows without integrating them into an application.

This UX option only lets you use centralized journey flows in your applications, with embedded journey flows not supported. Specifically, Ping Identity does not support embedding hosted pages in HTML frames.

This is the only UX option that supports SAML journey flows that use Advanced Identity Cloud as the IDP.

Learn more in Advanced Identity Cloud hosted pages.

ForgeRock Login Widget

The ForgeRock Login Widget provides an OOTB UI for end-user authentication journeys, such as login, registration, and password reset. It does not provide a UI for account management.

The Login Widget is low-code and framework-agnostic; it can be initiated with a few lines of code and can be easily integrated into any modern JavaScript application. It does not currently support server-side rendering (SSR), including Node.js.

The Login Widget provides OOTB support for localization, social login, WebAuthn, passkey, device profile, token management, and compliance with WCAG standards. It is highly themeable and customizable with CSS and Javascript.

Learn more in Ping Identity Login Widget.

ForgeRock SDKs

The ForgeRock SDKs let you develop your own custom UI for web, Android, or iOS applications. You then integrate it with your Advanced Identity Cloud tenant using the REST API.

Each SDK provides an OOTB UI module that allows you to prototype your custom UI; however, it is only provided as a starting point, and it is not intended for production use.

This option offers a lot of flexibility if you want to customize the behavior, layout, and theming of the UI, or want to support Android and iOS applications. Using it requires a higher level of technical skill than the previous options.

SDKs can use centralized and embedded journey flows.

Learn more in ForgeRock SDKs.

Advanced Identity Cloud REST API

The most flexible UX option is to build your own custom UIs and integrate with the Advanced Identity Cloud REST API. However, this is also the most complex and time-consuming UX option, as you need to build everything yourself without any Ping Identity prebuilt components.

In addition, you will also need deep identity implementation experience, including an understanding of how to securely store tokens locally.

Learn more in Advanced Identity Cloud REST API.

Ping Identity Platform login and end-user UIs (deprecated)

Ping Identity no longer recommends or supports this UX option due to the complexity of configuring the distributable packages. For a quick take on alternative options, learn more in Compare end-user UX options.

Ping Identity also provides the hosted pages UIs as distributable packages, known as the platform login and end-user UIs. You can self-host one or both of the UIs and configure them to use your Advanced Identity Cloud tenant.

This UX option offers flexibility if you want to customize the layout of the UIs or customize the theming beyond what the hosted pages provide. The UIs support web applications but not native applications.

This UX option also lets you use both centralized and embedded journey flows in your applications.

For background information about the platform end-user and login UIs, learn more in Platform UIs.

Compare end-user UX options

For background on UX options in PingOne Advanced Identity Cloud, learn more in End-user UX options for authentication journeys and account management.

Compare development effort against flexibility

The choice of end-user UX option is a balance between development effort and flexibility; the more flexible the option, the more complex and time-consuming it is to develop and implement:

ux options development effort against flexibility

Compare specific features

More specifically, the end-user UX option you choose will be based on a combination of these features:

Feature Hosted pages Login Widget SDKs APIs

OOTB end-user authentication journey UI

Yes

Yes

No

No

OOTB end-user authentication journey support

Yes

Yes

Yes

No

OOTB end-user account management UI

Yes

No

No

No

Hosted by

Ping Identity

You

You

You

Theming

Limited

No limitation

No limitation

No limitation

Web application (browser)

Yes

Yes

Prototype UI only

Can be developed

Native applications (Android, iOS)

No

No

Prototype UI only

Can be developed

Localization

Yes

Yes

N/A

Can be developed

Centralized journey flow

Yes

No

Yes

Can be developed

Embedded journey flow

No

Yes

Yes

Can be developed

SAML supported

Yes

No

No

Can be developed

CAPTCHA supported

Yes

Yes

Yes

Can be developed

QR codes supported

Yes

Yes

Yes

Can be developed

WebAuthn supported

Yes

Yes

Yes

Can be developed

Passkey supported

Yes

Yes

Yes

Can be developed

Device profile supported

N/A

Yes

Yes

Can be developed

Token management supported

No

Yes

Yes

Can be developed

WCAG compliance

Not always 100%

Yes

No

Can be developed

Social login

Yes

Apple, Facebook, Google only

Apple, Facebook, Google only

Can be developed

Include third-party CSS and JS

No

Yes

Yes

Can be developed

End-user UX journey flows

Journey flows define the sign-on experience for end users. The End-user UX options available in PingOne Advanced Identity Cloud offer two journey flows:

Not every end-user UX option supports both centralized and embedded journey flows. Learn more in Compare end-user UX options for more information.

Centralized journey flows

Centralized journey flows redirect end users to an external page to sign in. This is a common experience for most users. This approach is considered the security best practice for Advanced Identity Cloud, ensuring all your applications and websites can share the same, centralized authentication processes.

An example of a centralized journey flow is Google G Suite, where an end user is redirected to the same authentication page no matter which application they’re trying to access.

The following video shows a centralized journey flow with ForgeRock SDKs:

Use the hosted pages and the SDK end-user UX options to implement centralized journey flows.

Embedded journey flows

Embedded journey flows offer a more traditional sign-on experience, as end users are not redirected to an external page.

Embedded journey flows aren’t considered to be a security best practice for the following reasons:

  • Individual applications have access to end user’s credentials.

  • Individual applications have access to the authorization grant.

  • Each application must manually build in security during the sign-on process.

The following video shows an embedded journey flow with ForgeRock SDKs:

Use the Login Widget and the SDK end-user UX options to implement embedded journey flows.

Advanced Identity Cloud hosted pages

PingOne Advanced Identity Cloud hosts its own UI pages, referred to as hosted pages, that you can use in journeys and the Advanced Identity Cloud end-user UI. You can use these pages to quickly create and test common end-user self-service operations.

Advanced Identity Cloud offers two types of hosted pages:

  • Hosted account pages — Pages for end-user account management, shown after a login journey.

  • Hosted journey pages — Pages for end-user login journeys.

In the following example, the sign-in page was created using a hosted journey page. Barbara Jensen’s account page was created using a hosted account page.

600

Not only do these hosted pages support localization, but you can use themes to customize their look and feel to meet the branding guidelines of your organization.

Deactivate hosted account pages

Hosted account pages are activated by default. If you deactivate them, you can reactivate them at any time.

You can use the ForgeRock SDKs or APIs to create and host your own custom account pages. If you do this, Ping Identity recommends that you deactivate the hosted account pages to ensure there is no risk of unauthorized access to end-user profile information by a malicious user.

Hosted account pages can be deactivated independently from hosted journey pages.

When you deactivate the hosted accout pages, Advanced Identity Cloud displays the following web page to unauthorized end users:

450

After deactivating the default end-user profile, you can still use the hosted end-user journey UI while denying unauthorized access to end-user profiles. Your customers manage only their own profiles or delegate administration using your application.

Afterward, all hosted pages associated with your tenant are deactivated.

  1. In the Advanced Identity Cloud admin UI, open the TENANT menu (upper right), and go to Tenant Settings > Global Settings.

  2. Click End User UI.

  3. On the End User UI page, do one of the following:

    • To activate hosted pages, beside Hosted Account Pages, click Activate. The Global Settings toggle displays the status as Active.

    • To deactivate hosted pages, beside Hosted Account Pages, click Deactivate. The Global Settings toggle displays the status as Inactive.

The change takes effect immediately.

When you deactivate hosted pages, all hosted pages associated with your tenant are deactivated.

Deactivate hosted journey pages

You can use the ForgeRock SDKs or APIs to create and host your own custom journeys. If you do this, Ping Identity recommends that you deactivate the hosted journey pages to ensure there is no risk of unauthorized access to the login, registration, or password reset pages by a malicious user.

Hosted journey pages can be deactivated independently from hosted account pages.

When you deactivate the hosted journey pages, Advanced Identity Cloud displays the following web page to unauthorized end users:

450
450

After you deactivate the default hosted journey pages, you can still administer the tenant environment while preventing unauthorized access to default journey information.

For an explanation about how hosted pages integrate with the default journey, learn more in Journeys.

Other resources

Learn how to customize and use hosted pages:

  • Customize login and end user pages - Customize the look and feel of the login (journey) pages. This includes logos, headers, footers, the layout of the overall page, and the actions and information your end users have access to in the Advanced Identity Cloud end-user UI.

  • Localize login and end-user pages - Support different languages in the UI with localization.

  • End-user pages - Explore an example of a journey and the Advanced Identity Cloud end-user UI screens that display to end users (depending on the configuration).

Customize login and end-user pages

If you choose to present pages to end users by selecting the hosted pages UI integration option, customize the PingOne Advanced Identity Cloud provided pages with themes.

Themes let you customize the look and feel of login and Advanced Identity Cloud end-user UI pages, including the information presented to end users and the actions they can take when logged into the Advanced Identity Cloud end-user UI.

Notes on themes:

  • Advanced Identity Cloud realms have a default theme that includes the colors of buttons and links, typefaces, and so on. This default theme applies to the end-user and login UIs. You can add custom themes so that your end users are presented with screens specific to their authentication journey.

  • Custom themes let you create a different look and feel for each brand that you support, including logos, favicon, headers, footers, scripted tags, and the actions and information end users can see in the Advanced Identity Cloud end-user UI.

  • A theme is followed throughout an authentication journey. This means that if a user logs in through the Login UI with a specific theme, the remaining pages in the journey will have that same theme.

custom theme overview

Add a custom theme

In the Advanced Identity Cloud admin UI:

  1. Select Hosted Pages > + New Theme.

    Duplicate an existing theme by clicking next to the theme you want, then select Duplicate.

  2. Enter a theme name that describes the theme’s purpose; for example, the brand associated with an authentication journey.

  3. Use the tabs and options to customize various aspects of the theme:

    Tab Option What you can customize

    Global

    Styles

    You can customize:

    • Brand Colors — This includes colors for buttons, checkboxes, switches, high-level alert actions, and success actions.

    • Typography — The font applied to all journeys and customer-facing pages.

    • Buttons — The colors of buttons and their radius.

    • Links — The color of links, including when you hover over them and the option to bold all links.

    • Switches — The background color.

    Favicon

    Favicon logo displayed for all journey and account pages. You can localize the favicon. Learn more in Localize the favicon and theme logo.

    Settings

    The theme name and any journey(s) using this theme.

    From this screen, you can select journeys to apply to your theme.

    Journey Pages

    Styles

    You can customize:

    • Page Background — This includes the color of the journey background as well as a background image (optional).

    • Sign-in Card — The sign-in card is where end users enter their credentials. This includes the card colors, field colors, card shadow, border radius, and if the input text labels should sit above or in the input field.

    • Global Styles — These are the styles you set in the Global tab. Modifying this section from the Journey Pages updates the Global tab styles.

    Logo

    Logo to display on sign-in and registration pages. The displaying of the logo is optional. You can localize the logo. Learn more in Localize the favicon and theme logo.

    Layout

    This includes:

    • Layout — The position of the sign-in card on the page.

    • Button Position — The position of the button inside the sign-in card.

    • Header and footer: Place a header above or a footer below the sign-in card.

    • Error Heading Fallback — Turn off the error heading that displays as a fallback if there is no heading in the page content.

    • Remember Me — Add a checkbox to the sign-in card that lets end users choose to have their username remembered and prepopulated. If checked, the UI stores an end-user’s username in local storage after their next sign-in attempt.

      The optional Label field lets you specify a custom label to display to the end user to replace the default label of Remember Me.

    • Scripted Tags — Add HTML scripted tags to journey pages.

    • Focus First Form Item — Focus the first form input or button on each journey step.

    Account Pages

    Styles

    This includes customizing the colors of:

    • The left end-user Navigation pane.

    • The Top Bar where the user logs out.

    • The Page Styles that present user information.

    • The Cards that are contained within the page that display various information.

    • Global Settings — These are the styles you set in the Global tab. Modifying this section from the Account Pages updates the Global tab styles.

    Logo

    Logo to display on customer-facing pages

    Layout

    This includes:

  4. Configure the new theme as the default theme for the realm:

    The default theme is the theme that’s used when you don’t apply a specific theme to an authentication journey.

    1. From the Advanced Identity Cloud admin UI, go to Hosted Pages.

    2. From the list of themes, click the ellipsis (…​).

    3. Click Set as Realm Default.

To localize the favicon or theme logo:

  1. On the Global, Journey Pages, or Account Pages tabs, click the Favicon or Logo tabs from the right pane.

  2. Click the favicon or logo .

  3. Click + Specify a Locale.

  4. In the Locale field, enter the ISO 639-1 (2 letter country code) for the language. For example, for French the value would be fr.

  5. Click Add.

  6. In the Favicon URL field or the Logo URL field, enter the URL for the favicon or logo.

    The images must be publicly accessible.

  7. To set alternative text for the logo, in the Alt Text field, enter alternate text.

  8. Click Update.

  9. Click Save.

Apply a custom theme to a journey

In the Advanced Identity Cloud admin UI:

  1. Select Journeys.

  2. Select the journey to apply the custom theme.

  3. Click Edit.

  4. Click ... > Edit Details.

  5. Select Override theme.

  6. Select the custom theme that you want to apply to this journey, then click Save.

Theme definitions and the mappings between authentication journeys and themes are stored in Advanced Identity Cloud as configuration objects. They are therefore "static" in terms of Advanced Identity Cloud promotion. If you add a new theme or logo, your change must go through the promotion process. Theme selection can be dynamic, however. If you set a theme in a page node during a journey, for example, by setting stage var themeID=myTheme, that theme is applied dynamically for the remainder of the journey.

Custom headers and footers

Each theme lets you configure localized custom headers and footers:

Header Footer

Journey pages

Account pages

n/a

Headers and footers can take HTML or inline CSS to insert links, classes, and other elements. Scripting isn’t supported in headers and footers.

The account footer is separate from the journey footer. This lets you set up different buttons, links, and other elements, that display to an end user after they log in.

Enable headers and footers for a theme

  1. In the Advanced Identity Cloud admin UI, go to Hosted Pages, then select a theme.

  2. Select either Journey Pages or Account Pages.

  3. In the panel on the right-hand side, click Layout.

    1. Find the Header section (journey pages only), then enable the switch.

    2. Find the Footer section, then enable the switch.

Edit headers and footers

  1. Follow the steps above to find the appropriate Header or Footer section, then click the preview to open the editor.

  2. If you do not need localized content, edit the HTML as appropriate, then go to step 4.

  3. If you need localized content:

    1. Add as many locales as you need. Learn more in Localize headers and footers.

    2. Use the locale selector to change locales, and edit the HTML in each locale as appropriate.

  4. Click Save.

Localize headers and footers

  1. Follow the steps above to find the appropriate Header or Footer section, then click the preview to open the editor.

  2. To add an initial locale for the existing header or footer content:

    1. Click + Specify a Locale to open a secondary modal.

    2. In the Add a Locale secondary modal, enter a locale identifier; for example, fr (French), or fr-ca (French - Canada).

    3. Click Add to add the locale and close the secondary modal.

    4. The + Specify a Locale link will now be replaced by a locale selector, with the new locale preselected.

  3. To add an additional locale:

    1. Click the locale selector, then click + Add Locale to open a secondary modal.

    2. In the Add a Locale secondary modal, enter a locale identifier; for example, es (Spanish), or es-ar (Spanish - Argentina).

    3. Click Add to add the locale and close the secondary modal.

    4. The new locale will now be available in the locale selector, and be preselected. The header or footer content for the new locale will be a copy of the header or footer content from the initial locale.

    5. Translate the header or footer content for the new locale.

  4. Repeat step 3 for as many locales as you need.

  5. Click Save.

Configure actions and information for end users

Login UI

You can configure the following self-service features to control the actions and information displayed to end users in the Identity Cloud Login UI:

Configure terms and conditions

Configure the terms and conditions your end users must accept before they can complete a registration journey. Learn more in Terms and conditions.

Configure the external resources your end users can choose to share their data with. Learn more in Privacy and consent.

Configure security questions

Configure the security questions your end users answer during a registration journey and can later use during a reset journey to verify their identity. Learn more in Security questions.

End User UI

You control the information that is displayed and the actions end users can take from the Advanced Identity Cloud end-user UI.

The information and actions are broken out into the following sections:

Configure visible information and end-user actions

Your end users can only see the information and take actions that you configure.

To configure the information users can see and the actions they can take:

  1. From the Advanced Identity Cloud admin UI, go to Hosted Pages.

  2. Select a theme or click + New Theme.

    If you create a new theme, enter a Name for the theme and click Save.

  3. Select Account Pages from the top tabs. This refers to the Advanced Identity Cloud admin UI pages.

  4. In the tabs displayed in the right pane, select Layout.

  5. The Profile Information section dictates the actions and information end users can see. Select or deselect any of the following:

    Profile page component Description

    Personal Information

    Enable to allow the end user to view their attributes and update them. The attributes that display depend on settings at the property level. Learn more in Configure properties end users can view and update.

    Sign-in & Security

    Enable any of the following:

    • Password — Allow end users to update their password. Uses an existing session. This correlates to the default journey UpdatePassword.

      To change the journey used for password updates:

      1. From the Advanced Identity Cloud admin UI, select Native Consoles > Access Management.

      2. From the left navigation pane, click Services.

      3. Select Self Service Trees.

      4. In the updatePassword field, enter the name of the journey.

      5. Click Save Changes.

    • Security Questions — Allows end users to reset their security questions on their profile.

    • 2-step verification — If an end user has registered a device for two-factor/MFA, this option displays as enabled.

      If enabled, an additional Change button displays to end users. End users can select this button to rename their device(s) or delete their device(s) from Advanced Identity Cloud.

    Social Sign-In

    Allows end users to view the social providers that have authenticated with, such as Google or FaceBook.

    For details on letting end users connect to social providers from their profile page, learn more in Social authentication. After you configure social providers and create the journey, add it as the connectSocial journey for the realm:

    1. From the Advanced Identity Cloud admin UI, select Native Consoles > Access Management.

    2. From the left navigation pane, click Services.

    3. Select Self Service Trees.

    4. Add a connectSocial field whose value is the name of the journey.

    5. Click Save Changes.

    Trusted Devices

    Lets end users view the devices that have been used to log in to their account. End users can update the name of the device.

    To populate the Trusted Devices tab, add the Device Profile Collector node to your authentication journeys to collect end-user device information.

    Authorized Applications

    Allows end users to view and manage the applications that have access to their personal information.

    Preferences

    Allows end users to view and set preferences for communication. For example, an end user can select if they would like to receive emails regarding special offers and services.

    Consent

    Allows end users to view and manage how their data is shared with third parties.

    Account Controls

    Allows end users to download the data Advanced Identity Cloud has about them in a JSON format and allows end users to delete their account (identity) information.

  6. Click Save.

Configure properties end users can view and update

When an end user logs into the Advanced Identity Cloud end-user UI and selects Profile > Edit Personal Info, their profile data in Advanced Identity Cloud displays.

When you enable end user’s personal information from the theme, all the Advanced Identity Cloud properties are marked as User Editable. This means that end users can view and update most of their data in Advanced Identity Cloud. However, you may or may not want users to see all of their data.

For example, if you are not using all the properties available to you in Advanced Identity Cloud to store data for your end users, you might want to hide the unused properties for your end users, to decrease confusion and clutter.

To disable user properties from displaying to an end user, follow these steps:

  1. From the Advanced Identity Cloud admin UI, select Native Consoles > Identity Management.

  2. Select Configure > Managed Objects from the top tabs.

  3. The user object to update, such as Alpha_user or Bravo_user.

  4. From the Properties tab, select the property to modify.

  5. From the properties screen, under the Details tab, select Show advanced options.

  6. Disable the User Editable radio button.

  7. Click Save. The property is now hidden from the end user.

  8. Repeat steps 5-7 for every property you want to hide from the end user.

The following example shows:

  1. The Description property being visible to the Advanced Identity Cloud end-user UI.

  2. Going to Native Consoles > Identity Management and disabling the User Editable field for the Description property.

  3. Going back to the Advanced Identity Cloud end-user UI, refreshing the page, and showing that the Description property no longer displays to the end user.

Use script tags in Advanced Identity Cloud end-user and login UIs

You can include script tags in Advanced Identity Cloud end-user and login UIs to integrate third-party scripts such as customer analytics.

  1. In the Advanced Identity Cloud admin UI, go to Hosted Pages, then select a theme.

  2. Select either Journey Pages or Account Pages.

  3. In the panel on the right-hand side, click Layout.

    1. Find the Script Tags section.

    2. In the HTML field, enter your script code. The following example adds a script for the OneTrust cookie consent service:

      <script type="text/javascript" charset="UTF-8" src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" data-domain-script="<account-id>"></script>(1)
<script type="text/javascript">
  function OptanonWrapper() {};
</script>
      1 In this example, <account-id> needs replacing with a OneTrust account ID.

    3. Click Save.

  4. Update the tenant’s Content Security Policy:

    • If the tenant has an active report-only policy, update it by adding the domain of the third-party script to the script-src policy directive.

    • If the tenant has an active enforced policy, update it by adding the domain of the third-party script to the script-src policy directive.

    Learn more in Configure CSP to let hosted pages use a script from an external domain.

Localize login and end-user pages

PingOne Advanced Identity Cloud lets you localize login and end-user pages to support the different languages of your end users. Use ISO-639-1 language codes (for example fr and de) to provide locale specific content in as many locales as you need.

Localize at feature level

You can localize the following features related to journey and account pages:

Feature Description

Hosted pages

Learn more in Localize headers and footers and Localize the favicon and theme logo.

Security questions

Learn more in Security questions.

Terms and conditions

Learn more in Terms and conditions.

Email templates

Learn more in Email templates.

Localize journey authentication nodes

You can individually localize authentication nodes that display content in journey pages. For example, the Page node lets you add content to the Page Header property to display an initial journey message to end users. You can define as many localized versions of the message as you need:

ui journeys page node page header modal

Localize at UI level

You can localize static content and server messages in the login and end-user UIs using translation configuration. Learn more in Configure tenant localization.

End-user pages

If you choose hosted pages as your UI integration option, PingOne Advanced Identity Cloud provides an end-user UI for your end users.

The Advanced Identity Cloud end-user UI gives users various options, such as updating their profiles and accessing information. The end-user UI pages vary, depending on how you configure the UI, and on which Advanced Identity Cloud capabilities you have purchased.

The Advanced Identity Cloud end-user UI exposes personal information. Deactivate the Advanced Identity Cloud end-user UI if:

  • You do not want personal information exposed.

  • You’re using ForgeRock SDKs.

  • You’re using your own APIs to create custom web pages.

End-user menu items

end user screens

  • 1 Default navigation menu items.

  • 2 Additional navigation menu items displayed with purchase of Identity Governance.

This page is a reference. The menu items may or may not be present depending on what has been enabled or purchased.
Menu item Description

Dashboard

Dashboard that shows tasks and information that requires an end user’s attention.

Inbox

List of actions for the end user to take.

My Applications

List of applications the end user has access to. Users can click on applications in the list to navigate to them using SSO.

My Access

Access end users have in applications and in Advanced Identity Cloud.

This includes:

  • Accounts from onboarded target applications

  • Roles they’re assigned in Advanced Identity Cloud

  • Entitlements or privileges they have in onboarded target applications

My Directory

Delegates and direct reports (employees) end users have.

End users can perform the following actions:

  • Manage their delegates. Delegates are individuals that are assigned to their access reviews.

  • Access their direct reports and the access granted to them.

My Requests

End users can create requests to access resources, such as target applications, entitlements, or roles.

Profile

Profile page where end users can manage their information.

When this menu item is selected, additional sections appear that allow end users to take the following actions:

  • Manage their profile information

  • Reset their password

  • Manage devices end users have registered for an additional factor on sign-on

  • Access the social providers they have used to sign on with, such as Google or Facebook

  • Access the devices they have signed on with

  • Manage applications to which they have granted access to their personal information

  • Manage communication preferences

  • Manage the consent they have given on how their data is shared with third-parties.

  • Download and delete their account

The actions on this page vary depending on the configurations set in Configure actions and information for end users.

Sign on as an end user

The way your end users sign on can differ based on your Advanced Identity Cloud configuration.

For example, an end user can embed the sign-on URL on a portal page or associate it with a button.

The appearance of the end user pages, including branding and color, changes according to the theme settings you configure.

To sign on to the Advanced Identity Cloud end-user UI for a realm:

  1. Access the Login journey using one of the following URL formats:

    • If you are using the tenant domain, use one of these URL formats, replacing <realm> with the value alpha or bravo:

      • Full URL format:

        https://<tenant-env-fqdn>/am/XUI/?realm=<realm>&authIndexType=service&authIndexValue=Login

      • Shortcut URL format:

        https://<tenant-env-fqdn>/enduser/?realm=<realm>

    • If you are using a custom domain, use one of these URL formats:

      • Full URL format:

        https://<custom-domain-fqdn>/am/XUI/?authIndexType=service&authIndexValue=Login

      • Shortcut URL format:

        https://<custom-domain-fqdn>/enduser/

  2. Enter sign-on credentials.

  3. Click Next. The end user is signed on to the Advanced Identity Cloud end-user UI.

Dashboard

The dashboard provides a list of items that require end users' attention. For example, if Identity Governance is enabled, items that require an end user’s review appear here. If nothing requires an end user’s attention, an Edit Your Profile button displays that links to the profile.

To access the dashboard:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click Dashboard.

Inbox

The Inbox[9] section lists all items assigned to an end user. For example, if an end user is assigned an access review, items display for the user to act on.

To access the inbox:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click Inbox.

Approvals

The Approvals[9] section lists approval items (submitted access requests) for an approver (designated owner) to act on.

If an approver has delegates assigned, then the approval items are also assigned to the delegates.

To view approval tasks:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click Inbox > Approvals.

Learn more in Review request items (End user UI).

Access reviews

The Access Reviews[9] section lists the access reviews assigned to a certifier (individual assigned to review the access).

If a certifier has delegates assigned, then the access reviews are also assigned to the delegates.

To view access review tasks:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click Inbox > Access Reviews.

Learn more in Certify data using access reviews.