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 SaaS-based digital identity and access management (IAM) solution designed for workforce, consumer, and B2B identities. Ping Identity handles the deployment, management, upgrades, and monitoring of the platform’s various software components, ensuring a seamless and secure experience.

With 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. To find answers to common questions, create a support case, access training, and more, visit the Ping Identity Support Portal.

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.

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 Ping SDKs to set up authentication.

  7. Set up a login end-user journey.

Admin consoles

PingOne Advanced Identity Cloud provides three admin consoles to help you manage your tenant:

idcloudui admin consoles

① Advanced Identity Cloud admin console
② AM native admin console
③ IDM native admin console

Advanced Identity Cloud admin console

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

AM and IDM native admin consoles

These are secondary consoles, 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 console.

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

AM native admin console

Use to register SAML 2.0 applications, for example.

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

IDM native admin console

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 console, 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:

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.

Canada

Region Abbreviation Backup region

Montréal (northamerica-northeast1)

nane1

A different region within Canada.

United States

Region Abbreviation Backup region

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.

Brazil

Region Abbreviation Backup region

São Paulo (southamerica-east1)

sae1

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

Europe

Region Abbreviation Backup region

Finland (europe-north1)

en1

A different region within Europe.

Belgium (europe-west1)

ew1

A different region within Europe.

London (europe-west2)

ew2

A different region within Europe.

Frankfurt (europe-west3)

ew3

A different region within Europe.

Netherlands (europe-west4)

ew4

A different region within Europe.

Zurich (europe-west6)

ew6

A different region within Europe.

Paris (europe-west9)

ew9

A different region within Europe.

Middle East

Region Abbreviation Backup region

Dammam (me-central2)

mec2

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

Asia

Region Abbreviation Backup region

Singapore (asia-southeast1)

ase1

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

Jakarta (asia-southeast2)

ase2

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

Hong Kong (asia-east2)

ae2

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

Australia

Region Abbreviation Backup region

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.

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

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

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

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

    environments with uat

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

    environments with uat and uat2

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

Set up tenant administrators

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

You can set up additional tenant 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[1] and UAT[2] 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[1] environments)

    • April 18, 2023 (development, UAT[2], 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[1] environments)

    • May 10, 2022 and April 18, 2023 (development, UAT[2], 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, 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[1] environments)

  • April 18, 2023 (development, UAT[2], 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[1] environments)

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

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

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

  2. Click Create a case.

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

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

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Configuration

    What version of the product are you using?

    Select NA

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

    Field Value

    Provide a descriptive title for your issue

    Enter Enable outbound static IP addresses

    Describe the issue below

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

  6. Click Submit.

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

Tenant environment release information

Advanced Identity Cloud tenant environments each provide the following information about their status in the release process:

  • The current release version for that environment. This is available in all tenant environments.

  • The date and time of the next scheduled regular channel release to that environment. This is available in tenant environments that share promoted configuration (development, UAT[2], staging, and production).

    You can only view information about the next scheduled release using the API.

View release information using the admin console

The easiest way to view the release versions of your tenant environments is to use the admin console.

In the Advanced Identity Cloud admin console in any tenant environment, choose one of the following:

  • Open the TENANT menu (upper right), then go to settings Tenant Settings > Details. The release version is displayed under Identity Cloud Version.

  • Scroll to the bottom of a page. The release version is displayed in the page footnotes.

    The admin console does not display page footnotes in editors. For example, in the journey or hosted pages editors.

View release information using the API

You can use the API to view release information about your tenant environments. You might want to do this for these reasons:

  • To create monitoring alerts when release information changes.

  • To track the release information of your tenant environments in a single dashboard.

  • To track the seven-day deferral period for the next regular channel release to your production environment (if you’ve opted in to release deferral).

Release API endpoint

Advanced Identity Cloud provides the Release API endpoint to let you track release information.

Authenticate to the release API endpoint

To authenticate to the release API endpoint, use an access token created with the following scope:

Scope Description

fr:idc:release:*

Full access to the release API endpoint.

View release information

To view the release information in any tenant environment:

  1. Get an access token created with the fr:idc:release:* scope.

  2. Get the release information from the /environment/release endpoint:

    $ curl \
--request GET 'https://<tenant-env-fqdn>/environment/release' \(1)
--header 'Authorization: Bearer <access-token>' (2)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token.

  3. The response format depends on the type of tenant environment:

    • For sandbox[1] environments:

      Show response 
      {
    "currentVersion": "15374.0", (1)
}
      1 The current release version of the tenant environment.

    • For environments that share promoted configuration (development, UAT[2], staging, and production):

      Show response 
      {
    "currentVersion": "15158.7", (1)
    "nextUpgrade": "2024-10-29T14:00:00Z" (2) (3)
}
      1 The current release version of the tenant environment.
      2 The date and time of the next scheduled regular channel release to the tenant environment.
      3 If you have opted in to release deferral, nextUpgrade shows a date and time in your production environment that reflects your seven-day deferral period.

Tenant settings

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

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

View tenant details

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

Yes

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

    150

  2. Click Tenant Settings.

  3. Click Details.

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

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

      • Other
        Indicates a sandbox[1] environment.

      • Dev
        Indicates a development environment.

      • UAT
        Indicates a UAT[2] environment.

      • Staging
        Indicates a staging environment.

      • Prod
        Indicates a production environment.

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

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

Invite and view tenant administrators

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

No

No

Yes

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

Manage federated access

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

No

No

Yes

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

Access global settings

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

Yes

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

  2. Click Tenant Settings.

  3. Click Global Settings.

Tenant administrator settings

Tenant administrator groups

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

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

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

    • Invite tenant administrators.

    • Grant super administrator privileges to tenant administrators.

    • Revoke super administrator privileges from tenant administrators.

    • Enable federated access for a tenant.

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

  • Tenant auditor: Users in this group are tenant administrators with read-only permissions. They can access the same settings, configuration, and data as a tenant administrator but cannot modify them.

The tenant provisioning process initially creates a single super administrator.

Register to access a tenant admin console

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

Yes

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

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

  2. Perform one of the following sets of steps:

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

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

      2. Click Next.

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

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

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

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

      2. Enter your credentials and log in.

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

Sign on to a tenant admin console

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

Yes

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

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

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

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

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

Edit your own tenant administrator profile

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

Yes

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

    access admin profile

  2. On your tenant administrator profile page:

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

    • In the Sign-in & Security card:

      • To change your username, click Update.

        • Enter your current password, then click Next.

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

      • To change your password, click Reset.

        • Enter your current password, then click Next.

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

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

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

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

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

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

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

Invite tenant administrators

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

No

No

Yes

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

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

    tenant menu

  2. Click Invite admins.

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

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

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

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

View the tenant administrators list

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

No

No

Yes

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

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

  2. Click Tenant Settings > Admins.

    • To invite a new tenant administrator:

    • To deactivate a tenant tenant administrator:

      • Find a tenant administrator with the label Active.

      • Click More (), and select Deactivate.

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

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

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

Unlock a tenant administrator’s account

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

No

No

Yes

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

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

  2. Click Tenant Settings > Admins.

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

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

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

Modify a tenant administrator’s group

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

No

No

Yes

To modify a tenant administrator’s group

  1. Go to Tenant Settings > Admins.

  2. Click a tenant administrator.

  3. In the Group section, click Edit.

  4. On the Edit Group page:

    • To grant super administrator access, select Super Admin.

    • To grant tenant administrator access, select Tenant Admin.

    • To grant tenant auditor access, select Tenant Auditor.

      ui federation edit group access

  5. Click Save.

Manage tenant administrator 2-step verification

Tenant auditors[3] Tenant administrators Super administrators[4]

Action allowed?

Yes

Yes

Yes

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

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

  • ForgeRock Authenticator
    Lets you register the following authenticator applications:

    • The ForgeRock Authenticator app.

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

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

Register for 2-step verification

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

idcloudui tenant administrator set up 2 step verification

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

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

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

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

Manage verification codes

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

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

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

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

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

Change 2-step verification options

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

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

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

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

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

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

ESVs

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

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

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

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

Variables

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

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

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

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

Context How to reference Access as soon as set

Configuration placeholders

&{esv.my.variable}

Learn more in Configure placeholders to use with ESVs.


(requires restart)

Scripts

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

Learn more in Use ESVs in scripts.


(requires restart)

Variable expression types

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

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

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

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

string

String value (default)

Name

esv-email-provider-from-email

Placeholder

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

Value

bjensen@example.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:

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

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

ESV API endpoints

Advanced Identity Cloud provides these API endpoints for ESVs:

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 created with one of the following scopes:

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.

Service account access tokens granted the fr:idm:* scope also have access to API endpoints under the fr:idc:esv:* scope. However, this behavior is deprecated.

Manage ESVs using the admin console

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

Create variables

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

  2. Click the Variables tab.

  3. Click + Add Variable.

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

    Name

    Enter a variable name. Learn more in ESV naming.

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

    Type

    Select a variable expression type.

    Description

    (optional) Enter a description of the purpose of the variable.

    Value

    Enter a variable value.

    If the variable value is JSON, you can optionally click the JSON toggle to turn on JSON validation. You can find the toggle above the top right of the field.

  5. Click Save to create the variable.

Update variables

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

  2. Click the Variables tab.

  3. Find a variable in the paginated list of variables, then click + Update for that variable.

  4. In the Update Variable modal window:

    • At the top, you can optionally click Add a Description to update the variable description:

      1. Click the Add a Description link to open a secondary modal.

      2. In the Edit Variable Description secondary modal window, enter the following information:

        Description

        Enter a new or updated description of the purpose of the variable.

      3. Click Save Description to update the variable description and close the secondary modal.

    • Below that, you will see the read-only Configuration Placeholder field. The placeholder value is derived from the variable name. You can optionally use the clipboard widget to copy the placeholder value.

    • Below that, you can optionally click Edit to update the variable value:

      1. Click the Edit link to open a secondary modal.

      2. In the Edit Variable Value secondary modal window, enter the following information:

        Value

        Enter a new variable value.

        If the variable value is JSON, you can optionally click the JSON toggle to turn on JSON validation. You can find the toggle above the top right of the field.

      3. Click Save Value to update the variable value and close the secondary modal.

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

  5. Click Done to close the modal.

Delete variables

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

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

  2. Click the Variables tab.

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

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

Create secrets

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

  2. Click the Secrets tab.

  3. Click + Add Secret.

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

    Name

    Enter a secret name. Learn more in ESV naming.

    Secret names cannot be modified after the secret has been created.

    Description

    (optional) Enter a description of the purpose of the secret.

    Value

    Enter a secret value.

    The field obscures the secret value by default. You can optionally click the visibility toggle () to view the secret value as you enter it.

    If the variable value is JSON, you can optionally click the JSON toggle to turn on JSON validation. You can find the toggle above the top right of the field.

    The initial secret value is used to create the first secret version for the secret.

  5. Click Save to create the variable.

Update secrets

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

  2. Click the Secrets tab.

  3. Find a secret in the paginated list of secrets, then click + Update or Updated for that secret.

  4. In the Update Secret modal window:

    • At the top, you can optionally click Add a Description to update the secret description:

      1. Click the Add a Description link to open a secondary modal.

      2. In the Edit Secret Description secondary modal window, enter the following information:

        Description

        Enter a new or updated description of the purpose of the secret.

      3. Click Save Description to update the secret description and close the secondary modal.

    • Below that, you will see the read-only Configuration Placeholder field. The placeholder value is derived from the secret name. You can optionally use the clipboard widget to copy the placeholder value.

    • Below that, you will see the secret versions interface, which shows a paginated list of secret versions for the secret:

      idcloudui esv secrets manage versions

      Learn more about the rules for enabling, disabling, and deleting secret versions in Secret versions.

      1. To add a new secret version, click + New Version to open a secondary modal.

      2. In the Create a New Secret Version secondary modal window:

        1. At the top, you will see the readonly Secret field, which contains the secret name.

        2. Below that, enter the following information:

          Value

          Enter a secret value.

          The field obscures the secret value by default. You can optionally click the visibility toggle () to view the secret value as you enter it.

          If the variable value is JSON, you can optionally click the JSON toggle to turn on JSON validation. You can find the toggle above the top right of the field.

        3. Then, click the + Add Version button to create the secret version and close the secondary modal.

      3. The new secret version should now be visible at the top of the the secret versions interface:

        idcloudui esv secrets manage versions updated

      4. Click Done to close the modal.

Delete secrets

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

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

  2. Click the Secrets tab.

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

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

Apply updates

When one or more ESVs have been created or updated by any of the tenant administrators, the ESV entry screen displays a banner at the top to tell you how many updates are waiting to be applied:

idcloudui esv apply updates banner
Before you apply any updates, ensure that you have made all the ESV changes that you need, as applying the updates will disable ESV management in the admin console for the next 10 minutes and prevent further ESV changes. This behavior will apply to all tenant administrators.

To apply any pending updates:

  1. Click the View Updates button in the update banner.

  2. In the Pending Updates modal, review the list of ESVs that have been updated, then click Apply n Updates.

  3. In the Apply n Updates? confirmation modal, click Apply Now.

  4. The banner will change color from blue to orange while the updates are applied, and ESV management in the admin console will be disabled. This behavior will apply to all tenant administrators.

    idcloudui esv apply updates banner in progress

  5. When the update is complete, the banner will no longer be visible, and ESV management in the admin console will be enabled again.

Use ESVs in scripts

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

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

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

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

AM scripts

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

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

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

IDM scripts

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

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

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

Use ESVs for signing and encryption keys

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

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

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

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

Secret labels

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

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

Secret labels with fixed names

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

Secret labels with identifiers

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

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

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

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

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

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

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

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

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

Learn more in Authenticate OAuth 2.0 clients.

Map ESV secrets to secret labels

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

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

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

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

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

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

    2. Create the ESV secret:

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

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

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

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

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

    Secret Label

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

    aliases

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

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

  6. Click Create.

Rotate keys in mapped ESV secrets

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

idcloudui esv secrets manage versions rotation

Version 4

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

Version 3 and version 2

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

Version 1

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

Rotate SAML 2.0 certificates using ESVs

Generate an RSA key pair

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

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

    $ openssl genrsa -out private-key.pem

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

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

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

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

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

    1. Encode the key pair into base64:

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

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

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

Generate an AES or HMAC key

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

  1. Run the following command:

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

    Summary of command:

    • Generates a random number using /dev/urandom

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

    • Encodes the truncated random number into base64 using openssl

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

    1. Encode the key into base64 again:

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

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

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

Configure placeholders to use with ESVs

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

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

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

Set up configuration placeholders to reference an ESV

  1. In your development environment:

    1. Create the ESV using one of the following:

    2. Restart Advanced Identity Cloud services.

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

  2. In your staging environment:

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

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

  3. In your production environment:

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

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

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

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

Update an ESV referenced by a configuration placeholder

  1. Update the ESV using one of the following:

  2. Next, Restart Advanced Identity Cloud services.

Restart Advanced Identity Cloud services

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

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

Delete an ESV referenced by a configuration placeholder

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

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

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

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

Define and promote an ESV

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

To define and promote the variable:

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

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

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

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

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

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

The following illustration demonstrates the process:

image$esv set variable

Manage configuration placeholders using the API

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

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

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

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

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

Examples

Insert ESV placeholders into tenant email provider configuration

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

  1. Get an access token.

  2. Get the email provider configuration:

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

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

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

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

    ESV name ESV type Expression type Example value

    esv-email-provider-password

    Secret

    n/a

    esv-email-provider-username

    Variable

    String

    example.user

    esv-email-provider-from-email

    Variable

    String

    example.user@example.com

    esv-email-provider-port

    Variable

    Integer

    465

    esv-email-provider-use-ssl

    Variable

    Boolean

    true

  4. Update the email provider configuration:

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

Insert ESV placeholders into CORS configuration

This example shows how to configure placeholders in your tenant CORS configuration. Learn more in Allow cross-domain requests with CORS.

  1. Get an access token.

  2. Get the CORS configuration:

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

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

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

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

    ESV name ESV type Expression type Example value

    esv-cors-accepted-origins

    Variable

    Array

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

  4. Update the CORS configuration:

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

Insert ESV placeholders into journey node configuration

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

  1. Get an access token.

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

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

  3. Get the configuration of the LDAP decision node:

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

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

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

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

    ESV name ESV type Expression type Example value

    esv-journey-ldap-primary-servers

    Variable

    List

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

    esv-journey-ldap-heartbeat-interval

    Variable

    Integer

    10

    esv-journey-ldap-heartbeat-unit

    Variable

    String

    SECONDS

    esv-journey-ldap-password

    Secret

    n/a

    changeit

    esv-journey-ldap-username

    Variable

    String

    uid=myadmin

    esv-journey-ldap-behera-enabled

    Variable

    Boolean

    false

  5. Update the configuration of the LDAP decision node:

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

Insert an ESV placeholder into an LDAP connector

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

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

  1. Get an access token.

  2. Get the configuration of the LDAP connector:

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

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

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

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

    ESV name ESV type Expression type Example value

    esv-connector-ldap-password

    Secret

    n/a

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

  4. Update the connector configuration:

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

Manage configuration placeholders using the admin console

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

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

Admin console support for configuration placeholders

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

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

Admin console action Journey configuration Non-journey configuration

Add placeholder

Yes

No (use API)

View placeholder

Yes

Yes

Remove placeholder

Yes

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

Add a configuration placeholder to a field

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

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

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

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

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

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

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

  6. Select an ESV from the list.

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

  8. (Optional) To edit the placeholder:

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

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

    3. Repeat steps 2–7 above.

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

Delete a configuration placeholder for a field

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

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

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

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

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

Placeholder field states

Insertable

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

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

    image$ui esv insertable placeholder input text

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

    image$ui esv insertable placeholder input checkbox

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

    image$ui esv insertable placeholder input key value

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

Read-only

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

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

    image$ui esv read only placeholder input text

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

    image$ui esv read only placeholder input checkbox

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

    image$ui esv read only placeholder input key value

Key-value field conversion example

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

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

image$ui journeys page node page header modal

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

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

Introduction to self-service promotions

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

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

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

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

The Advanced Identity Cloud configuration model

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

Static and dynamic configuration

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

Lower and upper environments

In a sequential pair of environments, we refer to the lower environment (the configuration source), and the upper environment (the configuration destination). The terms lower environment and upper environment therefore refer to different environments, depending on which environment you are promoting to.

Standard promotion group of environments

A standard promotion group of environments consists of a development, staging, and production environment. If you have any sandbox environments, they aren’t included in this standard promotion group because it’s not possible to promote to or from a sandbox environment.

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

Development
environment		 Staging
environment		 Production
environment

Staging promotion

south lower

north upper

Production promotion

south lower

north upper

Key:

  • south lower = lower environment (configuration source)

  • north upper = upper environment (configuration destination)

Additional UAT environments

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

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

    Development
    environment    		 UAT
    environment    		 Staging
    environment    		 Production
    environment

    UAT promotion

    south lower

    north upper

    Staging promotion

    south lower

    north upper

    Production promotion

    south lower

    north upper

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

    Development
    environment    		 UAT
    environment    		 UAT2
    environment    		 Staging
    environment    		 Production
    environment

    UAT promotion

    south lower

    north upper

    UAT2 promotion

    south lower

    north upper

    Staging promotion

    south lower

    north upper

    Production promotion

    south lower

    north upper

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

Environment locking

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

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

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

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

Configuration integrity checks

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

Integrity check for missing ESVs

Promotion Rollback

Checked?

Yes

Yes

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

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

Integrity check for encrypted secrets

Promotion Rollback

Checked?

Yes

No

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

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

Manage self-service promotions using the API

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

Lower and upper environments

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

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

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.

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

Task 2: Lock the environments

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

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

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

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

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

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

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

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

        To resolve this:

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

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

          2. Start the promotion steps again.

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

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

          2. Start the promotion steps again.

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

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

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

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

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

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

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

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

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

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

Run a promotion

Task 1: Lock the environments

Follow the instructions in Lock environments.

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

Task 3: Run a dry-run promotion

When you’re ready to run a promotion, perform a dry-run promotion first. This lets you identify potential problems with missing ESVs or encrypted secrets without promoting any changes to the upper environment.

To run a dry-run promotion, follow the steps in Task 4: Run the promotion, but in step 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.

Task 4: Run the promotion

If you’ve opted in to release deferral, the deployment of the new regular channel release to your production environment is triggered by the first promotion to that environment during the seven-day deferral period. This means that you must pause promotions to your production environment until you’ve validated the new release in your lower environments.

  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 Task 4: Run the promotion, but in step 1, set the ignoreEncryptedSecrets flag to true:

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

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

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

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

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

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

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

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

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

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

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

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

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

Task 6: Unlock the environments

Follow the instructions in Unlock environments.

Run a rollback

Task 1: Lock the environments

Follow the instructions in Lock environments.

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

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

Task 4: Run the rollback

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

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

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

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

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

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

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

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

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

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

        To resolve this:

        1. Unlock the environments.

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

        3. Start the rollback steps again.

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

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

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

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

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

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

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

      This part of the rollback can take several minutes.

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

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

Task 5: Unlock the environments

Follow the instructions in Unlock environments.

Unlock environments

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

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

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

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

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

View previous promotion or rollback reports

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

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

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

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

Resolve environment errors that are preventing a promotion or a rollback

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

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

  2. Click Create a case.

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

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

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Tenant Settings

    What version of the product are you using?

    Select NA

    Which component is affected?

    Select Self-Service Promotion

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

    Field Value

    Provide a descriptive title for your issue

    Enter one of the following:

    • Resolve environment errors preventing a self-service promotion

    • Resolve environment errors preventing a self-service rollback

    Describe the issue below

    Enter the following details:

    • The error type, either:

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

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

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

  6. Click Submit.

Revert configuration in your development environment

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

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

  2. Click Create a case.

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

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

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Configuration

    What version of the product are you using?

    Select NA

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

    Field Value

    Provide a descriptive title for your issue

    Enter Select Restore from backup

    Describe the issue below

    Enter the following details:

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

    • The environment name (Dev).

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

  6. Click Submit.

Manage self-service promotions using the admin console

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

Lower and upper environments

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

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

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

Promotions functionality in the lower environment

In the lower environment, the admin console lets you:

  • View changes awaiting promotion to the upper environment

  • Promote changes to the upper environment

  • View history of promotions sent to the upper environment

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

View changes awaiting promotion to the upper environment

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

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

  3. The Promotion tab shows the following information:

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

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

        idcloudui promotion summary development

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

        Learn more in Additional UAT environments.

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

        idcloudui promotion summary staging

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

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

      idcloudui promotion view changes development

Sign in to the upper environment

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

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

idcloudui promotion screen title sign in development

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

idcloudui promotion screen title sign in staging

If you have a UAT[2] 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

If you’ve opted in to release deferral, the deployment of the new regular channel release to your production environment is triggered by the first promotion to that environment during the seven-day deferral period. This means that you must pause promotions to your production environment until you’ve validated the new release in your lower environments.

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

  2. Click Promote configuration.

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

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

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

  4. Click Promote n Changes.

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

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

    idcloudui promotion lock tenants development

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

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

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

    • If you want to cancel the promotion:

      1. Click Cancel Promotion.

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

    • If you want to proceed with the promotion:

      1. Click Start Promotion

      2. In the Start Promotion? modal window:

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

        2. Click Start Promotion again.

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

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

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

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

    • Click Done to return to the Promotion tab.

      idcloudui promotion success

View history of promotions sent to the upper environment

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

  2. Click Promote configuration.

  3. Click View promotion history.

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

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

idcloudui promotion history development

Promotions functionality in the upper environment

In the upper environment, the admin console lets you:

  • View a history of promotions received from the lower environment

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

View history of promotions received from the lower environment

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

  2. Click Tenant settings.

  3. Click the Details tab.

  4. Click View updates.

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

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

Restricted functionality

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

Restricted functionality in the lower environment

In the lower environment, the admin console has the following restricted functionality:

  • The left menu is hidden.

  • The page header shows Tenant Locked on the left.

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

idcloudui promotion review development

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

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

Restricted functionality in the upper environment

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

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

idcloudui promotion summary tenant locked staging

Troubleshooting

Resolve failed integrity check for missing ESVs

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

idcloudui promotion error esvs

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

To resolve this:

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

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

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

  4. Start the promotion steps again.

Resolve failed integrity check for encrypted secrets

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

idcloudui promotion error encrypted secrets

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

To resolve this:

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

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

  3. For each encrypted secret in the report:

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

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

  4. Start the promotion steps again.

Resolve tenant locked errors

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

idcloudui promotion error tenant locked

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

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

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

  2. Click Create a case.

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

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

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Tenant Settings

    What version of the product are you using?

    Select NA

    Which component is affected?

    Select Self-Service Promotion

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

    Field Value

    Provide a descriptive title for your issue

    Enter one of the following:

    • Resolve environment errors preventing a self-service promotion

    • Resolve environment errors preventing a self-service rollback

    Describe the issue below

    Enter the following details:

    • The error type, either:

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

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

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

  6. Click Submit.

Revert a promotion

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

Revert configuration in your development environment

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

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

  2. Click Create a case.

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

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

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Configuration

    What version of the product are you using?

    Select NA

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

    Field Value

    Provide a descriptive title for your issue

    Enter Select Restore from backup

    Describe the issue below

    Enter the following details:

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

    • The environment name (Dev).

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

  6. Click Submit.

Service accounts

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

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

Manage service accounts

A tenant administrator can manage service accounts in these ways:

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

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

Service account scopes

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

Scopes for AM and IDM APIs in Advanced Identity Cloud

Scope Purpose Reference

fr:am:*  

Access to /am/* API endpoints

PingAM REST API reference

fr:idm:*      

Access to /openidm/*

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. However, this behavior is deprecated.

Scopes for Advanced Identity Cloud environment APIs

Scope Purpose Reference

fr:idc:certificate:*  

Access to certificate API endpoints

Manage server certificates using the API

      fr:idc:certificate:read

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

fr:idc:content-security-policy:*  

Access to Content Security Policy API endpoints

Content Security Policy API endpoint

fr:idc:cookie-domain:*  

Full access to cookie domain API endpoints.

Manage cookie domains using the API

fr:idc:custom-domain:*  

Access to custom domain endpoints

Custom domains API endpoint

fr:idc:esv:*      

Access to ESV API endpoints

Manage ESVs using the API

      fr:idc:esv:read

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

      fr:idc:esv:update

Create, update, and delete access to ESV API endpoints

      fr:idc:esv:restart

Access to ESV API endpoint to restart Advanced Identity Cloud services

fr:idc:promotion:*  

Access to promotions API endpoints

Manage self-service promotions using the API

fr:idc:release:*  

Access to release management API endpoints

Release management API endpoint

fr:idc:sso-cookie:*  

Access to SSO cookie API endpoints

SSO cookie API endpoint

Scopes for Advanced Identity Cloud APIs under development

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

Scope Purpose Reference

fr:idc:analytics:*  

Access to analytics API endpoints

fr:idc:dataset:*  

Access to dataset deletion API endpoints

fr:idc:mtls:*  

Access to mTLS (mutual TLS) API endpoints

Scopes for add-on capability APIs

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

Scope Purpose Reference

fr:idc:proxy-connect:*  

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

Manage Proxy Connect using the API

      fr:idc:proxy-connect:read

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

      fr:idc:proxy-connect:write

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

fr:iga:*  

Access to IGA API endpoints

Identity Governance REST API reference

fr:idc:ws:admin  

Access to WS-Federation API endpoints

Used by the Advanced Identity Cloud admin console for the Microsoft 365 application.

Restricted scopes

The following scopes are restricted, so the API endpoints under them are not accessible using a service account access token. Learn how to access API endpoints using a tenant administrator access token in the article A scripted approach for creating and using service accounts in PingOne Advanced Identity Cloud.

Scope Purpose Reference

fr:idc:federation:*  

Access to federation API endpoints

Federation API endpoint

Get an access token using a service account

To get an access token using a service account, learn more in Authenticate to Advanced Identity Cloud REST API with access token.

You can also create a script to get a service account access token within your journeys. This approach lets you use the access token in API calls in a Scripted Decision node in Advanced Identity Cloud. Learn more in Get an access token in a journey for an example.

Manage service accounts using the admin console

View service accounts

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

    150

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts. The page displays existing service accounts for your tenant.

Create a new service account

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

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts.

  5. Click New Service Account.

  6. Enter a Name and optional Description for the service account.

  7. In the Scopes section, select the scopes that the service application can grant to an access token. Learn more in Service account scopes.

  8. Click Save.

  9. When the 'Service account successfully created!' message shows:

    1. Make a note of the service account ID, found in the ID field.

    2. Click Download Key to download the service account private key.

      You must download the private key at this point as it will not be available again.

  10. Click Done.

To get an access token using a service account, learn more in Authenticate to Advanced Identity Cloud REST API with access token.

Modify a service account

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

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts.

  5. Click the ellipsis on the right of a service account and select Edit.

  6. You can change the Name or optional Description.

  7. In the Scopes section, you can change the scopes that the service application can grant to an access token. Learn more in Service account scopes.

    Before removing scopes that the service application can grant to an access token, make sure you identify which of your integrations are dependent upon those scopes; otherwise those integrations will fail the next time they request an access token.

  8. Click Save.

Regenerate a key for a service account

Before regenerating a key, make sure you identify which of your integrations are dependent upon it to sign JWTs, as all those integrations need to be updated with the new key.

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

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts.

  5. Click the ellipsis on the right of a service account and select Regenerate Key.

  6. On the Regenerate Key dialog box, click Regenerate Key.

  7. When the 'Key successfully created!' message is shown:

    1. Click Download Key to download the new service account private key.

      You must download the private key at this point as it will not be available again.

  8. Click Done.

Delete a service account

Before deleting a service account, make sure none of your integrations are dependent upon its key to sign JWTs; otherwise those integrations will fail the next time they request an access token.

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

  2. Click Tenant settings.

  3. Click Global Settings.

  4. Click Service Accounts.

  5. Click the ellipsis on the right of a service account and select Delete.

  6. On the Delete Service Account page, click Delete Service Account.

Monitor your tenant

PingOne Advanced Identity Cloud lets you monitor uptime status and system performance.

Advanced Identity Cloud also provides APIs for extracting log data. Learn more in Get audit and debug logs.

Monitor uptime status

Tenant status page

Use your tenant status page to monitor uptime and historical trends for your production environment.

The tenant status page shows individual statuses for these services:

  • Access Management

  • Identity Management

  • UI

  • Logs

status services
If you don’t have access to this page, follow the instructions in Get status page access credentials for additional tenant administrators.

Manage access to your tenant status page

Get status page access credentials for the initial tenant administrator

If you are the initial tenant administrator, you should have received status page credentials when your tenant was set up.

If you have lost or forgotten those credentials, follow the instructions in Get status page access credentials for additional tenant administrators.

Get status page access credentials for additional tenant administrators

If monitoring Advanced Identity Cloud uptime status is part of a tenant administrator’s role, create a support case in the Ping Identity Support Portal to request that the administrator receive access to the tenant status page.

  • You can request access on behalf of one or more tenant administrators, including yourself.

  • In the request, provide the email address of each tenant administrator you want to have status page access.

Remove status page access for tenant administrators

If you want to remove status page access for one or more tenant administrators, create a support case in the Ping Identity Support Portal. In the request, provide the email address of each tenant administrator from which you want to remove access.

Access your tenant status page

If you don’t have access to this page, follow the instructions in Get status page access credentials for additional tenant administrators.

  1. Identify your tenant domain name by removing the protocol and any trailing slash from your tenant FQDN.

    Example: openam-mycompany-mytenant-usw1.id.forgerock.io

  2. Obtain your tenant status page URL by appending your tenant domain name to the Advanced Identity Cloud status page URL, https://status.id.forgerock.io.

    Example: https://status.id.forgerock.io/openam-mycompany-mytenant-usw1.id.forgerock.io

  3. Open your tenant status page URL in a browser.

  4. On the sign-on page, enter your status page credentials.

  5. Click Authenticate.

    Your tenant status page opens, showing real-time status information for your production tenant environment:

    status environments

View incident reports in your production tenant environment

You can view current and past service incidents on the status page, but only if the Ping Identity SRE team manually created the incident. This typically happens during an internal incident where we’ve identified an issue affecting your tenant and want to keep you informed.

The status page doesn’t include detailed incident reports. However, it does provide a historical list of incidents that were posted.

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.

    status filter components

  4. Click Filter Components again to view the incident reports.

Monitor system performance

Monitor using health check endpoint

Use the HTTP response codes from the /monitoring/health endpoint to integrate your tenant environment with external monitoring tools such as Pingdom.

$ curl 'https://<tenant-env-fqdn>/monitoring/health'

This endpoint returns the following HTTP response status codes:

200

Indicates all critical services in an environment are healthy. This status code also shows the informational message OK.

503

Indicates one or more critical services in an environment are not healthy. This status code also shows the informational message Service Unavailable.

Monitor using Prometheus endpoints

Advanced Identity Cloud provides monitoring endpoints you can use with Prometheus.

Endpoint Description

/monitoring/prometheus/am

Produces Prometheus-formatted metrics for Access Management.

Learn which AM metrics are available in the self-managed documentation:

/monitoring/prometheus/idm

Produces Prometheus-formatted metrics for Identity Management

Learn which IDM metrics are available in the self-managed documentation:

Advanced Identity Cloud adds a kubernetes_pod_name label to each metric to allow your monitoring to distinguish between the Kubernetes pods within a tenant environment:

 # TYPE am_authentication summary
 am_authentication_total{kubernetes_pod_name="am-75b55d85c8-gqw9l",outcome="failure",} 0.0
 am_authentication_count{kubernetes_pod_name="am-75b55d85c8-gqw9l",outcome="failure",} 0.0
 am_authentication_total{kubernetes_pod_name="am-75b55d85c8-gqw9l",outcome="success",} 7016.0
 am_authentication_count{kubernetes_pod_name="am-75b55d85c8-gqw9l",outcome="success",} 7016.0

You must obtain API credentials to authenticate to the /monitoring/prometheus/am and /monitoring/prometheus/idm endpoints. Learn more in Authenticate to Advanced Identity Cloud REST API with API key and secret.

You can download and run a Docker-based example of a Grafana dashboard. The demo requires that you have Docker Desktop installed, and requires macOS.

To try the demo:

  1. Download and extract the PingOne Advanced Identity Cloud Monitoring Demo ZIP file.

  2. Edit the setup_monitoring_config.sh file:

    1. In the TENANT_DOMAIN variable, enter the domain name of your tenant.

      Do not include the protocol, and do not add a trailing slash.

      For example:

      TENANT_DOMAIN="openam-mycompany-mytenant-usw1.id.forgerock.io"

    2. In the API_KEY_ID and API_KEY_SECRET variables, enter the API credentials you obtained earlier.

      For example:

      API_KEY_ID="b977d5724ef...562e4c57"
API_KEY_SECRET="d3628be865ce152f49...870e5fd3506c4"

    3. Save your changes.

  3. Run the setup_monitoring_config.sh script.

    The Shell script will set up the following config files:

    Config File Description

    prometheus/prometheus.yml

    The script populates the tenant domain and API credentials.

    docker/docker-compose.yml

    The script populates the working directory path.

  4. Run the following Docker command:

    docker-compose -f docker/docker-compose.yml up

    The command downloads a Prometheus Docker image and configures it for your tenant. It also downloads a Grafana Docker image, and configures it to use the Prometheus image as a data source.

  5. When the command output for the "grafana_1" container displays a message that contains "HTTP Server Listen", open http://localhost:3000 in a web browser.

  6. Log in with username admin, password admin.

  7. Enter a new password to use for the administrator, or click Skip.

  8. On the Grafana Home page, select Dashboards in the left-side hamburger menu.

    The Dashboards page appears.

  9. Select AM Overview to view the AM overview dashboard:

    Sample AM Grafana Dashboard

  10. Select IDM Sample Dashboard to view the IDM sample dashboard.

  11. Go to http://localhost:9090 to view the Prometheus dashboard.

Get audit and debug logs

PingOne Advanced Identity Cloud provides audit and debug logs to help you manage your tenant:

  • Use audit logs to investigate user and system behavior.

  • Use debug logs to investigate any issues that can arise in production.

Advanced Identity Cloud stores logs for 30 days. Use the /monitoring/logs endpoint to access the stored data.

You need to get an API key and secret before you can authenticate to the endpoints through the REST API.
Advanced Identity Cloud provides a console for monitoring log entries in your tenant. This beta feature is limited to development and sandbox[1] environments. Learn more in Monitor log entries in the admin console.

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 showing available sources in a result array:

{
  "result": [
    "am-access", (1)
    "am-activity",
    "am-authentication",
    "am-config",
    "am-core",
    "am-everything",
    "idm-access", (2)
    "idm-activity",
    "idm-authentication",
    "idm-config",
    "idm-core",
    "idm-everything",
    "idm-recon",
    "idm-sync",
    "ws-activity", (3)
    "ws-config",
    "ws-core",
    "ws-everything"
  ],
  "resultCount": 18,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": 1,
  "remainingPagedResults": 0
}
1 Start of log sources for AM audit events. Learn more in AM source descriptions.
2 Start of log sources for IDM audit events. Learn more in IDM source descriptions.
3 Start of log sources for WS-Federation[6] audit events. Learn more in WS-Federation source descriptions.

AM source descriptions

Source Type Description

am-access

Audit

Captures all incoming Advanced Identity Cloud access calls as audit events. This includes who, what, when, and the output for every access request.

Audit events:

  • AM-ACCESS-ATTEMPT

  • AM-ACCESS-OUTCOME

Show example 
{
  "payload": {
    "_id": "92c9b6a4-f36f-438a-b1d4-c6e6bd909da6-783933",
    "client": {
      "ip": "198.51.101.0"
    },
    "component": "OAuth",
    "eventName": "AM-ACCESS-ATTEMPT",
    "http": {
      "request": {
        "headers": {
          "content-type": [
            "application/x-www-form-urlencoded"
          ],
          "host": [
            "<tenant-env-fqdn>"
          ],
          "user-agent": [
            "Apache-HttpClient/4.5.13 (Java/11.0.11)"
          ],
          "x-forwarded-for": [
            "198.51.101.0, 203.0.116.0, 192.0.3.255"
          ],
          "x-forwarded-proto": [
            "https"
          ]
        },
        "method": "POST",
        "path": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token",
        "secure": true
      }
    },
    "level": "INFO",
    "realm": "/alpha",
    "request": {
      "detail": {
        "client_id": "RCSClient",
        "grant_type": "client_credentials",
        "scope": "fr:idm:*"
      }
    },
    "source": "audit",
    "timestamp": "<dateTime>",
    "topic": "access",
    "transactionId": "1634116808645-2e50ecbf0df5407a6870-226587/0"
  },
  "timestamp": "<dateTime>",
  "type": "application/json"
}
Access log format
_id

A universally unique identifier (UUID) for the message object, such as a568d4fe-d655-49a8-8290-bfc02095bec9-491.

timestamp

The timestamp when Advanced Identity Cloud logged the message, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ. For example: 2015-11-14T00:16:04.653Z

eventName

The name of the audit event. For example, AM-ACCESS-ATTEMPT and AM-ACCESS-OUTCOME.

transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling that request are assigned that transaction ID, so you could see the same transaction ID for different audit event topics. For example, 9c9e8d5c-2941-4e61-9c3c-8a990088e801.

userId

The universal identifier for authenticated users. For example, id=scarter,ou=user,o=shop,ou=services,dc=example,dc=com.

trackingIds

A unique random string generated as an alias for each Advanced Identity Cloud session ID and OAuth 2.0 token.

When Advanced Identity Cloud generates an access or grant token, it also generates a unique random value and logs it as an alias. In this way, you can trace an access token back to its originating grant token, trace the grant token back to the session in which it was created, and then trace how the session was authenticated. An example of a trackingIds property in an OAuth 2.0/OpenID Connect 1.0 environment is:

[ "1979edf68543ead001", "8878e51a-f2aa-464f-b1cc-b12fd6daa415", "3df9a5c3-8d1e-4ee3-93d6-b9bbe58163bc" ]
client.host

The client hostname. This field is populated only if reverse DNS lookup is enabled.

client.ip

The client IP address.

client.port

The client port number.

request.protocol

The protocol associated with the request operation.

Possible values: CREST, PLL, SAML2.

request.operation

The request operation. For common REST operations, possible values are: READ, ACTION, QUERY.

For PLL operations, possible values are: LoginIndex, SubmitRequirements, GetSession, REQUEST_ADD_POLICY_LISTENER.

request.detail

Detailed information about the request operation. For example:

  • {"action":"idFromSession"}

  • {"action":"validateGoto"}

  • {"action":"validate"}

  • {"action":"logout"}

  • {"action":"schema"}

  • {"action":"template"}

Example values for an OAuth 2.0 app tree flow:

{
    "oAuth2Client":"myClient",
    "configuredService":"oauth2Tree"
}

Example values for a SAML 2.0 app tree flow:

{
    "spEntity":"serviceprovider1",
    "idpEntity":"identityprovider1",
    "configuredService":"samlTree"
}
http.method

The HTTP method requested by the client. For example, GET, POST, PUT.

http.path

The path of the HTTP request; for example, https://<tenant-env-fqdn>//am/json/realms/root/realms/alpha/authenticate.

http.queryParameters

The HTTP query parameter string. For example:

  • { "_action": [ "idFromSession" ] }

  • { "_queryFilter": [ "true" ] }

  • { "_action": [ "validate" ] }

  • { "_action": [ "logout" ] }

  • { "realm": [ "/shop" ] }

  • { "_action": [ "validateGoto" ] }

http.request.headers

The HTTP header for the request.

Example 
{
    "accept": [
        "application/json"
    ],
    "accept-api-version": [
        "protocol=1.0,resource=2.1"
    ],
    "content-type": [
        "application/json"
    ],
    "host": [
        "example.forgeblocks.com"
    ],
    "origin": [
        "https://example.forgeblocks.com"
    ],
    "user-agent": [
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:120.0) Gecko/20100101 Firefox/120.0"
    ],
    "x-forwarded-for": [
        "188.39.235.130, 34.117.102.58, 10.154.0.3"
    ],
    "x-forwarded-proto": [
        "https"
    ],
    "x-requested-with": [
        "forgerock-sdk"
    ]
}
http.request.cookies

A JSON map of key-value pairs and appears as its own property to allow for denylisting fields or values.

http.response.cookies

Not used in Advanced Identity Cloud.

response.status

The response status of the request. For example, SUCCESS, FAILURE, or null.

response.statusCode

The response status code, depending on the protocol. For common REST, HTTP failure codes are displayed but HTTP success codes aren’t. For PLL endpoints, PLL error codes are displayed.

response.detail

The message associated with response.statusCode. For example, the response.statusCode of 401 has a response.detail of { "reason": "Unauthorized" }.

response.elapsedTime

The time to execute the access event, usually in millisecond precision.

response.elapsedTimeUnits

The elapsed time units of the response. For example, MILLISECONDS.

component

The Advanced Identity Cloud service utilized; for example, Server Info, Users, Config, Session, Authentication, Policy, OAuth, SAML2, Web Policy Agent, or Java Policy Agent.

realm

The realm where the operation occurred. For example, ("/alpha").

am-activity

Audit

Captures state changes to objects that were created, updated, or deleted by Advanced Identity Cloud end users. This includes session, user profile, and device profile changes.

Audit events:

  • AM-SELFSERVICE-REGISTRATION-COMPLETED

  • AM-SELFSERVICE-PASSWORDCHANGE-COMPLETED

  • AM-SESSION-CREATED

  • AM-SESSION-IDLE_TIME_OUT

  • AM-SESSION-MAX_TIMED_OUT

  • AM-SESSION-LOGGED_OUT

  • AM-SESSION-DESTROYED

  • AM-SESSION-PROPERTY_CHANGED

  • AM-IDENTITY-CHANGE

  • AM-GROUP-CHANGE

Show example 
{
  "timestamp": "<dateTime>",
  "payload": {
    "_id": "3fc956b8-00a1-4e10-b8aa-72295d003bfb-195032",
    "objectId": "3fc956b8-00a1-4e10-b8aa-72295d003bfb-195023",
    "transactionId": "cf2a721c-9cec-4224-bdd1-3a33e1f8ed56/4",
    "level": "INFO",
    "eventName": "AM-SESSION-CREATED",
    "timestamp": "<dateTime>",
    "component": "Session",
    "source": "audit",
    "topic": "activity",
    "trackingIds": [
      "3fc956b8-00a1-4e10-b8aa-72295d003bfb-195023"
    ],
    "realm": "/",
    "userId": "id=amadmin,ou=user,ou=am-config",
    "runAs": "id=amadmin,ou=user,ou=am-config",
    "operation": "CREATE"
  },
  "type": "application/json"
}
Activity log format
_id

A universally unique identifier (UUID) for the message object, such as a568d4fe-d655-49a8-8290-bfc02095bec9-487.

changedFields

Not used.

component

The Advanced Identity Cloud service utilized. For example, Session or ID Repo.

eventName

The name of the audit event. For example, AM-SESSION_CREATED, AM-SESSION-LOGGED_OUT, AM-NEW-CONNECTION-FACTORY.

level

The activity log level, INFO by default.

objectId

The unique identifier of the object that was created, updated, or deleted. For logging sessions, the session trackingId is used in this field.

operation

The stage change operation performed on the object. For example, CREATE or UPDATE.

runAs

The user to run the activity as, used in delegated administration.

transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling that request are assigned that transaction ID, so you could see the same transaction ID for different audit event topics. For example, 9c9e8d5c-2941-4e61-9c3c-8a990088e801.

trackingIds

An array containing the following:

  • A random context ID that identifies the session

  • A random string generated from an OAuth 2.0/OIDC 1.0 flow that could track an access token ID or a grant token ID.

For example, [ "c120669f-f636-467d-8da0-590d72aeaf08-181706" ].

userId

The universal identifier for authenticated users. For example, id=fe32c8fe-38a2-4159-a220-9385350f3aca,ou=user,ou=am-config.

timestamp

The timestamp when Advanced Identity Cloud} logged the message, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ. For example: 2015-11-14T00:16:04.652Z

type

The data type,application/json by default.

source`

The source of these logs, am-activity.

am-authentication

Audit

Captures when and how a user authenticated and related audit events.

Advanced Identity Cloud records an authentication audit event for each authentication node and the journey outcome. A node can provide extra data in the standard audit event, which is logged when an authentication node completes.

Audit events:

  • AM-BACK-CHANNEL-INITIALIZE

  • AM-LOGOUT

  • AM-LOGIN-COMPLETED

  • AM-NODE-LOGIN-COMPLETED

    Advanced Identity Cloud logs this audit event each time an authentication node completes.

    Show example 
    {
  "type": "application/json",
  "timestamp": "<dateTime>",
  "payload": {
    "topic": "authentication",
    "eventName": "AM-NODE-LOGIN-COMPLETED",
    "transactionId": "ad56bedd-7dab-45d1-84d9-505b0b64fd6d/6",
    "principal": [
      "amadmin"
    ],
    "timestamp": "<dateTime>",
    "component": "Authentication",
    "source": "audit",
    "realm": "/",
    "entries": [
      {
        "info": {
          "authLevel": "0",
          "displayName": "Page Node",
          "nodeId": "83a9d86e-d6f5-11ea-87d0-0242ac130003",
          "nodeOutcome": "outcome",
          "treeName": "FRLogin",
          "nodeType": "PageNode"
        }
      }
    ],
    "level": "INFO",
    "trackingIds": [
      "3fc956b8-00a1-4e10-b8aa-72295d003bfb-184020"
    ],
    "_id": "3fc956b8-00a1-4e10-b8aa-72295d003bfb-184022"
  }
}

  • AM-TREE-LOGIN-STARTED

    • Disabled by default in Advanced Identity Cloud.

  • AM-TREE-LOGIN-COMPLETED

    • If authentication completes successfully, the event has a result of SUCCESS.

    • If authentication fails, the event has a result of FAILED.

    • If the authentication ends in an exception, the event has a result of FAILED with the following additional field:

      exception: "An exception occurred during the authentication process"

      These exceptions let you troubleshoot authentication journeys that failed due to misconfiguration.

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

Authentication log format
_id

A universally unique identifier (UUID) for the message object, such as a568d4fe-d655-49a8-8290-bfc02095bec9-485.

timestamp

The timestamp when Advanced Identity Cloud} logged the message, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ. For example: 2015-11-14T00:16:04.640Z

eventName

The name of the audit event. For example, AM-LOGOUT and AM-NODE-LOGIN-COMPLETED.

transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling that request are assigned that transaction ID, so you could see the same transaction ID for different audit event topics. For example, 9c9e8d5c-2941-4e61-9c3c-8a990088e801.

user.id

The universal identifier for authenticated users. For example, id=scarter,ou=user,o=shop,ou=services,dc=example,dc=com.

trackingIds

An array containing a unique random context ID.

  • For OAuth 2.0/OIDC flows, this field identifies the session and a random string generated that can track an access token ID or a grant token ID.

  • For authentication journeys, this field identifies the journey.

result

The result of the authentication journey. Possible values are SUCCESSFUL or FAILED.

principal

The array of accounts used to authenticate. For example [ "tenantadmin" ] or [ "scarter" ].

context

Not used

entries

A JSON representation of the authentication journey or node. Advanced Identity Cloud} creates an event as each node completes and a final event at the end of the journey.

Example:

{
  "entries":[
      {
         "info":{
            "nodeOutcome":"true",
            "treeName":"Example",
            "displayName":"Data Store Decision",
            "nodeType":"DataStoreDecisionNode",
            "nodeId":"e5ec495a-2ae2-4eca-8afb-9781dea04170",
            "authLevel":"0"
         }
      }
   ]
}
component

The Advanced Identity Cloud} service utilized. For example, Authentication.

realm

The realm where the operation occurred. For example, ("/alpha").

am-config

Audit

Captures access management configuration changes for Advanced Identity Cloud with a timestamp and by whom.

Configuration changes can only be performed in development environments, so these logs are empty in staging and production environments.

Audit events:

  • AM-CONFIG-CHANGE

Show example 
{
  "payload": {
    "_id": "92c9b6a4-f36f-438a-b1d4-c6e6bd909da6-822860",
    "eventName": "AM-CONFIG-CHANGE",
    "level": "INFO",
    "objectId": "ou=Office365,ou=dashboardApp,ou=default,ou=GlobalConfig,ou=1.0,ou=dashboardService,ou=services,ou=am-config",
    "operation": "CREATE",
    "runAs": "id=bd220328-9762-458b-b05a-982ac3c7fc54,ou=user,ou=am-config",
    "source": "audit",
    "timestamp": "<dateTime>",
    "topic": "config",
    "trackingIds": [
      "92c9b6a4-f36f-438a-b1d4-c6e6bd909da6-821644"
    ],
    "transactionId": "1634122041174-2e50ecbf0df5407a6870-229391/0",
    "userId": "id=bd220328-9762-458b-b05a-982ac3c7fc54,ou=user,ou=am-config"
  },
  "timestamp": "<dateTime>",
  "type": "application/json"
}
Config log format
_id

A universally unique identifier (UUID) for the message object. For example, 6a568d4fe-d655-49a8-8290-bfc02095bec9-843.

timestamp

The timestamp when Advanced Identity Cloud logged the message, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ. For example, 2015-11-14T00:21:03.490Z

eventName

The name of the audit event. For example, AM-CONFIG-CHANGE.

transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling the request will be assigned that transaction ID, so you could see the same transaction ID for different audit event topics. For example, 301d1a6e-67f9-4e45-bfeb-5e4047a8b432.

user.id

Not used.

You can determine the value for this field by linking to the access event using the same transactionId.

trackingIds

Not used.

runAs

The user to run the activity as. Can be used in delegated administration.

objectId

The identifier of a system object that has been created, modified, or deleted. For example, ou=SamuelTwo,ou=default,ou=OrganizationConfig,ou=1.0, ou=iPlanetAMAuthSAML2Service,ou=services,o=shop,ou=services,dc=example,dc=com.

operation

The state change operation invoked: CREATE, MODIFY, or DELETE.

before

The JSON representation of the object prior to the activity.

Example:

{
   "sunsmspriority":[
      "0"
   ],
   "objectclass":[
      "top",
      "sunServiceComponent",
      "organizationalUnit"
   ],
   "ou":[
      "SamuelTwo"
   ],
   "sunserviceID":[
      "serverconfig"
   ]
}
after

The JSON representation of the object after the activity.

Example:

{
 "sunKeyValue":[
      "forgerock-am-auth-saml2-auth-level=0",
      "forgerock-am-auth-saml2-meta-alias=/sp",
      "forgerock-am-auth-saml2-entity-name=http://",
      "forgerock-am-auth-saml2-authn-context-decl-ref=",
      "forgerock-am-auth-saml2-force-authn=none",
      "forgerock-am-auth-saml2-is-passive=none",
      "forgerock-am-auth-saml2-login-chain=",
      "forgerock-am-auth-saml2-auth-comparison=none",
      "forgerock-am-auth-saml2-req-binding= urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
      "forgerock-am-auth-saml2-binding= urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact",
      "forgerock-am-auth-saml2-authn-context-class-ref=",
      "forgerock-am-auth-saml2-slo-relay=http://",
      "forgerock-am-auth-saml2-allow-create=false",
      "forgerock-am-auth-saml2-name-id-format= urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
   ]
}
changedFields

The fields that were changed. For example, [ "sunKeyValue" ].

revision

Not used.

component

Not used.

realm

The realm where the operation occurred. For example, ("/alpha").

am-core

Debug

Captures access management debug logs for Advanced Identity Cloud. Use am-core when debugging anything in access management without capturing audit events. am-core also captures logging in authentication scripts.

Development and sandbox environments provide DEBUG level logs, with logs in several areas tuned to INFO or WARNING.

To reduce log volumes, staging and production environments only provide WARNING level logs and above.

To troubleshoot and view the latest entries in the stored logs, you can tail am-core source. Learn more in Tail logs.

am-everything

Audit, Debug

Captures all access management audit and debug logs for Advanced Identity Cloud.

This includes all the logs captured in am-access, am-activity, am-authentication, am-config, and am-core.

IDM source descriptions

Source Type Description

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.

WS-Federation source descriptions

The following log sources are available for WS-Federation[6]:

Source Type Description

ws-activity

Audit

Captures WS-Federation user authentication events.

Show example 
{
    "payload": {
        "client": {
            "ip": "10.100.2.27"
        },
        "eventName": "AUTHN_ATTEMPT",
        "logFile": "audit.log",
        "request": {
            "adapterId": "1731608547",
            "connectionId": "urn:federation:MicrosoftOnline",
            "protocol": "WSFED",
            "role": "IdP"
        },
        "response": {
            "elapsedTime": "399",
            "elapsedTimeUnits": "MILLISECONDS",
            "status": "inprogress"
        },
        "server": {
            "hostname": "pingfederate-engine-bd49cb65d-kkqzc"
        },
        "source": "audit",
        "timestamp": "2024-12-03T19:37:39.024Z",
        "topic": "activity",
        "trackingId": "tid:JmiM3ipvXOC809styOOD13BAfeM",
        "transactionId": "f5f1cb6d-3899-4f45-b399-19253531de55/0"
    },
    "timestamp": "2024-12-03T19:37:39.024843174Z",
    "type": "application/json",
    "source": "ws-activity"
}
Activity log format
payload.client.ip

The client IP address.

payload.eventName

The name of the audit event (for example, AUTHN_REQUEST, AUTHN_ATTEMPT, SSO, AUTHN_SESSION_CREATED).

payload.request:
adapterId

The adapter instance ID(s) that were invoked (for example, 1731608547).

app

The target application URL if available.

connectionId

The federation realm ID (for example, urn:federation:MicrosoftOnline).

protocol

The associated authentication protocol (WSFED).

subject

The user name (for example, bjensen@example.com).

role

The authentication role (IdP, SP).

payload.response:
status

The status of the SSO request (success, failure, inprogress).

detail

Additional description of the event if available.

elapsedTime

The time to execute the access event, usually in millisecond precision (for example, 170).

elapsedTimeUnits

The elapsed time units of the response (for example, MILLISECONDS).

payload.server.hostname

The hostname of the PingFederate container (for example, pingfederate-engine-bd49cb65d-kkqzc).

payload.topic

A shortened version of this log source (activity).

payload.timestamp

The timestamp when Advanced Identity Cloud logged the event, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ (for example, 2015-11-14T00:16:04.653Z).

payload.trackingId

A unique ID for a user session (for example, tid:JmiM3ipvXOC809styOOD13BAfeM).

payload.transactionId

The UUID of the transaction, which identifies an external request when it comes into the system boundary. Any events generated while handling that request are assigned that transaction ID, so you could see the same transaction ID for different audit event topics (for example, f5f1cb6d-3899-4f45-b399-19253531de55/0).

timestamp

Refer to the description of payload.timestamp.

type

The log format (for example, application/json).

source

This log source (ws-activity).

ws-config

Audit

Captures WS-Federation configuration change events.

Show example 
{
    "payload": {
        "client": {
            "ip": "10.40.15.194"
        },
        "http": {
            "request": {
                "method": "GET",
                "path": "/configArchive/export"
            }
        },
        "logFile": "admin-api.log",
        "request": {
            "authType": "Bearer",
            "partnerId": "pingfederate-resource-server",
            "user": "pingfederate-resource-server"
        },
        "response": {
            "statusCode": "200"
        },
        "source": "audit",
        "timestamp": "2024-12-08T18:15:03.028Z",
        "topic": "config"
    },
    "timestamp": "2024-12-08T18:15:03.02886768Z",
    "type": "application/json",
    "source": "ws-config"
}
Configuration log format
payload.client.ip

The client IP address.

payload.eventName

The name of the administrative event (for example, EXPORT).

payload.http.request:
method

The HTTP method for the request (for example, POST).

path

The endpoint of the HTTP request.

payload.logFile

The log file name that generated this log entry (for example, admin-api.log or admin.log).

payload.message

Additional information of the event if available.

payload.request:
authType

The type of authentication used (Basic, Bearer).

adminSessionId

The unique administrative session ID.

component

The configuration component (for example, CONFIG_ARCHIVE).

partnerId

The federation realm ID (for example, urn:federation:MicrosoftOnline).

roles

The administrative roles associated with this user (for example, UserAdmin).

user

The administrative username (for example, pingfederate-resource-server).

payload.response.statusCode

The HTTP status code for the response.

payload.timestamp

The timestamp when Advanced Identity Cloud logged the event, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ (for example, 2015-11-14T00:16:04.653Z).

payload.topic

A shortened version of this log source (config).

timestamp

Refer to the description of payload.timestamp.

type

The log format (for example, application/json).

source

This log source (ws-config).

ws-core

Debug

Captures WS-Federation error and debug events.

Show example 
{
    "payload": {
        "level": "INFO",
        "logFile": "server.log",
        "logger": "org.sourceid.websso.servlet.reqparam.ValidationHub",
        "message": "Created 2 validators for parameter SpSessionAuthnAdapterId",
        "timestamp": "2024-12-02T23:13:20.208Z"
    },
    "timestamp": "2024-12-02T23:13:20.209188799Z",
    "type": "application/json",
    "source": "ws-core"
}
Core log format
payload.level

The level of the error or debug event (FATAL, ERROR, WARN, INFO, DEBUG, TRACE).

payload.logFile

The log file name that generated this log entry (for example, server.log).

payload.logger

The Java class that generated this log entry (for example, com.pingidentity.pf.admin.rest.filter.OAuth2AdminAuthHandler).

payload.message

A description of the event.

payload.timestamp

The timestamp when Advanced Identity Cloud logged the event, in UTC format to millisecond precision: yyyy-MM-ddTHH:mm:ss.msZ (for example, 2015-11-14T00:16:04.653Z).

timestamp

Refer to the description of payload.timestamp.

type

The log format (for example, application/json).

source

This log source (ws-core).

ws-everything

Audit, Debug

Captures WS-Federation audit and debug logs for Advanced Identity Cloud.

This includes all the logs captured in ws-activity, ws-config, and ws-core.

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

Filter logs for a specific request

All external requests into Advanced Identity Cloud are assigned the same unique transaction ID, which can be observed in the X-ForgeRock-TransactionID HTTP header:

$ 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: Secret12!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
...
x-forgerock-transactionid: <transaction-id>
...

An example transaction ID value is f89da9de-22f4-4e0b-8527-26b8d9c53d7b-request-1/0. The part before the forward slash is a fixed value that’s consistent across log entries from all log sources. The part after the forward slash is a number that increments as the request reaches different components inside the Advanced Identity Cloud system, so can differ between log entries from different log sources.

To filter the logs for a specific request, note the part of the transaction ID before the forward slash. For the previous example, that value is f89da9de-22f4-4e0b-8527-26b8d9c53d7b-request-1. Then add that value to the transactionId parameter on your logs API 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 'transactionId=<transaction-id>' (1)
1 Replace <transaction-id> with the part of a transaction ID before the forward slash.

Example response:

{
  "result": [{
    "payload": "<payload>",
    "timestamp": "<dateTime>",
    "type": "application/json",
    "source": "am-authentication"
  }, {
    "...": "..."
  }],
  "resultCount": "8",
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Filter log results

Use the _queryFilter parameter to filter log results on any field or combination of fields in a payload. You can add the parameter to the /monitoring/logs and /monitoring/logs/tail endpoints.

The benefits of the _queryFilter parameter are:

  • Lets you iteratively refine queries to remove extraneous results and find the specific log entries you are interested in. This is useful when searching logs to debug a production issue.

    Use the /monitoring/logs endpoint for iterative searching as the /monitoring/logs/tail endpoint only returns results from the last 15 seconds.

  • Lets you tune queries to reduce Advanced Identity Cloud log volume, making integration with external log tools such as Splunk or Elastic Stack more efficient and potentially reducing storage costs.

The _queryFilter parameter takes a URL-encoded filter expression:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=<source>' \
--data-urlencode '_queryFilter=<filter-expression>'

Learn more about constructing a filter expression in the filter expression rules for _queryFilter. Here are some basic examples:

Example filter expression Description

/payload co "WARNING"

Search plaintext results for a particular string.

/payload/client/ip co "10.104.1.5"

Search for JSON results containing a particular client IP address.

/payload/level eq "DEBUG"

Search for JSON results with a particular log level.

/payload/eventName eq "access"

Search for JSON results with a particular event name.

/payload/eventName co "AM-ACCESS-ATTEMPT"

Search for JSON results containing a particular event name.

/payload/timestamp eq "2023-05-16T08:21:34.632Z"

Search for JSON results with a particular timestamp.

/payload/timestamp sw "2023-05-14T16:34:34"

Search for JSON results with a timestamp that starts with a particular datetime.

/payload/client/ip co "10.104.1.5" and /payload/level eq "ERROR"

Search for JSON results containing a particular client IP address and also containing a particular log level.

/payload/entries/info/nodeType pr

Search for JSON results where an authentication node type is present.

Filter array items in log results

To filter on array items, do not include an array index in your filter expression.

For example, to search for JSON results where the authentication node type is ScriptedDecisionNode:

  • Wrong: /payload/entries/0/info/nodeType eq "ScriptedDecisionNode"

  • Right: /payload/entries/info/nodeType eq "ScriptedDecisionNode"

where a log entry for an authentication node looks like this:

    {
      "payload": {
        "_id": "7ae37a4b-f22b-4c5e-8621-2130d5bc603c-9310858",
        "component": "Authentication",
        "entries": [
          {
            "info": {
              "authLevel": "0",
              "displayName": "Using Invite?",
              "nodeId": "15edd2f7-22f1-4f32-bf0a-8ca3f98af850",
              "nodeOutcome": "False",
              "nodeType": "ScriptedDecisionNode",
              "treeName": "Login"
            }
          }
        ],
        "eventName": "AM-NODE-LOGIN-COMPLETED",
        ...
    }

Filter log results between two dates

To filter log results between two dates, use the beginTime and endTime query parameters with ISO 8601 datetime values:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=<source>' \
--data 'beginTime=<begin-datetime>' \
--data 'endTime=<end-datetime>' \
--data-urlencode '_queryFilter=<filter-expression>'

For example, to filter log results between two specific dates for a specific user :

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication' \
--data 'beginTime=2023-05-24T12:40:00.00Z' \
--data 'endTime=2023-05-24T12:45:00.00Z' \
--data-urlencode '_queryFilter=/payload/principal eq "user.name@example.com"'

Add response fields

Authentication events

You can use a script to add extra information to log entries for authentication events. Learn more in Add information to authentication audit log entries.

Identity object events

You can configure audit log results to include additional identity object events. For example, you may want to log the before and after values of specific activities, such as changes to a user’s last name or email address.

To include additional identity object event fields, add them to the includeIf property in the audit configuration. Make these changes in your development environment and then promote them.

By default, Advanced Identity Cloud audits identity object event fields that are safe to log. When adding audit event fields, be mindful of the type of information that you intend to expose in the logs. For example, you may need to keep personally identifiable information (PII) out of the logs.
Add identity object event fields to audit logging

  1. Get the current audit configuration.

    Example request:

    $ curl \
--request GET \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
'https://<tenant-env-fqdn>/openidm/config/audit'

    Learn more in the IDM REST API reference.

    Show response 
    {
  "_id": "audit",
  "auditServiceConfig": {
    "availableAuditEventHandlers": [
      "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
      "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
      "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
      "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
      "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
      "org.forgerock.openidm.audit.impl.RouterAuditEventHandler",
      "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler",
      "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler"
    ],
    "caseInsensitiveFields": [
      "/access/http/request/headers",
      "/access/http/response/headers"
    ],
    "filterPolicies": {
      "value": {
        "excludeIf": [
          "/access/http/request/cookies/&{com.iplanet.am.cookie.name}",
          "/access/http/request/cookies/session-jwt",
          "/access/http/request/headers/&{com.sun.identity.auth.cookieName}",
          "/access/http/request/headers/&{com.iplanet.am.cookie.name}",
          "/access/http/request/headers/accept-encoding",
          "/access/http/request/headers/accept-language",
          "/access/http/request/headers/Authorization",
          "/access/http/request/headers/cache-control",
          "/access/http/request/headers/connection",
          "/access/http/request/headers/content-length",
          "/access/http/request/headers/content-type",
          "/access/http/request/headers/proxy-authorization",
          "/access/http/request/headers/X-OpenAM-Password",
          "/access/http/request/headers/X-OpenIDM-Password",
          "/access/http/request/queryParameters/access_token",
          "/access/http/request/queryParameters/IDToken1",
          "/access/http/request/queryParameters/id_token_hint",
          "/access/http/request/queryParameters/Login.Token1",
          "/access/http/request/queryParameters/redirect_uri",
          "/access/http/request/queryParameters/requester",
          "/access/http/request/queryParameters/sessionUpgradeSSOTokenId",
          "/access/http/request/queryParameters/tokenId",
          "/access/http/response/headers/Authorization",
          "/access/http/response/headers/Set-Cookie",
          "/access/http/response/headers/X-OpenIDM-Password"
        ],
        "includeIf": []
      }
    },
    "handlerForQueries": "json"
  },
  "eventHandlers": [
    {
      "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
      "config": {
        "name": "json",
        "topics": [
          "access",
          "activity",
          "sync",
          "authentication",
          "config"
        ]
      }
    }
  ],
  "eventTopics": {
    "activity": {
      "filter": {
        "actions": [
          "create",
          "update",
          "delete",
          "patch",
          "action"
        ]
      },
      "passwordFields": [
        "password"
      ],
      "watchedFields": []
    },
    "config": {
      "filter": {
        "actions": [
          "create",
          "update",
          "delete",
          "patch",
          "action"
        ]
      }
    }
  },
  "exceptionFormatter": {
    "file": "bin/defaults/script/audit/stacktraceFormatter.js",
    "type": "text/javascript"
  }
}

  2. Make a backup of the audit configuration.

  3. Update the includeIf property (under filterPolicies) in the audit configuration to include the fields you want to add.

    The following example updates the audit configuration to include before and after values of a user’s last name and email address:

    $ curl \
--request PUT \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "_id": "audit",
  ...
   "filterPolicies": {
     "value": {
       "excludeIf": [
          "/access/http/request/cookies/&{com.iplanet.am.cookie.name}",
          "/access/http/request/cookies/session-jwt",
        ...
        ],
        "includeIf": [
           "/activity/before/sn", (1)
           "/activity/after/sn", (2)
           "/activity/before/mail", (3)
           "/activity/after/mail" (4)
        ]
      }
   },
  ...
}' \
'https://<tenant-env-fqdn>/openidm/config/audit'

    Fields added:

    1 Logs the user’s last name before change.
    2 Logs the user’s last name after change.
    3 Logs the user’s email address before change.
    4 Logs user’s email address after change.

Once updated, idm-activity and idm-everything audit logs will include the fields you have added.

For example, the following entry in a sample idm-activity log shows before and after values for changes to a user’s last name and email address from "Brown" to "Granger":

{
    "payload": {
        "message": "",
        "runAs": "bd220328-9762-458b-b05a-982ac3c7fc54",
        "transactionId": "1630683558570-abec9e9304c84ad368ba-28676/0",
        "before": {
            "sn": "Brown",
            "mail": "jbrown@example.com"
        },
        "operation": "PATCH",
        "passwordChanged": false,
        "_id": "52f7cea0-285d-4ef6-bda3-83256dda71c5-1300250",
        "revision": "00000000412cae36",
        "eventName": "activity",
        "userId": "bd220328-9762-458b-b05a-982ac3c7fc54",
        "status": "SUCCESS",
        "objectId": "managed/alpha_user/ce7492dc-8759-47b3-b4ee-eda8d4de4ab1",
        "timestamp": "2023-09-03T15:39:42.862Z",
        "changedFields": [],
        "after": {
            "sn": "Granger",
            "mail": "jgranger@example.com"
        }
    "type": "application/json",
    "timestamp": "<date-time>"
}

You can also exclude fields from audit logging by adding them to the excludeIf property in the audit configuration.

For example, to prevent audit logs from showing target object attributes for synchronization and reconciliation events, add the following entries to the excludeIf property in the audit configuration:

"/sync/targetObject/<attribute-name>",
"/recon/targetObject/<attribute-name>"

Rate limiting

Logs endpoint

To reduce unwanted stresses on the system, Advanced Identity Cloud limits the number of requests you can make to the /monitoring/logs endpoint in a certain timeframe:

  • The page-size limit is 1000 logs per request.

    Ping Identity recommends you do not override the page-size limit with a greater value as it could increase request throttling and reduce the overall number of logs you can request per minute.

  • The request limit is 60 requests per minute.

  • The theoretical upper rate limit is therefore 60,000 logs per minute.

These limits apply per environment, so your development, staging, and production environments each have their own quota.

The following rate limit notification response headers are sent for each request to the /monitoring/logs endpoint:

X-RateLimit-Limit

The maximum number of requests allowed in the current rate limit window.

X-RateLimit-Remaining

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

The time in seconds since Jan. 1, 1970, UTC when the rate limit window resets.

A 429 HTTP status code on the /monitoring/logs endpoint indicates that the rate limit has been exceeded, and no results are returned.

Logs tail endpoint

The /monitoring/logs/tail endpoint has the same limits and response headers as the /monitoring/logs endpoint described above. However, the endpoint also has a limit of 15,000 lines per request, which supersedes the page-size limit of 1000 logs per request.

Troubleshooting

Update audit configuration

Sometimes a log source is shown in the available sources in Advanced Identity Cloud but returns no results when you query the Advanced Identity Cloud logging endpoints. In this case, check the underlying IDM audit configuration to ensure that the corresponding audit topic for the source is enabled.

The following example shows how to enable the recon event handler so that reconciliation events appear in the audit logs:

  1. Get the current audit configuration.

    Example request:

    $ curl \
--request GET \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
'https://<tenant-env-fqdn>/openidm/config/audit'

    Learn more in IDM REST API reference.

  2. Update the audit configuration as needed. The following example enables the reconciliation audit event handler.

    Example update:

    $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/audit' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "_id": "audit",
  ...
  "eventHandlers": [
    {
      "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
      "config": {
        "elasticsearchCompatible": false,
        "enabled": true,
        "name": "json",
        "topics": [
          "access",
          "activity",
          "sync",
          "authentication",
          "config",
          "recon"
        ]
      }
    }
  ],
  ...
}' \
'https://<tenant-env-fqdn>/openidm/config/audit'

Include large log entries in filter log results

Some Advanced Identity Cloud log output is too large to be stored as a single log entry, so is stored across two log entries instead. When this happens, any log output in JSON format is stored as two plaintext log entries rather than a single JSON log entry. Consequently, any filter expression that filters on a specific JSON field will not find any of these plaintext log entries.

To work around this, you can combine a specific field filter with a plaintext filter. For example, if you were searching for log results containing a particular transaction ID using the filter expression:

/payload/transactionId co "<transaction-id>"

you could add a plaintext filter as follows:

/payload/transactionId co "<transaction-id>" or /payload co "<transaction-id>"

to include both JSON and plaintext log entries in the log results.

Import cURL commands into Postman

If you use Postman’s import cURL commands feature to convert cURL commands into Postman requests, you might have problems with the example commands on this page that use a GET request and include a --data parameter, such as this one:

$ curl -G \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs'
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication'

When you import the above command into Postman and run the request, it produces this error:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>400 Bad Request</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Bad Request</h1>
<h2>Your client has issued a malformed or illegal request.</h2>
<h2></h2>
</body></html>

This occurs because Postman adds the value of --data parameter twice—as a query string but also incorrectly as a message body. The equivalent incorrect cURL query of the import would be:

curl \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs?source=am-authentication' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=am-authentication'

To resolve, convert any --data parameters into a query string before importing into Postman:

$ curl \
--request 'https://<tenant-env-fqdn>/monitoring/logs?source=am-authentication'
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>'

Email provider

PingOne Advanced Identity Cloud uses email provider configuration to support email-dependent end-user journeys. For example, registration and password reset end-user journeys usually include an email component.

By default, Advanced Identity Cloud configures the email provider with default values to connect to a built-in SMTP server. This lets you quickly create and test email-dependent journeys in your tenant development environment using the ready-to-use email templates. No rate limiting is applied to password reset emails or any emails sent by the built-in SMTP server. This means an attacker can potentially spam a known user account with an infinite number of emails, filling that user’s inbox. In the case of password reset, the spam attack can obscure an actual password reset attempt.

In your staging and production tenant environments, you must update the email provider configuration with values to connect to something other than the built-in SMTP server.

Additionally, the built-in SMTP server does not support:

Setup process

Email provider configuration changes made in one realm are applied to both realms.

  1. Create a new email template.

  2. In your tenant development environment, create and test a journey that uses an email node. By default, the email provider uses the built-in SMTP server to test the email node.

  3. When you’re satisfied with your test results:

    1. Edit the email provider configuration to use your own external email provider.

    2. Verify that your email templates work with the external provider.

  4. Promote your configuration changes to your tenant staging environment.

  5. Optionally, you can revert the email provider to use the built-in SMTP server for testing purposes. Be sure to reconfigure the email provider to use your own external service before promoting configuration changes to your tenant staging environment.

Do not use the email provider with the built-in SMTP server in a tenant production environment. Advanced Identity Cloud provides this ready-to-use server for testing purposes only.

Email service configuration types

Advanced Identity Cloud supports two email service configuration types:

  • SMTP - Email service that uses the Simple Mail Transfer Protocol. Can be configured using the admin console or API.

  • MS Graph API - Email service that uses the MS Graph API sendMail endpoint. Can only be configured using the API.

International email addresses

To use international email addresses, you must:

  • Use SMTP as the provider type.

  • The SMTP provider must support international email addresses.

  • Configure mail.mime.allowutf8=true using the REST API or the UI.

    Learn more in smtpProperties sub-properties.

MS Graph API requirements

Use of the MS Graph API email client requires a properly configured Microsoft Azure tenant. The steps for configuring an Azure tenant should be used as an outline, as the specific options, menus, and features may have changed.

Microsoft Sandbox

If you need a sandbox for testing only, check out the Microsoft developer sandbox subscription. Although the sandbox accepts sendMail requests, the Microsoft Exchange service prevents messages from being delivered. The messages do show up in the sender’s "sent" box, which should be sufficient for manual testing purposes.

Configure Azure for MS Graph API email client

  1. Navigate to Azure Active Directory | App registrations.

  2. Create the Advanced Identity Cloud client application:

    1. From the menu bar, click + New Registration.

    2. On the Register an application page, enter the application Name, such as my-email-client.

    3. For Supported account types, select the applicable option for your organization.

    4. Click Register.

    5. On the my-email-client page, from the main Essentials area, record the Application (client) ID.

      This is the value for clientId in the auth settings of the email configuration. Learn more in oauth2 properties.

  3. Add a client secret:

    1. On the my-email-client page, in the main Essentials area, click Add a certificate or secret.

      Show Me
      Azure app - add a secret link

    2. On the Certificates & secrets page, select the Client secrets tab, and click + New client secret.

      Show Me
      Azure app - add a new client secret

    3. In the Add a client secret window, enter the details, and click Add.

    4. Copy the Value and Secret ID to a secure place before leaving the Certificates & secrets page.

      Use the secret Value for clientSecret in the auth settings of the email configuration. Learn more in oauth2 properties.

  4. Add API permissions:

    1. From the side menu, click API permissions.

    2. On the API permissions page, click + Add a permission.

    3. In the Request API permissions windows, select the Microsft APIs tab, and click Microsoft Graph.

    4. In the What type of permissions…​ area, click Application permissions.

    5. In the Select permissions search bar, type send.

    6. Expand the Mail node, and select Mail.Send.

    7. Click Add permissions.

      Show Me
      Azure app - Request API permissions

Configure the email provider

Email provider configuration changes made in one realm are applied to both realms.

In your staging and production tenant environments, configure the email provider to use your own external service:

  • For SMTP, you can use the UI or API.

  • For MS Graph API, you can only use the API.

Using the admin console

  1. In the Advanced Identity Cloud admin console, go to Email > Provider.

  2. On the Email Provider page, enable Use my own email provider.

  3. Enter details in the following fields:

    From Address

    Email address of the organization or individual sending the email.

    Example: mycompany@example.com.

    Not set by default.

    Although from is optional in the email configuration, the email service requires this property to send email. If you do not specify a from address in the email configuration, you must provide one in another way, for example:

    • From an email template.

    • As a parameter in the email service request (from or _from).

    From Name

    Name of sending organization.

    Host

    Hostname or IP address of your SMTP server.

    When no hostname is specified, Advanced Identity Cloud uses the built-in SMTP server.

    Port

    Port number of your SMTP server.

    Many SMTP servers require the use of a secure port such as 465 or 587. Many ISPs flag email from port 25 as spam.

    Default value is 587.

    Username

    Username for your SMTP server account.

    Password

    Password for your SMTP server account.

  4. Click Show advanced settings, and edit the options and fields:

    Socket Connection Timeout (ms)

    Elapsed time before Advanced Identity Cloud times out due to unsuccessful socket connection to the SMTP server. A setting of 0 disables this timeout.

    The default is 300000 ms (5 minutes).

    Socket Write Timeout (ms)

    Elapsed time before Advanced Identity Cloud times out because client can’t write to the SMTP server. A setting of 0 disables this timeout.

    The default is 300000 (5 minutes).

    Socket Timeout (ms)

    Elapsed time before Advanced Identity Cloud times out due to inactivity. A setting of 0 disables this timeout.

    The default is 300000 (5 minutes).

    Use STARTTLS

    • If enabled, and if the SMTP server supports the STARTTLS command, then Advanced Identity Cloud switches to a TLS-protected connection before issuing any login commands.

    • If the SMTP server does not support STARTTLS, the connection continues without the use of TLS.

    Enabled by default.

    Use SSL

    If enabled, Advanced Identity Cloud uses SSL to connect to the SMTP server.

    Disabled by default.

    Allow UTF-8

    If enabled, adds support for UTF-8 (Non-ASCII) characters in the local part of email addresses (everything before the @ character).

    Disabled by default.

    Do not set this property unless your SMTP provider supports UTF-8 characters. Learn more in International email addresses.

  5. To test your configuration, click Send Test Email.

    1. In the Send Test Email dialog box, enter your own email address.

    2. Click Send.

    If the test is successful, you’ll get a test email in your email inbox.

  6. To save the email provider configuration, click Save.

Using the API

You can edit the email service over REST at the openidm/config/external.email endpoint. The following example submits an email configuration over REST:

curl \
--header "Authorization: Bearer <access-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.

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.
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
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
smtpProperties sub-properties
Property Description Required? /
Type Support

mail.smtp.ssl.protocols

The enabled SMTP SSL connection protocols. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

No

Only for smtp type.

mail.smtps.ssl.protocols

The enabled SMTPS SSL connection protocols. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

No

Only for smtp type.

mail.mime.allowutf8

Adds support for UTF-8 (Non-ASCII) characters in the local part of email addresses (everything before the @ character) if set to true.

Do not set this property unless your SMTP provider supports UTF-8 characters. Learn more in International email addresses.

No

Only for smtp type.

Revert the email provider to use the built-in SMTP server

Email provider configuration changes made in one realm are applied to both realms.

If you need to revert the email provider to use the built-in SMTP server:

  1. In the Advanced Identity Cloud admin console, go to Email > Provider.

  2. On the Email Provider page, disable Use my own email provider.

  3. Click Save.

The built-in SMTP server does not support:

Email templates

PingOne Advanced Identity Cloud provides preconfigured email templates for common end-user journeys.

You can customize email templates using Markdown language. Advanced Identity Cloud uses a parser to let you preview your markup.

Email templates utilize Handlebar expressions to reference object data dynamically. For example, to reference the userName of an object:

{{object.userName}}

Create a new email template

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click + New Template.

  3. Provide the following details:

    • Template Name: Display name for the template.

    • From Address: Enter an email address for the group or individual sending the email.

    • From Name: Enter a name for the group or individual sending the email.

    • Description: A brief description of the template.

  4. Click Save. The new email opens in the email editor.

  5. Learn more in Edit an email template.

When you reference an email template, such as in a node or script, you must use the correct format. You can find the correct format for the email template name in the Advanced Identity Cloud admin console URL when editing the template.

For example, the Forgotten Username email template’s name is forgottenUsername:

https://<tenant-env-fqdn>/?realm=alpha#/email/templates/edit/forgottenUsername

Edit an email template

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. To change the wording in the email template, edit the Markdown text in the left window on the page. You can also:

  4. Add, modify, or delete locales to suit your end-user audience. Learn more in Manage email template locales.

  5. Repeat step 3 for each template locale.

  6. To edit the template styles, click Styles, and edit the CSS style code.

  7. To view available variables that you can use in the template, click Variables, and view the content on the Available Properties page. Click Done.

  8. To edit the template settings, click the More () icon at the top right of the page, and select Settings.

  9. Provide the following details:

    • Template Name: Display name for the template.

    • From Address: Enter an email address for the group or individual sending the email.

    • From Name: Enter a name for the group or individual sending the email.

    • Description: Enter a brief description of the template.

  10. Click Update.

  11. Click Save. This saves content changes in all template locales.

Add an image to an email template

  1. Upload your image to a hosted service, such as a content delivery network (CDN), so it is available over HTTPS. Local image paths are not permitted.

  2. In the Advanced Identity Cloud admin console, go to Email > Templates.

  3. On the Email Templates page, click a template name to open the email editor.

  4. Edit the Markdown text to reference your image:

    • To add an image at full size:

      ![alt text](<image url>)

      For example, the Markdown would look like this for an image hosted at https://example.com/image.ext where the alt text is this is an example image:

      ![this is an example image](<https://example.com/image.ext>)

    • To add an image and resize it in pixels:

      ![this is an example image](<https://example.com/image.ext> =100x100)

    • To add an image and resize it as a percentage:

      ![this is an example image](<https://example.com/image.ext> =50%x50%)

  5. Click Save.

Use HTML formatting in an email template

Although you can’t see HTML formatting in the editor, you can use inline HTML to format your email. Learn more in Markdown Syntax: Inline HTML.

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. Edit the Markdown text:

    • Specify HTML tags to format your content. For example:

      <h1>Reset Password</h1>

    • To add a table, include both the <thead> and <tbody> tags; otherwise the table will not convert correctly to Markdown when saved. For example:

      <table>
  <thead>
    <tr>
     <th>Header 1</th>
     <th>Header 2</th>
     <th>Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell Text 1</td>
      <td>Cell Text 2</td>
      <td>Cell Text 3</td>
    </tr>
  </tbody>
</table>

  4. Click Styles, and add CSS styles for the tag to format it as required. For example:

    h1 {
    font-family: Arial, Helvetica, sans-serif;
    color: #f96700;
    background-color: #032b75;
    font-size: 25px;
    padding: 10px;
}

  5. Click Save.

After saving your changes, the inline HTML tags are converted to Markdown, but the CSS styles for the tags persist. The CSS styles apply to all locales.

Alternatively, you can click Advanced Editor and modify the template in HTML. However, if you swap to the Advanced Editor, you cannot change back to Markdown.

Use ESV variables in an email template

You can use ESV variables in email templates to dynamically present different text, images, or links depending on the specific tenant environment.

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

To add ESV variables to an email template, you must use the Advanced Editor. After you have swapped to the Advanced Editor, you cannot change back to Markdown.
Add ESV variables to an email template

  1. Create the ESV variables to use in the email template:

    1. Create the variables using the Advanced Identity Cloud admin console or variables APIs.

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

  2. In the Advanced Identity Cloud admin console, go to Email > Templates.

  3. On the Email Templates page, click a template name to open the email editor.

  4. Click Advanced Editor.

  5. Add the placeholder for one or more ESV variables. For example:

    &{esv.my.variable}

  6. Click Save.

Example

  1. In step 1, add these two ESV variables:

  2. In step 5, add the link and image:

    • Add the link using the ESV placeholder, where the link text is the URL, for example:

      <p>For more information, go to our website: &{esv.test.link}</p>
      You can also add the link using the <a> tag with the href attribute. This is useful if you want to display different link text.

    • Add the image using the ESV placeholder, for example:

      <p>
<img src="&{esv.test.image}">
</p>

    The preview in the left window shows the ESV placeholder and an image placeholder rather than the actual link and image as these are only resolved when the email is sent.

Manage email template locales

You can create email content for different locales. When an email is sent during an end-user journey, Advanced Identity Cloud automatically selects the appropriate email template based on the value of the accept-language header, typically derived from the language set in the end user’s browser.

Use the browser’s developer tools to check the value set in the accept-language header.
When sending email templates, you can use a script to override the language set in the end user’s accept-language header. Use the sendTemplate action in your script and set the language in the params._locale object property. The language specified in the script takes precedence over the end user’s browser language. Learn more in Send email templates using a script.

The locale selector in the top left of the email template editor displays the current template’s locale in the format Locale: code, where code is a ISO-639-1 language code, for example, en or de. Some preconfigured email templates, such as the registration template, already include content for the en (default) and fr locales.

To manage email template locales:

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click a template name to open the email editor.

  3. Switch, add, modify, or delete a locale:

    • To switch locale:

      1. Click Locale: code.

      2. Select a locale.

    • To add a locale:

      1. Click Locale: code.

      2. Click add Add Locale to open the Add Locale modal.

      3. Enter a ISO-639-1 language code in the Code field.

      4. (Optional) Select Make Default to make the new locale the default for this template.

      5. Click Save to add the new locale to the template, populated with a copy of the content from the default locale. The changes apply immediately without saving the main template.

    • To modify a locale:

      1. Click Locale: code.

      2. Click the locale’s edit icon (edit) to open the Edit Locale modal.

      3. To change the locale, enter a ISO-639-1 language code in the Code field.

      4. To make the locale the default locale for the template, select Make Default.

      5. Click Save to close the modal window. Any changes apply immediately without saving the main template.

    • To delete a locale:

      1. Click Locale: code.

      2. Click the locale’s edit icon (edit) to open the Edit Locale modal.

      3. Click Delete Locale to delete the locale and its content. The deletion applies immediately without saving the main template.

Delete an email template

Deleting an email template cannot be undone.

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click the More () icon adjacent to any template.

  3. Select Delete.

  4. In the dialog box, click Delete.

Manage email templates

  1. In the Advanced Identity Cloud admin console, go to Email > Templates.

  2. On the Email Templates page, click the More () icon adjacent to any template, and do any of the following:

    • To disable a template, click Deactivate.

    • To enable a template, click Activate.

    • To duplicate a template, click Duplicate.

      1. In the Duplicate Template window, enter the following details:

        • Template Name: Display name for the template.

        • From Address: Enter an email address for the group or individual sending the email.

        • From Name: Enter a name for the group or individual sending the email.

        • Description: A brief description of the template.

      2. Click Save.

More information

Allow cross-domain requests with CORS

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. In PingOne Advanced Identity Cloud, you can configure CORS to allow browsers from trusted domains to access Advanced Identity Cloud protected resources. For example, you might want a custom web application running on your own domain to get an end-user’s profile information using the Advanced Identity Cloud REST API.

By default, CORS is configured to let the Ping SDKs access Advanced Identity Cloud. You can add additional CORS configurations that let other APIs or SDKs access Advanced Identity Cloud.

cors config

Configure CORS using ESVs

  1. In your development environment:

    1. Use the Advanced Identity Cloud admin console to set up one or more CORS configurations for your environment:

      You can create as many configurations as you need. The active configurations are combined to form the entire set of rules for resource sharing in your environment.

    2. For each CORS configuration:

      • If the acceptedOrigins field contains hard-coded configuration, use the Advanced Identity Cloud REST API to replace the value of the acceptedOrigins field with an ESV array. Learn more in Insert ESV placeholders into CORS configuration.

      • If the acceptedOrigins field already contains an ESV array, no action is needed.

    3. Check that the CORS configuration is working as expected in your development environment.

  2. In your staging environment:

    1. If you created any new ESV arrays in step 1b, create corresponding ESVs with the same names in your staging environment.

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

    3. Check that the CORS configuration is working as expected in your staging environment.

  3. In your production environment:

    1. If you created any new ESV arrays in step 1b, create corresponding ESVs with the same names in your production environment.

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

    3. Check that the CORS configuration is working as expected in your production environment.

Create a new CORS configuration

  1. In your development environment, open the TENANT menu (upper right), and choose Tenant settings.

  2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

  3. Click + New CORS Configuration.

  4. On the New CORS Configuration dialog box, choose a configuration type.

    Ping SDKs

    Choose this option when you want to work with the Ping SDKs.
    Advanced Identity Cloud pre-configures accepted origins, methods, and headers for you. You can modify the configuration in the next step.

    Custom

    Choose this option when you want to use your own SDK, APIs, or other software components.

  5. Click Next.

  6. In the New CORS Configuration dialog box, provide CORS details.

    Name

    Enter a display name. Use only numerals, letters, and hyphens (-).

    Accepted Origins

    Required. Accepted origins that will be allowed to make requests to Advanced Identity Cloud from your application in a cross-origin context. Wildcards are not supported. Each value should be identical to the origin of the CORS request.
    Example: https://myapp.example.com:443

    Accepted Methods

    Defaults are POST and GET. The set of (non-simple) accepted HTTP methods allowed when making CORS requests to Advanced Identity Cloud. Use only uppercase characters.

    Accepted Headers (optional)

    Accepted header names when making requests from the above specified trusted domains.
    Header names are case-insensitive. By default, the following simple headers are explicitly accepted: Cache-Control, Content-Language, ExpiresLast-Modified, Pragma.
    If you don’t specify values for this element, then the presence of any header in the CORS request, other than the simple headers listed above, will cause the request to be rejected.

  7. (Optional) Click Show advanced settings to display further CORS configuration settings:

    Exposed Headers (optional)

    Add the response header names that Advanced Identity Cloud returns.
    The header names are case-insensitive. User agents can make use of any headers that are listed in this property, as well as these simple response headers: Cache-Control, Content-Language, Expires, Last-Modified, Pragma, and Content-Type. User agents must filter out all other response headers.

    Enable Caching

    Max age is the maximum length of time, in seconds, that the browser is allowed to cache the pre-flight response. The value is included in pre-flight responses, in the Access-Control-Max-Age header.

    Allow Credentials

    Enable this property if you send Authorization headers as part of the CORS requests, or need to include information in cookies when making requests.

    When enabled, AM sets the Access-Control-Allow-Credentials: true header.

  8. Click Save CORS Configuration.

Activate or deactivate a CORS configuration

  • To activate or deactivate all CORS configurations:

    1. In your development environment, open the TENANT menu (upper right), and choose Tenant settings.

    2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

    3. On the CORS Configurations page, in the upper right side, click Activate or Deactivate.

  • To deactivate an individual CORS configuration:

    1. In your development environment, open the TENANT menu (upper right), and choose Tenant settings.

    2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

    3. On the CORS Configurations page, find the name of the configuration you want to deactivate.

    4. Click its More () menu, and choose Deactivate.

Edit a CORS configuration

  1. In your development environment, open the TENANT menu (upper right), and choose Tenant settings.

  2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

  3. On the CORS Configurations page, find the name of the configuration you want to edit.

  4. Click its More () menu, and choose Edit.

View CORS configurations

  1. Open the TENANT menu (upper right), and choose Tenant settings.

  2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

TLS, secrets, signing, trust, and encryption

PingOne Advanced Identity Cloud was built with security in mind:

This page describes the default implementations for each of these security factors. It also describes customization options, if they’re available.

TLS encryption

By default, your Advanced Identity Cloud tenant uses Google-managed certificates for TLS encryption.

If you prefer, Advanced Identity Cloud lets you use your own, self-managed certificates instead of using the Google-managed certificates.

Learn more about configuring your tenant to use a self-managed certificate in Self-managed certificates.

Secrets

When you configure Advanced Identity Cloud, the secrets you provide in your development environment normally don’t change when you promote your environment to staging and production. However, 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. However, you need Advanced Identity Cloud to use different credentials depending on whether it’s accessing the OTP provider from the development, staging, or production environment.

Environment secrets and variables (ESVs) let you configure different secrets in your Advanced Identity Cloud development, staging, and production environments. In the preceding example, instead of hard-coding a single set of credentials for the OTP provider in the Advanced Identity Cloud admin console, you could configure ESVs that hold the credentials. Then, the desired credentials to the OTP provider would be used depending on which Advanced Identity Cloud environment was running.

Learn more in Define and promote an ESV.

Signing keys and certificates

By default, Advanced Identity Cloud generates a set of secret labels in each Advanced Identity Cloud realm. Each secret label corresponds to functionality in Advanced Identity Cloud that requires a signing key or certificate. For a full list of secret labels, learn more in Secret labels.

Advanced Identity Cloud lets you override the generated secret labels. First, create an ESV secret that holds the key or certificate. Then, map the secret in the secret store of the desired realm.

Learn more in Use ESVs for signing and encryption keys.

Trust relationships with SAML 2.0 providers

If your Advanced Identity Cloud tenant has trust relationships with one or more SAML 2.0 providers, the tenant might receive SAML assertions signed by a certificate. The certificate might itself be signed by a certificate authority (CA). For Advanced Identity Cloud to trust this type of SAML assertion, the CA’s public certificate must be installed in Advanced Identity Cloud.

You can add a CA’s public certificate to your Advanced Identity Cloud configuration by creating a support case in the Ping Identity Support Portal.

Encrypted data at rest

In Advanced Identity Cloud, your tenant includes a unique data encryption key. All Advanced Identity Cloud data that’s stored at rest is encrypted with this key.

You cannot use your own encryption key to encrypt Advanced Identity Cloud data.

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 console (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 Configure customer-friendly domain names.

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 console, 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 Sign on to a tenant admin console.

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 console:

  • 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

Configure customer-friendly domain names

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 console continues to display the default tenant environment URL.

  • Don’t use your top-level domain name. This is because you must set up a CNAME record for each custom domain, but CNAME records aren’t permitted alongside other record types, including any A, NS, TXT, or SOA record types that belong to a top-level domain.

    • Wrong: mycompany.com

    • Right: id.mycompany.com

    Learn more in section 2.4 of RFC 1912.

  • 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 admin console

  1. Choose one of these options:

  2. In the Advanced Identity Cloud admin console, 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 admin console 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, open a support case to deactivate CNAME record verification.

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

  2. Click Create a case.

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

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

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Tenant Settings

    What version of the product are you using?

    Select NA

    Which component is affected?

    Select Custom Domains

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

    Field Value

    Provide a descriptive title for your issue

    Enter Disable CNAME record verification for a custom domain.

    Describe the issue below

    Enter your custom domain FQDN.

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

Learn more in Control cookie scope for custom domains.

Advanced Identity Cloud lets you configure the cookie domains of your custom domains so you can control which applications have access to the cookies you create.

By default, when you add a custom domain to an environment, no cookie domain is set for it. You must explicitly configure its cookie domain to suit your deployment. You can configure it in these ways:

  • Set it to use a single subdomain (for example, sso.mycompany.co.uk). This ensures cookies can be set or modified only by applications running on that subdomain.

  • Set it to use more than one subdomain. This lets you set cookies on one subdomain (for example, sso.mycompany.co.uk) but makes them available to an application running on a different subdomain (for example, banking.mycompany.co.uk).

  • Set it to use a domain (for example, mycompany.co.uk). This lets you set cookies at the domain level so they’re available to legacy applications yet to be migrated to Advanced Identity Cloud.

Learn how to set cookie domains in:

Advanced Identity Cloud always writes cookies to the default tenant environment FQDN of each of your environments. This is not configurable to ensure you retain access to your environments.

You can find background information on cookie domains in PingOne Advanced Identity Cloud in Control cookie scope for custom domains.

Advanced Identity Cloud provides the Cookie Domains API endpoint to manage cookie domains.

To authenticate to the cookie domain API endpoint, use an access token created with the following scope:

Scope Description

fr:idc:cookie-domain:*

Full access to the cookie domain API endpoint.

Advanced Identity Cloud always writes cookies to your default tenant FQDN to ensure you retain access. Make a GET request to the /environment/cookie-domain endpoint to view the other domains or subdomains where your tenant environment writes cookies.

To view the cookie domain configuration in any tenant environment:

  1. Get an access token created with the fr:idc:cookie-domain:* scope.

  2. Get the cookie domain configuration from the /environment/cookie-domains endpoint:

    $ curl \
--request GET 'https://<tenant-env-fqdn>/environment/cookie-domains' \(1)
--header 'Authorization: Bearer <access-token>' (2)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token.
    Show response 
    {
    "domains": [
        "sso.mycompany.co.uk",
        "banking.mycompany.co.uk"
    ]
}

Advanced Identity Cloud always writes cookies to your default tenant FQDN to ensure you retain access. Make a PUT request to the /environment/cookie-domain endpoint to set or update the other domains or subdomains where your tenant environment writes cookies.

To update the cookie domain configuration in any tenant environment:

  1. Review the existing cookie domain configuration. Learn more in in View cookie domains.

  2. Adapt the cookie domain configuration to suit your use case. Learn more in Control cookie scope for custom domains.

    If you intend to remove a domain or subdomain from the configuration, you must first update any existing applications that rely on cookies set using that domain or subdomain.

  3. Get an access token created with the fr:idc:cookie-domain:* scope.

  4. Replace the existing cookie domain configuration with the cookie domain configuration you adapted in step 2:

    $ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/cookie-domains' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json' \
--data '<cookie-domains-configuration>' (3)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token.
    3 Replace <cookie-domains-configuration> with a JSON array of cookie domains; for example, the following configuration adds a new subdomain account.mycompany.co.uk to the configuration example used in View cookie domains. 
    {
    "domains": [
        "sso.mycompany.co.uk",
        "banking.mycompany.co.uk",
        "account.mycompany.co.uk"
    ]
}
    Show response 
    {
    "domains": [
        "sso.mycompany.co.uk",
        "banking.mycompany.co.uk",
        "account.mycompany.co.uk"
    ]
}

    An asynchronous process updates the environment’s cookie domain configuration. This process can take up to 10 minutes to complete.

You can find background information on cookie domains in Control cookie scope for custom domains.

Advanced Identity Cloud always writes cookies to your default tenant FQDN to ensure you retain access. Use the Advanced Identity Cloud admin console to view or edit the other domains or subdomains where your tenant environment writes cookies.

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

  2. Click settings Tenant Settings.

  3. Click Global Settings, then click Cookie.

  4. Review the cookie domains configured in the Additional Cookie Domains field:

    • Each cookie domain is displayed in the field as a tag:

      cookie domains field

    • To add a cookie domain:

      1. Click inside the Additional Cookie Domains field to give it focus and display a text prompt below the tags.

      2. Enter a cookie domain value (for example, account.mycompany.co.uk).

      3. Click an area outside the text prompt (or press enter) to create a tag for the new cookie domain value.

    • To delete a cookie domain, click the close icon (close) on the right of the cookie domain’s tag.

      If you intend to remove a domain or subdomain from the configuration, you must first update any existing applications that rely on cookies set using that domain or subdomain.

  5. If you made changes in the previous step, click Save to confirm them.

    An asynchronous process updates the environment’s cookie domain configuration. This process can take up to 10 minutes to complete.

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

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

Register an application or service

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

    Sign-out URLs

    Custom URL for handling logout. Example: https://client.example.com:8443/am/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).

Task 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 native admin 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 self-managed admin console, 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>/am/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 native admin 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 self-managed admin console, 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 native admin console, go to Identities and add a user identity.

    2. IDP: In the AM self-managed admin console, go to Identities and add a user identity.

Task 2: Create an SP circle of trust

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

    1. In the AM native admin 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 native admin 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 native admin 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.

Task 3: Create an IDP circle of trust

  1. In the AM self-managed admin console, 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.

Task 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. PingGateway 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, PingGateway intercepts client requests and server responses. In this process, PingGateway enforces user or service authentication and authorization to HTTP traffic. Advanced Identity Cloud acts as the authentication and authorization provider.

PingGateway 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 console, 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:

      • In the Forbidden Realm realm - User attributes list, select user attributes to validate passwords against.

      • In the Minimum n characters for each attribute field, enter a substring length between 3 - 64 to use when validating passwords against user attribute values. The default is 5 characters.

    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 [7]

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

Example query on passwordLastChangedTime
curl \
--header "Authorization: Bearer <access-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"
    }
  ],
  ...
}

Journey nodes

This page lists the authentication nodes to use in PingOne Advanced Identity Cloud journeys.

Even though they appear in the UI, the following nodes are incompatible with Advanced Identity Cloud and their reference documentation isn’t provided:

Basic authentication nodes

Use the following nodes for basic authentication tasks:

Multi-factor authentication nodes

Use the following nodes to configure journeys with multi-factor authentication capabilities:

Risk management authentication nodes

Use the following nodes to examine the perceived risk and act on it:

Behavioral authentication nodes

Use the following nodes to adjust the behavior of authentication journeys:

Contextual authentication nodes

Use the following nodes to change the journey or set a cookie based on the authentication context:

Federation authentication nodes

Use the following nodes to configure journeys with federation capabilities:

Identity management authentication nodes

Use the following nodes to perform identity management during an authentication journey:

Utility nodes

Use the following nodes to perform various tasks during the journey:

Uncategorized nodes

Marketplace nodes

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.

The following table describes how you can configure journeys to customize the authentication experience for end users.

Task Resources

Modify the layout and appearance of journeys.

Use the Advanced Identity Cloud hosted pages.

Modify the journey templates.

Create a custom journey.

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

Set a default journey.

Configure Advanced Identity Cloud to display a default journey to end users.

Create journeys based on device context.

Use the Ping SDKs to configure device profiling authentication.

Customize the outcome of an authentication journey with JavaScript.

Use the auth scripting editor to create and manage scripts that run during the course of the authentication journey. You can create and include script types such as the following:

Learn more in auth script types.

Configure an application journey

Associate an authentication journey with a SAML 2.0 app or an OAuth 2.0/OIDC app to let users authenticate with a specific journey as part of the federation process.

Learn more in:

Always run journeys

When you create a journey, you have the option to configure the journey to always run.

This setting lets you enforce journeys to always run regardless of any existing user sessions or whether the journey is initiated over REST or by redirect.

Enable this option when you create custom journeys.

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 console, 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 Journey nodes.

  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 console, 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 Journey nodes.

  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 console, 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 Journey nodes.

  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 console, 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 Journey nodes.

  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 console, 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 Journey nodes.

  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 console, 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 Journey nodes.

  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 console, 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. (Optional) Enable journey options:

    • Default journey for end users: Sets this journey as the default.

    • Override theme: Specify a custom theme for this journey.

    • Run journey for all users regardless of current session: Configure the journey to execute regardless of any existing user sessions or whether the journey is initiated over REST or by redirect. Always running a journey doesn’t necessarily require the user to authenticate every time.

      For example, if you configure an authentication journey to first check for a valid session and a known device profile, the user could proceed directly to the successful outcome as long as they pass the checks. Alternatively, configure a journey to require multi-factor authentication every time.

      You can’t configure a journey to always run when it’s set as the default journey.

      Also, to prevent unexpected behavior in the authentication flow, don’t configure a journey to always run when it’s mapped to the default ACR.

      Learn more in Configure an authentication journey to always run.

    • Inner Journey: Prevent the journey from being used outside of its parent journey.

      Learn more in Disable direct access through a child journey.

  5. Click Create journey.

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

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

    Learn about all available nodes in Journey nodes.

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

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

Default journey

Advanced Identity Cloud displays the default journey 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 console, click Journeys > 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 console, click Journeys to view the list of journeys.

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

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 console, 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 console, go to Journeys.

  2. Check the checkbox beside one or 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 console, 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.

Delete journeys

Deleting a journey is a permanent operation. You won’t be able to retrieve it after it’s deleted.

Delete a journey in the following ways:

  • In the Advanced Identity Cloud admin console, go to Journeys, and check the checkbox beside one or more journeys. Click Delete Journeys.

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

You can’t delete a journey if it’s referenced by a SAML 2.0 app or an OAuth 2.0 client.

More information

Debug 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 console, 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 console:

    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 node in the journey. Because debug nodes can change the state of node information, inserting them between each node in the journey can cause a problem if a later node expects to access information in a specific state.

An example is when a node adds a password to transient state. The following debug node reads that password from transient state, which removes it. The next node in the journey expects to read the password from transient state, and when it tries to do so, this fails and causes an error.

Journey solutions

The Ping Identity Marketplace includes prebuilt sample journeys for PingOne Advanced Identity Cloud, all certified by Ping Identity. These journeys provide a starting point for common identity use cases, helping you accelerate journey development. You can download and use them as templates to create your own user journeys.

Threat detection with PingOne Protect

Incorporate threat detection into an Advanced Identity Cloud journey. This journey uses PingOne Protect to analyze user behavior and location, prompting for step-up authentication or blocking access when high-risk activity is detected.

Sign on (login) with self-service

Incorporate social sign-on and progressive profiling into an Advanced Identity Cloud journey. This journey demonstrates how to incorporate social sign-on, self-service registration, and progressive profiling to gather user information over time.

Threat detection with PingOne Protect

To protect against threats such as fraudulent sign-on attempts, you can incorporate threat detection into your PingOne Advanced Identity Cloud authentication journeys. The Ping Identity Marketplace includes a prebuilt authentication journey with threat detection that uses PingOne Protect to enable real-time monitoring of risk indicators, such as unusual login locations, device irregularities, or anomalous user behavior.

You can download this journey and import it into your Advanced Identity Cloud tenant. This guide details all the prerequisites and necessary configuration steps for using the journey.

This solution provides a sample journey as a template. Review and adapt it to meet your organization’s specific security policies and business requirements before deploying to a production environment.
Journey download
Journey name Version Download

Authentication Journey with Threat Detection

2.0

Download from Marketplace

Learn more about Threat detection using PingOne Protect.

About the threat detection journey

This solution uses a parent journey and inner journeys to evaluate the risk level of a user’s sign-on attempt.

Example use case

A company needs to identify and prevent fraudulent authentication when an end user attempts to sign on from an unusual geographical location. The goal is to reduce fraud while ensuring a frictionless experience for legitimate users.

With the Advanced Identity Cloud authentication with threat detection journey, the user’s geographical location is evaluated as part of a real-time threat detection process. If a user attempts to sign on from a location that exceeds a defined radius from the user’s expected location, it’s considered medium or high risk, depending on the extent of the deviation. The user is either prompted to step up with multi-factor authentication (MFA) or is denied access. If authentication is blocked or requires further verification, the user is notified by email or SMS to confirm that the attempt was legitimate.

Journey components

The threat detection journey includes one parent journey and seven inner journeys that work together to handle the authentication and threat detection flow.

Journey Description Configuration required?

Threat Detection Journey with PingOne Protect (parent journey)

Orchestrates the overall flow. It initializes variables, presents the sign-on page, calls the appropriate inner journeys, and records the final outcome for machine learning.

Yes

Threat Detection - Inner Journey

Uses the PingOne Protect nodes to initialize the SDK, capture user behavior signals, and evaluate risk.

Yes

MFA Device Registration - Inner Journey

Manages the flow for registering a new MFA device, if required.

Yes

MFA Authentication - Inner Journey

Handles the MFA challenge when a user needs to step up their authentication.

Yes

OATH Registration - Inner Journey

Sets the registration flow for OATH-based MFA.

No

Push MFA Method Registration - Inner Journey

Sets the registration flow for push-based MFA.

No

WebAuthn MFA Method Registration - Inner Journey

Sets the registration flow for WebAuthn-based MFA.

No

Combined OATH And PUSH MFA Methods Registration - Inner Journey

Sets the registration flow for OATH and push MFA.

No
Show the Threat Detection Journey with PingOne Protect (parent journey)
sample threat detection pingone protect journey

  • a A Scripted Decision node containing the initialize variables used in the authentication flow.

  • b The first call to the PingOne Protect Threat Detection - Inner Journey

  • c The second call to the PingOne Protect Threat Detection - Inner Journey for risk evaluation

  • d A call to the MFA Authentication - Inner Journey

  • e A call to the MFA Device Registration - Inner Journey

Task 1: Prepare your tenant environment

First, ensure you have the necessary prerequisites, then perform the required setup tasks in your tenant environment.

Before you begin

To implement the sample threat detection journey, you must have:

Setup tasks

To get the journey working, you’ll first need to perform some setup tasks in your Advanced Identity Cloud tenant environment.

Add custom attributes to the alpha_user managed object

Several additional user attributes are required by the threat detection user journey. These attributes store information about the user’s verified email, geographical location, operating system (OS), and MFA devices.

Add the following custom attributes to the alpha_user managed object. Learn more in Customize user identities using custom attributes.

Name Label Type Description

custom_emailVerified

Email verified

String

Confirms the user has verified their email address.

custom_protectActivityCity

PingOne Protect activity city

String

The city from which the user attempts to authenticate. This attribute is used in the Account Disabled and Suspicious Activity email templates.

custom_protectActivityState

PingOne Protect activity state

String

The state from which the user attempts to authenticate. This attribute is used in the Account Disabled and Suspicious Activity email templates.

custom_protectDeviceOS

PingOne Protect device OS

String

The OS of the device from which the user attempts to authenticate.

custom_mfaDevices

MFA devices

Array

Sets, fetches, and displays the user’s registered MFA devices.

custom_latestMFADevice

Latest used MFA device

String

The most recent MFA device registered by the user, used in the Device Registration FIDO email template.
(Optional) Set an ESV variable for PingOne Protect analysis

The Prerequisites & Init Variables node in the parent journey contains a script that uses the protectAnalysisRequired variable to determine if PingOne Protect analysis is enabled. By default, this variable is set to true within the script. To override this variable and control how PingOne Protect analysis is performed in different environments, you can set an Environment Secret & Variable (ESV) variable.

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

  2. Click the Variables tab.

  3. Click + Add Variable.

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

    Name

    p1-protect-analysis-required

    Type

    string

    Description (optional)

    PingOne Protect analysis required

    Value

    true

  5. Click Save to create the variable.

  6. Restart Advanced Identity Cloud services by applying updates in the Advanced Identity Cloud admin console.

Create the email templates

You’ll need to create the following email templates, which are used by Scripted Decision nodes to send emails at various points in the threat detection journey.

Email template Description Example email body

accountDisabled

Email sent when PingOne Protect detects critical risk associated with the account.
Show example 
<div style="display:block;width:400px;margin:0 auto;font-family:sans-serif;border:1px solid #c5c5c5;padding:30px 20px;text-align:center">
<img src="https://assets.pingone.com/ux/ui-library/5.0.2/images/logo-pingidentity.png" alt="Company Logo" style="height:65px;margin-bottom:10px" />
<div style="display:block">
<div style="display:inline-block;width:40px;height:40px;border-radius:50%;background-color:red;color:white;font-size:24px;line-height:40px;text-align:center">!</div>
<h2 style="margin-top:10px;margin-bottom:10px">Sign-in Attempt was blocked</h2>
<p>{{object.mail}}</p>
<hr style="width:100%;margin-top:20px;margin-bottom:25px;border:none;border-top:1px solid #c5c5c5" />
</div>
<div style="text-align:left">
<p id="alertText">Someone just attempted to sign onto your account nearby {{object.custom_protectActivityCity}}, {{object.custom_protectActivityState}}. We have disabled the account for your security. If this was you, please contact support.</p>
<p>Thanks,
      <br />The ${Brand Name} tea
    </p>
  </div>
</div>

deviceRegistration

Email sent when the user registers a new MFA device.
Show example 
<div style="display:block;text-align:center;font-family:'Arial',
  sans-serif;background-color:#f7f7f7;border:1px solid #e3e3e3;border-radius:10px;box-shadow:0 4px 8px rgba(0, 0, 0, 0.1);width:400px;margin:20px 20px;padding:30px 20px">
  <img src="https://assets.pingone.com/ux/ui-library/5.0.2/images/logo-pingidentity.png" alt="Company Logo" style="height:65px;margin-bottom:10px" />
  <h2 style="color:#333;font-size:24px;margin:20px 0">Sign On Device Added </h2>
  <p style="margin:20px 0 20px;font-size:16px;color:#555">The following device was successfully added to your
    account and can be used to authenticate. </p>
  <p style="margin:20px 0 20px;font-size:20px;color:#222">{{object.custom_latestMFADevice}}</p>
  <p style="margin:20px 0 20px;font-size:16px;color:#555">If you added this device, no further action is needed. </p>
  <p style="margin:20px 0 20px;font-size:16px;color:#555">If this device wasn't added by you, consider resetting
    your password to secure your account. </p>
</div>

suspiciousActivity

Email sent when PingOne Protect detects some risk associated with the account.
Show example 
<div style="display:block;width:400px;margin:0 auto;font-family:sans-serif;border:1px solid #c5c5c5;padding:30px 20px;text-align:center">
  <img src="https://assets.pingone.com/ux/ui-library/5.0.2/images/logo-pingidentity.png" alt="Company Logo" style="height:65px;margin-bottom:10px" />
  <div style="display:block">
    <div style="display:inline-block;width:40px;height:40px;border-radius:50%;background-color:red;color:white;font-size:24px;line-height:40px;text-align:center">!</div>
    <h2 style="margin-top:10px;margin-bottom:10px">Sign-in attempt detected</h2>
    <p>{{object.mail}}</p>
    <hr style="width:100%;margin-top:20px;margin-bottom:25px;border:none;border-top:1px solid #c5c5c5" />
  </div>
  <div style="text-align:left">
    <p id="alertText">Someone just attempted to sign onto your account nearby {{object.custom_protectActivityCity}}, {{object.custom_protectActivityState}}. If this was not you, please consider resetting your password or contact support. Otherwise, ignore.</p>
    <p>Thanks,
      <br />The ${Brand Name} team
    </p>
  </div>
</div>

welcome

Email sent when a new user account is created.
Show example 
<html>
  <head></head>
  <body style="background-color: #324054; color: #5e6d82; padding: 60px; text-align: center;">
    <p>Welcome. Your username is '{{object.userName}}'.</p>
  </body>
</html>

otp

Email containing the user’s one-time passcode (OTP).
Show example 
<html>
  <head></head>
  <body style="background-color: #324054; color: #455469; padding: 60px; text-align: center;">
    <div class="content" style="background-color: #fff; border-radius: 4px; margin: 0 auto; padding: 48px; width: 235px;">
      <p>
        <img src="https://www.pingidentity.com/content/dam/picr/nav/Ping-Logo-2.svg" alt>
        </p>
        <p>Hi {{object.givenName}}</p>
        <p>Here is your One Time Password. Please enter it into the login browser window:</p>
        <h1 id="objectotp">{{object.otp}}</h1>
        <p>PingOne Advanced Identity Cloud</p>
      </div>
    </body>
  </html>

Lean more about creating email templates in Email templates.

Create a logger library script for OTP

If you’re using OTP emails in your journey flow, you must create a library script. This script creates a logger, which is needed for OTP functionality to track and debug the process of sending OTP emails.

  1. In the Advanced Identity Cloud admin console, go to Scripts > Auth Scripts, then click + New Script.

  2. Select Other > Library and click Next.

  3. Enter a script name and description, and paste the following script into the JavaScript field:

    function XLogger(env) {
              this.logger = env.logger;
              this.scriptName = env.scriptName;
              this.logPrefix = "***" + env.scriptName + ": ";
              this.debug("logger initialised");
            }
            XLogger.prototype.debug = function (message) {
              this.logger.debug(this.logPrefix.concat(message));
            };
            XLogger.prototype.warn = function (message) {
              this.logger.warn(this.logPrefix.concat(message));
            };
            XLogger.prototype.error = function (message) {
              this.logger.error(this.logPrefix.concat(message));
            };
            module.exports.XLogger = XLogger;

  4. Click Save to save the script.

Task 2: Download and import the journey

Download the journey

  1. Go to Authentication Journey with Threat Detection on the Ping Identity marketplace.

  2. Click Download Integration to download a file called Authentication Journey with Threat Detection.json. This JSON file contains the parent journey and inner journeys, scripts, and email templates required for the authentication flow.

Import the journey

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

  2. Click either Download Backup or Skip Backup. Learn more in Import journeys.

  3. On the Import Journeys page, browse to and select Authentication Journey with Threat Detection.json.

  4. Select Alpha realm users because the journey is configured for the alpha realm.

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

    • Overwrite all conflicts (default)

    • Manually pick conflict resolution

  6. Click Next.

  7. Click Start Import.

  8. On the Import Complete page, click Done.

  9. On the left panel of the Journeys page, click Threat Detection (8) to view the threat detection journeys and inner journeys.

Threat detaction journeys

Task 3: Configure the journey components

Configure the Threat Detection Journey with PingOne Protect (parent journey)

  1. On the Journeys page, click Threat Detection Journey with PingOne Protect and click Edit.

  2. In the journey editor, configure the journey as follows:

    1. Review and set the initialize variables.

    2. If you have configured social identity providers other than Google and Facebook, enable social identity providers.

  3. Click Save.

To save your progress, periodically click Save in the top right of the journey editor. Failure to do this results in losing your work if the page reloads or if you lose your network connection.
Review and set the initialize variables

The Threat Detection Journey with PingOne Protect includes a Scripted Decision node containing the initialize variables used later in the authentication flow. This script lets you:

  • Set the allowed MFA types: FIDO2, OATH, PUSH, EMAIL, SMS, VOICE.

  • Enable or disable PingOne Protect analysis.

  • Enable or disable magic link.

To review and set the initial variables:

  1. Click the Prerequisites & Init Variables node.

  2. In the Script field, click the Pencil icon () to open the Threat Detection - Initialize Variables script.

  3. Review the script and make changes if needed.

  4. Click Save and Close.

You don’t need to update the values in the Script Outputs field of the Prerequisites & Init Variables node.
Enable social identity providers

  1. Click the Page node and then click the Select Identity Provider node.

  2. In the Filter Enabled Providers field, add or remove the social identity providers as needed. Only the social identity providers listed here will be presented to the end user when signing on.

    The social provider names must exactly match the names in your social authentication configuration, including the case.

  3. Click Save.

Configure the Threat Detection - Inner Journey

  1. On the Journeys page click Threat Detection - Inner Journey and click Edit.

  2. In the journey editor, configure the journey as follows:

    1. Click the PingOne Protect Initialize node.

    2. In the PingOne Worker Service ID field, select the ID of the PingOne worker service for connecting to PingOne. Learn more in PingOne Protect Initialize node.

    3. Click the Auth: PingOne Protect Evaluation node and enter the following:

      • PingOne Worker Service ID: Select the ID of the PingOne worker service for connecting to PingOne.

      • (Optional) Risk Policy Set ID: Enter the ID of the risk policy in PingOne. Learn more in PingOne Protect Evaluation node

    4. Click the Reg: PingOne Protect Evaluation node and enter the following:

      • PingOne Worker Service ID: Enter the ID of the PingOne worker service for connecting to PingOne.

      • (Optional) Risk Policy Set ID: Enter the ID of the risk policy in PingOne. Learn more in PingOne Protect Result node.

  3. Click Save.

Configure the MFA Device Registration - Inner Journey

This configuration is required if SMS or VOICE are opted in the allowedMFATypes array in the Threat Detection - Initialize Variables script in the Prerequisites & Init Variables node in the parent journey.

  1. On the Journeys page, click MFA Device Registration - Inner Journey and click Edit.

  2. In the journey editor, update the required fields in the following nodes:

  3. Click Save.

Configure the MFA Authentication - Inner Journey

This configuration is required if EMAIL, SMS, or VOICE are opted in the allowedMFATypes array in the Threat Detection - Initialize Variables script in the Prerequisites & Init Variables node in the parent journey.

  1. On the Journeys page, click MFA Authentication - Inner Journey and click Edit.

  2. In the journey editor, update the required fields in the following nodes:

  3. Click Save.

Task 4: Validate the journey

There are various paths the end user might go down, depending on the PingOne Protect risk evaluation and the MFA methods configured in the journey. For example, a user identified as low risk can sign on without MFA. However, for medium or high-risk sign-on attempts, the journey prompts the user to choose an MFA method, which could involve registering a new device. If a user signing on for the first time is identified as high risk, the registration attempt is blocked.

Before validating the journey, make sure you have a test user in the alpha realm. To authenticate using an OTP, the user must have a registered authenticator app.

Test a medium-risk sign-on

These steps demonstrate a sign-on attempt by an end user identified as medium risk.

  1. In the Advanced Identity Cloud admin console, go to Journeys and click Threat Detection Journey with PingOne Protect`.

  2. In the Preview URL field, click copy and paste the URL into an incognito window.

    The Advanced Identity Cloud end-user UI displays the Sign In screen.

    Threat detaction journey sign in screen

  3. Enter the test user’s username and password and click Next.

    A page displays prompting the user to select their preferred authentication method for MFA.

  4. Select OATH and click Next.

    Select MFA method

  5. Enter the OTP from the test user’s app, and click Submit

    Select MFA method

    You are signed on to the Advanced Identity Cloud end-user UI as the test user.

Best practices

This sample journey provides a strong foundation for threat detection. When preparing to use it in a production environment, consider the following best practices:

  • Treat as a template: Remember that this is a sample journey. Always adapt and harden it to meet your specific security policies and business requirements before deploying to production.

  • Use Environment Secrets & Variables (ESVs): Avoid hardcoding sensitive information like API keys and IDs directly in your journey scripts. Use ESVs to manage these values securely.

  • Test extensively: Validate all possible user paths, including low, medium, and high-risk scenarios, as different MFA registration and authentication flows. Ensure the user experience is smooth and the security responses are correct for each case.

  • Review PingOne Protect policies: Fine-tune your risk policies in PingOne Protect to align with your organization’s risk tolerance.

Sign on (login) with self-service

Incorporate self-service into your Advanced Identity Cloud journeys to let end users create and manage their own accounts, while you control the available features.

The Ping Identity Marketplace includes a prebuilt login with self-service journey. This sample journey lets end users sign on using a social identity provider (IdP), such as Google or Facebook, or the username and password of an account in the Advanced Identity Cloud datastore. If the end user doesn’t already have an account, they can create one using their social identity credentials.

The journey also includes progressive profiling. On their third successful sign-on attempt, end users are prompted to review their marketing preferences.

You can download the sample journey and import it into your Advanced Identity Cloud tenant. You can then modify the journey as needed to meet your requirements.

Example use case

A company wants to simplify sign-on and reduce friction by allowing end users to sign on with their Google or Facebook accounts. Additionally, they want to remind end users to review their preferences for receiving news and special offers, ensuring more personalized experiences while staying compliant with data protection regulations.

Before you begin

To implement the sample journey, you must have:

  • Tenant administrator access to your Advanced Identity Cloud development environment.

  • Social authentication configured in your Advanced Identity Cloud environment. Learn more in Social authentication.

    The sample journey uses Google and Facebook for social sign-on, but you can configure and enable any of the supported social IdPs.

  • A basic understanding of journeys.

  • A test end user in the alpha realm. Learn more in Create test users and roles.

Tasks

Task 1: Download the sample journey

  1. In the Ping Identity Marketplace, go to Login with Self-Service Journey.

  2. Click Download to download the Login with Self-Service Journey.json file. This JSON file contains the journeys and scripts required for the authentication flow.

Task 2: Import the sample journey into Advanced Identity Cloud

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

  2. Click either Download Backup or Skip Backup. Learn more in Import journeys.

  3. On the Import Journeys page, browse to and select Login with Self-Service Journey.json.

  4. Select Alpha realm - Users because the journey is configured for the Alpha realm.

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

    • Overwrite all conflicts (default)

    • Manually pick conflict resolution

    The progressive profile journey in the download matches the default journey included with Advanced Identity Cloud. If you’ve modified the default journey and want to retain your changes, select Manually pick conflict resolution and ensure it isn’t overwritten.

  6. Click Next.

  7. Click Start Import.

  8. On the Import Complete page, click Done.

  9. On the left panel of the Journeys page, click Login to view the imported journeys:

Login with self-service journey

The Login with self-service journey lets end users sign on using either a social IdP (such as Google or Facebook) or by entering their username and password. If they don’t already have an Advanced Identity Cloud account, end users can create one using their social identity credentials. During this process, they must create a local password and accept the current terms and conditions.

The journey includes an Inner Tree Evaluator node that links to a progressive profile journey. With this journey, end users are prompted to review and update their marketing preferences on their third successful login.

Login with self-service journey

The Login with self-service journey uses the following nodes:

Node Description

Page node

Combines the following nodes onto a single page for display to the user:

Social Provider Handler node

Attempts to authenticate a user with an IdP they selected in the Select Identity Provider node.

Attribute Present Decision node

Checks the specified identity resource in the underlying identity service and determines if all attributes required to create the specified object exist within the shared node state.

Page node

Combines the following nodes onto a single page for display to the user if they entered the required attributes:

Page node

Combines the following nodes onto a single page for display to the user if they didn’t enter the required attributes:

  • Attribute Collector node. This node is configured to collect required attributes for mail, sn, and givenName. You can reconfigure the node to collect different attributes as required.

  • Validate Input node. This Scripted Decision node validates the inputs entered by the user and disables the Next button if the required input fields are empty.

  • Accept Terms and Conditions node. Prompts the user to accept or reject the currently active Terms and Conditions. Learn more in Terms and Conditions.

Data Store Decision node

Checks that the credentials provided during local authentication match the ones stored in the realm datastore.

Increment Login Count node

If an account already exists for the user, increments the successful sign-on count property.

Inner Tree Evaluator node

Initiates the progressive profile inner journey. Learn more in Progressive profile.

Create Object node

Creates the user’s account.

Validation

This validation step demonstrates multiple sign-ons by an end user using their Advanced Identity Cloud username and password. On the third sign-on attempt, the end user is prompted to review and confirm their marketing preferences.

Steps

  1. In the Advanced Identity Cloud admin console, go to account_tree Journeys and click Login with self-service.

  2. In the Preview URL field, click copy and paste the URL into an incognito window.

    The Advanced Identity Cloud end-user UI displays the Sign On screen.

    Sign on with self service

  3. Enter the test end user’s username and password, and click Next.

    You are signed on to the Advanced Identity Cloud end-user UI as the test end user.

  4. Sign out of the Advanced Identity Cloud end-user UI:

    1. Click the test end user’s name in the upper-right corner of the Advanced Identity Cloud end-user UI.

    2. Select Sign Out.

      The page you’re directed to when you sign out is the default journey in the realm, not the Login with self-service journey. Learn more in Journeys.

  5. Repeat steps 1 - 4 to sign on and sign out a second time.

  6. Repeat steps 1 - 3 to sign on a third time. On the third sign-on attempt, you’re presented with a page for selecting preferences for receiving news and special offers.

    Select marketing preferences

  7. Select the test end user’s marketing preferences and click Next to sign on to the Advanced Identity Cloud end-user UI.

    • If the end user makes no selection, the reminder expires and isn’t displayed again.

    • If the end user selects one or more options, the preferences are set in the end user’s profile.

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 these attributes:

      • givenName

      • mail

      • passwordLastChangedTime

      • passwordExpirationTime

      • sn

      • userName

    • 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 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.
Create user identity custom attributes

To create a user identity custom attribute:

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

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

Access user identity custom attributes in scripts

To access a user identity custom attribute called custom_department in a Scripted Decision node:

  1. Configure the Identity Store Decision node:

    1. Make sure the Identity Store Decision node is placed before the Scripted Decision node in your journey.

    2. Select the Username as Universal Identifier checkbox in the Identity Store Decision node’s configuration. This ensures that the user’s UUID is stored in the username node state variable.

  2. Edit the script used by the Scripted Decision node:

    • To access the custom attribute using access management script functions, use the attribute fr-idm-custom-attrs. This contains a JSON object of all custom attributes, so it needs to be parsed to access individual attributes.

      • Next-generation

      • Legacy

      If your script uses the next-generation script engine:

      var uuid = nodeState.get('username');
var customAttrsRaw = idRepository.getIdentity(uuid).getAttributeValues('fr-idm-custom-attrs')[0];
var customAttrs = JSON.parse(customAttrsRaw);
var department = customAttrs.custom_department;

      If your script uses the legacy script engine:

      var uuid = nodeState.get('username').asString();
var customAttrsRaw = idRepository.getAttribute(uuid, 'fr-idm-custom-attrs').toArray()[0];
var customAttrs = JSON.parse(customAttrsRaw);
var department = customAttrs.custom_department;

      Learn more in Access profile data.

    • To access the custom attribute using identity management script functions, use the specific attribute name custom_department.

      • Next-generation

      • Legacy

      If your script uses the next generation script engine:

      var uuid = nodeState.get('username');
var userAttrs = openidm.read('managed/alpha_user/' + uuid, null, ['custom_department']);
var department = userAttrs.custom_department;

      If your script uses the legacy script engine, the openidm binding isn’t available. Ping Identity recommends that you upgrade your script to use the next generation script engine.

      Learn more in Access IDM scripting functions.

Delete user identity custom attributes

To delete a user identity custom attribute:

  1. Delete all data stored in the custom attribute for all users, then run a full reconciliation.

    If you don’t delete all data stored in the custom attribute before deleting the attribute, you might see errors when running subsequent reconciliations.

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

  3. Go to Configure > Managed Objects.

  4. Click Alpha_user or Bravo_user.

  5. In the list of attributes, find the row for the custom attribute that you want to delete:

    1. Click the row’s cross icon ().

    2. In the Delete Property confirmation modal, click Confirm.

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–20

  • 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 console, click Native Consoles > Identity Management.

  2. In the IDM admin console, 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–20 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 console 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 tenant 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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 console 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 console, 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 console, 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 console, 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 console, 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 console, 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 console, 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[1] environments:

    1. In the Advanced Identity Cloud admin console, go to Identities > Connect > Connector Servers.

    2. Click + New Connector Server.

    3. In the New Connector Server dialog box:

      1. Enter a Name for the connector server. Use only lowercase letters, numbers, underscores, or hyphens. No other special characters or spaces are allowed.

      2. Choose how you want your remote server (configured in later steps) to connect to the connector server:

        • By default, the connector server is configured to use a built-in OAuth 2.0 client called RCSClient. Your remote server uses the RCSClient credentials to connect.

        • (Optional) Select the Create a new OAuth Client checkbox to create a specific OAuth 2.0 client. The connector server uses this specific OAuth 2.0 client instead of RCSClient. Your remote server uses the credentials of the specific OAuth 2.0 client to connect.

          1. Enter a Client ID for the specific OAuth 2.0 client. Use only lowercase letters, numbers, underscores, or hyphens. No other special characters or spaces are allowed.

          2. Enter a Client Secret for the specific OAuth 2.0 client and note the value you entered.

    4. Click Save.

  2. To create a connector server in your UAT[2], 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

  1. Skip to Task 3: Download a remote server if either of these conditions apply:

    • If you selected the Create a new OAuth Client checkbox when creating the connector server in the previous step.

    • If you already know the client secret of the RCSClient.

  2. In the Advanced Identity Cloud admin console, go to web_asset OAuth2 Clients.

  3. Click RCSClient.

  4. Click Reset to change the client secret.

    RCSClient is a built-in OAuth 2.0 client that is the default client for connector servers in Advanced Identity Cloud. If you reset its client secret, you must update the configuration of any remote connectors configured to use it to connect to the tenant environment.

  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=<client-id>

      • connectorserver.clientSecret=<client-secret>

        • If you chose to create a specific OAuth 2.0 client in Task 1: Register a remote server, enter that client’s client secret.

        • Otherwise, enter the client secret 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 UAT[2], staging, and production environments, use three URLs in a space-delimited list[8]. 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 console. 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 console, go to Native Consoles > Identity Management.

  2. In the IDM admin console, 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 console, 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, allowing end users to authenticate with their existing DS password. The method documented here relies on an LDAP connector configured to synchronize accounts from your DS servers. It treats the hashed password as a simple string during synchronization, similar to any other LDAP attribute. It doesn’t use the DS password synchronization plugin.

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

    • PBKDF2-HMAC-SHA512T256 (for interoperability only)

    • 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 Advanced Identity Cloud admin console, go to Native Consoles > Identity Management, and 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 console, 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 console, 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 console, 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 console, 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 console:

Constraining how the Advanced Identity Cloud admin console 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, learn more in Searching for users in the UI is very slow in Advanced Identity Cloud.

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 console. 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 console. It does not affect Advanced Identity Cloud REST API queries.

To apply the setting:

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

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

To apply the setting:

  1. In the Advanced Identity Cloud admin console, 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 might 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 console to change the display name of a property, the change is reflected in both the IDM admin console and the Advanced Identity Cloud admin console; 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[9]

userName

uid

Common Name

cn

cn

Display Name

displayName

displayName

Password

password

userPassword

Status

accountStatus

inetUserStatus

First Name[9]

givenName

givenName

Last Name[9]

sn

sn

Email Address[9]

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

Custom attributes

custom_<attribute-name>

fr-idm-custom-attrs[10]

Direct Reports

reports

manager

Manager

manager

fr-idm-managed-user-manager

Authorization Roles

authzRoles

not available[11]

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

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[9]

passwordLastChangedTime

pwdChangedTime

Password Expiration Time[9]

passwordExpirationTime

pwdExpirationTime

Task Proxies[12]

taskProxies

n/a

Task Principals[12]

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 Indexed String 6[13]

frIndexedString6

fr-attr-istr6

Generic Indexed String 7[13]

frIndexedString7

fr-attr-istr7

Generic Indexed String 8[13]

frIndexedString8

fr-attr-istr8

Generic Indexed String 9[13]

frIndexedString9

fr-attr-istr9

Generic Indexed String 10[13]

frIndexedString10

fr-attr-istr10

Generic Indexed String 11[13]

frIndexedString11

fr-attr-istr11

Generic Indexed String 12[13]

frIndexedString12

fr-attr-istr12

Generic Indexed String 13[13]

frIndexedString13

fr-attr-istr13

Generic Indexed String 14[13]

frIndexedString14

fr-attr-istr14

Generic Indexed String 15[13]

frIndexedString15

fr-attr-istr15

Generic Indexed String 16[13]

frIndexedString16

fr-attr-istr16

Generic Indexed String 17[13]

frIndexedString17

fr-attr-istr17

Generic Indexed String 18[13]

frIndexedString18

fr-attr-istr18

Generic Indexed String 19[13]

frIndexedString19

fr-attr-istr19

Generic Indexed String 20[13]

frIndexedString20

fr-attr-istr20

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

Multivalue 2FA profile attributes

Display Name IDM Property AM Attribute

deviceProfiles [14]

deviceProfiles

deviceProfiles

devicePrintProfiles [14]

devicePrintProfiles

devicePrintProfiles

webauthnDeviceProfiles [14]

webauthnDeviceProfiles

webauthnDeviceProfiles

oathDeviceProfiles [14]

oathDeviceProfiles

oathDeviceProfiles

pushDeviceProfiles [14]

pushDeviceProfiles

pushDeviceProfiles

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. 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
Ping (ForgeRock) Login Widget

Use a widget to integrate authentication journeys easily into your client-side JavaScript web applications.
developer_mode
Ping 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 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 UIs can be customized with themes that let you adjust layouts, add company logos, headers, and footers, and change the colors of buttons, links, backgrounds, and more. You can create multiple themes in a realm, set the default theme for the realm, and assign specific themes to different end-user journeys.

Hosted pages are useful if you have limited theming needs or want to try new registration or authentication flows without integrating them into an application. The UIs are designed for web applications and aren’t supported on native applications.

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.

Ping (ForgeRock) Login Widget

The Ping (ForgeRock) Login Widget provides an OOTB UI for end-user authentication journeys, such as login, registration, and password reset. It doesn’t 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 (ForgeRock) Login Widget.

Ping SDKs

The Ping 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 Ping 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

You can find background information on UX options in PingOne Advanced Identity Cloud 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

Some limitations

No limitation

No limitation

Pixel-perfect implementation of design mockups

No

No

Yes

Can be developed

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

N/A

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 Ping 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 Ping 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 journey pages — Pages for end-user sign-on journeys.

  • Hosted account pages — Pages for end-user account management, shown after a sign-on journey.

In the following example, the sign-on 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 journey pages

You can use the Ping 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 sign-on, registration, or password reset pages by a malicious user.

Deactivating hosted journey pages disables them in both the Alpha and Bravo realms. You cannot deactivate hosted journey pages for just one realm.

Hosted journey pages can be deactivated independently of hosted account pages.

When you deactivate the hosted journey pages, Advanced Identity Cloud displays the following web page to unauthorized end users:

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.

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

Deactivating hosted account pages disables them in both the Alpha and Bravo realms. You cannot deactivate hosted account pages for just one realm.

Hosted account pages can be deactivated independently of hosted journey pages.

When you deactivate the hosted account 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.

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

Other resources

Learn how to customize and use hosted pages:

  • Customize sign-on and end-user pages: Customize the look and feel of the sign-on (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 sign-on 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 sign-on 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 sign-on 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 sign-on 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 sign-on 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 console:

  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. Click Save.

  4. 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: Customize the styles of the card in the center of the journey page where end users enter their credentials. This includes the card colors, field colors, card shadow, border radius, and if the input text labels should be placed above or inside 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 for sign-on 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-on card on the page.

    • Button Position: The position of the button inside the sign-on card.

    • Header: Place a header above the sign-on card. Learn more in Custom headers and footers.

      • Add a skip to main content link in the header for accessibility: Add a button that lets screen readers skip header content.

      • Focus Options: Choose how the tab key behaves in relation to the header:

        • Always focus on header: The tab index is set to the beginning of the header and the first tab key press by an end user focuses on the first link in the header.

        • Always focus on card: The tab index is advanced to the sign-on card and the first tab key press by an end user focuses on the first link or field in the sign-on card.

        • Focus on header for initial step - focus on card for subsequent steps: On the initial browser page load of a journey, the first tab key press by an end user focuses on the first link in the header. On each subsequent browser page load as the journey progresses, the first tab key press by an end user focuses on the first link or field in the sign-on card.

    • Footer: Place a footer below the sign-on card. Learn more in Custom headers and footers.

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

    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:

  5. Click Save.

  6. (Optional) 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. In the Advanced Identity Cloud admin console, go to Hosted Pages.

    2. In 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 console:

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

Sign-on UI

You can configure the following self-service features to control the actions and information displayed to end users when they sign on:

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 can control the information displayed and the actions end users can take from the Advanced Identity Cloud end-user UI. Learn more in:

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. In the Advanced Identity Cloud admin console, 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. Click the Account Pages tab. This refers to the Advanced Identity Cloud admin console pages.

  4. In the panel on the right-hand side, click Layout.

  5. The Profile Information section determines the actions and information end users can see. Select or deselect any of the following:

    Profile page component Description

    Personal Information

    Lets end users view and update their personal data. The attributes displayed depend on settings at the property level. Learn more in User identity attributes and properties reference.

    You can prevent end users from updating specific personal data. Learn more in Prevent end users from editing specific personal data.

    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. In the Advanced Identity Cloud admin console, select Native Consoles > Access Management.

      2. In 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: Lets end users 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

    Lets end users 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. In the Advanced Identity Cloud admin console, select Native Consoles > Access Management.

    2. In 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 sign on 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

    Lets end users view and manage the applications that have access to their personal information.

    Preferences

    Lets end users view and set preferences for communication. For example, an end user can select if they want to receive emails regarding special offers and services.

    Consent

    Lets end users view and manage how their data is shared with third parties.

    Account Controls

    Lets end users download the data Advanced Identity Cloud has about them in a JSON format and lets end users delete their account (identity) information.

  6. Click Save.

Prevent end users from editing specific personal data

End users can view their Advanced Identity Cloud personal data by selecting Profile > Edit Personal Info in the Advanced Identity Cloud end-user UI.

When you enable personal information for end users in the theme, all Advanced Identity Cloud properties are marked as User Editable. This means end users can view and update all their personal data directly in the Advanced Identity Cloud end-user UI. However, you might want to prevent end users from updating certain data. For example, email addresses could require verification, which can’t be guaranteed if end users can modify them.

To prevent end users from updating specific personal data:

  1. In the Advanced Identity Cloud admin console, select Native Consoles > Identity Management.

  2. Select Configure > Managed Objects from the top tabs.

  3. Click the user identity to update, for example Alpha_user.

  4. On the Properties tab, select the property to modify.

  5. On the Details tab, select Show advanced options.

  6. Deselect the User Editable option.

  7. Click Save. The property is no longer editable by end users.

  8. Repeat steps 4 - 7 for every property you want to prevent end users from updating.

You can hide a property from the personal data in the Advanced Identity Cloud end-user UI by deselecting the Viewable option. However, this hides the property of the user identity from both end users and tenant administrators.

Use script tags in Advanced Identity Cloud end-user and sign-on UIs

You can include script tags in Advanced Identity Cloud end-user and sign-on UIs to integrate third-party scripts such as customer analytics.

  1. In the Advanced Identity Cloud admin console, 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 sign-on and end-user pages

PingOne Advanced Identity Cloud lets you localize sign-on 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 sign-on and end-user UIs using translation configuration. Learn more in Localize tenant admin console and hosted pages.

Specify a preferred language for journey pages

By default, Advanced Identity Cloud localizes the content of journey pages using the value of the Accept-Language header, which is typically derived from the language settings in the end-user’s browser. You can override this behavior by appending a locale query parameter to the journey URL.

For example, to set the language to French, append locale=fr to the journey URL:

https://<tenant-env-fqdn>/am/XUI/?realm=/alpha&locale=fr&authIndexType=service&authIndexValue=Login

The language used to localize journey pages is determined in the following order of priority:

  1. The locale query parameter in the journey URL (for example, &locale=fr).

  2. The language preference set in the end-user’s browser.

  3. The default locale for hosted pages (en), used when neither a query parameter nor a browser language is provided.

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 Ping 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[15] 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[15] 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[15] 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.

My applications

The My Applications section lists the applications an end user has access to.

The following types of applications display in the My Applications section:

  • SAML-based applications - Configure SAML applications and assign end users or a role to the application. The SAML application then displays to the end user under the My Applications page.

  • Bookmark applications - Bookmark applications do not require authentication and are simply a redirect to a URL. When you assign a bookmark application to an end user or a role, it displays shortcut links on the My Applications page. When an end user clicks one of the links, the browser opens a new tab.

Application templates defined in the application catalog and custom OIDC applications do not display in the My Applications section.

To view and navigate to applications:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click My Applications.

  3. Click the desired application. The end user is redirected to the application.

Click to display an example

The example shows the following:

  1. An end user logging into the Advanced Identity Cloud end-user UI and having no applications assigned.

  2. An administrator, signed on to the Advanced Identity Cloud admin console, assigning a user to a bookmark and SAML application.

  3. The end user refreshing the page and the applications displaying under the My Applications menu item.

  4. The end user selecting a bookmark application (Google) and the application opening up in a new tab.

  5. The end user selecting a SAML application (Sample SAML App) and the user being redirected to the application already signed on.

My access

The My Access[15] section lists the access end users have in Advanced Identity Cloud when they sign on to the Advanced Identity Cloud end-user UI. It also lists the access they have in onboarded target applications.

To view access:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click My Access.

  3. Select any of the following tabs to view details:

    • Accounts - The accounts (user entities) that end users have in onboarded target applications. These correlate to the end user Advanced Identity Cloud identity.

    • Roles - The provisioning roles assigned to end users in Advanced Identity Cloud.

    • Entitlements - The entitlements end users have in onboarded target applications.

My directory

The My Directory[15] section includes the following tabs that allow end users to manage their tooltip:["delegates","Individuals who are auto-assigned an end user’s tasks indefinitely or for a specified time. Useful, for example, if an end user is on vacation and needs someone to cover their items."] and direct reports (employees):

Delegates

In Identity Governance, end users can delegate:

  • Access reviews

  • Line items forwarded to end users

  • Line items reassigned to users

  • Access requests when they’re the approver (designated owner) of a resource

Items still show up in end user’s inbox; however, they’re also sent to the delegate.

Delegation is useful, for example, if an end user is on vacation and needs someone to cover their items.
Assign a delegate

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click My Directory > Delegates.

  3. Click + Add Delegates.

  4. Search for another end user to delegate items to.

  5. (Optional) Set a start and end date for the delegate:

    1. Check the Assign role only during a selected time period box.

    2. Select a start and end date. Items are assigned during this timeframe only.

      If no start and end date is set, the delegate is set indefinitely.

  6. Click Save.

Remove a delegate

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click My Directory > Delegates.

  3. Find the delegate to remove and click > Remove.

  4. Click Delete.

When end users remove a delegate, the items sent to the delegate are automatically removed.
Direct reports

Direct reports are individuals who end users manage. In Identity Governance, end users can review their direct reports and the access their direct reports have.

For end users to view their direct reports' information:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click My Directory > Direct Reports. From this page, end users view their direct reports.

  3. Select the desired employee.

  4. Click the Accounts, Entitlements, and Roles tabs to view a direct reports access. TIP: As a manager, you can submit a remove access request to remove resources from a user. Learn more in Request to remove access.

My requests

The My Requests[15] section lets end users:

  • Create a request for themselves or others to gain access to an application, entitlement, or role

  • View requests they have submitted

To view and create requests:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click My Requests. From this page, end users view their pending requests.

  3. To create a request, click + New Request.

    The end user creates the request and sends it to the resource approvers for their approval or rejection.

    Learn more in Request access to resources.

Profile

The Profile section lets end users access and manage their information.

For end users to access the Profile section and update their personal information, you must:

  1. Enable the Personal Information UI menu item.

  2. Decide and configure which profile attributes are accessible to an end user.

For an end user to update their profile information follow these steps:

  1. Sign on to the Advanced Identity Cloud end-user UI.

  2. From the left navigation pane, click Profile.

  3. Select Edit Personal Info.

  4. Update one or more pieces of information.

  5. Click Save.

Ping SDKs

For an overview of all UI integration options, learn more in End-user UX options for authentication journeys and account management.

The Ping SDKs let you rapidly build applications against the PingOne Advanced Identity Cloud REST APIs.

Leverage Ping Identity’s identity best practices for token exchange, security, and the optimal OAuth 2.0 flow.

Ping SDKs are highly customizable and require a high level of technical skill; therefore, the SDK documentation is hosted separate from Advanced Identity Cloud documentation.

Integrate Ping SDKs with any of the following:

Upload provided files to integrate with Android or iOS apps

Associating a website(s) to your application is crucial when implementing Ping SDKs with Android or iOS applications. This allows you to share credentials or provide redirects within an application. Within the context of Ping SDKs, it is important to associate the SDKs with Android or iOS applications.

Google and Apple both provide ways assist in this process:

  • Android assetlinks.json - Establish trust between the application and a website(s) by automatically opening links for that domain.

  • iOS apple-app-site-association - Associate a website(s) with your application by having the associated domain file on your website and the appropriate entitlement in your application.

What is an Android assetlinks.json file?

An Android assetlinks.json file is a metadata file that lets your website declare an association with your Android apps. By convention, it is accessed from your website using the endpoint /.well-known/assetlinks.json.

To help you integrate your Android apps with PingOne Advanced Identity Cloud, you can upload an assetlinks.json file to a tenant environment and access it through a custom domain associated with the environment. You can do this for each custom domain in your set of environments.

As the configuration in your upper environments is immutable, you can only modify the content of an assetlinks.json file in your development environment configuration. You must then promote any configuration changes to your upper environments.

Ensure you have set up a custom domain for each environment and realm where you need to upload an assetlinks.json file.

High-level process

The high-level process to configure and promote an assetlinks.json file is as follows:

  1. In your development environment, use the endpoint naming format /openidm/config/fidc/assetlinks.<custom-domain-fqdn> to set assetlinks.json content in your configuration with an association to a custom domain. For example, for the custom domain id.mycompany.com, use the endpoint /openidm/config/fidc/assetlinks.id.mycompany.com.

  2. Promote the configuration to the upper environment that’s configured to use the custom domain; for example, if your production environment is configured to use the custom domain, you will need to promote to your staging environment, and then promote again to your production environment.

  3. Access the assetlinks.json file from your custom domain using the endpoint /.well-known/assetlinks.json; for example, for the custom domain id.mycompany.com, use the URL https://id.mycompany.com/.well-known/assetlinks.json.

Use a custom domain to view an assetlinks.json file. You don’t need to use an access token as the file is publicly accessible.

Show request 
$ curl \
--request GET 'https://<custom-domain-fqdn>/.well-known/assetlinks.json'(1)
1 Replace <custom-domain-fqdn> with a custom domain, for example id.mycompany.com.
Show response 
{
    "relation": [
        "delegate_permission/common.handle_all_urls",
        "delegate_permission/common.get_login_creds"
    ],
    "target": {
        "namespace": "web",
        "site": "https://id.mycompany.com"
    }
}

  1. Refer to the High-level process for configuring and promoting an assetlinks.json file.

  2. In your development environment:

    1. Get an access token.

    2. Set the assetlinks.json file contents in your configuration:

      Show request 
      $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/fidc/assetlinks.<custom-domain-fqdn>' \(1) (2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data-raw '{(4)
  "data": [
    {
      "relation": [
        "delegate_permission/common.handle_all_urls",
        "delegate_permission/common.get_login_creds"
      ],
      "target": {
        "namespace": "web",
        "site": "https://id.mycompany.com"
      }
    }
  ]
}'
      1 Replace <tenant-env-fqdn> with the domain of your development environment; for example, openam-mycompany.forgeblocks.com.
      2 Replace <custom-domain-fqdn> with the custom domain, for example id.mycompany.com.
      3 Replace <access-token> with the access token.
      4 Replace the example assetlinks.json JSON content with your own JSON content. Note that the JSON content is wrapped in a data object wrapper.
      Show response 
      {
  "_id": "fidc/assetlinks.id.mycompany.com",
  "data": [
    {
      "relation": [
        "delegate_permission/common.handle_all_urls",
        "delegate_permission/common.get_login_creds"
      ],
      "target": {
        "namespace": "web",
        "site": "https://id.mycompany.com"
      }
    }
  ]
}

    3. (Optional) Repeat the previous step for each additional custom domain that needs the assetlinks.json file uploading or replacing.

  3. Run a series of promotions to add the development environment configuration to your upper environments. Learn more in:

  4. Use your custom domain to view the assetlinks.json file. If you uploaded or replaced additional assetlinks.json files, repeat this for each custom domain.

  1. Refer to the High-level process for configuring and promoting an assetlinks.json file.

  2. In your development environment:

    1. Get an access token.

    2. Delete the assetlinks.json file contents from your configuration:

      Show request 
      $ curl \
--request DELETE 'https://<tenant-env-fqdn>/openidm/config/fidc/assetlinks.<custom-domain-fqdn>' \(1) (2)
--header 'Authorization: Bearer <access-token>'(3)
      1 Replace <tenant-env-fqdn> with the domain of your development environment, for example openam-mycompany.forgeblocks.com.
      2 Replace <custom-domain-fqdn> with your custom domain, for example id.mycompany.com.
      3 Replace <access-token> with the access token.
      Show response 
      {
  "_id": "fidc/assetlinks.id.mycompany.com",
  "data": [
    {
      "relation": [
        "delegate_permission/common.handle_all_urls",
        "delegate_permission/common.get_login_creds"
      ],
      "target": {
        "namespace": "web",
        "site": "https://id.mycompany.com"
      }
    }
  ]
}

    3. (Optional) Repeat the previous step for each additional custom domain that needs the assetlinks.json file deleting.

  3. Run a series of promotions to add the development environment configuration to your upper environments. Learn more in:

  4. Use your custom domain to view the assetlinks.json file and check that it is empty. If you deleted additional assetlinks.json files, repeat this for each custom domain.

Upload an iOS apple-app-site-association file

What is an iOS apple-app-site-association file?

An apple-app-site-association file is a metadata file that creates a secure association between your domain and your iOS apps. This lets you use universal links to open your iOS apps from your website. By convention, it is accessed from your website using the endpoint /.well-known/apple-app-site-association.

Learn more about creating and using a apple-app-site-association file in Supporting associated domains.

To help you integrate your iOS apps with PingOne Advanced Identity Cloud, you can upload an apple-app-site-association file to a tenant environment and access it through a custom domain associated with the environment. You can do this for each custom domain in your set of environments.

As the configuration in your upper environments is immutable, you can only modify the content of an apple-app-site-association file in your development environment configuration. You must then promote any configuration changes to your upper environments.

Ensure you have set up a custom domain for each environment and realm where you need to upload an iOS apple-app-site-association file.

High-level process

The high-level process to configure and promote an apple-app-site-association file is as follows:

  1. In your development environment, use the endpoint naming format /openidm/config/fidc/apple-app-site-association.<custom-domain-fqdn> to set apple-app-site-association content in your configuration with an association to a custom domain; for example, for the custom domain id.mycompany.com, use the endpoint /openidm/config/fidc/apple-app-site-association.id.mycompany.com.

  2. Promote the configuration to the upper environment that’s configured to use the custom domain. For example, if your production environment is configured to use the custom domain, you will need to promote to your staging environment, and then promote again to your production environment.

  3. Access the apple-app-site-association file from your custom domain using the endpoint /.well-known/apple-app-site-association; for example, for the custom domain id.mycompany.com, use the URL https://id.mycompany.com/.well-known/apple-app-site-association.

View an apple-app-site-association file

Use a custom domain to view an apple-app-site-association file. You don’t need to use an access token as the file is publicly accessible.

  1. View the apple-app-site-association file using a GET request:

    Show request 
    $ curl \
--request GET 'https://<custom-domain-fqdn>/.well-known/apple-app-site-association'(1)
    1 Replace <custom-domain-fqdn> with your custom domain; for example, id.mycompany.com.
    Show response 
    {
  "applinks": {
    "details": [
      {
        "appIDs": [
          "XXXXXXXXXX.com.example.AppName"
        ],
        "components": [
          {
            "/": "/reset/*",
            "comment": "Success after reset password journey"
          }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": [
      "XXXXXXXXXX.com.example.AppName"
    ]
  }
}

Upload or replace an apple-app-site-association file

  1. Refer to the High-level process for configuring and promoting an apple-app-site-association file.

  2. In your development environment:

    1. Get an access token.

    2. Set the apple-app-site-association file contents in your configuration:

      Show request 
      $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/fidc/apple-app-site-association.<custom-domain-fqdn>' \(1) (2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data-raw '{(4)
  "data": {
    "applinks": {
      "details": [
        {
          "appIDs": [
            "XXXXXXXXXX.com.example.AppName"
          ],
          "components": [
            {
              "/": "/reset/*",
              "comment": "Success after reset password journey"
            }
          ]
        }
      ]
    },
    "webcredentials": {
      "apps": [
        "XXXXXXXXXX.com.example.AppName"
      ]
    }
  }
}'
      1 Replace <tenant-env-fqdn> with the domain of your development environment; for example, openam-mycompany.forgeblocks.com.
      2 Replace <custom-domain-fqdn> with your custom domain; for example, id.mycompany.com.
      3 Replace <access-token> with your access token.
      4 Replace the example apple-app-site-association JSON content with your own JSON content.
      Show response 
      {
  "_id": "fidc/apple-app-site-association.id.mycompany.com",
  "data": {
    "applinks": {
      "details": [
        {
          "appIDs": [
            "XXXXXXXXXX.com.example.AppName"
          ],
          "components": [
            {
              "/": "/reset/*",
              "comment": "Success after reset password journey"
            }
          ]
        }
      ]
    },
    "webcredentials": {
      "apps": [
        "XXXXXXXXXX.com.example.AppName"
      ]
    }
  }
}

    3. (Optional) Repeat the previous step for each additional custom domain that needs the apple-app-site-association file uploading or replacing.

  3. Run a series of promotions to add the development environment configuration to your upper environments. Learn more in:

  4. Use your custom domain to view the apple-app-site-association file. If you uploaded or replaced additional apple-app-site-association files, repeat this for each custom domain.

Delete an apple-app-site-association file

  1. Refer to the High-level process for configuring and promoting an apple-app-site-association file.

  2. In your development environment:

    1. Get an access token.

    2. Delete the apple-app-site-association file contents from your configuration:

      Show request 
      curl \
--request DELETE 'https://<tenant-env-fqdn>/openidm/config/fidc/apple-app-site-association.<custom-domain-fqdn>' \(1) (2)
--header 'Authorization: Bearer <access-token>'(3)
      1 Replace <tenant-env-fqdn> with the domain of your development environment, for example openam-mycompany.forgeblocks.com.
      2 Replace <custom-domain-fqdn> with your custom domain, for example id.mycompany.com.
      3 Replace <access-token> with the access token.
      Show response 
      {
  "_id": "fidc/apple-app-site-association.id.mycompany.com",
  "data": {
    "applinks": {
      "details": [
        {
          "appIDs": [
            "XXXXXXXXXX.com.example.AppName"
          ],
          "components": [
            {
              "/": "/reset/*",
              "comment": "Success after reset password journey"
            }
          ]
        }
      ]
    },
    "webcredentials": {
      "apps": [
        "XXXXXXXXXX.com.example.AppName"
      ]
    }
  }
}

    3. (Optional) Repeat the previous step for each additional custom domain that needs the apple-app-site-association file deleting.

  3. Run a series of promotions to add the development environment configuration to your upper environments. Learn more in:

  4. Use your custom domain to view the apple-app-site-association file and check that it is empty. If you deleted additional apple-app-site-association files, repeat this for each custom domain.

User self-service journeys

You must configure user self-service journeys in PingOne Advanced Identity Cloud before your end users can experience them. For example, you can configure journeys for password reset, username retrieval, and more.

Use cases for user self-service

To let end users manage their own accounts in Advanced Identity Cloud, you must configure the necessary settings. For example, if you want users to create their own identities by registering themselves with Advanced Identity Cloud, you need to create a journey that collects the required information. After creating the journey, you must test it and push the journey’s configuration to your production tenant.

The features end users can access depend on what you configure.

The following table references the self-service actions available to end users in Advanced Identity Cloud, provided they are configured. You can configure these self-service journeys:

Use Case Description

Simple sign-on

Lets end users sign on by collecting a username and password.

Username recovery

Lets end users recover their username.

Password reset

Lets end users reset their password.

Password update

Lets end users update their password, after signing on and obtaining a session.

User self-registration

Lets end users register their own identity in Advanced Identity Cloud.

Social authentication

Lets end users authenticate using social providers, such as Google or Facebook.

Progressive profile

Asks users for more information based on a login count.

Sign on after losing access to your device

Creates a journey to let end users sign on with a recovery code if they lose their device.

For further use cases and questions about configuring the Advanced Identity Cloud end-user UI, learn more in FAQ: Advanced Identity Cloud hosted End User UI.

Scripting

You can extend Advanced Identity Cloud features with JavaScript.

Auth scripting
Custom endpoints
Event hooks

Auth scripting

You can use authentication and authorization (auth) scripting to modify default Advanced Identity Cloud behavior in many situations: client-side authentication, policy conditions, handling OpenID Connect claims, and others.

Use JavaScript for auth scripting in Advanced Identity Cloud. Groovy scripts are deprecated and will eventually be completely replaced with JavaScript scripts.

For JavaScript examples of all auth script types, review the sample scripts. Each sample script includes a list of available variables.

Scripts can potentially emit the personally identifiable information (PII) of your end users into Advanced Identity Cloud logs, and then into external services that consume 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.

Auth script types

The auth script types available in Advanced Identity Cloud include the following:

Journeys
Script type Description Information

Configuration Provider Node

Runs in a Configuration Provider node as a step in an authentication journey.

Configuration Provider node

Journey Decision Node

Runs in a Scripted Decision node as a step in an authentication journey.

Scripted decision node API
OAuth2 / OIDC
Script type Description Information

OAuth2 Access Token Modification

Modifies the key-value pairs contained within access tokens before they’re issued to a client.

Access tokens

OAuth2 Evaluate Scope

Retrieves and modifies scopes for OAuth 2.0 access token introspection.

Scope evaluation

OAuth2 May Act

Adds the may_act claim to tokens when performing token exchanges.

Token exchange

OAuth2 Trusted JWT Issuer

Dynamically retrieves the details of an issuer during the JWT profile for authorization grant.

JWT profile for authorization

OAuth2 Validate Scope

Modifies how Advanced Identity Cloud validates requested OAuth 2.0 scopes.

Scope validation

OIDC Claims

Modifies or overrides OIDC claims when issuing an ID token or in the response from the userinfo endpoint.

OIDC claims
SAML
Script type Description Information

SAML2 SP Adapter

Modifies the processing of the authentication request on the SP.

SP adapter

SAML2 IDP Adapter

Modifies the processing of the authentication request on the IDP.

IdP adapter

SAML2 IDP Attribute Mapper

Maps user-configured attributes to SAML attributes in the assertion returned by the IDP.

IdP attribute mapper

SAML2 NameID Mapper

Customize the value of the NameID attribute in the SAML assertion on the remote SP.

NameID mapper
Other
Script type Description Information

Client-side Authentication

Runs on the client during authentication.

Library

Contains reusable functionality that can be imported into journey decision node scripts or other library scripts.

Library scripts

Policy Condition

Modifies authorization policy decisions.

Scripted policy conditions

Social Identity Provider Profile Transformation

Adapts the fields received from a social identity provider to align with the fields expected by Advanced Identity Cloud.

Social Provider Handler node

Some script types aren’t yet available in the Advanced Identity Cloud admin console. To view a list of all the script types, under Native Consoles > Access Management, go to Realms > Realm Name > Scripts and click New Script.

Manage auth scripts

To manage your auth scripts, go to Realm > Scripts > Auth Scripts.

On the Scripts page, you can view a list of existing scripts. To edit, duplicate, or delete a script, click its More () menu.

The edit option in the More menu opens the script in a lightweight editor that features syntax highlighting and validation checking. You can maximize the editor to full screen to edit larger scripts:

Script editor

① JavaScript editor
② Fullscreen option
③ Syntax highlighting
④ Syntax error highlighting and validation checking

Create a new auth script

  1. Go to Realm > Scripts > Auth Scripts, then click + New Script.

  2. Choose an auth script type.

    After you select a script type, the editor opens. The editor is prepopulated with a default script for that type, which is intended as a starting point for your custom script.

    If you selected the wrong script type, click Previous to select a different script type.

  3. If the next-generation script engine is available for the script type, such as for journey decision node scripts, Advanced Identity Cloud displays the Choose Script Engine page.

    Select Legacy or Next Generation to set the script engine for your script.

  4. Enter a unique Name and optional Description for the script, then click Save.

    After you save a script, you can’t change its type.

Journey decision node scripts

Learn more about journeys in Journeys.

You can also create, edit, and validate journey decision node scripts directly from within a Scripted Decision node.

  1. Go to Realm > Journeys.

  2. Open a journey in the journey editor.

  3. Find an existing scripted decision node or add a new one.

  4. Select the scripted decision node to open the context pane on the right side.

  5. The following screenshot shows where you can create a new journey decision node script ④ or edit an existing one ⑤:

    Journey editor with Scripted Decision node

    ① Scripted decision node
    ② Context pane
    ③ Journey decision node script drop-down
    ④ Add new journey decision node script
    ⑤ Edit existing journey decision node script

Create a new journey decision node script

Add a new journey decision node script in the journey editor or from Realm > Scripts > Auth Scripts.

  1. Select Legacy or Next Generation on the Choose Script Engine page.

    Learn more about the enhanced scripting engine in Next-generation scripts.

  2. If you create or edit a Next Generation script, click the Libraries icon in the top right to display the following side panel:

    Next generation journey decision node script editor

    ① View and search library scripts to import in your script.
    ② Click to expand a library script and view its exported methods and constants.
    The font colors indicate the exported types:

    • Blue for functions

    • Red for numbers

    • Green for strings

    • Orange for boolean types

    • Purple for objects / properties

    ③ Click the Docs icon to view links to context-related documentation.
    A red dot denotes documentation updates.
    ④ Edit your script and import library scripts as necessary.

  3. Enter a unique Name and optional Description for the script, then click Save.

More information

Custom endpoints

You can use custom endpoints to run arbitrary JavaScript code through the REST API. Custom endpoint scripts are extremely flexible and can extend Advanced Identity Cloud behavior in many ways:

  • Validate user input fields before storing them in a user profile.

  • Create utility functions, such as getting today’s date.

  • Mandate user input fields during registration to support delegated administration decisions.

  • Query identities with a particular relationship, such as being a member of an organization, and page the results.

You can consume custom endpoints within Advanced Identity Cloud or integrate them into your external UIs or system applications.

Custom endpoints scripting introduction

For an introduction to custom endpoints scripting, read the following:

To understand how to create identity object query expressions to use in the request.queryExpression property, learn more in Define and call data queries.

Scripts can potentially emit the personally identifiable information (PII) of your end users into Advanced Identity Cloud logs, and then into external services that consume 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.

Manage custom endpoints

To manage your custom endpoints, go to Realm > Scripts > Custom Endpoints.

On the Custom Endpoints page, you can view a list of existing custom endpoints. To edit, duplicate, or delete a custom endpoint, click its More () menu.

The edit option in the More menu opens the custom endpoint script in a lightweight editor. The editor features syntax highlighting and validation checking. Maximize the editor to full screen to edit larger scripts:

idcloudui custom endpoints editor

① Endpoint name
② JavaScript editor
③ Fullscreen option
④ Syntax highlighting
⑤ Validation checking
⑥ cURL request tab, learn more in Generate a cURL request for a custom endpoint
⑦ Test tab, learn more in Run a test request for a custom endpoint

Create a custom endpoint

  1. Go to Realm > Scripts > Custom Endpoints, then click + New Script.

  2. Enter a Name for your new endpoint; for example, getDate.

    • Access the new custom endpoint over HTTP at:
      https://<tenant-env-fqdn>/openidm/endpoint/<name>

    • Access the new custom endpoint in a script using:
      openidm.read('endpoint/<name>')

  3. (Optional) Enter a Description for your new endpoint; for example, Get the current date.

  4. Next, use the editor to create your script. The editor is prepopulated with a default script, which is intended as a starting point for your custom script.

  5. To test your script, click Save, then either:

    1. Generate a cURL request for a custom endpoint

    2. Run a test request for a custom endpoint

  6. When your testing is complete, click Save and Close.

Generate a cURL request for a custom endpoint

In the script editor:

  1. Click the angled brackets icon (<>) to open the cURL Request tab.

  2. In the Method field, choose an HTTP request method for the cURL request. Learn more about how HTTP request methods relate to the script request.method property values in this mapping table.

  3. (Optional) In the Body field, enter a JSON-formatted body for the cURL request (except when using the GET HTTP request method). For example:

    {
    "param1": "foo",
    "param2": "bar"
}
    In the script, you can access the body using the request.content property. The example above maps to request.content.param1 and request.content.param2.

  4. Click Generate to output the cURL request, which appears below your script. The cURL request is complete with an access bearer token and ready to run.

  5. Click the copy icon () to copy the cURL request from the editor, then paste and run it in a terminal window.

Run a test request for a custom endpoint

In the script editor:

  1. Click the triangle icon () to open the Test tab.

  2. In the form field, enter a JSON-formatted configuration object for the cURL request. The form field is prepopulated with a default configuration object:

      {
    "request": {
      "method": "create"
    }
  }

    This default configuration object creates a request using the POST HTTP request method. Learn more about how HTTP request methods relate to the script request.method variable parameter values in this mapping table.

  3. (Optional) To supply a body with the request, add a request.content property:

      {
    "request": {
      "method": "create",
      "content": {
        "param1": "foo",
        "param2": "bar"
      }
    }
  }
    In the script, you access the body using the request.content property. The example above maps to request.content.param1 and request.content.param2.

  4. Click Run to run the cURL request. The result appears below the editor.

HTTP request methods mapped to script request.method property values

HTTP request method Script request.method

GET

read

POST

create

PUT

update

PATCH

patch

DELETE

delete

Authenticate to Advanced Identity Cloud REST API

The Advanced Identity Cloud REST API has two different authentication methods, depending on what you are trying to achieve:

  • Use an API key and secret for read-only operations.
    Examples: Advanced Identity Cloud monitoring and logging.

  • Use an access token for access management operations or identity management operations.
    Examples: Setting up authentication journeys or policies; configuring user profiles, roles, or assignments.

Summary of authentication methods

The following table summarizes the REST API endpoints and their different authentication methods:

REST endpoints Authentication method

  • /monitoring/health

  • /.well-known/* (for GET requests)

Not applicable (publicly accessible endpoint)

  • /monitoring

  • /logs

API key and secret.

Learn more in Authenticate to Advanced Identity Cloud REST API with API key and secret.

  • /am/*

  • /openidm/*

  • /.well-known/*

  • /environment/certificates, /environment/csrs 

  • /environment/content-security-policy/*

  • /environment/cookie-domains

  • /environment/custom-domains

  • /environment/promotion/*

  • /environment/proxy-connect/*

  • /environment/release

  • /environment/restart, /environment/secrets, /environment/variables 

  • /environment/release

  • /environment/sso-cookie

Access token

Learn more in Authenticate to Advanced Identity Cloud REST API with access token.

Authenticate to Advanced Identity Cloud REST API with API key and secret

You will need an API key and secret to authenticate to the following Advanced Identity Cloud REST API endpoints:

  • /monitoring

  • /logs

Summary of use:

  1. Create an API key and secret in the Advanced Identity Cloud admin console.

  2. Set the API key and secret as x-api-key and x-api-secret HTTP headers for each API request:

    x-api-key: <api-key>
x-api-secret: <api-secret>

Get an API key and secret

  1. In the Advanced Identity Cloud admin console, click the user icon, and then click Tenant Settings.

    Show me where

    tenant menu

  2. On the Global Settings tab, click Log API Keys.

  3. Click New Log API Key, provide a name for the key, and then click Create Key.

    A dialog box appears containing the new keys:

    log api key

  4. Store the api_key_id and api_key_secret values securely.

    You cannot view the api_key_secret value again once you click Done.

  5. Click Done.

Use an API key and secret

To use the API credentials, set them as x-api-key and x-api-secret HTTP headers:

Show request 
$ curl \
--request GET 'https://<tenant-env-fqdn>/monitoring/logs/sources?_prettyPrint=true' \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>'
Show 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
}

Authenticate to Advanced Identity Cloud REST API with access token

You need an access token to authenticate to the following Advanced Identity Cloud REST API endpoints:

Summary of use:

  1. Create a service account in the Advanced Identity Cloud admin console and download a private key.

  2. Create a JSON Web Token (JWT) and sign it using the private key.

  3. Create an access token using the JWT profile for OAuth 2.0 authorization grant flow.

  4. Set the access token as a bearer token in the Authorization HTTP header for each API request:

     Authorization: Bearer <access-token>

Get an access token

Prerequisites

You need the jose command-line tool to run some of the commands. The jose command-line tool is a C-language implementation of the Javascript Object Signing and Encryption (JOSE) standards. You can find installation instructions for your particular package manager in https://command-not-found.com/jose.

The instructions won’t work using any of the Node.js tools called jose. Although they have the same name, they’re separate implementations of the JOSE standards.

Task 1: Create a service account and download its private key

  1. Follow the steps in Create a new service account.

    1. In step 9, save the private key as a local file called key.jwk.

    2. Note the ID for the service account you created. An example of an ID is 449d7e27-7889-47af-a736-83b6bbf97ec5.

Task 2: Create and sign a JWT

  1. Set the following variables in your terminal, to be used as claims in a JWT payload:

    1. Set SERVICE_ACCOUNT_ID to hold the ID of the service account. For use in the iss (issuer) and sub (subject) claims.

      $ SERVICE_ACCOUNT_ID="<service-account-id>"(1)
      1 Replace <service-account-id> with the service account ID; for example, 449d7e27-7889-47af-a736-83b6bbf97ec5.

    2. Set AUD to hold the URL (including port number) where the JWT will be used to request the access token. For use in the aud (audience) claim.

      $ AUD='https://<tenant-env-fqdn>:443/am/oauth2/access_token'

    3. Set EXP to hold a 15-minute expiration time for the JWT, expressed as a Unix timestamp. For use in the exp (expiration time) claim.

      $ EXP=$(($(date -u +%s) + 899))
      Service account access tokens have a non-configurable, fixed expiry of 899 seconds (15 minutes), so the previous example sets a timestamp value that matches the fixed expiry. Despite the expiry being non-configurable, you must supply the exp claim, set with a nominal future timestamp, to create an access token successfully.

    4. Set JTI to hold a unique ID for the JWT. For use in the jti (JWT ID) claim.

      $ JTI=$(openssl rand -base64 16)

  2. Combine the claims to create a payload for the JWT:

    $ echo -n "{
    \"iss\":\"${SERVICE_ACCOUNT_ID}\",
    \"sub\":\"${SERVICE_ACCOUNT_ID}\",
    \"aud\":\"${AUD}\",
    \"exp\":${EXP},
    \"jti\":\"${JTI}\"
}" > payload.json

  3. Sign the JWT using the private key you downloaded and saved as key.jwk in step 1a:

    $ jose jws sig -I payload.json -k key.jwk -s '{"alg":"RS256"}' -c -o jwt.txt

Task 3: Get an access token using the JWT profile authorization grant

  1. Request an access token from the /oauth2/access_token endpoint using the JWT:

    $ curl \
--request POST ${AUD} \
--data "client_id=service-account" \(1)
--data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \(2)
--data "assertion=$(< jwt.txt)" \(3)
--data "scope=<scope>"(4)
    1 The client ID service-account targets the built-in OAuth 2.0 public client for service accounts. The client only allows the JWT profile for OAuth 2.0 authorization grant flow.
    Access the built-in OAuth 2.0 public client using the tenant FQDN. You cannot access it using an Alpha or Bravo realm alias URL or a custom domain URL.
    2 The grant type urn:ietf:params:oauth:grant-type:jwt-bearer represents the JWT profile for OAuth 2.0 authorization grant flow.
    3 The assertion parameter is populated with the output of the signed JWT from step 2c.
    4 Replace <scope> with a scope or a space delimited set of scopes; for example, fr:idc:esv:* or fr:am:* fr:idm:*. Learn more in Service account scopes. The specified scopes must be the same as (or a subset of) the scopes that you assigned to the service account.

  2. Examine the response to find the access token, represented as access_token:

    {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... ...8ECmkyDJKow8Qp_Tnp_lGNRJzLWi18iUGQrCTtxyTXw",
    "scope": "fr:am:* fr:idm:*",
    "token_type": "Bearer",
    "expires_in": 899
}

Use an access token

To use the access token with the REST API, set it as a bearer token in the Authorization HTTP header for each API request.

The following example uses the access token to get a list of identities:

Show request 
$ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/managed/<realm>_user?_fields=userName,givenName,sn,mail,accountStatus&_prettyPrint=true&_queryFilter=true' \(1)
--header 'Authorization: Bearer <access-token>'(2)
1 Replace <realm> with the realm where you created the access token.
2 Replace <access-token> with the access_token in the authentication response (learn more in Get an access token).
Show response 
{
    "result": [
        {
            "_id": "f413db4c-cebd-4950-81e6-57bdb47921a4",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": "exampleuser@example.com"
        },
        {
            "_id": "15249a65-8f9a-4063-9586-a2465963cee4",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser2",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": "exampleuser2@example.com"
        },
        {
            "_id": "30485bc4-fdbb-4946-8ce4-1a53c6824d92",
            "_rev": "0000000016e6754b",
            "userName": "exampleuser3",
            "accountStatus": "active",
            "givenName": "Example",
            "sn": "User",
            "mail": "exampleuser3@example.com"
        }
    ],
    "resultCount": 3,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}

Advanced Identity Cloud Postman collection

Advanced Identity Cloud provides REST APIs to help you manage identities, authenticate to the system, monitor Advanced Identity Cloud, and more.

You can also use the AM and IDM APIs with Advanced Identity Cloud.

To help you quickly use and understand these REST APIs, Advanced Identity Cloud provides a Postman collection, containing example requests grouped into features.

Features include:
 
・Intelligent Access
・User Self-Service
・Session Management
・Identity Profiles
・Managed Identities
・Auditing/Monitoring
・OAuth 2.0 Flows

postman collection overview

Download Postman and import the Advanced Identity Cloud collection

  1. Download and install the Postman application.

  2. Download the Advanced Identity Cloud Postman collection.

  3. In Postman:

    1. Go to File > Import... > Upload Files.

    2. Browse to the collection JSON file you downloaded in the previous step, and then click Open.

    3. Click Import to bring the collection into your workspace.

Create a service account and download its private key

To use the Advanced Identity Cloud Postman collection, you must create a service account that the requests in the collection can use to connect to your Advanced Identity Cloud instance.

Follow the steps in Create a new service account.

  • In step 9, save the private key as a local file called key.jwk.

  • Make a note of the ID for the service account you created.

    An example of an ID is 449d7e27-7889-47af-a736-83b6bbf97ec5.

Proceed to the next section to learn how to enter these values into the collection, plus other settings necessary to use Postman with Advanced Identity Cloud.

Configure collection variables

The Advanced Identity Cloud Postman collection uses a number of configurable variables to populate the requests.

These variables are stored at the collection level. To view them, click on the top level of the collection menu labeled PingOne Advanced Identity Cloud Collection, and then select the Variables tab.

Editing the default variables used by the Postman collection
Figure 1. Editing the default variables used by the Postman collection

The variables are initially set with placeholder values that you must modify or replace. For example, the collection needs to know the Advanced Identity Cloud URL, as well as your admin access credentials.

To edit the variables, enter new values in the INITIAL VALUE column. Then click Save to make the edits permanent.

To understand which variables you need to edit before you can use the collection, learn more in Required variable values. To understand which variables you can optionally edit to customize the collection to suit your environment, learn more in Optional variable values.

You can then start using the collection.

You can also override the default collection-level variables by creating a Postman Environment. Use the same variable names as the Required variable values.

This is useful if you have more than one Advanced Identity Cloud tenant, as you can configure the connection and username values as separate environments in Postman.

You can also enter potentially sensitive values in an environment to keep them separate from the collection. This means you can share the collection without sharing your credentials.

For information on creating a Postman Environment, learn more in Managing environments in the "Postman Learning Center".

Required variable values

Before using the collection, you must provide the correct values for the following variables. You can provide the value at the collection level or add them at the environment level.

Ensure you use strong passwords for access credentials.
Server URLs
platformUrl
Default

https://<tenant-env-fqdn>

Description

Specifies the root URL of your Advanced Identity Cloud.

amUrl
Default

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

Description

Specifies the URL of the Access Management (AM) component of your Advanced Identity Cloud.

idmUrl
Default

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

Description

Specifies the URL of the Identity Management (IDM) component of your Advanced Identity Cloud.

User credentials
postmanServiceAccountID
Default

Not set

Description

Specifies the ID of the service account you created to allow the Postman collection access to your tenant.

The collection uses this ID when creating a JWT to sign, which it then uses to obtain an access token.

The JWT is generated when you run the Prerequisite requests.

Example

c41515a8e-9c7d-4c37-4b2a-58c0fdea2080

postmanServiceAccountJWK
Default

Not set

Description

Specifies the private key you downloaded as key.jwk when you created the service account.

Open the downloaded key.jwk in a text editor, and then enter the entire JSON web key into the field in Postman, including the curly braces.

The collection uses this key to sign a JWT token, which it then uses to obtain an access token.

The JWK is used to sign the JWT when you run the Prerequisite requests.

Example
{
  "d": "MsVF...dmvw",
  "dp": "0iic...jdrw",
  "dq": "BXja...4epQ",
  "e": "AQAB",
  "kty": "RSA",
  "n": "stO0...qNyU",
  "p": "3VoI-ZPcw",
  "q": "ztGg...EJBw",
  "qi": "NHkA...NV_Gw"
}
postmanClientSecret
Default

Not set

Description

Specifies the secret used by the OAuth 2.0 clients the collection creates.

You create these clients when you run the Prerequisite requests.

postmanDemoPassword
Default

Not set

Description

Specifies the password used by the managed realm user the collection creates for demonstration purposes.

You create the realm user when you run the Prerequisite requests.

Logging API
logApiKey
Default

Not set

Description

Specifies the API key used to access the monitoring endpoints.

Add this key to run the auditing and monitoring requests.

Learn more in Obtaining API Credentials.

Example

0405de08ea73f1d84f

logApiSecret
Default

Not set

Description

Specifies the API secret used to access the monitoring endpoints.

Add this key to run the auditing and monitoring requests.

Learn more in Obtaining API Credentials.

Example

58932ad661ccf7ea5eda0b...a8d310e1676c9cac7f

Optional variable values

The collection uses the following additional variables that work using their default values; however, you can modify them.

List of optional variable values
postmanDemoUsername
Default

postmanDemoUser

Description

Specifies the username of the managed realm user the collection creates for demonstration purposes.

postmanDemoEmail
Default

demo.user@postman.example.com

Description

Specifies the email of the managed realm user the collection creates for demonstration purposes.

Enter an email address you have access to if you want to test the forgotten username or password flows in the user self-service section of the collection.
realm
Default

/realms/root/realms/alpha

Description

Specifies the realm that the majority of the requests in the collection use.

You must specify the entire hierarchy of the realm, starting at the root realm.

Prefix each realm in the hierarchy with the realms keyword.

Example

/realms/root/realms/customers/realms/europe.

cookieName
Default

Not set

Description

Specifies the name of the session cookie the tenant uses to store session tokens.

The collection sets this value automatically when you run the first request in the Prerequisites folder.

loginJourney
Default

Login

Description

Specifies the authorization journey name to use.

For information on the default journeys that Advanced Identity Cloud provides, learn more in Login.

redirect_uri
Default

https://httpbin.org/anything

Description

Specifies the URI to which the OAuth 2.0 client will redirect the user upon a successful authentication request.

postmanConfidentialClientId
Default

postmanConfidentialClient

Description

Specifies the ID of the OAuth 2.0 private client.

postmanPublicClientId
Default

postmanPublicClient

Description

Specifies the ID of the OAuth 2.0 public client.

Hard-coded variable values

The collection uses the following additional variables that must not be modified.

List of hard-coded variable values
postmanUtilLib
Description

Contains the postman-util-lib utility library that the collection uses to sign requests and generate certain keys.

Learn more in postman-util-lib on GitHub.

Use the collection

Before using the Advanced Identity Cloud Postman collection, you should run the Prerequisite requests. The requests configure your Advanced Identity Cloud with the necessary elements, such as OAuth 2.0 clients and managed users

Running the prerequisite requests

Ensure you have configured the required collection variables as described in Configure collection variables before running the prerequisite requests.

  1. In Postman, with the Advanced Identity Cloud collection loaded, open the Prerequisites section.

  2. Select the first request in the list, examine the details, and when you’re satisfied the request is properly formed, click Send.

    Many of the requests have associated tests; for example, that the response code was 200. Postman displays the test results alongside the response to the request.

    Many of the requests set a global variable containing a value returned in the response for use in subsequent requests.

    View the details of these in the Tests tab of a request. You can also view the values of these global variables by clicking Environment Quick Look ().

  3. Repeat the previous step for each request in the Prerequisites folder.

When completed, Advanced Identity Cloud contains the following:

  • An alpha_user identity, named postmanDemoUser by default, which demonstrates a number of user-related endpoints, such as identity profiles, and user self-service.

  • Two OAuth 2.0 clients:

    1. A client named postmanConfidentialClient, which is used by the OAuth 2.0 requests to demonstrate a number of grant flows.

    2. A client named postmanPublicClient, which is used by the OAuth 2.0 requests to demonstrate a number of grant flows.

If you need to recreate any of the above, or decide to alter the default values, run each of the steps in the Prerequisite folder again.

Running the requests

The requests in the collection are split into different features. To run the calls for a feature, open the relevant folder, and run each request in sequence.

The value in square brackets in the name shows what type of authentication the request requires:

[User]

The request acts on a user’s data or profile.

These requests often authenticate as postmanDemoUser in the collection.

[fr:am:*]

The request requires an access token that has the fr:am:* scope so that it can perform access management related actions.

These requests authenticate as the service account you created earlier.

[fr:idm:*]

The request requires an access token that has the fr:idm:* scope so that it can perform identity management related actions.

These requests authenticate as the service account you created earlier.

Note that intelligent access and identity profiles have additional functionality. Refer to each section for details.

Intelligent access

There are scripts in the Intelligent Access requests that attempt to detect the callbacks that the first step returns, and sets the next request to handle it.

To view the details of this script:

  1. Click on the top level of the collection menu (labelled PingOne Advanced Identity Cloud Collection), then select the Pre-request Scripts tab.

  2. Within the tab, examine the detectCallbacks script.

When manually running through the steps, examine the response returned in the first call, and run the relevant next step. The collection is able to handle the following ready-to-use callbacks:

Intelligent Access Callback Steps
Step Callback

Step 2a

Username and password callbacks, together in a page node.

Step 2b

Validated create username and password callbacks, together in a page node.

Step 2c

Choice callbacks.

Step 2d

Text input callbacks.

Step 2e

Device profile callbacks. Learn more in Configure Device Profiling.

Step 2f

Progressive profile callbacks.
Identity profiles

Some endpoints require the ID of an identity, rather than the username.

An example of this is when getting the OAuth 2.0 profiles a user has provided consent to.

When running the Identity Profiles requests, ensure you have also executed the request named Step 3: [User] Read session info and store ID in the Authenticate as "Postman Demo User" folder.

The result is stored in the demoUserId global variable.

Advanced Identity Cloud API reference

Many of the features available through Advanced Identity Cloud UIs are also available through REST APIs.

Some documented APIs aren’t active in all Advanced Identity Cloud tenants.

The REST APIs have Evolving interface stability. This interface is continuing to evolve and so is subject to change in backwards-incompatible ways. All changes are documented at the time of release.

API versions

To maintain compatibility between releases, many REST APIs are versioned (v1.0, v2.0, and so on). The version number of a feature increases when Advanced Identity Cloud introduces breaking changes to an API.

Advanced Identity Cloud provides versions for these API aspects:

resource

Any changes to the structure or syntax of a returned response result in a change to the resource version. For example, changing errorMessage to message in a JSON response.

protocol

Any changes to the methods used to make REST API calls result in change to the protocol version. For example, changing _action to $action in the required parameters of an API feature.

When an API is versioned, include resource versions in your REST calls by setting the Accept-API-Version request header. The following example requests resource version 2.0 and protocol version 1.0:

Accept-API-Version: resource=2.0, protocol=1.0

This header ensures you call the correct version of the API, avoiding unexpected behavior due to incompatible changes.

The APIs

Learn more in the API reference pages:

1 Identity Governance is an add-on capability to Advanced Identity Cloud. Contact your Ping Identity representative if you want to add PingOne® Identity Governance to your Advanced Identity Cloud subscription.

Advanced Identity Cloud REST API custom headers

Advanced Identity Cloud adds several custom headers to its REST API responses. These custom headers allow you to make logic decisions in your scripts and journeys. For example, you might use the country code in the X-Client-Region header to enforce MFA in a sign-on journey for clients originating from a specific country or set of countries.

Debugging

X-ForgeRock-TransactionID

This header contains a unique value, such as f89da9de-22f4-4e0b-8527-26b8d9c53d7b-request-1/0, that can be used to identify the current request and correlate it with Advanced Identity Cloud log entries from all log sources. Learn more in Filter logs for a specific request.

Advanced Identity Cloud adds a similar header X-Cloud-Trace-Context for tracing requests. This is used internally by the Ping Identity support team. It’s also deprecated, so you shouldn’t use this header in your integrations.

Client IP addresses

X-Forwarded-For

This header contains a comma-separated list of originating IP addresses for the client.

  • If the request doesn’t have an X-Forwarded-For header set before it connects to the tenant environment load balancer, the header is added to the request and contains the following IP addresses:

    X-Forwarded-For: <client-ip-address>, <load-balancer-ip-address>

    • <client-ip-address> is the IP address of the client when it connects to the tenant environment load balancer.

    • <load-balancer-ip-address> is the IP address of the tenant environment load balancer.

  • If the request already has an X-Forwarded-For header set before it connects to the tenant environment load balancer, the header is modified to contain the following IP addresses:

    X-Forwarded-For: <existing-ip-address>, <client-ip-address>, <load-balancer-ip-address>

    • <existing-ip-address> is the IP address the X-Forwarded-For header contains when the client connects to the tenant environment load balancer.

    • <client-ip-address> is the IP address of the client when it connects to the tenant environment load balancer.

    • <load-balancer-ip-address> is the IP address of the tenant environment load balancer.

There are security and privacy concerns associated with the use of this header. Learn more in the MDN doc X-Forwarded-For.
X-Trusted-Forwarded-For

This header contains a comma-separated list of trusted IP addresses for the client:

X-Trusted-Forwarded-For: <trusted-ip-address>, <client-ip-address>, <load-balancer-ip-address>

  • <trusted-ip-address> is a trusted client IP address, verified by Ping Identity.

  • <client-ip-address> is the IP address of the client when it connects to the tenant environment load balancer.

  • <load-balancer-ip-address> is the IP address of the tenant environment load balancer.

X-Real-IP

This header contains a trusted client IP address, verified by Ping Identity:

X-Real-IP: <trusted-ip-address>
For the X-Trusted-Forwarded-For and X-Real-IP headers, if the client is behind a reverse proxy, the trusted client IP address contains the real IP address of the reverse proxy, not the client.

Learn more in Identify originating client IP addresses.

Client geolocation

X-Client-Region

This header contains the country (or region) associated with the client’s IP address in the form of a two-letter region code, such as US or FR. For most countries, these region codes correspond directly to ISO-3166-2 codes.

X-Client-City

This header contains the name of the city where the client request originated. For example, Mountain View for Mountain View, California. There’s no canonical list of valid values for this header. The city names can contain ASCII letters, numbers, spaces, and the following characters: "!#$%&'*+-.^_`|~".

X-Client-City-Lat-Long

This header contains the latitude and longitude of the city where the client request originated. For example, 37.386051,-122.083851 for a request from Mountain View.

For the X-Client-Region, X-Client-City and X-Client-City-Lat-Long headers, if the client is behind a reverse proxy, the geolocation information represents the reverse proxy, not the client. If you require greater accuracy, Ping Identity recommends that you integrate an IP lookup service into your end-user journeys.

Learn more in Identify client geolocation.

Other

X-Forwarded-Proto

This header contains the HTTP protocol the client used to connect to the tenant environment load balancer. Possible values are http or https. Learn more in the MDN doc X-Forwarded-Proto.

X-Requested-With

This header contains the name of the originating web technology or platform. For example, most JavaScript frameworks set the value as XMLHttpRequest. The header can be used to influence application behavior. For example, returning HTML data by default but returning JSON data for requests that set the value as XMLHttpRequest. The header can also be used to protect against CSRF attacks. Learn more in CSRF attacks.

Advanced Identity Cloud REST

Advanced Identity Cloud REST is a REST API framework defining common APIs to access web resources and collections of resources.

Resources

Endpoints generally return JSON-format resources, though resource formats can depend on the implementation.

Resources in collections can be found by their unique identifiers (IDs). IDs are exposed in the resource URIs. For example, if a service has a user collection under /users, you can access a user at /users/user-id. The ID is also the value of the _id field of the resource.

Resources are versioned using revision numbers. A revision is specified in the resource’s _rev field. Revisions make it possible to figure out whether to apply changes without resource locking and without distributed transactions.

Verbs

The Advanced Identity Cloud REST APIs use the following verbs, sometimes referred to collectively as CRUDPAQ. For details and HTTP-based examples of each, follow the links to the sections for each verb.

Verb Description

Create

Add a new resource with HTTP PUT or HTTP POST.

Read

Retrieve a single resource with HTTP GET.

Update

Replace an existing resource with HTTP PUT.

Delete

Remove an existing resource with HTTP DELETE.

Patch

Modify part of an existing resource with HTTP PATCH.

Action

Perform a predefined action with HTTP POST.

Query

Search a collection of resources with HTTP GET.

Query parameters

Advanced Identity Cloud REST reserved query string parameter names start with an underscore (_).

Reserved query string parameters include, but are not limited to, the following names:

_action
_api
_countOnly
_crestapi
_fields
_mimeType
_pageSize
_pagedResultsCookie
_pagedResultsOffset
_prettyPrint
_queryExpression
_queryFilter
_queryId
_sortKeys
_totalPagedResultsPolicy

Some parameter values are not safe for URLs; URL-encode parameter values as necessary.

Extension points

The action verb is the main vehicle for extensions. For example, to create a new user with HTTP POST rather than HTTP PUT, you might use /users?_action=create. An endpoint can define additional actions. For example, /tasks/1?_action=cancel.

A service can define stored queries to call by ID. For example, /groups?_queryId=hasDeletedMembers. Stored queries can call for additional parameters. The parameters are also passed in the query string. Which parameters are valid depends on the stored query.

Create

There are two ways to create a resource: HTTP POST or HTTP PUT.

To create a resource using POST, perform an HTTP POST with the query string parameter _action=create and the JSON resource as a payload. The service creates the identifier if not specified:

POST /users?_action=create HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
{ JSON resource }

To create a resource using PUT, perform an HTTP PUT with the case-sensitive identifier for the resource in the URL path and the JSON resource as a payload. Optionally, include the If-None-Match: * header to prevent overwriting an existing object:

PUT /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-None-Match: *
{ JSON resource }

The _id and the content of the resource depend on the endpoint. The service is not required to use the _id the client provides. The response to the create request indicates the resource location as the value of the Location header.

  • If you do include the If-None-Match: * header, the request creates the object if it does not exist or fails if the object does exist.

  • If you do not include the If-None-Match: * header, the request creates the object if it does not exist or updates the object if it does exist.

  • If you include the If-None-Match header with any value other than *, the response is an HTTP 400 Bad Request error. For example, creating an object with If-None-Match: revision returns a bad request error.

Parameters

You can use the following query string parameters:

Parameter Description

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_prettyPrint=true

Format the body of the response.

Read

To retrieve a single resource, perform an HTTP GET on the resource by its case-sensitive identifier (_id) and accept a JSON response:

GET /users/some-id HTTP/1.1
Host: example.com
Accept: application/json

Parameters

You can use the following query string parameters:

Parameter Description

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_mimeType=mime-type

Some resources have fields containing multimedia resources, such as a profile photo.

If the feature is enabled for the endpoint, read a single multimedia resource field by specifying the field and mime-type.

The content type of the field value returned matches the mime-type. The body of the response is the multimedia resource

Do not use the Accept header. For example, Accept: image/png does not work. Use the _mimeType query string parameter instead.

_prettyPrint=true

Format the body of the response.

Update

To update a resource, perform an HTTP PUT including the case-sensitive identifier (_id) as the final element of the path to the resource and the JSON resource as the payload.

Use the If-Match: _rev header to verify the version you modify. Use If-Match: * if the version does not matter.

PUT /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-Match: _rev
{ JSON resource }

When updating a resource, include all the attributes to retain. Omitting an attribute in the resource amounts to deleting it unless it is not under the control of your application. Attributes not under the control of your application include private and read-only attributes. Virtual attributes and relationship references might not be under the control of your application.

Parameter Description

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_prettyPrint=true

Format the body of the response.

Delete

To delete a single resource, perform an HTTP DELETE by its case-sensitive identifier (_id) and accept a JSON response:

DELETE /users/some-id HTTP/1.1
Host: example.com
Accept: application/json

Parameters

You can use the following query string parameters:

Parameter Description

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_prettyPrint=true

Format the body of the response.

Patch

To patch a resource, send an HTTP PATCH request with an array of operation objects in the payload. Each operation object uses some combination of these fields:

operation

The type of operation.

field

The target field.

value

The value to apply.

from

The source field.

The service applies the PATCH operations in order.

PATCH /users/some-id HTTP/1.1
Host: example.com
Accept: application/json
Content-Length: ...
Content-Type: application/json
If-Match: _rev
{ JSON array of patch operations }

PATCH operations work differently depending on the field types:

Single-value

An object, string, boolean, or number.

List semantics array

The elements are ordered, and duplicates are allowed.

Set semantics array

The elements are not ordered, and duplicates are not allowed.

Whether an endpoint supports a specific operation depends on the implementation.

Add operation

The add operation ensures the target field contains the value provided, creating parent fields as necessary.

If the target field is single-valued, the value replaces the value of the target.

If the value is an array, the outcome depends on the type:

List semantics arrays

If you add an array of values, the operation appends the array to the existing list of values.

If you add a single value, specify an ordinal element in the target array, or use the {-} special index to add the value to the end of the list.

Set semantics arrays

The operation merges the value(s) in the patch with the existing set of values. Any duplicates in the array are removed.

As an example, start with the following list semantic array resource:

{
  "fruits": ["orange", "apple"]
}

The following add operation appends pineapple at the end of the array:

{
  "operation": "add",
  "field": "/fruits/-",
  "value": "pineapple"
}

The resulting resource is:

{
  "fruits": ["orange", "apple", "pineapple"]
}

Copy operation

The copy operation replaces the value(s) of the target field with the value(s) from the source field.

The following example replaces the value of another_mail with the value of mail:

[{
  "operation": "copy",
  "from": "mail",
  "field": "another_mail"
}]

If the source field value and the target field value are arrays, the result depends on whether the array has list semantics or set semantics. Learn more in Add operation.

Increment operation

The increment operation changes the value or values of the target field by the amount you specify. The value must be a positive or negative number. The target must be a single-valued number.

The following example adds 1000 to /user/payment:

[{
  "operation": "increment",
  "field": "/user/payment",
  "value": "1000"
}]

Move operation

The move operation removes existing values from the source and adds them to the target field. The operation creates the target field if it does not exist.

The following example moves surname values to lastName:

[{
  "operation": "move",
  "from": "surname",
  "field": "lastName"
}]

To apply a move to an array, the source and target must have compatible semantics. Learn more in Add operation.

Remove operation

The remove operation deletes values in the target field.

When no value is specified, the operation removes the field:

[{
  "operation": "remove",
  "field": "phoneNumber"
}]

For arrays, the result depends on the semantics:

List semantic arrays

Delete the specified element in the array.

The following example removes the first phone number (zero-based array index):

[{
  "operation": "remove",
  "field": "/phoneNumber/0"
}]
Set semantic arrays

Delete the specified values from the array.

The following example removes the specified phone number:

[{
  "operation": "remove",
  "field": "/phoneNumber",
  "value": "+1 408 555 9999"
}]

Replace operation

The replace operation removes existing values in the target, replacing them with the provided value(s).

The following example replaces existing telephoneNumber values with +1 408 555 9999:

[{
  "operation": "replace",
  "field": "/telephoneNumber",
  "value": "+1 408 555 9999"
}]

For list semantic arrays, you can target items by their indexes. As an example, start with the following resource:

{
  "fruits": ["apple", "orange", "kiwi", "lime"]
}

Apply the following operation:

[{
  "operation": "replace",
  "field": "/fruits/1",
  "value": "pineapple"
}]

The result is:

{
  "fruits": ["apple", "pineapple", "kiwi", "lime"]
}

Transform operation

The transform operation changes the field value based on a script or a data transformation command.

The following example applies the something.js script to the /objects value:

[{
  "operation": "transform",
  "field": "/objects",
  "value": {
    "script": {
      "type": "text/javascript",
      "file": "something.js"
    }
  }
}]

Limitations

Some HTTP client libraries do not support the HTTP PATCH operation.

Make sure the library you use supports HTTP PATCH before using this REST operation. For example, the Java method HttpURLConnection.setRequestMethod("PATCH") throws ProtocolException.

Parameters

You can use the following query string parameters:

Parameter Description

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_prettyPrint=true

Format the body of the response.

Action

Actions are a means of extending Advanced Identity Cloud REST APIs and are defined by the resource provider. The actions you can use depend on the implementation.

The standard action indicated by _action=create is described in Create.

Parameters

You can use the following query string parameters. Other parameters depend on the specific action implementation:

Parameter Description

_fields=field[,field...]

Return only the specified fields in the body of the response.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_prettyPrint=true

Format the body of the response.

Query

To query a resource collection, which you can think of as a resource container, perform an HTTP GET and accept a JSON response including at least a _queryFilter or _queryId parameter. These parameters cannot be used together.

GET /users?_queryFilter=true HTTP/1.1
Host: example.com
Accept: application/json

The endpoint returns the result as a JSON object including a results array and other fields related to the query string parameters.

Parameters

You can use the following query string parameters:

Parameter Description

_fields=field[,field...]

Return only the specified fields in each element of the results.

The field values are JSON pointers. For example, if the resource is {"parent":{"child":"value"}}, parent/child refers to the "child":"value".

If the field is left blank, the endpoint returns all default values.

_pagedResultsCookie=string

The string is an opaque cookie to keep track of the position in the search results. The service returns the cookie in the JSON response as the value of pagedResultsCookie.

In the request _pageSize must be set and non-zero. You receive the cookie value from the provider on the first request. You supply the cookie value in subsequent requests until the service returns a null cookie when the final page of results has been returned.

Use this parameter with the _queryFilter parameter. It is not guaranteed to work with the _queryId parameter.

The _pagedResultsCookie and _pagedResultsOffset parameters are mutually exclusive. Do not use them together.

_pagedResultsOffset=integer

When _pageSize is non-zero, use this as an index in the result set indicating the first page to return.

The _pagedResultsCookie and _pagedResultsOffset parameters are mutually exclusive. Do not use them together.

_pageSize=integer

Return query results in pages of this size.

After the initial request, use _pagedResultsCookie or _pageResultsOffset to page through the results.

_prettyPrint=true

Format the body of the response.

_queryFilter=filter-expression

Query filters request entries matching the filter expression. You must URL-escape the filter expression.

Learn more in Filter expressions.

_queryId=identifier

Specify a query by its identifier.

Specific queries can take their own query string parameter arguments depending on the implementation.

_sortKeys=[-][.var]##field##[,[-]field...]

Sort the resources returned based on the specified field(s) in + (ascending, default) or in - (descending) order.

As ascending order is the default, including the ` character in the query is unnecessary. If you do include the `, it must be URL-encoded as %2B:

https://<tenant-env-fqdn>/api/users?_prettyPrint=true&_queryFilter=true&_sortKeys=%2Bname/givenName

The _sortKeys parameter is not supported for predefined queries (_queryId).

_totalPagedResultsPolicy=string

When a non-zero _pageSize is specified, the service calculates the totalPagedResults in accordance with the totalPagedResultsPolicy, and provides the value as part of the response.

The totalPagedResults is:

  • An estimate of the total number of paged results (_totalPagedResultsPolicy=ESTIMATE).

  • The exact total result count (_totalPagedResultsPolicy=EXACT).

If no count policy is specified in the query, or if _totalPagedResultsPolicy=NONE, result counting is disabled. The service returns "totalPagedResults": -1.

Filter expressions

Query filters request entries matching the filter expression. You must URL-escape the filter expression.

The string representation is summarized as follows:

Expr           = OrExpr
OrExpr         = AndExpr ( 'or' AndExpr ) *
AndExpr        = NotExpr ( 'and' NotExpr ) *
NotExpr        = '!' PrimaryExpr | PrimaryExpr
PrimaryExpr    = '(' Expr ')' | ComparisonExpr | PresenceExpr | LiteralExpr
ComparisonExpr = Pointer OpName JsonValue
PresenceExpr   = Pointer 'pr'
LiteralExpr    = 'true' | 'false'
Pointer        = JSON pointer
OpName         = 'eq' |  # equal to
                 'co' |  # contains
                 'sw' |  # starts with
                 'lt' |  # less than
                 'le' |  # less than or equal to
                 'gt' |  # greater than
                 'ge' |  # greater than or equal to
                 STRING  # extended operator
JsonValue      = NUMBER | BOOLEAN | '"' UTF8STRING '"'
STRING         = ASCII string not containing white-space
UTF8STRING     = UTF-8 string possibly containing white-space

JsonValue components of filter expressions follow RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format. In particular, as described in section 7 of the RFC, the escape character in strings is the backslash character. For example, to match the identifier test\, use _id eq 'test\\'. In the JSON resource, the \ is escaped the same way: "_id":"test\\".

When using a query filter in a URL, notice the filter expression is part of a query string parameter. URL-encoded the filter expression. Learn more in RFC 3986: Uniform Resource Identifier (URI): Generic Syntax. For example, whitespace, double quotes ("), parentheses, and exclamation characters need URL encoding. The following rules apply to URL query components:

query       = *( pchar / "/" / "?" )
pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
pct-encoded = "%" HEXDIG HEXDIG
sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
                  / "*" / "+" / "," / ";" / "="

ALPHA, DIGIT, and HEXDIG are core rules of RFC 5234: Augmented BNF for Syntax Specifications:

ALPHA       =  %x41-5A / %x61-7A   ; A-Z / a-z
DIGIT       =  %x30-39             ; 0-9
HEXDIG      =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"

As a result, a backslash escape character in a JsonValue component is percent-encoded in the URL query string parameter as %5C. To encode the query filter expression _id eq 'test\\', use _id+eq'test%5C%5C'+, for example.

A simple filter expression can represent a comparison, presence, or a literal value.

For comparison expressions use json-pointer comparator json-value, where the comparator is one of the following:

eq (equals)
co (contains)
sw (starts with)
lt (less than)
le (less than or equal to)
gt (greater than)
ge (greater than or equal to)

For presence, use json-pointer pr to match resources where:

  • The JSON pointer is present.

  • The value it points to is not null.

Literal values include true (match anything) and false (match nothing).

Complex expressions employ and, or, and ! (not), with parentheses, (expression), to group expressions.

HTTP status codes

When working with a Advanced Identity Cloud REST API, client applications should expect at least the following HTTP status codes. Not all services necessarily return all status codes identified here:

200 OK

The request succeeded and a resource returned, depending on the request.

201 Created

The request succeeded and the resource was created.

204 No Content

The action request succeeded, and there was no content to return.

304 Not Modified

The read request included an If-None-Match header, and the value of the header matched the revision value of the resource.

400 Bad Request

The request was malformed.

401 Unauthorized

The request requires user authentication.

403 Forbidden

Access was forbidden during an operation on a resource.

404 Not Found

The specified resource could not be found, perhaps because it does not exist.

405 Method Not Allowed

The HTTP method is not allowed for the requested resource.

406 Not Acceptable

The request contains parameters that are not acceptable, such as a resource or protocol version that is not available.

409 Conflict

The request would have resulted in a conflict with the current state of the resource.

410 Gone

The requested resource is no longer available, and will not become available again. This can happen when resources expire.

412 Precondition Failed

The resource’s current version does not match the version provided.

415 Unsupported Media Type

The request is in a format not supported by the requested resource for the requested method.

428 Precondition Required

The resource requires a version, but no version was supplied in the request.

500 Internal Server Error

The service encountered an unexpected condition that prevented it from fulfilling the request.

501 Not Implemented

The resource does not support the functionality required to fulfill the request.

503 Service Unavailable

The requested resource was temporarily unavailable. The service may be disabled, for example.

About Identity Governance

Advanced Identity Cloud add-on capability

Contact your Ping Identity representative if you want to add PingOne® Identity Governance to your Advanced Identity Cloud subscription.

Identity Governance lets you administer and manage end user access to applications and data across your company to support corporate and regulatory compliance. Identity Governance uses onboarded target applications when reviewing identity data.

With Identity Governance, you can:

Ping Identity does not support Identity Governance actions for users authenticated in the Bravo realm of a tenant. Configuring Identity Governance in both Alpha and Bravo realms can cause issues since Identity Governance is not realm-aware. This may result in users gaining unauthorized access to customer data across realms and features.

To avoid these issues, Ping Identity recommends setting up an Advanced Identity Cloud instance for your workforce/Identity Governance use cases using only the Alpha realm and another instance for your CIAM use cases using one or both realms depending on application.

Contact your Ping Identity representative to discuss your particular deployment options.

To access Identity Governance administration functions in Advanced Identity Cloud, you must be a tenant administrator.

When you purchase Identity Governance, the Governance-related menu items are added to the left navigation pane:

governance admin left nav items

Additional menu items are also added to the End-user pages.

governance end user ui screens

Access certification

In Identity Governance, certifying access means reviewing the data and access a user has, such as access to applications, the accounts in those applications, and more.

Steps to certify access

To certify access for users, you must:

  1. Create templates — Allows you to configure the data you want to certify.

  2. Run campaigns — After you create a template and are ready to kick off the review process, create a campaign.

  3. Certify data and access by end users — After you start a campaign, the template-defined end users (certifiers) receive notifications to review the data. The certifiers' review of the data is referred to as an access review.

Certifications tab

Certifications and related features can be found by selecting Certification from the left navigation bar in the Advanced Identity Cloud admin console.

Three tabs display under Certification:

Overview tab

To access the Overview tab, from the Advanced Identity Cloud admin console, go to Certification > Overview.

governance overview tab

The Overview landing page displays various metrics that allow you to view items such as campaign status, active reviews, and campaigns by type.

You can hover your cursor over the charts to view the data details.

Data Element Description

Active Campaigns

The number of campaigns currently in progress.

Expiring Campaigns

The number of campaigns that expire in the next two weeks.

Active Reviews

The total amount of line items in access reviews that are in progress. A line item is a record for a certifier to review. For example, the user Barbara Jensen’s record that details their access to a particular application is a line item.

Campaigns By Type

A breakdown of the varying types of certifications.

Campaigns By Status

A breakdown of certifications by status.

access review History

The number of line items certified versus revoked from campaigns.

Example of certifying access

As an example of certifying access, let’s say you want to know what applications a specific user, Barbara Jenson, has access to. You may want to do this for a couple of reasons; increasing your company’s security landscape by ensuring users have accurate, appropriate access, or to comply with organizational, industry, or governmental policies. Barbara Jensen has an account and access to an application, called App A.

With Identity Governance, perform the following actions to achieve this:

  • Configure and assign end users (certifiers) in your company to review Barbara’s access to App A using templates.

  • Kick off the data review using campaigns. Campaigns are the active processes, where certifiers review the data. In this case, it is Barbara’s data. Certifiers are assigned to review the data in a campaign.

  • Certifiers review Barbara’s data and either certify (allow) or revoke (remove) the access to App A.

Configure data to review using templates

Templates are the first step in certifying access for users.

Templates are the underlying configurations of certifying access and define the data to review, who is responsible for the review, and when the data needs to be reviewed (on a periodic or ad hoc basis).

Often, organizations need to review the same data multiple times a year to ensure access is accurate. Templates make the certification process easier by saving the configuration settings used in the data review process.

Manage (create, duplicate, edit, or delete) templates on the Templates tab and schedule each campaign to run at a specific interval (if desired).

You can run templates on an ad-hoc or scheduled basis.

View saved templates

To view saved templates, from the Advanced Identity Cloud admin console, click Certification > Templates tab. The page displays saved templates.

governance templates tab
Field Description

Name

The name of the template.

Next run date

A date displays when the template is configured to run according to a schedule. If the template runs ad-hoc, then (None Scheduled) displays.

Status

A template can be in one of the following states:

  • Creating: The template is created in the background. This is a temporary state.

  • Unused: The template is not part of a campaign. In this state, you can edit/modify the template.

  • Active: The template is turned into a campaign. In this state, you can view the template details, but you cannot edit/modify it.

The general sequence of states are Creating → Unused → Active.

Which certification template to choose?

Identity Governance provides various certification templates to choose from. The underlying business objective you want to achieve determines which template type you choose.

Refer to the following scenarios when determining which template type to choose:

  • You want to review the template to certify or revoke access to applications (accounts). You can specify to review the entitlements or roles a user has. The primary certifier (reviewer) of the certification should be users' managers.

    Identity Entitlement assignment Role membership Notes

    Not every user has entitlements. If you want to review the applications users have access to, and include those users who don’t have entitlements, choose the identity certification.

  • You want to review to certify or revoke specific entitlements assigned to users in target applications. The primary certifier of the certification should be entitlement owners.

    Identity Entitlement assignment Role membership Notes

    The entitlement assignment certification is the best choice in this scenario. It provides entitlement owners the ability to review the access users have to their entitlements.

  • You want to review the template to certify or revoke a user’s role memberships. The primary certifier of the certification should be role owners.

    Identity Entitlement assignment Role membership Notes

    The role membership certification is the best choice in this scenario as it provides the ability to review roles and users who are assigned to roles in Advanced Identity Cloud.

Create templates

Before you create a template, consider creating custom governance glossary attributes to enhance the data for onboarded target applications, entitlements, or roles. This will assist with template filtering and business decisions.

To create a template:

  1. Navigate to the Certification > Templates tab.

  2. Click + New Template.

  3. Select the template type:

    • Identity certification — Review and certify user accounts, entitlements, and access a user has on some or all applications. Primary reviewers are the users' managers, a single user, or users assigned to a role.

    • Entitlement assignment certification — Review and certify entitlements and the users who have access to entitlements in target applications. Primary reviewers are entitlement owners, a single user, or users assigned to a role.

    • Role membership certification — Review and certify role memberships and the users who have access to roles in Advanced Identity Cloud. Primary reviewers are role owners, a single user, or users assigned to a role.

  4. Click Next.

    To continue setting up the template you select, click on the preceding links in step 3.

Modify templates

You can modify various template items:

  1. From the Advanced Identity Cloud admin console, go to Certification > Template tab.

  2. Locate the template and click the ellipsis (...) to perform various actions:

    To view additional templates, click the caret icons at the bottom of the table.
    Field Description

    Duplicate

    Duplicate the template details to create a new template, and edit/modify as needed. The characters (copy) are appended to the newly duplicated template.

    View Details

    This option displays if the template has been run at least once. It provides a read-only view into the configurations on the template. After you run a template, you cannot change the configuration settings.

    Edit Template

    This option displays if you create the template, but never run it to create a campaign. In this case, you can edit/modify the template configuration.

Activate templates

Activate a template to kick off the review process (a campaign).

You can activate a template by:

  • Creating a schedule when you define the template.

  • Adding a schedule to the template after you define the template.

  • Running the template on an ad-hoc basis.

To activate a template:

  1. From the Advanced Identity Cloud admin console, go to Certification > Template tab.

  2. Locate the template and click to perform various actions:

    To view additional templates, click the caret icons at the bottom of the table.
    Action Field

    Run Now

    This activates the template and kicks off the review process (campaign). When selected, the active campaign displays in the Campaigns tab.

    When you create a template, if you select Run on a schedule under the When to Certify section. The campaign runs on the set schedule and display on the Campaigns tab at the specified interval.

    Schedule Campaign

    This option displays if you did not configure a schedule when creating the template. This creates a run schedule for the template.

    Edit Schedule

    This option displays if you did configure a schedule when creating the template, but you would like to modify the existing schedule.

Delete a template

To delete an existing template:

  1. From the Advanced Identity Cloud admin console, go to Certification > Template tab.

  2. Locate the template, click , and click Delete. This action cannot be undone.

You can only delete templates in the Creating or Unused states. This action cannot be undone.

Identity certification

Select an identity certification type to certify user accounts and entitlements for specific applications.

To review information about templates, refer to Create templates.

You must populate the Display Name Attribute on the target application User entity object in the Details tab.

This allows each account pulled into Advanced Identity Cloud to display with a human-readable name. This is required for the data to properly display when a certifier (reviewer) reviewers their certification.

Perform the following:

  1. From the Advanced Identity Cloud admin console, go to Applications > Select Application.

  2. Select the object that represents the user entity in the target application.

  3. Go to the Details tab.

  4. Populate the Display Name Attribute with an attribute from the target application.

The following video shows an example:

The following table lists the areas to configure for each campaign template type:

Section Description

Details

General details of the template, such as the name, description, and a default certifier.

What to Certify

The items to be certified.

When to Certify

The cadence in which the review process is kicks off (campaign).

Who will Certify

The end users responsible for certifying the items in the campaign.

Notifications

Optional. Set up email notifications based on various events that take place during the certification process.

Additional options

Optional. Various configurations to allow during the campaign, such as bulk actions on line items or self-certification.

Summary

Summary of configured sections.

Details

This section includes basic information about the template, such as the display name, description, owner, and staging process.

To complete this section, do the following:

  1. From the Advanced Identity Cloud admin console, click Certification > Templates > + New Template.

  2. Select Identity Certification.

  3. Click Next.

  4. Complete the following fields:

    Field Description

    Name

    The display name for the campaign. This campaign name displays on both the certifications tab and the end-user tasks dashboard.

    You can define a date variable in the name of the campaign to know which campaign kicks off. Identity Governance uses moment.js to format the date.

    For example, if you have a campaign scheduled to run every two weeks, appending the date to the name lets you know which campaign you are working on. The campaign name can include the date (year, month, day), time (hour, minute), and time of day (AM/PM):

    Campaign name — {{YYYY-MM-DD-hh:mma}}

    When you kick off the template into a campaign, an example of the name is: Campaign name — 2023-12-12-08:18pm

    NOTE: Once the campaign kicks off you cannot modify the name.

    Description

    Enter a general description for the campaign. Your company should follow a descriptive convention to describe each of your campaign.

    This field is limited to 1000 characters.

    Campaign Owner

    Enter the owner of the campaign. Only campaign owners can fully control their campaigns, including certification decisions, certifier assignment changes, sign off, and more.

    Enable Campaign Staging

    Enable staging to set up the campaign in the system but not activate it in production. This option allows compliance officers to preview a campaign before it is activated and exposed to end users. Compliance officers can inspect and review the content, decision items, and other details to determine whether to activate or delete it.

  5. Click Next.

What to Certify

This sections lets you define the items to certify, including the organizations, users, applications, accounts, and entitlements.

To complete this section, do the following:

  1. Complete the following fields:

    Field Description

    Organizations

    Filter any generated certification by organization. This feature only appears for identity certification campaigns.

    • All organizations

    Include child organization

    Click to include any suborganizations in the campaign.

    Users

    Certify one of the following:

    • All users

    • A single user

    • Users matching a filter — Create a filter to certify select users.

    Accounts, Entitlements, Roles

    Select at least one of the following:

    • Certify User Accounts.

    • Certify User Entitlements.

    • Certify User Roles.

    Applications

    Certify one of the following:

    • All applications

    • Specific applications — If you select this, an additional box displays to select which Applications to certify.

    • Applications matching a specific filter — Create a filter to certify specific applications.

      If you create a governance glossary attribute and enhance the target application(s) with the attribute, you can filter on attribute(s) you create. For more information, refer to Create an application glossary attribute.

    Accounts

    Displays if you selected Certify User Accounts.

    • Select All accounts in selected applications if you selected Certify User Accounts.

    Entitlements

    Displays if you selected Certify User Accounts.

    • Certify one of the following if you selected Certify User Entitlements:

    • All entitlements

    • Entitlements matching a filter — Create a filter to certify specific entitlements.

      If you create a governance glossary attribute and populate the attribute you create on the onboarded entitlement(s), you can filter on the attribute(s) you create. For more information, refer to Create an entitlement glossary attribute.

    Roles

    Displays if you selected Certify User Roles.

    Certify one of the following if you selected Certify User Roles:

    • All roles

    • Roles matching a filter — Create a filter to certify specific roles.

      If you create a governance glossary attribute and populate the attribute you create on roles, you can filter on the attribute(s) you create. For more information, refer to Create a role glossary attribute.

    Exclude access granted only from a role

    Enabled by default.

    Excludes account and entitlement line items that are granted only through a role.

    Identity Governance cannot certify or revoke an application or entitlement from an end user when they’re granted access through a role; therefore, excluding these line items can help reduce unnecessary information in the certification.

    For more information, refer to Decisions change based on how you grant access.

    Exclude dynamically granted role memberships

    Displays if you selected Certify User Roles.

    Enabled by default if you are creating a role membership certification.

    Exclude role line items that are granted to an end user through a condition.

    Identity Governance can’t certify or revoke an end user being a member of a role through a condition; therefore, excluding these line items can help reduce unnecessary information in the certification.

    For more information, refer to Decisions change based on how you grant access.

    (Optional) Show advanced filters

    To certify accounts based on properties from the last certification decision made on a line item from the drop-down, select Filter by last certification decision.

    A line item is a particular record for a certifier to review. For example, the user Barbara Jensen’s record that details their access to a particular application is a line item.

  2. Click Next.

When to Certify

The When to Certify section lets the administrator specify when to kick off the review process (campaign) and what to do in the event the campaign expires.

To complete this section, do the following:

  1. Complete the following fields:

    Field Description

    Schedule

    Define whether the template will kick off on a periodic basis. If selected, input various choices to define the schedule.

    Check the Run on a schedule box to define a schedule for the template.

    Options include:

    • Run Every - Run the certification every specified number of days, weeks, months, or years.

    • Start - Specify a start time when this campaign kicks off for the first time.

    • End - Run the certification on its defined periodic basis until this date is reached.

    Campaign Duration

    Specify the amount of time each access review (campaign) has before expiration. You can specify the duration in days, weeks, months, or years.

    When Campaign Expires

    Select a behavior to handle the open access review (campaign) line items when the campaign expires:

    • Close open items - Complete the items using the given information after the campaign expires. The administrator can select what decision to add to the item (certify, revoke, and allow exception to) and when that decision takes effect. The decision can take effect immediately or after a duration (in days).

    • Reassign to - Select a given user or role that the access review (campaign) is reassigned to after the expiration date. The campaign will not be closed.

    • Do Nothing - No action will be taken, and the line items will remain in progress.

  2. Click Next.

Who will Certify

This section allows you to specify the users that review and make decisions about the items you defined in the What to Certify section.

To complete this section, do the following:

  1. Complete the following fields:

    Field Description

    Certifier Type

    Specify who can review and certify user access by selecting one of the following:

    • User — Select a single user to review and make a decision on every record. When you select this, a Select user box displays. Select the user who will certify the campaign.

    • Role — Select a role that allows any of its members to review every record. When you select this, a Select a role box displays. Select a role from the list of the created roles in Advanced Identity Cloud.

    • Manager — The user’s manager becomes the certifier of their data (also known as a line item).

    • Organization Admin - Select an administrator for an organization who can certify their data.

    Enable default certifiers

    Select a certifier to assign in case an access review (campaign) line item is not assigned a certifier. For example, if the manager is the certifier and the user has no manager defined, then the default certifier will be assigned the access review for this user.

  2. Click Next.

Notifications

This optional section allows you to send email notifications when one or more campaign events are triggered. For example, when a campaign is about to expire or when a certifier is reassigned.

To complete this section, do the following:

  1. Define an email template for each selected notification. Each notification requires an associated email template. From the left navigation pane in the Advanced Identity Cloud admin console, go to Email > Templates. For more information, refer to Email templates.

    There are preset email templates created for certification templates. Use these as a base, copy the email template, and customize them to suit your needs.

    To reference variables in your email templates for Identity Governance, the object is nested an additional level. The following table shows how to access these objects:

    Item Usage

    User attributes

    Use the syntax object.user.userAttribute.

    Use the attributes available from the email template screen. For more information, refer to Email templates.

    Manager attributes

    Use the syntax object.manager.managerAttribute.

    Use the attributes available from the email template screen. For more information, refer to Email templates.

    If the manager is the certifier type in the Who will Certify section, use the same user attributes in the managerAttribute. For example, if you need to reference a user’s manager within the email, then use this object.

    Campaign attributes

    Use the syntax object.campaign.campaignAttribute.

    Available attributes are name and type.

  2. Select any of the notification types:

    Field Description

    Send initial notification

    Send a notification any time a certifier is assigned to a line item.

    Send reassign notification

    Send to a new certifier when a line item in an access review (campaign) is reassigned or forwarded to them.

    Send expiration notification

    Send a reminder notification to the certifiers before a campaign expires. Select the number of days, before the campaign expires, to send the reminder.

    To illustrate the expiration notification mechanism:

    If the notification is set for three days prior to expiration, reviewers will receive an email when the campaign is three days away from the expiration date. If the deadline is extended by a week, the expiration date of the notification will be recalculated and sent three days before the new deadline, regardless of any previously sent notifications.

    Send reminders

    Send a notification to remind certifiers to take action on access review (campaign) line items. Select the number of days, weeks, months, or years to send the reminder.

    Enable escalation

    Send an escalation notification to specific recipients that certifiers have not completed their actions on a campaign. When selected, an additional Escalation Owner box displays. Select the number of days, weeks, months, or years and the user to send the escalation to.

  3. Click Next.

Additional options

This optional section allows you to configure other options for a campaign, such as performing bulk certifications or reassigning tasks to another user or group.

To complete this section, do the following:

  1. Complete the following optional fields:

    Field Description

    Allow self-certification

    Allows select individuals to certify their own data.

    The options to choose from are:

    • All certifiers - Users who are certifying the access review (campaign) can certify their own access.

    • Owners and administrators - Users who are campaign owners or tenant administrators can certify their own access.

    Enable line item reassignment and delegation

    Allow the certifier to reassign or forward a line item to another user.

    When you select this box, you can choose the following options:

    • Forward - Allow certifiers to forward their access review (campaign) to another certifier. When forwarding an access review, other certifiers are removed from the access review in its entirety. For more information, refer to forward line items.

    • Reassign - Select the privileges the current certifier can assign to the new certifier:

      • Add Comment

      • Make Decision

      • Reassign/Forward

      • Sign off

        For context on how you use this as a certifier, refer to reassign line items.

    Require justification on revoke

    Require a mandatory comment or reason for the revocation.

    Require justification on exception

    Require a mandatory comment or reason for any allowed exception.

    Allow exceptions

    Allow certifiers to continue to certify line items assigned to them after the campaign expires. Select a duration in days, months, weeks, or years.

    Allow bulk-decisions

    Allow certifiers to make line item decisions in bulk.

    This includes:

    • Making a decision (certify, revoke, exception).

    • If Enable line item reassignment and delegation is enabled, then you can bulk Reassign and/or Forward line items.

    As an administrator, most access reviews require an in-depth look on each line item. This is to ensure accuracy of each item. Bulk-decisions allow for a certifier to make a decision on many items at once, which could lead to inaccurate data. Use caution when selecting this option.

    Allow partial sign-off

    Allow a certifier to sign-off on an access review before their assigned line items have a decision made on them.

    Process remediation

    Revokes the end user’s access in the target application when a certifier revokes (denies) the line item. Select a workflow to run either immediately after revocation of access or after a duration.

    To ensure end-user access is removed when revoking a line item, you must enable this property.

  2. Click Next.

Summary

The Summary section is the final section in creating a template. It gives a breakdown of each section in the template, allowing for a review.

Summary steps:

  1. Review each section.

  2. Click Save to complete the certification template.

    Under the What to Certify review section, ensure that the Total Decision Items is greater than 0. If you identify that this is 0, this means that the template did not identify items to be certified. Therefore, if you create the campaign off of the template, the system will immediately cancel the campaign. If you identify this to be 0, go back to the What to Certify section and adjust your settings.

Entitlement assignment certification

Select an entitlement assignment certification type to certify the entitlements users have in specific applications.

Certifiers review the accounts and entitlements a user has in every onboarded target applications. When certifying, if the entitlement line item, and the line item has the decision of revoke, then the entitlement the user has in the application will be removed when the certification is signed-off.

To review information about templates, refer to Create templates.

You must populate the Display Name Attribute on the target application User entity object in the Details tab.

This allows each account pulled into Advanced Identity Cloud to display with a human-readable name. This is required for the data to properly display when a certifier (reviewer) reviewers their certification.

Perform the following:

  1. From the Advanced Identity Cloud admin console, go to Applications > Select Application.

  2. Select the object that represents the user entity in the target application.

  3. Go to the Details tab.

  4. Populate the Display Name Attribute with an attribute from the target application.

The following video shows an example:

The following table lists the areas to configure for each campaign template type:

Section Description

Details

General details of the template, such as the name, description, and a default certifier.

What to Certify

The items to be certified.

When to Certify

The cadence in which the review process is kicks off (campaign).

Who will Certify

The end users responsible for certifying the items in the campaign.

Notifications

Optional. Set up email notifications based on various events that take place during the certification process.

Additional options

Optional. Various configurations to allow during the campaign, such as bulk actions on line items or self-certification.

Summary

Summary of configured sections.

Details

This section includes basic information about the template, such as the display name, description, owner, and staging process.

To complete this section, do the following:

  1. From the Advanced Identity Cloud admin console, click Certification > Templates > + New Template.

  2. Select Entitlement Assignment Certification.

  3. Click Next.

  4. Complete the following fields:

    Field Description

    Certification Name

    The display name for the certification. This certification name displays on both the certifications tab and the end-user tasks dashboard.

    Define a date variable in the name of the certification to know which campaign kicks off. Identity Governance uses moment.js to format the date.

    For example, if you have a certification that is scheduled to run every two weeks, appending the date to the name lets you know which campaign you are working on.

    For example, the certification name can include the date (year, month, day), time (hour, minute), and time of day (AM/PM):

    Campaign name — {{YYYY-MM-DD-hh:mma}}

    When you kick off a template into a campaign, an example of the name is: Campaign name — 2023-12-12-08:18pm

    Once the campaign kicks off you cannot modify the name.

    Description

    Enter a general description for the certification. Your company should follow a descriptive convention to describe each of your certifications.

    This field is limited to 1000 characters.

    Certification Owner

    Enter the owner of the certification. Only certification owners can fully control their certifications, including certification decisions, certifier assignment changes, sign off, and more.

    Enable Campaign Staging

    Enable certification staging to set up the certification in the system but not activate it in production. This option allows compliance officers to preview a certification before it is activated and exposed to end users. Compliance officers can inspect and review the content, decision items, and other details to determine whether to activate or delete it.

  5. Click Next.

What to Certify

This section lets you define the items to certify, including the users, applications, accounts, and entitlements.

To complete this section, do the following:

  1. Complete the following fields:

    Field Description

    Entitlements

    Certify one of the following:

    • All entitlements

    • Entitlements matching a filter — Create a filter to certify specific entitlements.

      If you create a governance glossary attribute and enhance the onboarded entitlement(s) with the attribute, you can filter on the attribute(s) you create.

      For more information, refer to the Manage governance glossary.

    Applications

    Certify one of the following:

    • All applications

    • Specific applications — If you select this, an additional box is displayed to select which Applications to certify.

    • Applications matching a specific filter — Create a filter to certify specific applications.

      If you create a governance glossary attribute and enhance the target application(s) with the attribute, you can filter on the attribute(s) you create. For more information, refer to the Manage governance glossary.

    Users

    Certify one of the following:

    • All users

    • A single user

    • Users matching a filter — Create a filter to certify select users.

    Exclude access granted only from a role

    Enabled by default.

    Excludes entitlement line items that are granted only through a role.

    Identity Governance cannot certify or revoke an entitlement from an end user when they’re granted access through a role; therefore, excluding these line items can help reduce unnecessary information in the certification.

    For more information, refer to Decisions change based on how you grant access.

    (Optional) Show advanced filters

    To certify accounts based on properties from the last certification decision made on a line item from the drop-down, select Filter by last certification decision.

    A line item is a particular record for a certifier to review. For example, the user Barbara Jensen’s record that details their access to a particular application is a line item.

  2. Click Next.

When to Certify

The When to Certify section lets the administrator specify when to kick off the review process (campaign) and what to do in the event the campaign expires.

To complete this section, do the following:

  1. Complete the following fields:

    Field Description

    Schedule

    Define whether the template will kick off on a periodic basis. If selected, input various choices to define the schedule.

    Check the Run on a schedule box to define a schedule for the template.

    Options include:

    • Run Every - Run the certification every specified number of days, weeks, months, or years.

    • Start - Specify a start time when this campaign kicks off for the first time.

    • End - Run the certification on its defined periodic basis until this date is reached.

    Campaign Duration

    Specify the amount of time each access review (campaign) has before expiration. You can specify the duration in days, weeks, months, or years.

    When Campaign Expires

    Select a behavior to handle the open access review (campaign) line items when the campaign expires:

    • Close open items - Complete the items using the given information after the campaign expires. The administrator can select what decision to add to the item (certify, revoke, and allow exception to) and when that decision takes effect. The decision can take effect immediately or after a duration (in days).

    • Reassign to - Select a given user or role that the access review (campaign) is reassigned to after the expiration date. The campaign will not be closed.

    • Do Nothing - No action will be taken, and the line items will remain in progress.

  2. Click Next.

Who will Certify

This section allows you to specify the users that review and make decisions about the items you defined in the What to Certify section.

To complete this section, do the following:

  1. Complete the following fields:

    Field Description

    Certifier Type

    Specify who can review and certify user access by selecting one of the following:

    • User — Select a single user to review and make a decision on every record. When you select this, a Select user box displays. Select the user who will certify the campaign.

    • Role — Select a role that allows any of its members to review every record. When you select this, a Select a role box displays. Select a role from the list of the created roles in Advanced Identity Cloud.

    • Entitlement Owner — Select the user who manages the entitlement.

    Enable default certifiers

    Select a certifier to assign in case an access review (campaign) line item is not assigned a certifier. For example, if the manager is the certifier and the user has no manager defined, then the default certifier will be assigned the access review for this user.

  2. Click Next.

Notifications

This optional section allows you to send email notifications when one or more campaign events are triggered. For example, when a campaign is about to expire or when a certifier is reassigned.

To complete this section, do the following:

  1. Define an email template for each selected notification. Each notification requires an associated email template. From the left navigation pane in the Advanced Identity Cloud admin console, go to Email > Templates. For more information, refer to Email templates.

    There are preset email templates created for certification templates. Use these as a base, copy the email template, and customize them to suit your needs.

    To reference variables in your email templates for Identity Governance, the object is nested an additional level. The following table shows how to access these objects:

    Item Usage

    User attributes

    Use the syntax object.user.userAttribute.

    Use the attributes available from the email template screen. For more information, refer to Email templates.

    Manager attributes

    Use the syntax object.manager.managerAttribute.

    Use the attributes available from the email template screen. For more information, refer to Email templates.

    If the manager is the certifier type in the Who will Certify section, use the same user attributes in the managerAttribute. For example, if you need to reference a user’s manager within the email, then use this object.

    Campaign attributes

    Use the syntax object.campaign.campaignAttribute.

    Available attributes are name and type.

  2. Select any of the notification types:

    Field Description

    Send initial notification

    Send a notification any time a certifier is assigned to a line item.

    Send reassign notification

    Send to a new certifier when a line item in an access review (campaign) is reassigned or forwarded to them.

    Send expiration notification

    Send a reminder notification to the certifiers before a campaign expires. Select the number of days, before the campaign expires, to send the reminder.

    To illustrate the expiration notification mechanism:

    If the notification is set for three days prior to expiration, reviewers will receive an email when the campaign is three days away from the expiration date. If the deadline is extended by a week, the expiration date of the notification will be recalculated and sent three days before the new deadline, regardless of any previously sent notifications.

    Send reminders

    Send a notification to remind certifiers to take action on access review (campaign) line items. Select the number of days, weeks, months, or years to send the reminder.

    Enable escalation

    Send an escalation notification to specific recipients that certifiers have not completed their actions on a campaign. When selected, an additional Escalation Owner box displays. Select the number of days, weeks, months, or years and the user to send the escalation to.

  3. Click Next.

Additional options

This optional section allows you to configure other options for a campaign, such as performing bulk certifications or reassigning tasks to another user or group.

To complete this section, do the following:

  1. Complete the following optional fields:

    Field Description

    Allow self-certification

    Allows select individuals to certify their own data.

    The options to choose from are:

    • All certifiers - Users who are certifying the access review (campaign) can certify their own access.

    • Owners and administrators - Users who are campaign owners or tenant administrators can certify their own access.

    Enable line item reassignment and delegation

    Allow the certifier to reassign or forward a line item to another user.

    When you select this box, you can choose the following options:

    • Forward - Allow certifiers to forward their access review (campaign) to another certifier. When forwarding an access review, other certifiers are removed from the access review in its entirety. For more information, refer to forward line items.

    • Reassign - Select the privileges the current certifier can assign to the new certifier:

      • Add Comment

      • Make Decision

      • Reassign/Forward

      • Sign off

        For context on how you use this as a certifier, refer to reassign line items.

    Require justification on revoke

    Require a mandatory comment or reason for the revocation.

    Require justification on exception

    Require a mandatory comment or reason for any allowed exception.

    Allow exceptions

    Allow certifiers to continue to certify line items assigned to them after the campaign expires. Select a duration in days, months, weeks, or years.

    Allow bulk-decisions

    Allow certifiers to make line item decisions in bulk.

    This includes:

    • Making a decision (certify, revoke, exception).

    • If Enable line item reassignment and delegation is enabled, then you can bulk Reassign and/or Forward line items.

    As an administrator, most access reviews require an in-depth look on each line item. This is to ensure accuracy of each item. Bulk-decisions allow for a certifier to make a decision on many items at once, which could lead to inaccurate data. Use caution when selecting this option.

    Allow partial sign-off

    Allow a certifier to sign-off on an access review before their assigned line items have a decision made on them.

    Process remediation

    Revokes the end user’s access in the target application when a certifier revokes (denies) the line item. Select a workflow to run either immediately after revocation of access or after a duration.

    To ensure end-user access is removed when revoking a line item, you must enable this property.

  2. Click Next.

Summary

The Summary section is the final section in creating a template. It gives a breakdown of each section in the template, allowing for a review.

Summary steps:

  1. Review each section.

  2. Click Save to complete the certification template.

    Under the What to Certify review section, ensure that the Total Decision Items is greater than 0. If you identify that this is 0, this means that the template did not identify items to be certified. Therefore, if you create the campaign off of the template, the system will immediately cancel the campaign. If you identify this to be 0, go back to the What to Certify section and adjust your settings.

Kick off data review process using campaigns

Campaigns are the second step in certifying access for users.

Once you create a template, and you are ready to start the review process, create a campaign.

After you start a campaign, the end users (certifiers), that are defined in the template, are notified to start reviewing the data. The process of certifiers reviewing data is called an access review.

When you kick off a campaign, through the ad-hoc (one time) run under the Templates tab or through the schedule set in the template, the Certification tab displays the certification.

The following video shows an example:

To access campaigns, from the Advanced Identity Cloud admin console, click Certification > Campaigns tab.

governance campaigns tab

View campaigns

The landing page/modal on the Campaigns tab displays Active campaigns.

To view campaigns that have a specific status, such as Closed or Canceled, click the Status drop-down and filter the status.

To view additional campaigns, click the caret icons at the bottom of the table.
Campaign statuses to filter
Status Description

Active

The campaign is in progress. In the Status column, this includes the In-progress, Expiring and Overdue states.

  • In-progress — The campaign is in progress and active.

  • Expiring — The campaign is in process and expires in two days or less. The template defines the deadline; however, you can update the deadline at any time.

  • Overdue — The campaign is past the expiration date but in process. Tasks still require completion. Identity Governance sets this status when you select one of the following settings in the template:

    • When to Certify > When certification expires > Close open items > Reassign.

    • Do nothing.

      The template defines the deadline; however, you can update the deadline at any time.

Expired

The campaign expired. Advanced Identity Cloud triggers this status when you select When to Certify > When certification expires > Close open items > immediately in the template.

Cancelled

This campaign was canceled manually and is no longer in progress. In certain situations when there is an error creating the campaign from the template, a campaign might automatically go into this state.

Completed

The campaign finished as expected with no issues.

Staged

The campaign is staged and is not active. For more information, refer to the details section of creating a template.

Campaign landing page columns

The campaigns listed on the landing page of the Campaigns tab consists of a table with various columns.

Field Description

Name

The name of the campaign. This name is generated from the template.

Deadline

The campaign completion date.

Status

The state the campaign is in. Refer to Campaign statuses to filter for more information.

Progress

The percent complete of the campaign.

To view the percentage and number of items that are complete, hover over the progress icon.
To filter a column, click the up/down icon (where applicable).
Update deadline of campaign

The deadline (expiration) of a campaign can be updated once a campaign is ran.

To update the deadline:

  1. From the Advanced Identity Cloud admin console, click Certifications.

  2. Select the Campaigns tab.

  3. Click next to the campaign to update the deadline.

  4. Enter a new date.

  5. Click Save.

View details of campaign

From the Campaigns tab on the landing page, click the desired campaign to view more details.

The data the page displays depends on the certification type in the template.

The selected campaign includes two tabs:

Details tab

The Details tab includes graphical information about the campaign. For example, the percentage of completeness or the reviews currently in progress.

The information is broken out into various cards. The following table shows the various information by card.

Campaign details page
Card/Title Description

Status

Provides information about when the campaign expires. You can select Cancel Campaign to cancel the campaign.

If the campaign status is Staged, you can select Activate to kick-off the campaign.

Campaign Details

Shows the percentage of the campaign complete, including the number of reviews completed versus the total amount of reviews, as well as general information about the campaign:

  • Campaign Owner — The person responsible for the overall campaign.

  • Duration — The length of the campaign.

  • Start Date — The date the campaign was started (either manually through ad-hoc or via a pre-defined schedule).

  • Deadline — The date the campaign expires.

  • Description — Information about the campaign.

Users

Pie chart.

The number of new users versus previously certified users in the campaign.

Decisions Breakdown

Pie chart.

A breakdown of the decisions made in the campaign by certifiers (certified, revoked, exception).

Access by Application

Pie chart.

The number of accounts by application to be certified in the campaign.

Users with no email address

Numerical.

The number of users that do not have an email address on their profile.

Certifiers with no email address

Numerical.

The number of certifiers (reviewers) that do not have an email address on their profile.

Access reviews tab

The Access Reviews tab contains information on the certifiers in the campaign. The certifiers could be an individual or a role. This includes the progress they have made on their reviews, as well as the ability to view the items each certifier is responsible for.

By default, the page displays the certifiers who are reviewing the access review, which is in the Active state.

To view other statuses, select the Status drop-down:

Certifier statuses to filter
Status Description

Active

The certifier has line items on the campaign that do not have a decision made on them. A line item is a record for a certifier to review. For example, the user Barbara Jensen’s record that details their access to a particular application is a line item.

Expired

The campaign has passed its deadline and the certifier has line items that do not have a decision made on them.

Completed

The certifier has reviewed and made decisions on the line items assigned to them in their access review and signed off.

You can use the search icon to search for a specific campaign by its name.

There are three columns in the Access Reviews tab:

  • Certifier — The individual or users assigned to a role responsible for a part of the campaign.

  • Status — The status of the campaign.

  • Progress — The progress the certifier has made in their reviews.

    To view the percentage and number of items that are complete, hover over the progress icon.

Click the arrow icon on Certifier to filter alphabetically (ascending or descending).

To view additional features, such as forwarding a certifier’s items to another person or end users assigned to a role, click to the right of the table.

To gain a detailed view of the items left for a certifier, click on their record in the table. The drilled-down view is the same view a certifier utilizes when completing their items for the campaign. For more information on this view, refer to Certify data using access reviews.

Cancel existing campaign

You can only cancel a campaign that is in the Active state (which includes the states Expiring and Overdue). For more information, refer to Campaign statuses to filter.

There are two ways to cancel a campaign:

  1. When viewing campaigns from the Certifications > Campaigns landing page:

    1. Click next to the campaign.

    2. Click Cancel.

    3. Click Cancel Campaign.

  2. In the drill-down campaign view:

    1. Click into a campaign.

    2. Click Cancel Campaign.

    3. Click Cancel Campaign again in the confirmation screen.

Certify data using access reviews

Access reviews are the final step of certifying access for users.

After you kick off the data review process in a campaign, the data defined for review is sent to the end users you define in the template.

The process of end users certifying the data assigned to them is called an access review.

Notes on access reviews:

  • An access review consists of one or more line items or records to review and certify.

  • An end user who has an access review is considered a reviewer of the certification, also called a certifier.

  • Multiple certifiers can be assigned to review the same data.

  • When an end user is designated as a reviewer from a campaign, it displays under Inbox > Access Reviews or in the Dashboard landing page.

  • You define the certifiers when you create a template and kick off a campaign. A reviewer can also be added through forwarding or reassignment by certifiers and administrators.

  • Certifiers can change the decision a previous certifier made for a line item; however, changes cannot be made to a campaign after a decision is set and the campaign is signed off (completed). Additional changes require remediation through another campaign.

    For example, if one certifier decides to certify the access for a line item, but another certifier decides to revoke access for it after, then the last certifier’s decision is the decision that prevails.

  • For more information on how access reviews display to certifiers in the end-user UI, refer to Access reviews.

As there are various features that become enabled or disabled for end user access reviews depending on the configurations in the template, the following is a table to quick links in this page.

Details
Item Description

View access review tasks

A landing screen that shows access reviews that are assigned to an end user.

This includes an explanation of the access review landing page columns.

View individual access review line items

The screen where end users complete the access review of the line items for a campaign.

A line item is a record for a certifier to review. For example, the user Barbara Jensen’s record that details their access to a particular application is a line item.

This includes:

  • Access review task columns: A description of the columns that display when end users certify items.

  • High-level reviewer steps: An overview of potential steps to take when reviewing items. Since there are various combinations of configurations you can make in the template, this process is subject to change.

Filter and group items

Filter campaign items that display data in different ways.

Customize table columns

Rearrange or hide the table columns.

Add comment

Provide a comment on a line item in the access review.

Use cases include:

  • Justification for why a decision was made.

  • Rationale for reassigning the item.

  • Rationale for forwarding the item.

  • To view/respond to a comment left by another reviewer.

Make a decision (certify)

Make a decision to either certify access, revoke access, or provide an exception to access for a specified duration (you must enable the configurations in the template).

View other certifiers

View other reviewers assigned to a line item in the access review.

Reassign an item[16]

An end user can reassign an item that is assigned to them and define the permissions of the new assignee.

There are two ways to reassign a line item:

Forward an item[16]

Remove prior reviewers and assign the line item to another individual(s). Full permissions on the item are given to the forwarded individual(s).

There are two ways to forward a line item:

Bulk certify items[16]

Perform a bulk line item certification. Not recommended for every campaign as this will bypass much needed manual oversight on each item.

View access review tasks

To view the access review tasks, from the Advanced Identity Cloud end-user UI, click Inbox > Access Reviews.

The landing screen on Access Reviews is a view of the active campaigns that have a task assigned to an end user.

To view campaigns that have a specific status, such as Closed or Canceled, click the Status drop-down and filter the status.

To view additional tasks, click the caret icons at the bottom of the table.
Campaign statuses to filter
Status Description

Active

The campaign is in progress. In the Status column, this includes the In-progress, Expiring and Overdue states.

  • In-progress: The campaign is in progress and active.

  • Expiring: The campaign is in process and expires in two days or less. The template defines the deadline; however, you can update the deadline at any time.

  • Overdue: The campaign is past the expiration date but in process. Tasks still require completion. Identity Governance sets this status when you select one of the following settings in the template:

    • When to Certify > When certification expires > Close open items > Reassign.

    • Do nothing.

      The template defines the deadline; however, you can update the deadline at any time.

Expired

The campaign expired. Advanced Identity Cloud triggers this status when and end user selects When to Certify > When certification expires > Close open items > immediately in the template.

Completed

The campaign finished as expected with no issues.

Access reviews landing page columns

The campaigns listed on the landing page of the Access Reviews tab consists of a table with various columns.

Field Description

Name

The name of the campaign. This name is generated from the template.

Deadline

The date in which the campaign must be completed.

Status

The state the campaign is in. Refer to Campaign statuses to filter for more information.

Progress

The percent complete of the campaign.

To view the percentage and number of items that are complete, hover over the progress icon.
To filter a column, click the up/down icon.

To view additional features, such as forwarding a certifier’s items to another person or end users assigned to a role, click to the right of the table.

View individual access review line items

For an end user to review the line items they need to certify, click an access review (campaign).

The top section of the screen shows information about the access review including:

  • The Status metric shows the percentage of items to complete, as well as a numeric value of items that are complete versus the total amount of items.

  • The Decisions pie chart is shows the number of records certified versus revoked.

  • The Deadline is the campaign completion date. Click the View campaign details to view additional information such as the description of the campaign and the campaign owner.

Access review task columns

The following columns can change depending on the certification type and configuration options in the template.

The columns in the line items table are:

Field Description

User

The user in Advanced Identity Cloud.

Application

The onboarded application the user has access to.

Account

The account in the application that correlates to a user in Advanced Identity Cloud.

Entitlement

The entitlement in the application the user has granted.

Flags

Information about how access was given. One or more of these flags can display on a line item:

  • sync Reconciliation — Access was granted through a reconciliation process.

  • person_add Request-based - Access was granted through a request.

  • assignment_ind Role-based — Access was granted through a role.

  • date_range Temporal constraints — Access was granted through a role; however, only for a specified period of time.

  • add_circle_outline New access — Access is new and has never been certified.

Comment

Comments that have been made on a record in a campaign. A number above the comment icon indicates the amount of comments left.

Decision

The action taken on a record in a certification.

Options are:

  • Certify access

  • Revoke access

  • Allow an exception: For this to display, you must configure the Additional options section of the template.

To view information about a line item, click on the item under the column. For example, to review a user’s information in Advanced Identity Cloud for an identity certification type, click the user’s name and a modal window pops up displaying the information for review. The same is true for each single item in a row.

The following video shows an example:
To view additional line items in the access review, click the caret icon at the bottom of the table.

High-level reviewer steps

The following are typical steps when an end user certifies line items in an access review (campaign):

  1. Click into a record and review information by clicking into each item in the row.

  2. Add a comment if necessary (or mandatory if the campaign requires it).

  3. Make a decision by selecting Certify access, Revoke access, or Allow an exception. The last reviewer on the item to make a decision is the decision that will prevail for the item.

  4. Repeat steps 1-3 for each line item in the table.

  5. Once an end user certifies every record, click Sign-off. Once this takes place, no changes can be made to the campaign as it acts as the final decision on a certification.

    If Allow partial sign-off is enabled in the Additional Options section of the campaign template, then the line items do not have to be completed before the task can be signed off. A gradual fashion can be used whereas a subset of the items can be signed off and the other items can be completed at a later date. For more information on setting these configurations in the template, refer to additional options.

    The following video shows an example:

These steps may vary depending on the configurations made in the template. For example, if bulk actions is enabled, then the certifier has the ability to make a decision for the items in the table at once. Additionally, the task could be reassigned or forwarded.

Subsequent sections display various functions of the certifier process in detail.

Filter and group items

End users can filter and group items to make them more manageable when certifying.

The following video shows an example:

Filter items

Certifiers can manipulate the data presented on an access review.

To filter the items, click on the filter icon in the top right of the line items table. Once selected, there are two ways to filter:

  • By decision: Filter the table by the decision made on a line item, either Certified, Revoked, Exception Allowed, or No Decision.

  • By item attributes: Filter the table by a particular column item, such as a user. Click the item to filter on, then enter the appropriate value in the additional box that is displayed.

Group items

Grouping items aggregates duplicate information.

For example, if a user has four entitlements, the campaign items table displays this as four separate records. In grouping by fields, the entitlements display as a sub-table under a record, reducing the redundancy of reviewing the same record’s information.

To group the items, click the Group By icon above the Filter icon.

When end users select an object to group by, for example, Account, the view of the table changes splitting the screen in half.

If an end user selects multiple items in the What to Certify, such as accounts and entitlements, they can navigate between the various items.

Customize table columns

An end user can modify the columns presented in the line items table.

For example, they may want to display additional user properties.

To customize columns:

  1. Click the view column icon (view_column).

  2. Under Available Columns, click each section and select or deselect the columns to display.

  3. Under Active Columns, rearrange the order of the columns by clicking the drag icon (drag_indicator) and dragging each column to the desired order.

    To delete an Active Column, click the delete icon (delete).

  4. Click Apply.

Add comment

Certifiers can leave a comment in an access review.

The comment could vary in nature due to a number of reasons:

  • A justification for the decision being made.

  • A comment about why the item is being reassigned.

  • A comment about why the item is being forwarded.

  • A comment from another certifier if there are multiple certifier on the line item(s).

An auto-generated comment is created when an item is forwarded or reassigned.

To add a comment:

  1. To get to the comment box either:

    • Click the comment icon box.

    • Click next the item to comment on and click the Add Comment.

  2. Enter the comment.

  3. Click Add Comment.

Once a comment has been made and added to a line item, it cannot be removed.

Make a decision (certify)

A decision is an action a certifier makes on a line item in an access review.

governance user tasks certs decision choices

A certifier can do one of the following:

  • To Certify (keep) access, click the green checkmark icon.

  • To Revoke (deny) access, click the circle-backslash icon. After selecting this, a mandatory comment box displays to the certifier in which they must enter a reason for revoking the line item.

    When the campaign is signed off, if the Process remediation configuration option is enabled in the Additional Options section of the template, then the line item will be removed from the onboarded application.

  • The clock icon is disabled unless you explicitly enable exceptions by marking Allow Exceptions (under Additional Options) as allowed.

    You can also specify the duration for exceptions under Additional Options. For more information, refer to additional options.

A certifier can only make a decision once per line item, no matter the number of certifiers. The decision made by the last certifier on a line item is the decision that prevails. After an access review (campaign) is signed off, a decision cannot be modified.

Decisions change based on how you grant access

Depending on the certification type and how an end user is given access to a resource, the decisions a certifier can take on a line item changes:

How you grant access Cert type Notes

To an application or entitlement via a role.

Identity

Identity Governance cannot certify or revoke the line item if you assign an end user to an application or entitlement using a role.

To remove the user from the application or entitlement, remove them from the role.

Identity Governance displays that the access is role-based by the assignment_ind Role-based flag being present in the Flags column.

In the What to Certify section of the template, you select to certify Roles and an end user is assigned to a role through a condition being met.

Identity

Identity Governance cannot certify or revoke an end user being a member of a role through a condition.

To remove the end user from the role, update them to no longer meet the condition.

To an entitlement via a role.

Entitlement

Identity Governance cannot certify or revoke the line item if you assign an end user to an entitlement using a role.

To remove an end user from an entitlement, when they’re granted access through a role, remove them from the role.

Through a role with a condition.

Role membership

Identity Governance cannot certify or revoke an end user being a member of a role through a condition.

To remove the end user from the role, update them to no longer meet the condition.

For each situation, the following UI elements change:

  • The Revoke and Allow an Exception decisions are disabled.

  • The Certify text changes to Acknowledge.

  • The line item cannot be used with bulk certify.

View other certifiers

For each line item in the access review, certifiers have the ability to view the other certifiers. To view the certifiers, click next to the item and click View Reviewers.

From here an end user has the ability to:

Edit certifier privileges
To edit the privileges a certifier has, you must enable the configuration setting Enable line item reassignment > Reassign in the Additional Options section of the template.

To edit the permissions of a certifier on a line item:

  1. Click next to the line item and click View Reviewers.

  2. End users locate the certifier they would like to modify and click > Edit.

  3. Select/deselect the privileges on the certifier.

  4. Click Save.

Reassign an item

End users reassign a line item by adding another certifier to review the item. When a certifier adds another certifier, they specify the privileges of the certifier.

To reassign an item, you must enable the configuration setting Enable line item reassignment > Reassign in the Additional Options section of the template. For more information, refer to additional options.

There are two ways to reassign an item:

Reassign from view reviewers screen

  1. On the item, click > View Reviewers.

  2. Click + Add a Reviewer.

  3. Select to add either Add a user or Add a role to the line item.

  4. Search for the individual or role and select it.

  5. Select the privileges that the new end user or role will have on the line item. The privileges you can add are:

    1. View — Allows another end user to view the line item.

    2. Comment — Allows another end user to leave a comment on the line item.

    3. Decide — Allows another end user to make a decision on the line item.

    4. Assign/Forward — Allows another end user to reassign or forward the line item.

    5. Sign off — Allows another end user to sign-off on the line item.

      You can only select a privilege if enabled from the template under the Additional Options section. Therefore, the options listed above are subject to change. For more information, refer to additional options.

  6. Click Reassign.

Reassign from bulk reassign
The option for bulk certify and reassign must first be enabled in the Additional Options section of the template before bulk reassign can be utilized. For more details, refer to Bulk certify items.

  1. After selecting more than one item, click the Actions drop-down that shows and select Reassign.

  2. In the modal, choose to reassign to Another user or to Users with assigned role to the line item.

  3. Search for the individual or role and select it.

  4. Select the privileges that the user or role will have on the line item. The privileges you can add are:

    1. View — Allows a user to view the line item.

    2. Comment — Allows a user to leave a comment on the line item.

    3. Decide — Allows a user to make a decision on the line item.

    4. Forward — Allows a user to reassign or forward the line item.

    5. Sign off — Allows a user to sign-off on the line item.

      You will only be able to select a privilege if allowed from the template under the additional options section. Therefore, the options listed above are subject to change.

  5. Click Reassign.

Forward an item

When end users forward a line item in an access review, the end user removes prior certifiers and assigns the line item to another end user or role. The new certifier(s) have full permissions on the line item.

To forward a line item, you must enable the configuration setting Enable line item reassignment > Forward in the Additional Options section of the template.

There are two ways to forward an item:

Individual forwarding

  1. On the line item, click > Forward.

  2. In the modal, choose to forward the line item to Another user or to Users with assigned role.

  3. Search for the individual or role.

  4. End users leave a comment as to why they are forwarding the line item.

  5. Click Forward Item.

Bulk forwarding
The option for bulk certify and forward must first be enabled in the Additional Options section of the certification campaign template before bulk reassign can be utilized. For more details, refer to Bulk certify items.

  1. Select more than one item via the checkbox next to the items in the left of the certification items table or check the Select All box.

  2. Click the Actions drop-down that is displayed.

  3. Select Forward.

  4. A modal window is displayed.

  5. Select if the line items should be forwarded to Another user or Users with assigned role.

  6. Search for the individual or role.

  7. End users leave a comment as to why they are forwarding the line items.

  8. Click Forward Item.

Bulk certify items

The bulk certification of line items allow for many items to undergo the certification process at once instead of one-by-one. This configuration setting is not enabled by default and should be used with caution. Most access reviews require an in-depth look into the accuracy of data and bulk certification circumvents this.

To bulk certify line items, you must enable the configuration setting Allow Bulk Decisions in the Additional Options section of the template. For more information, refer to additional options.

Once the bulk certify option is enabled, checkboxes display to the left of the line items table. Additionally, a Select drop-down button displays at the top left of the campaign items table.

When end users select one or more items via the checkboxes, or they select All items (in the drop-down button of Select), an additional Actions drop-down button displays. End users click this button to view actions they can make in a bulk fashion.

Under the Select drop-down button, end users can choose to select All items that under review, All on this page, or Deselect all items.

The items that display under the Actions button vary depending on if the configuration settings that you enable in the template, but can include:

  • Certify

  • Revoke

  • Allow an exception

  • Reassign

  • Forward

Access requests

In Identity Governance, end users can request access to resources, such as target applications, entitlements, or roles.

You define the resources end users can request by adding them to the access catalog.

An organization works with access requests as follows:

  1. An Identity Governance administrator who can configure access requests. This includes defining which resources end users can request in the access catalog.

  2. After an administrator defines requestable resources in the access catalog, end users submit requests to gain or remove (managers only) access to resources using the end user UI.

  3. Approvers approve or deny access requests — End users configured as the approver (designated owner) to review and approve or reject the request. The items that display to the approver are known as request items.

Manage workflows

When you configure access requests, you can implement workflows, an end-to-end sequence of Identity Governance actions that result in either approving or rejecting an access request. You can configure workflows using the Advanced Identity Cloud’s workflow editor or REST APIs.

Workflows give complete flexibility over all access request types by allowing you to define custom workflow definitions. For example, when an end user requests access to an application, you can specify the actions Identity Governance takes for the access request to be approved or rejected.

These actions could include:

  • Requiring more than one approval for the request. You could require an end user’s manager and the application owner to approve the request before Identity Governance provisions access to the end user.

  • If the access request is rejected, send an email to the end user stating their access request has been denied.

Important aspects of workflows

  • Identity Governance provides default workflows for each access request type. Identity Governance also requires a workflow for each access request type; therefore, every access request type must have an associated workflow.

  • Each workflow has two states:

    • Draft: A staging state to validate a workflow before publishing. For a workflow to be live, you must publish it.

    • Published: The workflow is read-only and live.

  • You can create workflows using the following:

    • Workflow editor: An intuitive UI to easily create the workflows using nodes.

    • REST APIs: Use the REST APIs for workflow scripting.

  • Workflows are saved in JSON format.

The out-of-the-box Identity Governance workflows do not currently support the approval of custom request types, like event-based requests. In this case, you can use workflows with custom scripted nodes that can handle event-based situations, such as user create or user update. Learn more in Workflow use cases.

Access request types

Identity Governance provides six out-of-the-box workflows for each access request type.

The following table displays the different access request types and out-of-the-box workflows:

Access request type Workflow name Description

Grant Application

BasicApplicationGrant

Request access to an application.

Remove Application

BasicApplicationRemove

Request to remove access to an application for an end user.

Grant Entitlement

BasicEntitlementGrant

Request access to an entitlement (additional privilege inside an application).

Remove Entitlement

BasicEntitlementRemove

Request to remove access to an entitlement from an end user.

Grant Role

BasicRoleGrant

Request access to an Advanced Identity Cloud provisioning role.

Remove Role

BasicRoleRemove

Request to remove access to a role from an end user.

Create workflows using the workflow editor

To manage workflows, from the Advanced Identity Cloud admin console, go to manage_accounts Workflows.

There is a default published workflow for each access request type.

The workflow editor canvas.

  • 1 Click Governance > Workflows on the Advanced Identity Cloud end-user UI.

  • 2 Click New Workflow to create a workflow.

  • 3 Click Import to import a workflow JSON file.

  • 4 Enter a workflow in the Search field.

  • 5 Click the ellipsis () to do the following tasks depending on the workflow type:

    Every workflow has two states: draft and published. You can only modify a workflow in the draft state.

    • Workflow draft only: When a workflow is first created or imported, you get a workflow draft. The following options are available:

      • Edit draft

      • Export draft

      • Delete draft

    • Workflow published only: If a workflow draft is published, you will only have a published version. The following options are available:

      • New Draft

      • View published

      • Export published

      • Delete published

    • Out-of-the-box workflow: When you publish an out-of-the-box workflow, you will have a published version, which you can view, duplicate, or export. The following options are available:

      • View published

      • Duplicate

      • Export published

    • Workflow draft and published: If you have a published workflow, you can create a draft of it. Then, when you edit and save the draft, there will be both a draft and a published version of the workflow. The following options are available:

      • Edit draft

      • View published

      • Export draft

      • Export published

      • Delete draft

      • Delete published

Workflow editor canvas

When you click a workflow, a blank workflow canvas appears with workflow nodes in the left pane, which you can drag-and-drop onto the canvas.

The workflow editor canvas.

  • 1 Available workflow editor nodes.

  • 2 Perform orientation functions:

    zoom_in — Zoom in

    zoom_out — Zoom out

    fullscreen — Toggle fullscreen

    grid_on — Auto layout nodes on the canvas

    delete — When you select on or more nodes, the delete icon displays.

  • 3 Toggle between the draft and published states of a workflow.

  • 4 Click more_horiz (ellipsis icon) to:

    • View Details — View metadata, such as the state and workflow name.

    • Import — Upload a JSON file to create or override an existing draft.

    • Export — Download a JSON file of the workflow state.

    • Delete Draft — Only present when viewing the draft state of a workflow.

  • 5 Switch between viewing the workflow through the canvas UI or through JSON.

  • 6 Save or publish the existing workflow.

  • 7 The workflow editor canvas. Drag, drop, and connect nodes in the canvas to create your workflow.

When you click Publish in a workflow, it overrides the existing published version. Identity Governance prompts you to download Download backup. Always download a backup in case of an error.

View workflow in JSON

For technical users, Identity Governance provides the ability to view and download workflows using JSON. From the workflow editor canvas, toggle JSON. If you want to export the workflow JSON, click ellipsis (), and then Export. You can make adjustments and re-import the JSON into Identity Governance.

If you are exporting an out-of-box workflow, Identity Governance pulls the UUID of the users or roles from the environment and uses it in the JSON file. Make sure to reset or update the approver values in the Approver node in the JSON.
The Workflow JSON UI.

  • 1 Copy the JSON workflow file.

  • 2 Click to View Details, Import, and Export the JSON file.

  • 3 Toggle to enable or disable JSON view.

Workflow nodes

When you define a workflow, you specify each task through a node.

Identity Governance provides several nodes that allow you to customize your workflow.

For information on how to place nodes in a workflow, refer to workflow editor canvas.To use an If/else node or Switch node, you must set outcomes in the script.

For a comprehensive example of using the following nodes, refer to Workflow use cases.

Approval node

Requires a user’s input in the workflow. Define:

  • User(s) to approve the access request

  • What to do when the request expires. The end user defines the expiration when they create the access request.

  • Notifications to send.

Outcomes

  • Approved

  • Reject

Evaluation continues along the Approved outcome path if any of the defined approvers approve the request.

Evaluation continues along the Reject outcome path if any of the defined approvers reject the request.

Properties

Property Usage

Approvers

Select user(s) that must approve the access request.

  1. Select add.

  2. Select the approver type.

  3. Select the approver permissions for the access request.

  4. Click Add.

    To add more users to this task, repeat steps 1-4.

To define custom approvers that aren’t listed in step 2, click define a script > edit and write a JavaScript script.

Form

Select dynamic forms or choose a specific form to present to the reviewer.

  • Dynamic form selection.

  • Choose a form.

Expiration Settings

The end user defines the expiration when they create the access request. Select one of the following:

Reject request

Reject the access request.

Reassign request

Reassign the request to another user or role.

Do nothing

Take no action.

Notification Settings

Select which email notifications to send. By default all notifications are enabled. Select any of the following:

Assignment notification

Initial email to the approver(s) of a resource when an end user submits an access request. The default email template is Request Assigned. Select the email template to send.

Reassignment notification

Email to the new assignee when an approver forwards a request item. The default email template is Request Reassigned. Select the email template to send.

Assignee reminders

Email to the approver(s) as a reminder that they have a request item to act on. The default email template is Request Reminder.

  • Select the email template to send.

  • Define the frequency to send the reminder.

Escalation notification

Email to an individual assigned as the escalation point of contact. The default email template is Request Escalated.

  • Select the email template to send.

  • Define the frequency to send the escalation.

  • Select the user or role to send the escalation to.

Expiration notification

Email to the approver(s) when a request item expires. The default email template is Request Expired.

  • Select the email template to send.

  • Specify when to send the notification to the approvers (in days) before the request expires.

Email node

You can add an email node to your Identity Governance workflow that sends an email using a notification template.

Outcomes

  • Success

  • Failed

Properties

Property Usage

Name

Add a display name for the email node.

Notification Template

Select a notification template for the email. To view an email template on the Identity Cloud analytics dashboard, go to Email > Templates.

  • To: Enter a user ID for the email’s recipient, or click define a script.

  • Cc: Enter a user ID to send a copy of the email to another recipient, or click define a script.

  • Bcc: Enter a user ID to send a blind carbon copy (Bcc) of the email to another recipient, or click define a script.

Message substitution

Pass message variables into your email node template.

You can use the Message substitution field to pass in a variable:

  1. Click Message substitution.

  2. In the Message substitution modal, enter one or more variables in a JSON object. For example, if your email template has a variable:

    One or more certification tasks for {{object.givenName}} have been escalated to you.

    You can pass in the variable:

    {"givenName": "Amy"}

    Or if you have multiple variables in the email template:

    One or more certification tasks for {{object.givenName}} {{object.surName}} have been escalated to you.

    You can pass in variables as follows:

    {
    "givenName": "Amy",
    "surName": "Smith"
}

  3. Click Update.

Fulfillment node

The Fulfillment node assigns a fulfillment task to users, requiring them to manually complete of a governance task. In this case, an authorized user reviews the task details and marks it as complete. Workflows using the fulfillment node should also include flows to suspend the process while waiting for a response.

Administrators can use the Fulfillment node in chain tasks or used in conjunction with the Switch node to implement serial or parallel flows.

The Fulfillment node enables the complete orchestration of end-to-end lifecycles and event-driven flows.

Outcomes

  • FULFILL

  • DENY

Properties

Property Usage

Reviewers

Select user(s) that must approve the access request.

  1. Select add.

  2. Select the approver type.

  3. Select the approver permissions for the access request. Options are:

    • Fulfill

    • Deny

    • Forward

    • Modify

    • Comment

  4. Click Add.

    To add more users to this task, repeat steps 1-4.

To define custom approvers that aren’t listed in step 2, click define a script > edit and write a JavaScript script.

Form

Allow dynamic form selection or choose a specific form to present to the reviewer.

Dynamic form selection

Select a dynamic form.

Choose a form

Select a form.

Expiration Settings

The end user defines the expiration when they create the access request. Select one of the following:

Reject request

Reject the access request.

Reassign request

Reassign the request to another user or role.

Do nothing

Take no action.

Notification Settings

Select which email notifications to send. By default all notifications are enabled. Select any of the following:

Assignment notification

Initial email to the approver(s) of a resource when an end user submits an access request. The default email template is Request Assigned. Select the email template to send.

Reassignment notification

Email to the new assignee when an approver forwards a request item. The default email template is Request Reassigned. Select the email template to send.

Assignee reminders

Email to the approver(s) as a reminder that they have a request item to act on. The default email template is Request Reminder.

  • Select the email template to send.

  • Define the frequency to send the reminder.

Escalation notification

Email to an individual assigned as the escalation point of contact. The default email template is Request Escalated.

  • Select the email template to send.

  • Define the frequency to send the escalation.

  • Select the user or role to send the escalation to.

Expiration notification

Email to the approver(s) when a request item expires. The default email template is Request Expired.

  • Select the email template to send.

  • Specify when to send the notification to the approvers (in days) before the request expires.

If/else node

To use this node, there must be a preceding Script node that sets at least one outcome.

Also referred to as an exclusive gateway, this node has the outcomes validationSuccess and ValidationFailure. Once a condition evaluates to true, the node stops evaluating and takes that outcome.

Outcomes

  • validationSuccess

  • validationFailure

Evaluation continues along the validationSuccess outcome path when the defined condition is met.

Evaluation continues along the validationFailure outcome path when the defined condition is met.

Properties

Property Usage

Outcomes

Specify which outcome (defined in a preceding Script node) meets the condition. Set the following properties:

check validationSuccess

  1. Click validationSuccess.

  2. Add the outcome condition that correlates to valdiationSuccess. For example, if the outcome set in the Script node is failureReason, you could set the script to the following:

    failureReason === null;

    This implies there isn’t a failure with validation since the preceding script didn’t set the failure reason.

  3. Click Update.

close validationFailure

  1. Click validationFailure.

  2. Add the outcome condition that correlates to valdiationFailure. For example, if the outcome set in the Script node is failureReason, you could set the script to the following:

    failureReason != null;

    This implies that the validation failed since the failure reason is present.

  3. Click Update.

Script node

Write custom logic in a workflow with the Script node.

The logic you write depends on the task you are trying to achieve.

For example, you can write a script to set parameters to deny an access request, or you can write a script that sets outcomes you can use in conjunction with an If/else node or Switch node.

Outcomes

Single outcome path; however, you will often set outcomes in the script that you will use with the If/else node or Switch node.

Properties

Property Usage

Script

Define your custom logic by writing a JavaScript script.

  1. Click edit.

  2. Write the script. To use an If/else node or Switch node, you must set outcomes in the script.

    For example, the following sets the outcome failureReason:

    failureReason = "Validation failed: Error reading application with id " + applicationId + ". Error message: " + e.message;

execution.setVariable("failureReason", failureReason);

    Now that the failureReason outcome has been set, use it in the If/else node or Switch node.

When an access request is created, the relevant data is stored in a request object. The data accessible through the script node varies depending on the type of access request. For example, an application grant workflow contains information about the application whereas a role grant workflow contains information about the role.

Potential scenarios

The following scenarios reference the request object. To view all properties available in the request object, use the REST API endpoint iga/governance/requests/requestId. For more information, refer to Identity Governance-related APIs.

Identity Governance attributes can be referenced using PingIDM functions, such as reading a resource using openidm.read or openiam.action. For more information, refer to Functions available in identity-related scripts.

For an application grant request, grab the application ID and name submitted in the request:

var content = execution.getVariables();                                                     1
var requestId = content.get('id');
var app = null;
var applicationName = null;

var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});     2
applicationId = requestObj.application.id;
app = openidm.read("managed/alpha_application/" + applicationId);                           3
applicationName = app.name;                                                                 4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a /governance endpoint.

  • 3 Using the openidm.read function, grab all data associated to the application and store it in a local variable, app.

  • 4 Grab the application name.

For an application grant request, grab the value of the custom created glossary attribute, riskLevel:

var content = execution.getVariables();                                                             1
var requestId = content.get('id');
var appId = null;
var appGlossary = null;
var riskLevel = null;

var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});             2
appId = requestObj.application.id;
appGlossary = openidm.action('iga/governance/application/' + appId + '/glossary', 'GET', {}, {});   3
riskLevel = appGlossary.riskLevel;                                                                  4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a /governance/requests endpoint.

  • 3 Using the application id grabbed from the iga/governance/requests endpoint, obtain information about the glossasry attributes for the application using the iga/governance/application endpoint.

  • 4 Grab the glossary attribute, riskLevel, and store it in a local variable, riskLevel. The glossary name riskLevel comes from the name that you define when you create a glossary attribute.

For an application grant, access the requester user properties. In this scenario, access the frIndexedString1 property which correlates to a user’s line of business (LOB):

var content = execution.getVariables();                                                     1
var requestId = content.get('id');
var user = null;
var lineOfBusiness = null;

var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});     2

user = openidm.read("managed/alpha_user/" + requestObj.user.id);                            3

lineOfBusiness = user.frIndexedString1;                                                     4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a iga/governance/requests endpoint.

  • 3 Using the openidm.read function, put the user;s data into the requester variable.

  • 4 Grab line of business the user is in, which is stored in the property frIndexedString1.

For an entitlement grant request, grab the entitlement ID and name submitted in the request:

var content = execution.getVariables();                                                     1
var requestId = content.get('id');
var requestObj = null;
var entitlementName = null;
var entitlementId = null;

requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});         2
entitlementName = requestObj.descriptor.idx./entitlement.displayName;                       3
entitlementId = requestObj.assignment.id;                                                   4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a iga/governance/requests endpoint.

  • 3 Grab the entitlement name from requestObj. The entitlement.displayName is derived from the display name attribute on the application’s entitlement object.

  • 4 Grab the entitlement id from the requestObj.

    The assignment.id is unique whereas the entitlement.id isn’t. The entitlement object is raw data from the application. Applications with the same entitlement.id can cause collisions if you reference entitlement.id in your scripts. Therefore, make sure to reference the assignment.id when you want to reference an entitlement.

For a role grant request, grab the role ID and name submitted in the request:

var content = execution.getVariables();                                                 1
var requestId = content.get('id');
var requestObj = null;
var roleId = null;
var role = null;
var roleName = null;

requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});     2
roleId = requestObj.role.id;
role = openidm.read("managed/alpha_role/" + roleId);                                    3
roleName = role.name;                                                                   4

  • 1 To leverage the workflow process variables from when the request was created, grab the variables and put them into the content variable. For an access request, the only variable passed is the id.

  • 2 Obtain information about the access request using a iga/governance/requests endpoint.

  • 3 Using the openidm.read function, grab all data associated to the role and store it in a local variable, role.

  • 4 Grab the role name.

Switch node

You must precede this node with a Script node that sets two or more outcomes.

The Switch node (also referred to as an inclusive gateway) lets you script two or more conditional outcomes. Any or all conditions can be true.

The Switch node and If/else node both evaluate conditions. However, the Switch node continues evaluating conditions after one condition is met.

Outcomes

  • Choice 1

    …​

  • Choice n

Properties

Property Usage

Name

The name of the node.

The name must be alphanumeric with no spaces or special characters.

Outcomes

Specify the outcome paths based on the output of the preceding Script node.

  1. Click add.

  2. Enter the following details:

    • Name — Enter a name for the outcome. Name this property to correlate logically to the outcome from the Script node. For example, if an application grant access request has an application glossary attribute called Risk Level` that’s set to High, name this outcome riskLevelHigh``.

    • Script — Define a script to meet the condition. For example, if the preceding Script node retrieves a role’s riskLevel variable, then you can set the Switch node’s outcome to the following:

      high
riskLevel == "high";

      If the condition is met, the Switch node continues down the outcome path and continues evaluating the other conditions set in additional outcomes.

  3. Click Add.

  4. Define the rest of your outcomes by repeating steps 1 - 3. For example, you can add additional outcomes respectively for riskLevel so that all riskLevel conditions are met:

    medium
riskLevel == "medium";

low
riskLevel == "low";

null
riskLevel == "null";

Require multiple approvals in parallel

You can use a Switch node to evaluate multiple paths instead of nesting multiple If/else nodes. However, you can also use a Switch node to send multiple approval paths in parallel. For example, you can send an approval to the role owner of a role and to an end user’s manager at the same time. Only when both approvals are approved can the workflow proceed.

To achieve this:

  • There must be a proceeding Script node before the Switch node.

  • A switch node must set two or more outcomes with their respective scripts set to true.

  • Each outcome of the Switch node routes to an Approval node.

  • The Approve outcome of each Approval node must route to an additional Switch node.

  • The additional Switch node must only have one outcome with the script set to true.

An example of using a Script node to have multiple approvals in parallel.

You can find a detailed example of using a Switch node for parallel paths in Role grant workflow example.

Violation node

Assigns a compliance violation task to users. Workflows using the Violation node can better route violation handling in your company.

You can use the node in chain tasks or used in conjunction with the Switch node to implement serial or parallel flows.

Outcomes

  • Remediate

  • Allow

  • Expiration

Properties

Property Usage

Name

Violation Task

Actors

Select user(s) who acts on the violation.

  1. Click .

  2. Select the actor type. Options are:

    • Role

    • Manager

    • Violation owner

  3. Select the user.

  4. Select the permissions for the access request. Permissions are:

    • Allow

    • Exception

    • Remediate

    • Forward

    • Comment

  5. Click Add.

    To add more users to this task, repeat steps 1-4.

    To define custom approvers that are not listed in step 2, click define a script > edit, write a JavaScript script, and click Update.

    Click to display a custom script example that returns an array of actors 
    (function() {
    var content = execution.getVariables();
    var requestId = content.get('id');
    var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
    return [{
        "id": "managed/user/" + requestIndex.applicationOwner[0].id,
        "permissions": {
            "approve": true,
            "reject": true,
            "forward": true,
            "modify": true,
            "comment": true
        }
    }];
})()

Expiration Settings

Define what to do when the violation expires. Options are:

Reject request

Reject the access request.

Reassign request

Reassign the request to another user or role.

Do nothing

Take no action.

Notification Settings

Select which email notifications to send. By default all notifications are enabled. Select any of the following:

Assignment notification

Initial email to the approver(s) of a resource when an end user submits an access request. The default email template is Request Assigned. Select the email template to send.

Reassignment notification

Email to the new assignee when an approver forwards a request item. The default email template is Request Reassigned. Select the email template to send.

Assignee reminders

Email to the approver(s) as a reminder that they have a request item to act on. The default email template is Request Reminder.

  • Select the email template to send.

  • Define the frequency to send the reminder.

Escalation notification

Email to an individual assigned as the escalation point of contact. The default email template is Request Escalated.

  • Select the email template to send.

  • Define the frequency to send the escalation.

  • Select the user or role to send the escalation to.

Expiration notification

Email to the approver(s) when a request item expires. The default email template is Request Expired.

  • Select the email template to send.

  • Specify when to send the notification to the approvers (in days) before the request expires.

Wait node

The Wait node pauses the workflow until a specified date and time. Identity Governance checks the specified timestamp and sets the response of the node to RESUME at which point, the workflow resumes.

The workflow author is expected to provide:

  • Name of the node

  • Resume date in a selected time period or the variable to extract the resume date from

For example, the following workflow demonstrates how you can use the Wait node to grant temporary access to an application. The workflow grants access, pauses until the start date is established, and then automatically validates the application grant.

An example workflow for Basic Application Grant Temporal with a Wait node.

Outcomes

  • wait

  • resume

Properties

Property Usage

Name

Enter a name for the node. For example, enter Wait Task.

Select a duration

Enter the number and select the time periods to wait. Options are:

  • minute(s)

  • hour(s)

  • day(s)

  • week(s)

  • month(s)

Request property

Enter a path to a date property on the request object. For example, enter custom.date, which points to the request object, request.common.startDate property.

Workflow variable

Enter the name of a custom workflow variable that stores the resume date. For example, enter resumeDate.

Workflow use cases

This section presents workflow use cases featuring workflow nodes. For detailed information on each node, refer to Workflow nodes.

This section covers the following workflows use cases:

Application grant workflow

In this example, an administrator wants to create an application grant workflow that:

  • Requires the manager to approve the request. If an administrator sends a request, the request is auto-approved.

  • If approved, check what line of business (LOB) the application is in.

  • Based on the LOB, the workflow requires a separate approver to approve the request.

Assumptions

  • Each application has an application owner. An application owner is a user identity designated to manage the application. You populate this value for each target application.

  • You create an application glossary attribute LOB, and populate the LOB for each application. For this scenario, the LOBs are:

    • Sales

    • Finance

    • Human Resources

  • Your end users have a manager assigned to them. An administrator populates this property and it isn’t modifiable by the end user.

Example

An example of an application grant workflow.

  • 1 Use a Script node to do a context check for the request.

    Click to display the request context check script 
    /*
Script nodes are used to invoke APIs or execute business logic.
You can invoke governance APIs or IDM APIs.
You can find details in Manage workflows.

Script nodes should return a single value and should have the
logic enclosed in a try-catch block.

Example:
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
}
catch (e) {
  failureReason = 'Validation failed: Error reading request with id ' + requestId;
}
*/
var content = execution.getVariables();
var requestId = content.get('id');
var context = null;
var skipApproval = false;
var lineItemId = false;
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  if (requestObj.request.common.context) {
    context = requestObj.request.common.context.type;
    lineItemId = requestObj.request.common.context.lineItemId;
    if (context == 'admin') {
      skipApproval = true;
    }
  }
}
catch (e) {
  logger.info("Request Context Check failed "+e.message);
}

logger.info("Context: " + context);
execution.setVariable("context", context);
execution.setVariable("lineItemId", lineItemId);
execution.setVariable("skipApproval", skipApproval);

  • 2 Use an IF/ELSE node to set the context gateway for auto approval or standard approval based on a manager review.

  • 3 Use the Script node to run any auto approvals:

    Click to display the auto approval script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = content.get('context');
var lineItemId = content.get('lineItemId');
var queryParams = {
  "_action": "update"
}
try {
  var decision = {
      "decision": "approved",
      "comment": "Request auto-approved due to request context: " + context
  }
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
}
catch (e) {
  var failureReason = "Failure updating decision on request. Error message: " + e.message;
  var update = {'comment': failureReason, 'failure': true};
  openidm.action('iga/governance/requests/' + requestId, 'POST', update, queryParams);
}

  • 4 Using an Approval node, the manager of the end user must approve the request.

  • 5 If approved, a Script node checks the application glossary attribute lineOfBusiness (LOB) and sets the outcome based on the LOB of the application. Based on the outcome, the Switch node evaluates the LOB.

    Click to display check LOB script 
    var content = execution.getVariables();
var requestId = content.get('id');
var requestObj = null;
var appId = null;
var appGlossary = null;
var lob = null;

try {
  requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  appId = requestObj.application.id;
  }
  catch (e) {
	logger.info("Validation failed: Error reading application grant request with id " + requestId);
  }

try {
  appGlossary = openidm.action('iga/governance/application/' + appId + '/glossary', 'GET', {}, {});
  lob = appGlossary.lineOfBusiness || "default";
  execution.setVariable("lob", lob);
}
catch (e) {
  logger.info("Could not retrieve glossary with appId " + appId + " from application grant request ID " + requestId);
}

  • 3 If the LOB is:

    • sales — An Approval node requires members of the role Sales App Approver to approve the request.

    • finance — An Approval node requires members ot the fole Finance App Approver to approve the request.

    • humanResources — An Approval node requires members of the role Human Resources App Approver to approve the request.

    • null — An Approval node requires the application owner to approve the request.

  • 7 If the required approvals are met, a Script node runs a validation check.

    Click to display app grant validation script 
    logger.info("Running application grant request validation");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;
var applicationId = null;
var app = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
}
catch (e) {
  failureReason = "Validation failed: Error reading request with id " + requestId;
}

// Validation 1 - Check application exists
if (!failureReason) {
  try {
    app = openidm.read('managed/alpha_application/' + applicationId);
    if (!app) {
      failureReason = "Validation failed: Cannot find application with id " + applicationId;
    }
  }
  catch (e) {
    failureReason = "Validation failed: Error reading application with id " + applicationId + ". Error message: " + e.message;
  }
}

// Validation 2 - Check the user does not already have application granted
// Note: this is done at request submission time as well, the following is an example of how to check user's accounts
if (!failureReason) {
  try {
    var user = openidm.read('managed/alpha_user/' + requestObj.user.id, null, [ 'effectiveApplications' ]);
    user.effectiveApplications.forEach(effectiveApp => {
      if (effectiveApp._id === applicationId) {
        failureReason = "Validation failed: User with id " + requestObj.user.id + " already has effective application " + applicationId;
      }
    })
  }
  catch (e) {
    failureReason = "Validation failed: Unable to check effective applications of user with id " + requestObj.user.id + ". Error message: " + e.message;
  }
}

if (failureReason) {
  logger.info("Validation failed: " + failureReason);
}
execution.setVariable("failureReason", failureReason);

    If any Approval node has the Reject outcome, a Script node denies the request.

    Click to display reject request script 
    logger.info("Rejecting request");

var content = execution.getVariables();
var requestId = content.get('id');

logger.info("Execution Content: " + content);
var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

  • 8 If the If/Else node outcome is:

    • validationSuccess — A Script node provisions the application to the end user.

      Click to display auto provisioning script 
      logger.info("Auto-Provisioning");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  logger.info("requestObj: " + requestObj);
}
catch (e) {
  failureReason = "Provisioning failed: Error reading request with id " + requestId;
}

if(!failureReason) {
  try {
    var request = requestObj.request;
    var payload = {
      "applicationId": request.common.applicationId,
      "startDate": request.common.startDate,
      "endDate": request.common.endDate,
      "auditContext": {},
      "grantType": "request"
    };
    var queryParams = {
      "_action": "add"
    }

    logger.info("Creating account: " + payload);
    var result = openidm.action('iga/governance/user/' + request.common.userId + '/applications' , 'POST', payload,queryParams);
  }
  catch (e) {
    failureReason = "Provisioning failed: Error provisioning account to user " + request.common.userId + " for application " + request.common.applicationId + ". Error message: " + e.message;
  }

  var decision = {'status': 'complete', 'decision': 'approved'};
  if (failureReason) {
    decision.outcome = 'not provisioned';
    decision.comment = failureReason;
    decision.failure = true;
  }
  else {
    decision.outcome = 'provisioned';
  }

  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}

    • validationFailure — A Script node doesn’t provision the application to the end user.

      Click to display validation failure script 
      var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = content.get('failureReason');

var decision = {'outcome': 'not provisioned', 'status': 'complete', 'comment': failureReason, 'failure': true, 'decision': 'approved'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.

Entitlement grant workflow

In this example, an administrator wants to create an entitlement grant workflow that:

  • An entitlement owner must approve the request. If an administrator sends a request, the request is auto-approved.

  • If approved, check if the entitlement is marked as privileged.

    Companies can define what privileged means in the glossary. However, in most cases, a privileged entitlement gives administrative rights to sensitive data, such as view access to quarterly reports before public release.

  • If the entitlement is privileged or null, the end user’s manager must approve the request.

Assumptions

  • Each entitlement has an entitlement owner. An entitlement owner is a user identity designated to manage the entitlement.

  • You create a boolean entitlement glossary attribute , isPrivileged. This attribute is populated for each entitlement.

  • Your end users have a manager assigned to them. An administrator populates this property and isn’t modifiable by the end user.

Example

An example of an entitlement grant workflow.

  • 1 Use a Script node to do a context check for the request.

    Click to display the request context check script 
    /*
Script nodes are used to invoke APIs or execute business logic.
You can invoke governance APIs or IDM APIs.
Learn more in Manage workflows.

Script nodes should return a single value and should have the
logic enclosed in a try-catch block.

Example:
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
}
catch (e) {
  failureReason = 'Validation failed: Error reading request with id ' + requestId;
}
*/
var content = execution.getVariables();
var requestId = content.get('id');
var context = null;
var skipApproval = false;
var lineItemId = false;
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  if (requestObj.request.common.context) {
    context = requestObj.request.common.context.type;
    lineItemId = requestObj.request.common.context.lineItemId;
    if (context == 'admin') {
      skipApproval = true;
    }
  }
}
catch (e) {
  logger.info("Request Context Check failed "+e.message);
}

logger.info("Context: " + context);
execution.setVariable("context", context);
execution.setVariable("lineItemId", lineItemId);
execution.setVariable("skipApproval", skipApproval);

  • 2 Use an IF/ELSE node to set the context gateway.

  • 3 Use the Script node to run an auto approval:

    Click to display the auto approval script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = content.get('context');
var lineItemId = content.get('lineItemId');
var queryParams = {
  "_action": "update"
}
var lineItemParams = {
  "_action": "updateRemediationStatus"
}
try {
  var decision = {
      "decision": "approved",
      "comment": "Request auto-approved due to request context: " + context
  }
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
}
catch (e) {
  var failureReason = "Failure updating decision on request. Error message: " + e.message;
  var update = {'comment': failureReason, 'failure': true};
  openidm.action('iga/governance/requests/' + requestId, 'POST', update, queryParams);
}

  • 4 Using an Approval node, the entitlement owner must approve the request.

  • 5 Use a Script node to check the value of the entitlement glossary attribute isPrivileged and set the outcome.

    Click to display the entitlement privileged script 
    var content = execution.getVariables();
var requestId = content.get('id');
var requestObj = null;
var entId = null;
var entGlossary = null;
var entPriv = null;

//Check entitlement exists and grab entitlement info
try {
  requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  entId = requestObj.assignment.id;
}
catch (e) {
  logger.info("Validation failed: Error reading entitlement grant request with id " + requestId);
}
//Check glossary for entitlement exists and grab glossary info
try {
  entGlossary = openidm.action('iga/governance/resource/' + entId + '/glossary', 'GET', {}, {});
  // Sets entPriv based on the glossary contents, if present, otherwise defaults to true
  entPriv = (entGlossary.hasOwnProperty("isPrivileged")) ? entGlossary.isPrivileged : true;
  //Sets entPriv based on glossary contents, if present, otherwise defaults to false
  //entPriv = !!entGlossary.isPrivileged;
  execution.setVariable("entPriv", entPriv);
}
catch (e) {
  logger.info("Could not retrieve glossary with entId " + entId + " from entitlement grant request ID " + requestId);
}

  • 6 Use a switch node to route outcomes based on the script. If the outcome is:

    • privileged (entPriv==true) — An additional Approval node requires the end user’s manager to approve the request.

    • notPrivileged(entPriv==false`) — An additional approval isn’t required.

  • 7 If the required approvals are met, the Script node runs a validation check.

    Click to display the entitlement grant validation script 
    logger.info("Running entitlement grant request validation");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;
var applicationId = null;
var assignmentId = null;
var app = null;
var assignment = null;
var existingAccount = false;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
  assignmentId = requestObj.assignment.id;
}
catch (e) {
  failureReason = "Validation failed: Error reading request with id " + requestId;
}

// Validation 1 - Check application exists
if (!failureReason) {
  try {
    app = openidm.read('managed/alpha_application/' + applicationId);
    if (!app) {
      failureReason = "Validation failed: Cannot find application with id " + applicationId;
    }
  }
  catch (e) {
    failureReason = "Validation failed: Error reading application with id " + applicationId + ". Error message: " + e.message;
  }
}

// Validation 2 - Check entitlement exists
if (!failureReason) {
  try {
    assignment = openidm.read('managed/alpha_assignment/' + assignmentId);
    if (!assignment) {
      failureReason = "Validation failed: Cannot find assignment with id " + assignmentId;
    }
  }
  catch (e) {
    failureReason = "Validation failed: Error reading assignment with id " + assignmentId + ". Error message: " + e.message;
  }
}

// Validation 3 - Check the user has application granted
if (!failureReason) {
  try {
    var user = openidm.read('managed/alpha_user/' + requestObj.user.id, null, [ 'effectiveApplications' ]);
    user.effectiveApplications.forEach(effectiveApp => {
      if (effectiveApp._id === applicationId) {
        existingAccount = true;
      }
    })
  }
  catch (e) {
    failureReason = "Validation failed: Unable to check existing applications of user with id " + requestObj.user.id + ". Error message: " + e.message;
  }
}

// Validation 4 - If account does not exist, provision it
if (!failureReason) {
  if (!existingAccount) {
    try {
      var request = requestObj.request;
      var payload = {
        "applicationId": applicationId,
        "startDate": request.common.startDate,
        "endDate": request.common.endDate,
        "auditContext": {},
        "grantType": "request"
      };
      var queryParams = {
        "_action": "add"
      }

      logger.info("Creating account: " + payload);
      var result = openidm.action('iga/governance/user/' + request.common.userId + '/applications' , 'POST', payload,queryParams);
    }
    catch (e) {
      failureReason = "Validation failed: Error provisioning new account to user " + request.common.userId + " for application " + applicationId + ". Error message: " + e.message;
    }
  }
}

if (failureReason) {
  logger.info("Validation failed: " + failureReason);
}
execution.setVariable("failureReason", failureReason);

    If any Approval node has the Reject outcome, a Script node denies the request.

    Click to display the reject request script 
    logger.info("Rejecting request");

var content = execution.getVariables();
var requestId = content.get('id');

logger.info("Execution Content: " + content);
var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

  • 8 If the If/else node outcome is:

    • validationFlowSuccess — A Script node provisions the application to the end user.

      Click to display the auto provisioning script 
      logger.info("Auto-Provisioning");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  logger.info("requestObj: " + requestObj);
}
catch (e) {
  failureReason = "Provisioning failed: Error reading request with id " + requestId;
}

if(!failureReason) {
  try {
    var request = requestObj.request;
    var payload = {
      "entitlementId": request.common.entitlementId,
      "startDate": request.common.startDate,
      "endDate": request.common.endDate,
      "auditContext": {},
      "grantType": "request"
    };
    var queryParams = {
      "_action": "add"
    }

    var result = openidm.action('iga/governance/user/' + request.common.userId + '/entitlements' , 'POST', payload,queryParams);
  }
  catch (e) {
    failureReason = "Provisioning failed: Error provisioning entitlement to user " + request.common.userId + " for entitlement " + request.common.entitlementId + ". Error message: " + e.message;
  }

  var decision = {'status': 'complete', 'decision': 'approved'};
  if (failureReason) {
    decision.outcome = 'not provisioned';
    decision.comment = failureReason;
    decision.failure = true;
  }
  else {
    decision.outcome = 'provisioned';
  }

  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}

    • validationFlowFailure — A Script node doesn’t provision the application to the end user.

      Click to display the validation failure script 
      var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = content.get('failureReason');

var decision = {'outcome': 'not provisioned', 'status': 'complete', 'comment': failureReason, 'failure': true, 'decision': 'approved'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

Download the JSON file for this workflow here.

For information on how to import or export workflows, refer to workflow editor canvas.

Role grant workflow

In this example, an administrator wants to create a role grant workflow that:

  • Checks the risk level of the role.

  • Separate approvals are required based on the risk level. Specifically, if the risk level is high, send two approvals, in parallel, to the end user’s manager and the role owner.

Assumptions

  • Each role has a role owner. The role owner is a user identity designated to manage the role.

  • You create a role glossary attribute (string with enumerated value), riskLevel, that has the following values:

    • low

    • medium

    • high

      For each role, this attribute is populated.

  • Your end users have a manager assigned to them. An administrator populates this property and isn’t modifiable by the end user.

Example

An example of a role grant workflow.

  • 1 A Script node checks the value of the role glossary attribute riskLevel and sets outcomes.

    Click to display risk level script 
    var content = execution.getVariables();
var requestId = content.get('id');
var requestObj = null;
var roleId = null;
var roleGlossary = null;
var riskLevel = null;

try {
  requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  riskId = requestObj.risk.id;
}
catch (e) {
  logger.info("Validation failed: Error reading role grant request with id " + requestId);
}

try {
  roleGlossary = openidm.action('iga/governance/role/' + roleId + '/glossary', 'GET', {}, {});
  riskLevel = roleGlossary.riskLevel;
  execution.setVariable("riskLevel", riskLevel);
}
catch (e) {
  logger.info("Could not retrieve glossary with roleId " + roleId + " from role grant request ID " + requestId);
}

  • 2 A Switch node determines the path to take based on the Script node.

  • 3 If the risk level is:

    • low — An Approval node requires either the role owner or the end user’s manager to approve the request.

    • medium — An Approval node requires the role owner to approve the request.

  • 4 If the risk level is high or null then:

    • A Switch node sends two approval tasks in parallel.

    • An Approval node requires the role owner to approve the request.

    • An Approval node requires the end user’s manager to approve the request.

    • A closing Switch node waits for both approvals before proceeding to provision the role.

  • 5 If the required approvals are met, a Script node runs a validation check.

    Click to display the Role Grant Validation script 
    logger.info("Running role grant request validation");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;
var roleId = null;
var role = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  roleId = requestObj.role.id;
}
catch (e) {
  failureReason = "Validation failed: Error reading request with id " + requestId;
}

// Validation 1 - Check role exists
if (!failureReason) {
  try {
    role = openidm.read('managed/alpha_role/' + roleId);
    if (!role) {
      failureReason = "Validation failed: Cannot find role with id " + roleId;
    }
  }
  catch (e) {
    failureReason = "Validation failed: Error reading role with id " + roleId + ". Error message: " + e.message;
  }
}

if (failureReason) {
  logger.info("Validation failed: " + failureReason);
}
execution.setVariable("failureReason", failureReason);

    If any Approval node has the Reject outcome, a Script node denies the request.

    Click to display Reject Request script 
    logger.info("Rejecting request");

var content = execution.getVariables();
var requestId = content.get('id');

logger.info("Execution Content: " + content);
var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

  • 6 If the If/else node outcome is:

    • validationFlowSuccess — A Script node provisions the application to the end user.

      Click to display Auto Provisioning script 
      logger.info("Auto-Provisioning");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  logger.info("requestObj: " + requestObj);
}
catch (e) {
  failureReason = "Provisioning failed: Error reading request with id " + requestId;
}

if(!failureReason) {
  try {
    var request = requestObj.request;
    var payload = {
      "roleId": request.common.roleId,
      "startDate": request.common.startDate,
      "endDate": request.common.endDate,
      "auditContext": {},
      "grantType": "request"
    };
    var queryParams = {
      "_action": "add"
    }

    var result = openidm.action('iga/governance/user/' + request.common.userId + '/roles' , 'POST', payload,queryParams);
  }
  catch (e) {
    failureReason = "Provisioning failed: Error provisioning role to user " + request.common.userId + " for role " + request.common.roleId + ". Error message: " + e.message;
  }

  var decision = {'status': 'complete', 'decision': 'approved'};
  if (failureReason) {
    decision.outcome = 'not provisioned';
    decision.comment = failureReason;
    decision.failure = true;
  }
  else {
    decision.outcome = 'provisioned';
  }

  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}

    • validationFlowFailure — A Script node doesn’t provision the application to the end user.

      Click to display Validation Failure script 
      var content = execution.getVariables();
var failureReason = content.get('failureReason');

var decision = {'outcome': 'not provisioned', 'status': 'complete', 'comment': failureReason, 'failure': true, 'decision': 'approved'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.

Role remove workflow

In this example, an administrator wants to create a workflow that:

  • Handles a normal role removal access request.

  • Includes a context check for administrator-submitted requests.

  • Skips the the approval task process and runs auto-approval and auto-deprovisioning scripts if the context check passes.

Assumptions

  • Each role has a role owner.

  • Notification settings and email templates exist.

  • Make sure to catch any error/failure conditions.

Example

An example of a role removal workflow.

  • 1 The Script node invokes the APIs and checks the context. If the context is admin or certification, it skips the manual approval process.

    Click to display request context check script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = null;
var skipApproval = false;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  if (requestObj.request.common.context) {
    context = requestObj.request.common.context.type;
    if (context === 'admin' || context === 'certification') {
      skipApproval = true;
    }
  }
}
catch (e) {}

logger.info("Context: " + context);
execution.setVariable("context", context);
execution.setVariable("skipApproval", skipApproval);

  • 2 The Approval node assigns an approval task to users and roles. The node chains tasks in conjunction with a Switch node to implement serial or parallel flows.

    Click to display the approval task properties
    Item Description

    Name

    Approval Task

    Approvers

    Two options are available:

    • Add users and roles manually, such as Role Owner and define Approver type

      • Approve

      • Reject

      • Forward

      • Modify

      • Comment

    • Define users using a script:

    Form

    Select a form to present to the reviewer:

    • Dynamic form selection. This selection is typically used for basic out-of-the-box workflows, like BasicApplicationGrant and others.

    • Choose a form. This selection is typically used for custom request type forms.

    Expiration Settings

    Options are:

    • Reject request

    • Reassign request

    • Do nothing

    Notification Settings

    Options are:

    • Assignment notification and email templates, such as requestAssigned.

    • Reassignment notification and email templates, such as requestReassigned.

    • Assignee reminders and email templates, such as requestReminder.

      • Sends every number of time periods, such as 3 day(s).

    • Escalation notifications and email templates, such as requestEscalated.

      • Send every number of day(s), such as 5 day(s).

      • Send to Send escalation to to User, and select User.

    • Expiration notification and email templates, such as requestExpired.

      • Send the notification on the configured number of days before expiration.

  • 3 Invokes the auto-approval script if scriptApproval is true.

    Click to display auto-approval script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = content.get('context');
var queryParams = {
  "_action": "update"
}

try {
  var decision = {
      "decision": "approved",
      "comment": "Request auto-approved due to request context: " + context
  }
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
}
catch (e) {
  var failureReason = "Failure updating decision on request. Error message: " + e.message;
  var update = {'comment': failureReason, 'failure': true};
  openidm.action('iga/governance/requests/' + requestId, 'POST', update, queryParams);
}

  • 4 Runs a RejectRequest script when Approval task node returns a reject.

    Click to display RejectRequest script 
    logger.info("Rejecting request");

var content = execution.getVariables();
var requestId = content.get('id');

logger.info("Execution Content: " + content);
var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

  • 5 Run Auto Deprovisioning script.

    Click to display the auto deprovisioning script 
    logger.info("Auto-Deprovisioning");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  logger.info("requestObj: " + requestObj);
}
catch (e) {
  failureReason = "Deprovisioning failed: Error reading request with id " + requestId;
}

if(!failureReason) {
  try {
    var request = requestObj.request;
    var payload = {
      "roleId": request.common.roleId,
      "startDate": request.common.startDate,
      "endDate": request.common.endDate,
      "auditContext": {},
      "grantType": "request"
    };
    var queryParams = {
      "_action": "remove"
    }

    var result = openidm.action('iga/governance/user/' + request.common.userId + '/roles' , 'POST', payload,queryParams);
  }
  catch (e) {
    failureReason = "Deprovisioning failed: Error deprovisioning role to user " + request.common.userId + " for role " + request.common.roleId + ". Error message: " + e.message;
  }

  var decision = {'status': 'complete', 'decision': 'approved'};
  if (failureReason) {
    decision.outcome = 'not provisioned';
    decision.comment = failureReason;
    decision.failure = true;
  }
  else {
    decision.outcome = 'provisioned';
  }

  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.

Violation workflow

In this example, an administrator creates a workflow that:

  • Processes a single violation task.

  • If the violation outcome is Remediate, it remediates the violation, validates the result, and removes the entitlements.

  • If the violation outcome is Allow, it creates an exception.

  • If the violation outcome is expiration, it goes to a manual decision via the Fulfillment node.

  • If the end user tasked with the manual fulfillment approves of the various outcomes, the workflow is complete.

  • If the end user tasked with the manual fulfillment denies the resulting outcomes, the workflow calls a reject requests script, and loops back for another manual confirmation.

Assumptions

  • Each violation has an owner.

  • Make sure to catch any error/failure conditions.

Example

An example of a violation handling workflow.

  • 1 The Violation node routes the violation to the appropriate outcome. Options are: Remediate, Allow, and Expiration.

  • 2 The Remediate Violation Script node gets the context information for the violation and sets the remediationResponse.

    Click to display Remediate Violation script 
    logger.info("Remediating violation");

var content = execution.getVariables();
var violationId = content.get('id');
var remediation = content.get('remediation');
logger.info("Remediating violation - violationId: " + violationId + ', remediation payload: ' + remediation);

var remediationContent = null;

var remediationResponse = openidm.action('iga/governance/violation/' + violationId + '/remediate', 'POST', remediation);
logger.info("Remediating response: " + remediationResponse);

remediationContent = remediationResponse.decision.remediation;
execution.setVariable("remediation", remediationContent);

  • 3 The Remediate Violation IF/ELSE node routes successful validations to an auto remove script node and validation failures to a failure handling node.

  • 4 The Remove Grants Auto script node removes the entitlement grants that caused the violation.

    Click to display Auto Remove Entitlement Grants script 
    logger.info("Removing grants automatically");

var content = execution.getVariables();
var violationId = content.get('id');
var failureReason = null;
var phaseName = content.get('phaseName');
var violationObj;

logger.info("Removing entitlement grants for violation " + violationId + " with phase name " + phaseName);

try {
  violationObj = openidm.action('iga/governance/violation/lookup/' + violationId, 'GET', {}, {});
}
catch (e) {
  failureReason = "Removing entitlement grants failed: Error reading violation with id " + violationId + ". Error message: " + e.message;
}

if (!failureReason) {
  var remediation = violationObj.decision.remediation;
  var failedDeprovisioning = false;
  var deprovisionedIds = [];
  for(var grant of violationObj.violatingAccess) {
    if (!remediation.grantIds.includes(grant.compositeId)) {
      continue;
    }

    var userId = violationObj.user.id;
    logger.info("Removing entitlement grant: " + grant.compositeId + ", user: " + userId + ", violation: " + violationId);

    try {
      var payload = {
        entitlementId: grant.assignment.id
      };
      logger.info('Payload to remove grant: ' + JSON.stringify(payload));

      var queryParams = {
        "_action": "remove"
      }

      var result = openidm.action('iga/governance/user/' + userId + '/entitlements', 'POST', payload,queryParams);
      execution.setVariables(result);

      logger.info("Deprovisioned " + grant.assignment.id + " successfully, user " + userId + + ", violation: " + violationId);
      deprovisionedIds.push(grant.compositeId);
    }
    catch (e) {
      failureReason = failureReason + ". Removing grants failed: Error deprovisioning entitlement" + grant.assignment.id + " from user. Error message: " + e.message + ".";
      failedDeprovisioning = true;
    }
  }

  if (!failedDeprovisioning) {
    openidm.action('iga/governance/violation/' + violationId + '/remediation/status/complete', 'POST', {});
  } else {
    failureReason = failureReason + ". Grants removed: " + deprovisionedIds;
  }
}

if (failureReason) {
  var update = { 'comment': failureReason };
  openidm.action('iga/governance/violation/' + violationId + '/comment', 'POST', update, {});
}

  • 5 The Allow Violation script node logs the information. If a failure arises, Identity Governance posts the failure with the reason.

    Click to display Allow Violation script node 
    logger.info("Allowing violation");
var content = execution.getVariables();
var violationId = content.get('id');
var phaseName = content.get('phaseName');
logger.info("Violation to be allowed: " + violationId + " with phase name " + phaseName);

var failureReason = null;
try {
    var allowResponse = openidm.action('iga/governance/violation/' + violationId + '/allow', 'POST', {});
logger.info("Violation " + violationId + " was allowed successfully.");} catch (e) {
    failureReason = "Failed allowing violation with id " + violationId + ". Error message: " + e.message;
}

if (failureReason) {
    var update = { "comment": failureReason };
    try {
        openidm.action('iga/governance/violation/' + violationId + '/phases/' + phaseName + '/comment', 'POST', update, {});
    } catch (e) {
        openidm.action('iga/governance/violation/' + violationId + '/comment', 'POST', update, {});
    }
}

  • 6 The Fulfillment node requests a manual completion of the task by an authorized end user, typically during review time. If successful, the task is fulfilled, and the workflow is complete.

  • 7 The Reject Request script node retrieves the requestID, logs the rejection, and sends a reject request.

    Click to display Reject Request script 
    logger.info("Rejecting request");

var content = execution.getVariables();
var requestId = content.get('id');

logger.info("Execution Content: " + content);
var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.

User create event workflow - send email

In this example, an administrator creates a workflow that:

  • Sends an email notification to the new user when a user create event occurs.

  • Copies their manager, as well, if present.

Assumptions

  • Each user has a manager.

  • Make sure to catch any error/failure conditions.

Example

An example of user create event send email workflow.

  • 1 The Script node sends email to the new user and cc’s to the user’s manager.

    Click to display send email script 
    logger.info("Running user create event role workflow - send email");

var content = execution.getVariables();
var requestId = content.get('id');

// Read event user information from request object
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  var userObj = requestObj.request.common.blob.after;
  var userDisplayName = userObj.givenName + " " + userObj.sn + " (" + userObj.userName + ")";
  var body = {
    subject: "New user created: " + userDisplayName,
    to: userObj.mail,
    body: "New user created: " + userDisplayName + ".",
    object: {}
  };
  if (userObj && userObj.manager && userObj.manager.mail) {
    body.cc = userObj.manager.mail
  };
  openidm.action("external/email", "send", body);
}
catch (e) {
  logger.info("Unable to send new user creation email");
}

// Update event request as final
var decision = {'status': 'complete', 'outcome': 'fulfilled', 'decision': 'approved'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
logger.info("Request " + requestId + " completed.");

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.

User create event workflow - catalog lookup

In this example, an administrator creates a workflow that:

  • Submits a request to add the Data Analyst and Security roles to a newly created user when a user create event occurs.

  • Looks up the two roles in the catalog.

Assumptions

  • Roles exist in the catalog.

  • Make sure to catch any error/failure conditions.

Example

An example of user create event workflow to request two roles when a user is created.

  • 1 The Script node looks up two roles in the catalog. If the roles are present in the catalog, the script generates a request for roles.

    Click to display Submit Request for Roles script 
    logger.info("Running user create event role workflow");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;
var userObj = null;
var userId = null;

// Read event user information from request object
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  userObj = requestObj.request.common.blob.after;
  userId = userObj.userId;
}
catch (e) {
  failureReason = "Validation failed: Error reading request with id " + requestId;
}

// Define roles to request
var roleNames = [ "Data Analyst", "Security" ];

// Look up roles in catalog
var operand = [];
for (var index in roleNames) {
  operand.push({operator: "EQUALS", operand: { targetName: "role.name", targetValue: roleNames[index] }})
}
var body = { targetFilter: {operator: "OR", operand: operand}};
var catalog = openidm.action("iga/governance/catalog/search", "POST", body);
var catalogResults = catalog.result;

// Define request catalogs key
var catalogBody = [];
for (var idx in catalogResults) {
  var catalog = catalogResults[idx];
  catalogBody.push({type: "role", id: catalog.id})
}

// Define request payload
var requestBody = {
  priority: "low",
  accessModifier: "add",
  justification: "Request submitted on user creation.",
  users: [ userId ],
  catalogs: catalogBody
};

// Create requests
try {
  openidm.action("iga/governance/requests", "POST", requestBody, {_action: "create"})
}
catch (e) {
  failureReason = "Unable to generate requests for roles";
}

// Update event request as final
var decision = failureReason ?
  {'status': 'complete', 'outcome': 'cancelled', 'decision': 'rejected', 'comment': failureReason, 'failure': true} :
  {'status': 'complete', 'outcome': 'fulfilled', 'decision': 'approved'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
logger.info("Request " + requestId + " completed.");

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.

User create event workflow - request two roles

In this example, an administrator creates a workflow that submits a separate request to add two roles to the newly created user. The script is triggered when a user create event occurs.

Assumptions

  • Roles exist in the catalog.

  • Make sure to catch any error/failure conditions.

Example

An example of user create event workflow to request two roles when a user is created.

  • 1 The Script node gets a user ID from the event request and returns the user object.

    Click to display Get User ID from event request script 
    logger.info("Get User Id From Event Request: UserCreateEventWithSteps");
var content = execution.getVariables();
var requestId = content.get('id');

// Read event user information from request object
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  var userObj = requestObj.request.common.blob.after;
  execution.setVariable("userId", userObj.userId);
}
catch (e) {
  execution.setVariable("failureState", "Validation failed: Error reading request with id " + requestId);
}

  • 2 The Script node makes a call to create the request. The payload contains two catalog IDs for the Data Analyst and Security roles.

    Click to display Submit request for roles script 
    logger.info("Submit Role Requests: UserCreateEventWithSteps");
var content = execution.getVariables();
var userId = content.get('userId');
var failureState = content.get('failureState');

// Define request payload
if (!failureState) {
  var requestBody = {
    priority: "low",
    accessModifier: "add",
    justification: "Request submitted on user creation: UserCreateEventWithSteps.",
    users: [ userId ],
    catalogs: [
      { type: "role", id: "b9224b9ae535c9eab3f493dc206ac689dc9f6733b417d0def37f8969bef3e95dad7c812e4585056f698c7b3eb15c970dfa939eca8217741af187978359af13df"},
      { type: "role", id: "e7ec51656c6f5ca297d82772a681e3069d8a7c24c04f15afaa8060856e17ad6e76f88bdeb635d4dc8c3d8faa462f376189322e85df379ae0721fcb2d28d1a222"}
    ]
  };

  // Create requests
  try {
    openidm.action("iga/governance/requests", "POST", requestBody, {_action: "create"})
  }
  catch (e) {
    execution.setVariable("failureState", "Unable to generate requests for roles");
  }
}

  • 3 The Script node completes the request.

    Click to display Finalize request script 
    logger.info("Finalize Request: UserCreateEventWithSteps");
var content = execution.getVariables();
var requestId  = content.get('requestId');
var failureState = content.get('failureState');

if (!failureState) {
  try {
    // Update event request as final
    var decision = {'status': 'complete', 'outcome': 'fulfilled', 'decision': 'approved'}
    var queryParams = { '_action': 'update'};
    openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
    logger.info("Request " + requestId + " completed.");
  }
  catch (e) {
    execution.setVariable("failureState", "Unable to finalize request.");
  }
}

  • 4 The Script node handles any failures.

    Click to display Failure handler script 
    logger.info("Failure Handler: UserCreateEventWithSteps");
var content = execution.getVariables();
var requestId  = content.get('requestId');
var failureReason  = content.get('failureReason');

// Update event request as final
if (failureReason) {
  var decision = {'status': 'complete', 'outcome': 'cancelled', 'decision': 'rejected', 'comment': failureReason, 'failure': true}
  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}

    The User create event workflow - send email, User create event workflow - catalog lookup, and User create event workflow - request two roles examples present User create event workflows. However, you can also adjust the workflows for User update events. For example, in the User create examples, the user object returns the current or after state of the user:

    var userObj = requestObj.request.common.blob.after

    Update events also have access to the before (or pre-update) state by referencing the object, which you can also use in your scripts.

    var userObj = requestObj.request.common.blob.before

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.

User offboarding workflow

In this example, an administrator creates a workflow that triggers a series of offboarding tasks when a user update occurs, such as a status, manager, or department change.

The offboarding tasks include:

  • Setting up a replacement user ID for the inactive user. Depending on the case, the replacement user is the manager or former manager.

  • Setting up a replacement user ID as a delegate for the inactive user.

  • Replacing all instances of other users delegating to the inactive user with replacement user ID.

  • Replacing the inactive user with the replacement user ID as an app owner.

  • Replacing the inactive user with the replacement user ID as an entitlements owner.

  • Replacing the inactive user with the replacement user ID as a role owner.

  • Replacing the inactive user with the replacement user ID as an access request approver.

  • Replacing the inactive user with the replacement user ID as a violations approver.

Assumptions

  • Human Resources confirms the user’s change in status, manager, or department and has activated offboarding tasks to stakeholders.

Example

An example of an inactivated user workflow.

  • 1 The Script node reads the event user information, including manager data from the request object.

    Click to display the Get Replacement User ID script 
    // Insert logic to set ID of user who will be replacing inactive user
logger.info("Getting ID of user who will be replacing inactive user.");

var content = execution.getVariables();
var requestId = content.get('id');

// Read event user information from request object
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  var previousUserObj = requestObj.request.common.blob.before;
  var currentUserObj = requestObj.request.common.blob.after;
  var userId = currentUserObj.id;
  var replacementId = null;

  // Check current value of manager, or previous manager if not present, to find a replacement user ID
  if (currentUserObj && currentUserObj.manager) {
    replacementId = currentUserObj.manager.id;
  }
  else if (previousUserObj && previousUserObj.manager) {
    replacementId = previousUserObj.manager.id;
  }

  execution.setVariable('userId', userId);
  execution.setVariable('replacementId', replacementId);
}
catch(e) {
  logger.info("Unable to get replacement user ID for inactive user " + userId);
}

  • 2 The Script node adds the replacement user as a delegate for the inactive user so that they can act on their tasks.

    Click to display Set Replacement User as Inactive User script 
    // Adding the Replacement User as a delegate for the Inactive User so that they will be able to act on their tasks
var content = execution.getVariables();
var userId = content.get('userId');
var replacementId = content.get('replacementId');

// Read event user information from request object
try {
  if (replacementId) {
    logger.info("Adding " + replacementId + " as inactive user " + userId + "'s delegate");
    var payload = { proxyIds: [ "managed/user/" + replacementId ]};
    var proxyUpdate = openidm.action('iga/governance/user/' + userId + '/set-proxy', 'POST', payload, {});
    logger.info("Added " + replacementId + " as a delegate for inactive user " + userId);
  }
}
catch(e) {
  logger.info("Unable to add delegate for inactive user " + userId);
}

  • 3 The Script node replaces all instances of other users delegating to the inactive user with the replacement user.

    Click to display the Replace Inactive User as delegate script 
    // Replacing all instances of others delegating to the inactive user with replacement user
// Before script: User A and User B both delegate to inactive User
// After script: User A and User B both delegate to replacement User

var content = execution.getVariables();
var userId = content.get('userId');
var replacementId = content.get('replacementId');

try {
  if (replacementId) {
    logger.info("Replacing instances of users delegating to inactive user " + userId + " with " + replacementId);

    // Get the list of users delegating to inactive user
    var inactiveUser = openidm.query("managed/alpha_user/" + userId + '/taskPrincipals', { _queryFilter: 'true' }, [ '_refResourceId' ]);
    var usersDelegatingToInactiveUser = inactiveUser.result;

    // Set the payloads
    var removePayload = { proxyIds: [ "managed/user/" + userId ]};
    var addPayload = { proxyIds: [ "managed/user/" + replacementId ]};

    // For each delegate, remove the inactive user and add the replacement user
    for (var i = 0; i < usersDelegatingToInactiveUser.length; i++) {
      var delegatingUserId = usersDelegatingToInactiveUser[i]._refResourceId;
      openidm.action("iga/governance/user/" + delegatingUserId + "/remove-proxy", "POST", removePayload, {});
      openidm.action("iga/governance/user/" + delegatingUserId + "/set-proxy", "POST", addPayload, {});
    }
    logger.info("Replaced instances of users delegating to inactive user " + userId + " with " + replacementId);
  }
}
catch(e) {
  logger.info("Unable to replace instances of users delegating to inactive user " + userId + " with " + replacementId);
}

  • 4 The Script node invokes the APIs and executes business logic.

    Click to display the App Owner Replacement script 
    /*
Script nodes are used to invoke APIs or execute business logic.
You can invoke governance APIs or IDM APIs.
Refer to https://backstage.forgerock.com/docs/idcloud/latest/identity-governance/administration/workflow-configure.html for more details.

Script nodes should return a single value and should have the
logic enclosed in a try-catch block.

Example:
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
}
catch (e) {
  failureReason = 'Validation failed: Error reading request with id ' + requestId;
}
*/

var content = execution.getVariables();
  var userId = content.get('userId');
  var replacementId = content.get('replacementId');
  var queryFilter =  {"_queryFilter": "true"}
  var removeBody = [];
  var addBody = [];

  var applications = openidm.query('managed/alpha_user/' + userId + '/ownerOfApp', queryFilter, []);

  for(var app of applications['result']){
    removeBody.push({
      "operation": "remove",
      "field": "/ownerOfApp",
      "value": {
          "_ref": app._ref,
          "_refProperties": {
              "_id": app._id,
              "_rev": app._rev
          },
          "_refResourceCollection": "managed/alpha_application",
          "_refResourceId": app._refResourceId
      }
  })
    addBody.push({
      "operation": "add",
      "field": "ownerOfApp/-",
      "value": {
          "_ref": app._ref,
          "_refProperties": {}
      }
    })
  }
  openidm.patch('managed/alpha_user/'+ userId, null, removeBody)
  openidm.patch('managed/alpha_user/'+ replacementId, null, addBody)

  • 5 The Script node replaces the entitlement owner.

    Click to display the Entitlement Owner Replacement script 
    /*
Script nodes are used to invoke APIs or execute business logic.
You can invoke governance APIs or IDM APIs.
Refer to https://backstage.forgerock.com/docs/idcloud/latest/identity-governance/administration/workflow-configure.html for more details.

Script nodes should return a single value and should have the
logic enclosed in a try-catch block.

Example:
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
}
catch (e) {
  failureReason = 'Validation failed: Error reading request with id ' + requestId;
}
*/
var content = execution.getVariables();
  var userId = content.get('userId');
  var replacementId = content.get('replacementId');
  var targetFilter =  {"targetFilter": {
      "operator": "EQUALS",
      "operand": {
          "targetName": "entitlementOwner.id",
          "targetValue": userId
      }
  }}

  var entitlements = openidm.action('iga/governance/resource/search', 'POST', targetFilter, {});

  for(var entitlement of entitlements['result']){
    var body = openidm.action('iga/governance/resource/' + entitlement.id + '/glossary', 'GET', {}, {})
    body.entitlementOwner = "managed/user/" + replacementId;
    openidm.action('iga/governance/resource/' + entitlement.id + '/glossary', 'PUT', body, {})
  }

  • 6 The Script node replaces the role owner.

    Click to display the Role Owner Replacement script 
    /*
Script nodes are used to invoke APIs or execute business logic.
You can invoke governance APIs or IDM APIs.
Refer to https://backstage.forgerock.com/docs/idcloud/latest/identity-governance/administration/workflow-configure.html for more details.

Script nodes should return a single value and should have the
logic enclosed in a try-catch block.

Example:
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
}
catch (e) {
  failureReason = 'Validation failed: Error reading request with id ' + requestId;
}
*/

var content = execution.getVariables();
  var userId = content.get('userId');
  var replacementId = content.get('replacementId');
  var targetFilter =  {"targetFilter": {
      "operator": "EQUALS",
        "operand": {
            "targetName": "glossary.idx./role.roleOwner",
            "targetValue": "managed/user/"+ userId
      }
  }}

  var results = openidm.action('iga/governance/catalog/search', 'POST', targetFilter, {});

  for(var result of results['result']){
    var body = openidm.action('iga/governance/role/' + result.role.id + '/glossary', 'GET', {}, {})
    body.roleOwner = "managed/user/" + replacementId;
    openidm.action('iga/governance/role/' + result.role.id + '/glossary', 'PUT', body, {})
  }

  • 7 The Script node reassigns approvals.

    Click to display the Reassign Approvals script 
    /*
Script nodes are used to invoke APIs or execute business logic.
You can invoke governance APIs or IDM APIs.
Refer to https://backstage.forgerock.com/docs/idcloud/latest/identity-governance/administration/workflow-configure.html for more details.

Script nodes should return a single value and should have the
logic enclosed in a try-catch block.

Example:
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
}
catch (e) {
  failureReason = 'Validation failed: Error reading request with id ' + requestId;
}
*/

var content = execution.getVariables();
var userId = content.get('userId');
var replacementId = content.get('replacementId');
var targetFilter =  {
  "targetFilter": {
        "operator": "AND",
        "operand": [
            {
                "operator": "EQUALS",
                "operand": {
                    "targetName": "decision.actors.active.id",
                    "targetValue": "managed/user/" + userId
                }
            },
            {
                "operator": "EQUALS",
                "operand": {
                    "targetName": "decision.status",
                    "targetValue": "in-progress"
                }
            }
        ]
    }
}

var results = null
var params = {
  "_pageSize": 100,
  "_pageNumber": 0
}
do{
  results= openidm.action('iga/governance/requests/search', 'POST', targetFilter, params);

  for(var result of results['result']){
    var phaseName = null;
    var actors = [];
    for(var user of result.decision.actors.active){
      if(user.id === "managed/user/"+ userId){
        phaseName = user.phase;
        actors.push({"id": "managed/user/" + replacementId, "permissions": user.permissions})
      }
    }
    for(var user of result.decision.actors.active){
      if(user.phase === phaseName && user.id !== "managed/user/"+ userId){
        actors.push({"id": user.id, "permissions": user.permissions})
      }
    }
    var body = { "updatedActors": actors  };
    if(phaseName){
      openidm.action('/iga/governance/requests/' + result.id + '/phases/' + phaseName + '/reassign', 'POST', body, {})
    }
  }
}
while (results.result.length > 0)

  • 8 The Script node reassigns violations.

    Click to display the Reassign Violations script 
    /*
Script nodes are used to invoke APIs or execute business logic.
You can invoke governance APIs or IDM APIs.
Refer to https://backstage.forgerock.com/docs/idcloud/latest/identity-governance/administration/workflow-configure.html for more details.

Script nodes should return a single value and should have the
logic enclosed in a try-catch block.

Example:
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
}
catch (e) {
  failureReason = 'Validation failed: Error reading request with id ' + requestId;
}
*/

logger.info('Script Task 3');

logger.info('User Task');

var content = execution.getVariables();
var userId = content.get('userId');
var replacementId = content.get('replacementId');
var targetFilter =  {
  "targetFilter": {
        "operator": "AND",
        "operand": [
            {
                "operator": "EQUALS",
                "operand": {
                    "targetName": "decision.actors.active.id",
                    "targetValue": "managed/user/" + userId
                }
            },
            {
                "operator": "EQUALS",
                "operand": {
                    "targetName": "decision.status",
                    "targetValue": "in-progress"
                }
            }
        ]
    }
}
var results = null
var params = {
  "_pageSize": 10,
  "_pageNumber": 0
}
do{
results = openidm.action('iga/governance/violation/search', 'POST', targetFilter, params);
if(results['result'].length > 0){
    for(var result of results['result']){
      var phaseName = null;
      var actors = [];
      for(var user of result.decision.actors.active){
        if(user.id === "managed/user/"+ userId){
          phaseName = user.phase;
          actors.push({"id": "managed/user/" + replacementId, "permissions": user.permissions})
        }
      }
      for(var user of result.decision.actors.active){
        if(user.phase === phaseName && user.id !== "managed/user/"+ userId){
          actors.push({"id": user.id, "permissions": user.permissions})
        }
      }
      var body = { "updatedActors": actors  };
      if(phaseName){
        openidm.action('/iga/governance/violation/' + result.id + '/phases/' + phaseName + '/reassign', 'POST', body, {})
      }
    }
  }
}
while(results.result.length > 0)

  • 9 The Script node completes the process and sets the ID of the user, replacing the inactive user.

    Click to display the Complete Process script 
    // Insert logic to set ID of user who will be replacing inactive user
logger.info("Completing request workflow.");

var content = execution.getVariables();
var requestId = content.get('id');

// Read event user information from request object
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  var decision = {'status': 'complete', 'decision': 'approved', 'outcome': 'fulfilled'};
  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}
catch(e) {
  logger.info("Error finalizing user inactive workflow")
}

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.

Workflow using custom request type and form

In this example, an administrator wants to create a custom request type called Create New User to add new employees or contractors to the system. Administrators or form creators need to carry out the following tasks:

After these tasks, the approver receives the request and can start processing the approval.

Assumptions

  • Each application has an application owner. An application owner is a user identity designated to manage the application. You populate this value for each target application.

  • You have designated an end user or a test user who can approve the request.

  • You have configured notifications to the end user or test user properly to receive the emails.

Example

Task 1: Create a custom request type

The initial task is to create a custom request type, Create New User that lets an administrator easily add a new user to the system. The Create New User request type has the following nonmodifiable properties:

  • userName. Username of the new user.

  • givenName. First name of the new user.

  • sn. Last name of the new user.

  • mail. Email address of the new user.

    1. Create a custom request type called createUser using the API. Enter the following command using curl to create your custom request type:

      Details 
      curl --location 'http://<hostname>/iga/governance/requestTypes' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "id": "createNewUser",
    "schemas": {
        "custom": [
            {
                "_meta": {
                    "type": "system",
                    "displayName": "Create User",
                    "properties": {
                        "userName": {
                            "isRequired": true,
                            "isInternal": false,
                            "isMultiValue": false,
                            "display": {
                                "name": "User Name",
                                "isVisible": true,
                                "order": 1,
                                "description": "The userName of the new user"
                            }
                        },
                        "givenName": {
                            "isRequired": true,
                            "isInternal": false,
                            "isMultiValue": false,
                            "display": {
                                "name": "First Name",
                                "isVisible": true,
                                "order": 2,
                                "description": "The first name of the new user"
                            }
                        },
                        "sn": {
                            "isRequired": true,
                            "isInternal": false,
                            "isMultiValue": false,
                            "display": {
                                "name": "Last Name",
                                "isVisible": true,
                                "order": 3,
                                "description": "The last name of the new user"
                            }
                        },
                        "mail": {
                            "isRequired": true,
                            "isInternal": false,
                            "isMultiValue": false,
                            "display": {
                                "name": "Email Address",
                                "isVisible": true,
                                "order": 4,
                                "description": "The email address of the new user"
                            }
                        }
                    }
                },
                "properties": {
                    "userName": {
                        "type": "text"
                    },
                    "givenName": {
                        "type": "text"
                    },
                    "sn": {
                        "type": "text"
                    },
                    "mail": {
                        "type": "text"
                    }
                }
            }
        ]
    },
    "workflow": {
        "id": "createNewUser",
        "type": "bpmn"
    },
    "validation": {
        "source": "var validation = {\"errors\" : [], \"comments\" : []}; if (request.custom.userName == undefined || request.custom.givenName == undefined || request.custom.sn == undefined ||  request.custom.mail == undefined) { validation.errors.push(\"Must include all of userName, givenName, sn, and mail fields.\");} validation;"
    },
    "custom": true,
    "displayName": "Create User",
    "uniqueKeys": [
        "custom.userName"
    ],
    "notModifiableProperties": []
}'
Task 2: Create a form for the custom request type

You have two options to create a form for a custom request type: use the UI or the API.

Using the admin console

  1. In the Advanced Identity Cloud admin console, click Governance > Forms.

  2. On the New Form modal, click Custom request form, and then click Next.

  3. On the Custom request form modal, enter the following:

    Field Description

    Form

    Enter a descriptive name for your form.

    Description (optional)

    Enter a general description for your form.

    Request Type (optional)

    Select a custom request type from the list. In this example, select Create User.

    You can only assign one form to each request type.

    Use this form for request creation

    Click this option to make this form available to the end user when creating new requests of this request type. If unchecked, the request type only provides form field key suggestions during the form design process. For this example, leave this checkbox unchecked.

    Once you create your form, you can go back and make edits to any of the previous form settings by clicking the ellipsis() in the top right, and then click Settings.

  4. Use the Forms editor to create a form for your custom request type. For example, drag-and-drop four text fields onto the canvas for the fields and label them: User Name, E-mail address, First Name, and Last Name.

    1. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the User Name field:

      User name text field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the curl step under the schemas entry. For example, enter custom.userName as the key.

      Label

      Enter a general label for this text field. For example, enter User Name.

      Description

      Enter help text for the text field. The description appears below your text field.

      Required

      Click if this text field is required. In this example, click Required.

      Read Only

      Click to make the field non-editable.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. For this example, enter 6.

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter 0.

      Use validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

      Regex

      Enter a regular expression to validate the text field.

      Error message

      Enter an error message when the regular expression fails.

    2. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the E-mail address field:

      E-mail address text field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the curl step under the schemas entry. For example, enter custom.mail as the key.

      Label

      Enter a general label for this text field. For example, enter E-mail address.

      Description

      Enter help text for the text field. The description appears below your text field.

      Required

      Click if this text field is required. In this example, click Required.

      Read Only

      Click to make the field non-editable.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. For this example, enter 6.

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter 0.

      Use Validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

      Regex

      Enter a regular expression to validate the text field.

      Error message

      Enter an error message when the regular expression fails.

    3. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the First Name field:

      First name text field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the curl step under the schemas entry. For example, enter custom.givenName as the key.

      Label

      Enter a general label for this text field. For example, enter First Name.

      Description

      Enter help text for the text field. The description appears below your text field.

      Required

      Click if this text field is required. In this example, click Required.

      Read Only

      Click to make the field non-editable.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. For this example, enter 6.

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter 0.

      Use validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

      Regex

      Enter a regular expression to validate the text field.

      Error message

      Enter an error message when the regular expression fails.

    4. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the Last Name field:

      Last name text field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the curl step under the schemas entry. For example, enter custom.sn as the key.

      Label

      Enter a general label for this text field. For example, enter Last Name.

      Description

      Enter help text for the text field. The description appears below your text field.

      Required

      Click if this text field is required. In this example, click Required.

      Read Only

      Click to make the field non-editable.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. For this example, enter 6.

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter 0.

      Use validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

      Regex

      Enter a regular expression to validate the text field.

      Error message

      Enter an error message when the regular expression fails.

  5. Click Save.

    An example of a form for the `Create User` custom request type.
Using the API

  1. Enter the following curl command to create your form for the custom request type:

    Details 
    curl --location 'http://<hostname>/iga/governance/requestForms' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Create New User",
    "type": "request",
    "description": "Form for creation of a new user",
    "categories": {
        "applicationType": null,
        "objectType": null,
        "operation": "create"
    },
    "form": {
        "fields": [
            {
                "id": "dd155b12-fb27-44e5-b4d6-476587b31a71",
                "model": "custom.userName",
                "type": "string",
                "label": "User Name",
                "description": "User name of the new user",
                "validation": {
                    "required": true
                },
                "layout": {
                    "columns": 6,
                    "offset": 0
                }
            },
            {
                "id": "88c73e69-86b1-453f-878b-527ceddeccf4",
                "model": "custom.mail",
                "type": "string",
                "label": "E-mail address",
                "description": "E-mail address of the new user",
                "validation": {
                    "required": true
                },
                "layout": {
                    "columns": 6,
                    "offset": 0
                }
            },
            {
                "id": "683892f9-2c13-41c7-a1cc-fcf38d7d0183",
                "model": "custom.givenName",
                "type": "string",
                "label": "First Name",
                "description": "First name of the new user",
                "validation": {
                    "required": true
                },
                "layout": {
                    "columns": 6,
                    "offset": 0
                }
            },
            {
                "id": "76fd5526-2ade-42a9-9b03-b6899e65aa31",
                "model": "custom.sn",
                "type": "string",
                "label": "Last Name",
                "description": "Last name of the new user",
                "validation": {
                    "required": true
                },
                "layout": {
                    "columns": 6,
                    "offset": 0
                }
            }
        ]
    }
}'

  2. Enter the following curl command to assign the form to the custom request type.

    Details 
    curl --location 'http://<hostname>/iga/governance/requestFormAssignments?_action=assign' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "formId": "b309b500-112c-4e6d-b832-a902f91362a3",
    "objectId": "requestType/createNewUser"
}'
Task 3: Create a workflow to use the custom request type and form

Create a new workflow called Create New User to use the custom request type and form.

An example of a workflow using the organization request type and form.

  • 1 Use a Script node to do a context check for the request.

    Click to display the Request Context Check script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = null;
var skipApproval = false;
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  if (requestObj.request.common.context) {
    context = requestObj.request.common.context.type;
    if (context == 'admin') {
      skipApproval = true;
    }
  }
}
catch (e) {
  logger.info("Request Context Check failed "+e.message);
}

logger.info("Context: " + context);
execution.setVariable("context", context);
execution.setVariable("skipApproval", skipApproval);

  • 2 Use an IF/ELSE node and name it Context Gateway. If skipApproval==true, route it to the Auto Approval node. If skipApproval==false, route it to the Approval Task node.

  • 3 Use a Script node for the Auto Approval task.

    Click to display the Auto Approval script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = content.get('context');
var queryParams = {
  "_action": "update"
}
try {
  var decision = {
      "decision": "approved",
      "comment": "Request auto-approved due to request context: " + context
  }
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
}
catch (e) {
  var failureReason = "Failure updating decision on request. Error message: " + e.message;
  var update = {'comment': failureReason, 'failure': true};
  openidm.action('iga/governance/requests/' + requestId, 'POST', update, queryParams);

}

  • 4 Use a Script node to create a new user using the custom request type.

    Click to display the Create User script 
    logger.info("Creating User");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  logger.info("requestObj: " + requestObj);
}
catch (e) {
  failureReason = "Provisioning failed: Error reading request with id " + requestId;
}

if(!failureReason) {
  try {
    var request = requestObj.request;
    var payload = {
      "userName": request.custom.userName,
      "givenName": request.custom.givenName,
      "sn": request.custom.sn,
      "mail": request.custom.mail,
      "password": 'DemoP@ssword1'
    };

    /** Create new user **/
    var result = openidm.create('managed/alpha_user', null, payload, queryParams);

    /** Send new user email **/
    var body = {
      subject: "Welcome " + payload.givenName + " " + payload.sn + "!",
      to: payload.mail,
      body: "Your new user has been created in the system.\n\nUsername: " + payload.userName + "\nPassword: " + payload.password + "\n\nLogin to your account here: https://openam-gov-dev-4.forgeblocks.com/am/XUI/?realm=/alpha#/",
      object: {}
    };
    openidm.action("external/email", "send", body);
  }
  catch (e) {
    failureReason = "Creating user failed: Error during creation of user " + request.custom.userName + ". Error message: " + e.message;
  }

  var decision = {'status': 'complete', 'decision': 'approved'};
  if (failureReason) {
    decision.outcome = 'not provisioned';
    decision.comment = failureReason;
    decision.failure = true;
  }
  else {
    decision.outcome = 'provisioned';
  }

  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}

  • 5 The Approval node assigns an approval task to users and roles. The node chains tasks in conjunction with a Switch node to implement serial or parallel flows.

    Click to display the Approval Task properties
    Item Description

    Name

    Approval Task

    Approvers

    Two options are available:

    • Add users and roles manually, such as Role Owner, and define the Approver type. For this example, click . In the Approver Type field, select User, and then select a user. Give the approvers the permissions below. Click Add.

      • Approve

      • Reject

      • Forward

      • Modify

      • Comment

    • Define users using a script:

    Form

    Select a form to present to the reviewer.

    • Dynamic form selection. Skip this step

    • Click Choose a form and select Create New User.

    Expiration Settings

    Options are:

    • Reject request. For this example, you can select this option.

    • Reassign request

    • Do nothing

    Notification Settings

    Options are:

    • Assignment notification and email templates, such as requestAssigned.

    • Reassignment notification and email templates, such as requestReassigned.

    • Assignee reminders and email templates, such as requestReminder.

      • Sends every number of time periods, such as 3 day(s).

    • Escalation notifications and email templates, such as requestEscalated.

      • Send every number of day(s), such as 5 day(s).

      • Send to Send escalation to to User and select User.

    • Expiration notification and email templates, such as requestExpired.

      • Send a configured number of days before expiration.

  • 6 Use the Script node to process any request rejections.

    Click to display the Reject Request script 
    logger.info("Rejecting request");

var content = execution.getVariables();
var requestId = content.get('id');

logger.info("Execution Content: " + content);
var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.
Task 4: Submit the custom request

You can enter a curl command to submit a Create New User request.

curl --location 'https://<hostname>/iga/governance/requests/createNewUser' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "custom": {
        "userName": "acabby",
        "givenName": "Amy",
        "sn": "Cabby",
        "mail": "amy.cabby@example.com"
    }
}'
Example Response 
{
  "id": "d289d1dd-b376-4860-a3d9-db3dd29702b2",
  "requester": {
    "givenName": "Joe",
    "id": "managed/teammember/ce6ef368-c050-4131-bc07-32aa4f58a785",
    "mail": "joe.admin@example.com",
    "sn": "Admin",
    "userName": "jadmin"
  },
  "requestType": "createNewUser",
  "request": {
    "custom": {
      "userName": "acabby",
      "givenName": "Amy",
      "sn": "Cabby",
      "mail": "amy.cabby@example.com"
    },
    "_rev": 1,
    "common": {
      "isDraft": false,
      "context": {
        "type": "request"
      }
    }
  },
  "decision": {
    "status": "in-progress",
    "decision": null,
    "type": "request",
    "outcome": null,
    "startDate": "2024-09-09T15:53:49+00:00",
    "completionDate": null,
    "deadline": null,
    "comments": [],
    "actors": {
      "active": [
        {
          "givenName": "Frank",
          "id": "managed/teammember/ce6ef368-c050-4131-bc07-32aa4f58a785",
          "mail": "frank.york@exampe.com",
          "sn": "York",
          "userName": "fyork",
          "permissions": {
            "approve": false,
            "comment": true,
            "modify": false,
            "forward": false,
            "reject": false,
            "cancel": false,
            "fulfill": false,
            "deny": false
          }
        }
      ],
      "inactive": [],
      "actorTags": [
        "activeId=managed%2Fteammember%2Fce6ef368-c050-4131-bc07-32aa4f58a785&phase=",
        "phase=&activeId=managed%2Fteammember%2Fce6ef368-c050-4131-bc07-32aa4f58a785"
      ]
    }
  }
}
Approver Task: Process the request

  1. Once the administrator submits the request, the approver (for example, "Frank York") receives a notification email.

    Notification email sent to the approver.

  2. The approver logs in to the Advanced Identity Cloud end-user UI and clicks Pending Approvals.

    Approver’s end-user UI displaying requests

  3. The approver can carry out different tasks: click Approve, Reject, or ellipsis () to Forward, Add Comment, or View Details.

    Approver clicks the specific create user request

  4. The approver clicks View Details.

    The approver review the details of the request.

Workflow to create an Organization custom request type and form

In this example, an administrator wants to create a custom request type called Create Organization to add new organizations to the system. Administrators and form creators need to carry out the following tasks:

After these tasks, the approver receives the request and can start reviewing it.

Assumptions

  • You have designated an end user who can function as an approver and review the request.

  • You have configured notification emails to alert the approver of incoming requests.

Example

Task 1: Create an organization request type

The initial task is to create a custom request type, Create Organization that lets an administrator easily add a new organization to the system.

  • Create a custom request type called Create Organization using the API. Enter the following command using curl to create your custom request type:

    Details 
    curl --location 'http://<hostname>/iga/governance/requestTypes' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "id": "createOrganization",
    "schemas": {
        "common": [
            {
                "_meta": {
                    "type": "system",
                    "displayName": "commonRequest",
                    "properties": {
                        "justification": {
                            "isRequired": false,
                            "isInternal": true,
                            "display": {
                                "name": "Justification",
                                "isVisible": true,
                                "order": 3,
                                "description": "The reason for the request"
                            }
                        },
                        "externalRequestId": {
                            "isRequired": false,
                            "isInternal": true,
                            "isChangable": false,
                            "display": {
                                "name": "External Request ID",
                                "isVisible": true,
                                "order": 4,
                                "description": "The external ID for the request"
                            }
                        },
                        "requestIdPrefix": {
                            "isRequired": false,
                            "isInternal": true,
                            "display": {
                                "name": "Request ID prefix",
                                "isVisible": true,
                                "order": 5,
                                "description": "Prefix for the request ID"
                            }
                        },
                        "isDraft": {
                            "isRequired": false,
                            "isInternal": true
                        },
                        "priority": {
                            "isRequired": false,
                            "display": {
                                "name": "Priority",
                                "isVisible": true,
                                "order": 6,
                                "description": "The priority of the reqeust"
                            },
                            "text": {
                                "defaultValue": "low"
                            }
                        },
                        "expiryDate": {
                            "isRequired": false,
                            "isInternal": true,
                            "display": {
                                "name": "Request expiration date",
                                "isVisible": true,
                                "order": 7,
                                "description": "User provided date on which the request will cancel"
                            }
                        },
                        "context": {
                            "isRequired": false,
                            "isInternal": true,
                            "isMultiValue": false,
                            "display": {
                                "name": "Context",
                                "isVisible": true,
                                "order": 1,
                                "description": "The context of the request"
                            }
                        },
                        "workflowId": {
                            "isRequired": false,
                            "isInternal": true,
                            "isChangable": false,
                            "display": {
                                "name": "BPMN workflow ID",
                                "isVisible": true,
                                "order": 7,
                                "description": "The ID key of the BPMN workflow"
                            }
                        },
                        "blob": {
                            "isRequired": false,
                            "isInternal": true
                        }
                    }
                },
                "properties": {
                    "justification": {
                        "type": "text"
                    },
                    "externalRequestId": {
                        "type": "text"
                    },
                    "requestIdPrefix": {
                        "type": "text"
                    },
                    "isDraft": {
                        "type": "boolean"
                    },
                    "priority": {
                        "type": "text"
                    },
                    "expiryDate": {
                        "type": "text"
                    },
                    "context": {
                        "type": "object"
                    },
                    "workflowId": {
                        "type": "text"
                    },
                    "blob": {
                        "type": "object"
                    }
                }
            }
        ],
        "custom": [
            {
                "_meta": {
                    "type": "system",
                    "displayName": "Create Organization",
                    "properties": {
                        "name": {
                            "isRequired": true,
                            "isInternal": false,
                            "isMultiValue": false,
                            "display": {
                                "name": "Name",
                                "isVisible": true,
                                "order": 1,
                                "description": "The name of the organization"
                            }
                        },
                        "description": {
                            "isRequired": false,
                            "isInternal": false,
                            "isMultiValue": false,
                            "display": {
                                "name": "Description",
                                "isVisible": true,
                                "order": 2,
                                "description": "The description of the organization being created"
                            }
                        },
                        "parent": {
                            "isRequired": false,
                            "isInternal": false,
                            "isMultiValue": false,
                            "display": {
                                "name": "Parent Organization",
                                "isVisible": true,
                                "order": 3,
                                "description": "The ID of the parent organization for this organization"
                            }
                        },
                        "admins": {
                            "isRequired": false,
                            "isInternal": false,
                            "isMultiValue": true,
                            "display": {
                                "name": "Organization Administrators",
                                "isVisible": true,
                                "order": 4,
                                "description": "The IDs of the users who will be this organization’s admins"
                            }
                        },
                        "includeSelfAdmin": {
                            "isRequired": false,
                            "isInternal": false,
                            "isMultiValue": false,
                            "display": {
                                "name": "Include Self as Admin",
                                "isVisible": true,
                                "order": 4,
                                "description": "If selected, include requester as an organization admin"
                            }
                        }
                    }
                },
                "properties": {
                    "name": {
                        "type": "text"
                    },
                    "description": {
                        "type": "text"
                    },
                    "parent": {
                        "type": "text"
                    },
                    "admins": {
                        "type": "text"
                    },
                    "includeSelfAdmin": {
                        "type": "boolean"
                    }
                }
            }
        ]
    },
    "workflow": {
        "id": "createOrganization",
        "type": "bpmn"
    },
    "validation": {
        "source": "var validation = {\"errors\" : [], \"comments\" : []}; if (request.custom.name == undefined) { validation.errors.push(\"Must include all name field.\");} validation;"
    },
    "custom": true,
    "displayName": "Create Organization",
    "uniqueKeys": [
        "custom.name"
    ],
    "notModifiableProperties": []
}'
Task 2: Create a form for the organization request type

  1. In the Advanced Identity Cloud admin console, click Governance > Forms.

  2. On the New Form modal, click Custom request form, and then click Next.

  3. On the Custom request form modal, enter the following:

    Field Description

    Form

    Enter a descriptive name for your form. In this example, enter: Create Organization.

    Description (optional)

    Enter a general description for your form. In this example, enter: Form used to create a new organization.

    Request Type (optional)

    Click and select a request type for the form. In this example, enter: Create Organization.

    You can only assign one form to each request type.

    Use this form for request creation

    Click this option to make this form available to the end user when creating new requests of this request type. If unchecked, the request type only provides form field key suggestions during the form design process. For this example, leave this checkbox unchecked.

    Once you create your form, you can go back and make edits to any of the previous form settings by clicking the ellipsis() in the top right, and then click Settings.

  4. Use the Forms editor to create a form for your custom request type. For example, drag-and-drop five form fields onto the canvas for the fields and label them:

    1. On the Forms editor canvas, drag-and-drop the Text node to the canvas, and fill in the properties in the right pane for the Organization Name field:

      Organization name text field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the example in Task 1 under the schemas entry. For example, enter custom.name as the key.

      Label

      Enter a general label for this text field. For example, enter User Name.

      Description

      Enter help text for the text field. The description appears below your text field. Enter Name of the organization.

      Required

      Click if this text field is required. In this example, click Required.

      Read Only

      Click to make the field non-editable. In this example, skip this step.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. For this example, use the default (12 columns).

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, use the default (0).

      Use validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

    2. On the Forms editor canvas, drag-and-drop the Textarea node to the canvas, and fill in the properties in the right pane for the Description field:

      Description textarea field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the example in Task 1 under the schemas entry. For example, enter custom.description as the key.

      Label

      Enter a general label for this text field. For example, enter Description.

      Description

      Enter help text for the text field. The description appears below your text field.

      Required

      Click if this text field is required. In this example, skip this step.

      Read Only

      Click to make the field non-editable. In this example, skip this step.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. For this example, use the default (12 columns).

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, use the default (0).

      Use Validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

    3. On the Forms editor canvas, drag-and-drop the Select node to the canvas, and fill in the properties in the right pane for the Parent Organization field:

      Parent Organization Select field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the example in Task 1 under the schemas entry. For example, enter custom.parent as the key.

      Label

      Enter a general label for this text field. For example, enter Parent Organization (optional).

      Description

      Enter help text for the text field. The description appears below your text field.

      Required

      Click if this text field is required. In this example, skip this step.

      Read Only

      Click to make the field non-editable. In this example, skip this step.

      Options

      Click one of the following to populate the Select field entries: Enumerated or Object.

      • Click Enumerated to manually set enumerated values in the Select field.

        1. Click the icon.

        2. On the Add Option modal, do the following:

        3. Value: enter a value for the option field. For example, if you want to add a menu of administrators, go Identities > Manage. Search for an administrator to pull up their information. On the user’s page, click Raw JSON. Copy the user’s id, for example, 94080e61-f6a5-4bd0-bfc4-d26d6ae5c1b8 and enter the ID into the Value field.

        4. Label: enter a label for the option field. Enter the user’s name, for example, Cleo Patrascu.

        5. Click Selected by default to make the option a default enumerated value for the field.

        6. Click Add.

        7. Repeat the steps to add additional users.

      • Click Object to get a list of options taken from the API.

        1. Select one of the following object types:

          • User

          • Role

          • Organization

          • Application

          • Entitlement

          For example, if you want to create a Parent Organization select field, select Organization.

        2. Click Save.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. In this example, use the default (12).

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. For this example, enter 0.

      Use validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

      Regex

      Enter a regular expression to validate the text field.

      Error message

      Enter an error message when the regular expression fails.

    4. On the Forms editor canvas, drag-and-drop the Select node to the canvas, and fill in the properties in the right pane for the Organization Admins field:

      Organization Admins Select field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the example in Task 1 under the schemas entry. For example, enter custom.admins as the key.

      Label

      Enter a general label for this text field. For example, enter Organization Admins (optional).

      Description

      Enter help text for the text field. The description appears below your text field.

      Required

      Click if this text field is required. In this example, skip this step.

      Read Only

      Click to make the field non-editable. In this example, skip this step.

      Options

      Click one of the following to populate the Select field entries: Enumerated or Object.

      • Click Enumerated to manually set enumerated values in the Select field.

        1. Click the icon.

        2. On the Add Option modal, do the following:

        3. Value: enter a value for the option field. For example, if you want to add a menu of administrators, go Identities > Manage. Search for an administrator to pull up their information. On the user’s page, click Raw JSON. Copy the user’s id, for example, 94080e61-f6a5-4bd0-bfc4-d26d6ae5c1b8 and enter the ID into the Value field.

        4. Label: enter a label for the option field. Enter the user’s name, for example, Cleo Patrascu.

        5. Click Selected by default to make the option a default enumerated value for the field.

        6. Click Add.

        7. Repeat the steps to add additional users.

      • Click Object to get a list of options taken from the API.

        1. Select one of the following object types:

          • User

          • Role

          • Organization

          • Application

          • Entitlement

          For example, if you want to create a Parent Organization select field, select Organization.

        2. Click Save.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. In this example, use the default (12).

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. In this example, use the default (0).

      Use validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

    5. On the Forms editor canvas, drag-and-drop the Checkbox node to the canvas, and fill in the properties in the right pane for the Include yourself as administrator field:

      Include yourself as administrator Checkbox field properties
      Field Description

      Key

      Enter the key for the text string. You can retrieve this key from the example in Task 1 under the schemas entry. For example, enter custom.includeSelfAdmin as the key.

      Label

      Enter a general label for this text field. For example, enter Include yourself as administrator.

      Description

      Enter help text for the text field. The description appears below your text field.

      Read Only

      Click to make the field non-editable. In this example, skip this step.

      Provide Default Value

      Click Provide Default Value to assign a default value for this text field. In this example, skip this step.

      Columns

      Enter the number of columns for this text field. Values are from 1 to 12. In this example, use the default (12).

      Offset

      Enter the number of columns to offset from the left for this text field. Values are from 0 to 11. In this example, use the default (0).

      Use validation

      Click if you want to validate the text field using a regular expression. In this example, skip this step.

  5. Click Preview to review your form.

  6. Click Save.

    An example of a form for the `Create Organization` custom request type.
Task 3: Create a workflow to use the organization request type and form
An example of a workflow using the organization request type and form.

  • 1 Use a Script node to do a context check for the request.

    Click to display the Request Context Check script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = null;
var skipApproval = false;
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  if (requestObj.request.common.context) {
    context = requestObj.request.common.context.type;
    if (context == 'admin') {
      skipApproval = true;
    }
  }
}
catch (e) {
  logger.info("Request Context Check failed "+e.message);
}

logger.info("Context: " + context);
execution.setVariable("context", context);
execution.setVariable("skipApproval", skipApproval);

  • 2 Use an IF/ELSE node and name it Context Gateway. If skipApproval==true, route it to the Auto Approval node. If skipApproval==false, route it to the Approval Task node.

  • 3 Use a Script node for the Auto Approval task.

    Click to display the Auto Approval script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = content.get('context');
var queryParams = {
  "_action": "update"
}
try {
  var decision = {
      "decision": "approved",
      "comment": "Request auto-approved due to request context: " + context
  }
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
}
catch (e) {
  var failureReason = "Failure updating decision on request. Error message: " + e.message;
  var update = {'comment': failureReason, 'failure': true};
  openidm.action('iga/governance/requests/' + requestId, 'POST', update, queryParams);

}

  • 4 Use a Script node to create a new organization using the custom request type.

    Click to display the Create Organization script node 
    logger.info("Creating Organization");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  logger.info("requestObj: " + requestObj);
}
catch (e) {
  failureReason = "Provisioning failed: Error reading request with id " + requestId;
}

if(!failureReason) {
  try {
    var request = requestObj.request;
    var payload = {
      "name": request.custom.name,
      "description": request.custom.description,
      "admins": []
    };

    if (request.custom.parent) {
      payload.parent = {
        "_ref": "managed/alpha_organization/" + request.custom.parent,
        "_refProperties": {}
      }
    }

    if (request.custom.admins) {
      request.custom.admins.forEach(function(admin) {
        payload.admins.push({ "_ref": "managed/alpha_user/" + admin, "_refProperties": {}});
      });
    }

    if (request.custom.includeSelfAdmin) {
      payload.admins.push({ "_ref": "managed/alpha_user/" + requestObj.requester.id.split('/')[2], "_refProperties": {}});
    }

    /** Create new org **/
    var result = openidm.create('managed/alpha_organization', null, payload);

    /** Send new org admins email **/

    payload.admins.forEach(function(admin) {
      var id = admin._ref
      var adminUser = openidm.read(id);
      var body = {
        subject: "Welcome " + adminUser.givenName + " " + adminUser.sn + "!",
        to: adminUser.mail,
        body: "You have been added as an administrator for a new organization.\nOrganization: " + payload.name + "",
        object: {}
      };
      openidm.action("external/email", "send", body);
    });
  }
  catch (e) {
    failureReason = "Creating org failed: Error during creation of organization " + request.custom.name + ". Error: " + e.message;
  }

  var decision = {'status': 'complete', 'decision': 'approved'};
  if (failureReason) {
    decision.outcome = 'not provisioned';
    decision.comment = failureReason;
    decision.failure = true;
  }
  else {
    decision.outcome = 'provisioned';
  }

  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}

  • 5 The Approval node assigns an approval task to users and roles. The node chains tasks in conjunction with a Switch node to implement serial or parallel flows.

    Click to display the Approval Task properties
    Item Description

    Name

    Approval Task

    Approvers

    Two options are available:

    • Add users who can approve the request, such as fyork, and define the Approver type. For this example, click . In the Approver Type field, select User, and then select a user. Give the approver all permissions below. Click Add.

      • Approve

      • Reject

      • Forward

      • Modify

      • Comment

    • Define users using a script:

    Form

    Select a form to present to the reviewer.

    • Dynamic form selection. Skip this step

    • Click Choose a form and select Create Organization.

    Expiration Settings

    Options are:

    • Reject request. For this example, you can select this option.

    • Reassign request

    • Do nothing

    Notification Settings

    Options are:

    • Assignment notification and email templates, such as requestAssigned.

    • Reassignment notification and email templates, such as requestReassigned.

    • Assignee reminders and email templates, such as requestReminder.

      • Sends every number of time periods, such as 3 day(s).

    • Escalation notifications and email templates, such as requestEscalated.

      • Send every number of day(s), such as 5 day(s).

      • Send to Send escalation to to User and select User.

      • Send escalation to: Select User and select a user to handle the escalation.

    • Expiration notification and email templates, such as requestExpired.

      • Send a configured number of days before expiration.

  • 6 Use the Script node to process any request rejections.

    Click to display the Reject Request script 
    logger.info("Rejecting request");

var content = execution.getVariables();
var requestId = content.get('id');

logger.info("Execution Content: " + content);
var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

Download the JSON file for this workflow here.

Learn more about how to import or export workflows in workflow editor canvas.
Task 4: Submit the organization request

You can enter a curl command to submit a Create Organization request.

curl --location 'https://<hostname>/iga/governance/requests/createOrganization?_action=publish' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
    "custom": {
        "name": "IGA Organization",
        "description": "Organization for all IGA members.",
        "parent": "a27172ad-8adf-425e-a93f-ebd7c7aaa776",
        "admins": [
            "c51d9ee1-43b3-49d1-8742-cbb33842a5cc",
            "e140e883-8ec7-4201-889d-f77ea118fcf3",
            "adeb08c0-f3b7-44eb-a31a-a31fba305a40"
        ],
        "includeSelfAdmin": false
    },
    "common": {

    }
}'

Currently, you must include the common key either unpopulated or to provide additional information, such as justification.
Approver Task: Process the organization request

Once the administrator submits the request, the approver (for example, "Frank York") can review the request.

Organization request

Workflow for entitlement grant with custom approvers

In this example, an administrator wants to create a basic entitlement grant workflow that uses a custom list of approvers in the Approval node.

Administrators need to carry out the following tasks:

Assumptions

  • You have designated an end user or a test user who can approve the request.

Example

Task 1: Create a custom glossary property

The initial task is to create a custom entitlement glossary property, Approvers, that lets an administrator easily set a custom list of approvers.

  1. In the Advanced Identity Cloud admin console, click Governance > Glossary.

  2. Click Entitlement and then Entitlement Glossary Item.

  3. In the Add Entitlement Glossary Item modal, enter the following, and click Save.

    Field Description

    Name

    Enter a label for the entitlement glossary item. For example, approvers.

    Display Name

    Enter a display name for the entitlement glossary item. For example, Approvers.

    Description (optional)

    Enter a general description for the glossary item.

    Type

    Select User.

    Multi-Valued

    Click Multi-Valued.

    Enumerated Values

    Leave disabled.
Task 2: Create a workflow with custom approvers

Create a new workflow called Basic Entitlement Grant Custom Approvers.

An example of an entitlement grant workflow using custom approvers.

  • 1 Use a Script node to perform a context check for the request.

    Click to display the Request Context Check script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = null;
var skipApproval = false;
var lineItemId = false;
try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  if (requestObj.request.common.context) {
    context = requestObj.request.common.context.type;
    lineItemId = requestObj.request.common.context.lineItemId;
    if (context == 'admin') {
      skipApproval = true;
    }
  }
}
catch (e) {
  logger.info("Request Context Check failed "+e.message);
}

logger.info("Context: " + context);
execution.setVariable("context", context);
execution.setVariable("lineItemId", lineItemId);
execution.setVariable("skipApproval", skipApproval);

  • 2 Use an IF/ELSE node and name it Context Gateway. If skipApproval==true, route it to the Auto Approval node. If skipApproval==false, route it to the Approval Task node.

  • 3 Use a Script node for the Auto Approval task.

    Click to display the Auto Approval script 
    var content = execution.getVariables();
var requestId = content.get('id');
var context = content.get('context');
var lineItemId = content.get('lineItemId');
var queryParams = {
  "_action": "update"
}
var lineItemParams = {
  "_action": "updateRemediationStatus"
}
try {
  var decision = {
      "decision": "approved",
      "comment": "Request auto-approved due to request context: " + context
  }
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
}
catch (e) {
  var failureReason = "Failure updating decision on request. Error message: " + e.message;
  var update = {'comment': failureReason, 'failure': true};
  openidm.action('iga/governance/requests/' + requestId, 'POST', update, queryParams);

}

  • 4 Use a Script node to create an approval task with custom approvers.

    Click to display the Approval Task properties with custom approvers script 
    (function() {
    var content = execution.getVariables();
    var requestId = content.get('id');
    var entitlementId = null;
    var users = [];

    try {
      var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
      entitlementId = requestObj.request.common.entitlementId;
    }
    catch (e) {
      failureReason = "Validation failed: Error reading request with id " + requestId;
    }
    try{
      var glossary = openidm.action('iga/governance/resource/' + entitlementId +'/glossary', 'GET', {}, {})
      let approvers = glossary.approvers
      for(var i = 0; i < approvers.length; i++){
        var userId = approvers[i];
        users.push({
          "id": userId, "permissions": {"approve": true, "reject": true, "forward": true, "modify": true, "comment": true}
        })

      }

    }
    catch (e){
      failureReason = "Validation failed: Error reading request with id " + requestId;
    }

    if(users.length > 0){
      return users;
    }
    else {
      // default approver logic
    }
})()

  • 5 Use the Script node to validate the entitlement grant.

    Click to display the Entitlement Grant Validation script 
    logger.info("Running entitlement grant request validation");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;
var applicationId = null;
var assignmentId = null;
var app = null;
var assignment = null;
var existingAccount = false;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  applicationId = requestObj.application.id;
  assignmentId = requestObj.assignment.id;
}
catch (e) {
  failureReason = "Validation failed: Error reading request with id " + requestId;
}

// Validation 1 - Check application exists
if (!failureReason) {
  try {
    app = openidm.read('managed/alpha_application/' + applicationId);
    if (!app) {
      failureReason = "Validation failed: Cannot find application with id " + applicationId;
    }
  }
  catch (e) {
    failureReason = "Validation failed: Error reading application with id " + applicationId + ". Error message: " + e.message;
  }
}

// Validation 2 - Check entitlement exists
if (!failureReason) {
  try {
    assignment = openidm.read('managed/alpha_assignment/' + assignmentId);
    if (!assignment) {
      failureReason = "Validation failed: Cannot find assignment with id " + assignmentId;
    }
  }
  catch (e) {
    failureReason = "Validation failed: Error reading assignment with id " + assignmentId + ". Error message: " + e.message;
  }
}

// Validation 3 - Check the user has application granted
if (!failureReason) {
  try {
    var user = openidm.read('managed/alpha_user/' + requestObj.user.id, null, [ 'effectiveApplications' ]);
    user.effectiveApplications.forEach(effectiveApp => {
      if (effectiveApp._id === applicationId) {
        existingAccount = true;
      }
    })
  }
  catch (e) {
    failureReason = "Validation failed: Unable to check existing applications of user with id " + requestObj.user.id + ". Error message: " + e.message;
  }
}

// Validation 4 - If account does not exist, provision it
if (!failureReason) {
  if (!existingAccount) {
    try {
      var request = requestObj.request;
      var payload = {
        "applicationId": applicationId,
        "startDate": request.common.startDate,
        "endDate": request.common.endDate,
        "auditContext": {},
        "grantType": "request"
      };
      var queryParams = {
        "_action": "add"
      }

      logger.info("Creating account: " + payload);
      var result = openidm.action('iga/governance/user/' + request.common.userId + '/applications' , 'POST', payload,queryParams);
    }
    catch (e) {
      failureReason = "Validation failed: Error provisioning new account to user " + request.common.userId + " for application " + applicationId + ". Error message: " + e.message;
    }
  }
}

if (failureReason) {
  logger.info("Validation failed: " + failureReason);
}
execution.setVariable("failureReason", failureReason);

  • 6 Use the Script node to reject the request.

    Click to display the Reject Request script 
    logger.info("Rejecting request");

var content = execution.getVariables();
var requestId = content.get('id');

logger.info("Execution Content: " + content);
var requestIndex = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
var decision = {'outcome': 'denied', 'status': 'complete', 'decision': 'rejected'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

  • 7 Use an IF/ELSE node and name it Validation Gateway. If validationFlowSuccess==true, route it to the Auto Provisioning node. If validationFlowFailure==false, route it to the Entitlement Grant Validation Failure node.

  • 8 Use the Script node to run auto provisioning.

    Click to display the Auto Provisioning script 
    logger.info("Auto-Provisioning");

var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = null;

try {
  var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});
  logger.info("requestObj: " + requestObj);
}
catch (e) {
  failureReason = "Provisioning failed: Error reading request with id " + requestId;
}

if(!failureReason) {
  try {
    var request = requestObj.request;
    var payload = {
      "entitlementId": request.common.entitlementId,
      "startDate": request.common.startDate,
      "endDate": request.common.endDate,
      "auditContext": {},
      "grantType": "request"
    };
    var queryParams = {
      "_action": "add"
    }

    var result = openidm.action('iga/governance/user/' + request.common.userId + '/entitlements' , 'POST', payload,queryParams);
  }
  catch (e) {
    failureReason = "Provisioning failed: Error provisioning entitlement to user " + request.common.userId + " for entitlement " + request.common.entitlementId + ". Error message: " + e.message;
  }

  var decision = {'status': 'complete', 'decision': 'approved'};
  if (failureReason) {
    decision.outcome = 'not provisioned';
    decision.comment = failureReason;
    decision.failure = true;
  }
  else {
    decision.outcome = 'provisioned';
  }

  var queryParams = { '_action': 'update'};
  openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);
  logger.info("Request " + requestId + " completed.");
}

  • 9 Use the Script node to process an entitlement grant validation failure.

    Click to display the entitlement grant validation failure 
    var content = execution.getVariables();
var requestId = content.get('id');
var failureReason = content.get('failureReason');

var decision = {'outcome': 'not provisioned', 'status': 'complete', 'comment': failureReason, 'failure': true, 'decision': 'approved'};
var queryParams = { '_action': 'update'};
openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);

Download the JSON file for this workflow here.

Learn more about importing or exporting workflows in workflow editor canvas.

Request access to resources

After you configure access requests, end users can request access to resources on the Advanced Identity Cloud end-user UI. An end user can request access to resources for themselves or for others. They can also request access to multiple resources in the same request.

Access request landing page

The access request landing page displays the access requests an end user submits for themselves and for others.

Learn more about how to sign on to the Advanced Identity Cloud end-user UI in end-user screens.

governance enduser ui my requests landing page

  • 1 Click My Requests from the Advanced Identity Cloud end-user UI to display the access requests landing page.

  • 2 Filter access requests by status:

    • Pending — The access request is pending approval by the approver(s).

    • Completed — The approver has either Approved or Rejected the request. Click a request to view the approver’s decision.

    • Canceled — Requests that expire or you cancel.

  • 3 Click Sort By and sort the request by an attribute in ascending or descending order.

  • 4 Click Show Filters to filter by attributes or priority. An end user sets the priority when they create the request.

  • 5 To view the details of a submitted request, click the request.

Create request

There are many options an end user can select when creating a request.

The following sections breakout the request process for readability purposes.

Start request

  1. From the access request landing page, click + New Request.

  2. Select one of the following:

    • Myself — Create a request for yourself.

    • Other Users — Select up to 10 users to submit a request for.

  3. Click Next.

    A page to select resources displays.

    governance enduser ui my requests select resources

  • 1 Search, sort, and select resources to add to the access request.

  • 2 End users review current access and the resources they’ve selected, add a justification for the access, set a priority of the request, and optionally add an expiration date.

Select resources

End users can select a combination of up to 10 applications, entitlements, and/or roles in the same request.

There are three types of resources: applications, entitlements, and roles.

On each tab, an end user can:

  • Search for a resource in the search bar.

  • Filter on resources using attributes.

    For more information, refer to create and configure glossary attributes.

  • Sort returned results by owner or resource name in ascending or descending order.

The following steps explore going through each resource tab to select which resources an end user wants. However, it isn’t necessary to click through each resource tab.

To select resources:

  1. From the Applications tab, click + Request next to each application to search for and select the desired applications.

    If an end user selects a resource they already have access to or if the request is in a pending state, an error code is generated:

    The following user(s) either already have the requested item assigned or in
a pending request. Choose another item to request for the selected user(s).

    The message also appears if other users are submitting on behalf of the end user.

  2. Click the Entitlements tab. Entitlements are specific privileges in applications.

  3. Search for and select desired entitlements. To do this, click + Request next to each entitlement.

    Select applications in the Filter by application field to display entitlements that pertain to a specific application.

  4. Click the Roles tab.

  5. Search for and select desired roles. To do this, click + Request next to each role.

Enter request details and submit request

The request details pane is where an end user reviews the resources selected in the request and enters information, such as justification.

  1. In the right pane, under Requesting for, click the user(s) name to view their current access.

  2. Under Requested Access, review the resources selected.

  3. Fill out the following fields:

    1. Justification — Enter a reason for requesting access to the selected resources.

    2. Priority — Select one of the following:

      The priority levels bear no meaning in Identity Governance. your company determines the value assigned to the request.

      • Low

      • Medium

      • High

    3. Apply Expiration Date — Optional. Expire (cancel) the access request if it isn’t approved or rejected by the approver(s) by the specified date.

      For example, an end user might need access to a resource by the end of the week, and if they don’t get the access by that time, then they don’t need the permission anymore.

  4. Click Complete Request. The end user is redirected to the access request landing page.

    After the end user submits a request, a Request ID displays on each resource the end user requests access to. The Request ID tracks the request from the end user requesting access to the approver approving or rejecting access.

Example video

The following video details a typical example of an end user submitting an access request:

Add comments to request

  1. On the access request landing page, click the request to which you want to add a comment.

  2. On the request page, click the Comments tab.

  3. Click + Add Comment.

  4. Enter comment.

  5. Click Add Comment.

Cancel pending request

  1. On the access request landing page, click the request you want to cancel.

  2. Click Cancel Request.

  3. Click Cancel Request again to confirm cancellation.

Assign access privileges to identities

Identity Governance requires end users to have permissions through an internal role to access an identity. For example, if an end user submits a role access request but lacks the required privileges, the role owner attribute displays a UUID instead of the role owner’s name. This occurs because the end user doesn’t have read access to the identity. The solution is to create an internal role with the read privileges to the identity and assign the internal role to the end user.

iga ss1

To create an internal role and assign it to the end user:

  1. In the Advanced Identity Cloud admin console, select Identities > Manage > Internal Roles.

  2. Click add New Internal Role.

    1. In the New Internal role modal, enter the following and click Next:

      • Name: Enter a name for the internal role.

      • Description (optional): Add a description for the internal role.

    2. In the Internal role Permissions modal, select Alpha realm - Users managed/alpha_user and click Next.

    3. In the Dynamic Internal role Assignment modal, click Next.

    4. In the Time Constraint modal, click Save.

    5. On your internal role page, select Privileges > add Add Privileges.

    6. In the Add Privileges modal, select Alpha realm - Users managed/alpha_user and click add Add.

    7. Click Show advanced.

    8. In the Attribute Permissions section, select set all attributes and select None to set all permissions to None.

    9. Click Read for the following attributes:

      • userName

      • givenName

      • sn

        If you are granting privileges for the Alpha Realm - Roles or Alpha Realm - Organizations identity, set Read access for the name attribute instead of the userName, givenName, and sn attributes.

    10. Click Save.

  3. On the internal role page, select Members > add Add Members.

    1. In the Add Members modal, select the end user and click Save.

  4. When the end user enters an access request for a role, they see the role owner information:

    iga ss2

Request to remove access

Managers can remove access from their direct reports through a remove access request for accounts (applications), roles, and entitlements.

When a manager submits the remove access request, the approver(s) of the resource approve or reject the remove access request.

To submit a remove access request:

  1. Sign on to the Advanced Identity Cloud end-user UI and navigate to My Directory > Direct Reports.

    For more information on this screen, refer to direct reports.

  2. Click any of the following tabs:

    1. Accounts (applications)

    2. Entitlements

    3. Roles — For roles, if the Assignment column has the value of rule-based, you cannot request to revoke the role.

  3. Click the ellipsis icon () next to the desired resource, and click Revoke.

  4. Next, fill out the following fields:

    1. Justification — Enter a reason for revoking access to the selected resources.

    2. Priority — Select one of the following:

      The priority levels don’t affect how Identity Governance processes requests. your company determines the value assigned to the request.

      • Low

      • Medium

      • High

    3. Apply Expiration Date — Optional. Expire (cancel) the remove access request if the approver(s) haven’t approved or rejected it by the specified date.

  5. Click Submit Request.

Review request items (End user UI)

When an end user submits an access request, designated owners (approvers) must grant approval for the provisioning of resources.

The items on which approvers review and make decisions are referred to as request items.

Approvers review and make decisions on items referred to as request items in the Advanced Identity Cloud end-user UI. For more information, refer to End-user pages.

Sign on to the Advanced Identity Cloud end-user UI and navigate to Inbox > Approvals.

governance enduser ui approvals landing page

  • 1 Click Inbox > Approvals from the Advanced Identity Cloud end-user UI to display the access requests landing page.

  • 2 Filter submitted request items by status:

    • Pending — The items are pending review.

    • Completed — The approver reviewed the items and made a decision (approve or reject).

  • 3 Click Sort By, and sort the items by an attribute in ascending or descending order.

  • 4 Click Show Filters to filter by attributes or priority. An end user sets the priority when they create the access request.

  • 5 Click on the item to view the details of the request.

Access request types

End users and managers can submit different access request types, such as removing and adding access requests.

The access request type breaks out the request items displayed to approvers.

The following table describes the access request types:

Access request type Description

Grant Application

End user requests access to an application.

Remove Application

End user’s manager requests to remove an application from an end user.

Grant Role

End user requests access to an Advanced Identity Cloud provisioning role.

Remove Role

End user’s manager requests to remove a role from an end user.

Grant Entitlement

End user requests access to an entitlement (an additional privilege inside an application).

Remove Entitlement

End user’s manager requests to remove an entitlement from an end user.

The access request type is indicated at the top of each request item.

governance enduser ui approvals request type

When end users enter an entitlement request, end users will see a warning message if the request results in a Segregation of Duties (SoD) violation.

Granting access to these entitlement(s) will result in a Segregation of Duties (SoD) violation.

End users can click View Details to review the entitlements on the Violations Found modal. The end user has the option to click Submit with Violation or Close the modal.

Approve, reject, or forward a request item

The access request details of a request item include the requested resource(s), justification, and submission date.

Click a request item to view the details and take action, such as approve or reject.

governance enduser ui approvals details page

Approve item

  1. Click the desired item to view the details.

  2. Optional. Add a comment to the request:

    1. Click the Comments tab, then click + Add Comment.

    2. Enter a comment, and then click Add Comment to save it.

  3. Click Approve.

  4. Click Approve again to confirm the approval of the resource.

    Identity Governance provisions the resource to the end user.

Reject item

  1. Click the desired item to view the details.

  2. Optional. Add a comment to the request:

    1. Click the Comments tab, then click [.label]# + Add Comment#.

    2. Enter a comment, and then click + Add Comment.

  3. Click Reject.

  4. Enter a justification as to why the request is being rejected.

  5. Click Reject.

Forward to another user or role

If the owner is unable to make a decision on their assigned access request due to insufficient information or other reasons, they can approve the request item request to one or more users assigned to a specific role.

To forward a request item to another user or role:

  1. Click desired request to view the details.

  2. Click Forward.

  3. Select one of the following:

    • Another user — Forward the item to a single user.

    • Users with assigned role — Forward the item to users in a role.

      Every user within the role can make a decision on the item. However, once a decision is reached, the assigned request item is considered complete.

  4. Select the user or role to assign the item to.

  5. Enter a comment as to why the item is being forwarded.

  6. Click Forward.

Extend capabilities

Identity Governance offers capabilities to enrich the process of certifying users. While they are not mandatory when performing the certification process, they allow you to customize your governance processes further.

The additional capabilities in Identity Governance are:

  • Entitlements — Entitlements are permissions given to an account in an target application and each entitlement correlates to a permission.

    Identity Governance aggregates entitlements together from onboarded target applications. You can then:

    • Use the entitlements when specifying what to certify templates.

    • Add business logic by creating governance glossary attributes and populating the attribute(s) on the entitlement(s).

  • Governance glossary — Attach custom attributes to applications, entitlements, and roles that you can use to extend the data you review using governance glossary attributes.

Manage entitlements

In Identity Governance, an entitlement is a specific access right assigned to an account within a target application and corresponds to a particular permission. It defines what a user can perform, such as viewing, modifying, or managing entitlements once they have access to the resource.

Identity Governance lets you take action on entitlements, such as:

  • Discover and onboard entitlements

  • Grant entitlements including:

    • Using access requests

    • Using provisioning roles

    • Using direct assignment by administrators

  • Certify users who have been granted entitlements

  • Perform segregation of duties (SoD) checks to identity entitlement assignments that violate compliance policies.

  • Manage the entitlements lifecycles using Governance Workflows

Entitlements catalog

Identity Governance aggregates entitlements from onboarded target applications into a centralized repository called the entitlements catalog, providing a unified view of the entitlements.

The entitlement catalog gives you the ability:

  • To create new entitlements

  • To enrich the business metadata or glossary of the entitlement

  • To manage the lifecycle of existing entitlements using Governance Workflows

  • To view users who have been assigned the entitlement in onboarded target applications

    UI example of the Entitlements Catalog

Prepare the application for entitlements

Before your end users can work entitlements, tenant or governance administrators must prepare the application(s) for entitlements. Key tasks are:

For more details on provisioning applications, learn more in Provision an application.

Load entitlements into Advanced Identity Cloud

When you onboard a target application into Advanced Identity Cloud, it also pulls in the application’s entitlements. Each application’s account schema includes one or more attributes that define the account’s privileges assigned to accounts within the target system. These attributes depend on other objects in the application, known as non-account objects (NAO), which serve as the source for the account’s allowed entitlements.

Any changes to entitlements are later brought into the system through reconciliation, the process of comparing and synchronizing identity data between the IGA system and external target systems.

You must run entitlement reconciliations at regular intervals depending upon how frequently new entitlements are added to or deleted from the target application.

Validate the entitlement configuration

After you have pulled in the entitlements into Advanced Identity Cloud, you see that most applications in the Application Catalog have predefined entitlement configurations. You must first validate the application configuration by:

  • Verifying that the account attribute has been correctly tagged as an entitlement based on your requirements.

  • Verify the account attribute is associated with the correct non-account object (NAO).

To validate the entitlement configuration and verify the account attribute:

  1. In the Advanced Identity Cloud admin console, go to Applications > Browse App Catalog.

  2. Select an application and click the Provisioning tab.

  3. On the Details page, make sure you are viewing the User object type.

  4. On the User object page, click Properties.

  5. Select the account attribute containing the entitlements to be assigned to the account.

    For most applications in the Application Catalog, the attribute is identified by a star.

    Account attributs identified as an entitlement have a star next to them.

  6. Click > Edit to view or edit the property.

  7. Verify that the application object type attribute has the correct non-account object (NAO) specified and that the entitlement property is checked. For example, the following image displays the servicePlanIds property:

    The Edit Property page displaying the Entitlement box.

    There are some applications that require you to manually set the NAO including:

    • Scripted REST

    • Scripted Groovy

    • Scripted Table

    • PowerShell

    • Multi-file CSV

    • SCIM

    Learn more in Manually set non-account objects for an account object.

  8. Click Data to preview the information, providing a real-time view of the target system data. You can scroll right to view the whole dataset.

    Applications Data view.

Configure user-friendly display names

When you onboard entitlements into Advanced Identity Cloud, they can have highly cryptic or technical names that make its purpose difficult to ascertain. To ensure user-friendly names appear when displaying accounts or entitlements, configure the application object types accordingly.

  1. In the Advanced Identity Cloud admin console, go to Applications > Browse App Catalog.

  2. Select an application and click the Provisioning tab.

  3. On the Details page, make sure you are viewing the User object type.

  4. In the Display Name Attribute field, select a single-valued string attribute from the target application.

  5. Click Save.

  6. Repeat steps 1–5 for the other object types.

    The following video shows an example:

Configuring the entitlement glossary

Administrators can enhance entitlements by adding meaningful business context, helping users understand their purpose and supporting Identity Governance in decision-making. This context is managed through the Entitlement Glossary, where administrators can add custom attributes in addition to the default ones.

Learn more in Managing the Governance Glossary.

Loading entitlements on-demand

Before running a reconciliation, make sure you have configured it to your requirements.

  1. In the Advanced Identity Cloud admin console, go to Applications > Browse App Catalog.

  2. Select an application and click the Provisioning tab.

  3. On the Details page, make sure you are viewing the User object type.

  4. Click Reconciliation > Reconcile.

  5. Click Reconcile Now if you want to onboard the entitlements immediately.

    The results of your reconciliation are displayed on the page. You can see the successful and unsuccessful matches.

    The application reconciliation page displaying a summary of successful and unsuccessful matches.

View entitlements

When you load entitlements into Advanced Identity Cloud, they appear in the left navigation pane under the Governance > Entitlements tab.

The administrator view of the entitlements.

There are three tabs that appear on the entitlements screen:

  • Details — Shows the entitlement owner of the entitlement as well as the entitlement glossary attributes.

  • Object Properties — Displays the entitlement data as it is in the target application.

  • Users — Shows the Advanced Identity Cloud user and the corresponding user entity in the target application.

Administrator view of the entitlement details, object properties, and users assigned the entitlements.

Manage governance glossary

In Identity Governance, you can use the governance glossary to attach custom attributes (metadata) to applications, entitlements, or roles to enhance certifications or access requests.

When using the governance glossary, you can create the following custom attributes:

Typical steps to make use of a governance glossary attribute

  1. Create governance glossary attribute (application, entitlement, or role).

  2. Populate the governance glossary attribute you create. For example, if you create an application glossary attribute, the attribute will appear on every target application in the Details tab.

  3. Use the attribute you create to:

    1. Filter on what you would like to certify when you create a template.

    2. Allow the end user to filter on the attribute in applications, entitlements, or roles when they request access.

Example of when to use the governance glossary

If you are already familiar with the use case(s) of governance glossary, start with Create a governance glossary attribute.

There are many scenarios in which using identity glossary attributes can provide useful business logic to make decisions.

Oftentimes, organizations have specific attributes to track users' entitlements from applications.

An example could be that you want to attach a risk score to each entitlement pulled into Advanced Identity Cloud. This could be to determine the sensitivity of the entitlement (privilege) in the target application.

Steps:

  1. From the Advanced Identity Cloud admin console, click Glossary.

  2. Click Entitlement > + Entitlement Glossary Item.

  3. Enter the following values:

    1. Name - riskScore

    2. Display Name - Risk score

    3. Type - Number

      For more information, refer to create entitlement attribute.

  4. Once you create the entitlement glossary attribute, it displays as metadata for each entitlement. To view this metadata in an entitlement, go to Entitlements > Select entitlement to view the attribute under the Details tab.

  5. Assign a risk score of 80 using the newly created Risk score attribute. The higher the risk score for an entitlement, the more sensitive operations that entitlement allows.

Now that you have created an entitlement glossary attribute and enriched existing entitlements with the Risk score attribute, you can leverage this new business-relevant data.

For example, you can create an entitlement assignment certification template that filters the template to show entitlements to review that have a Risk score of 75 or higher. This allows you to certify highly-sensitive entitlements.

This is just one scenario in which the identity glossary can be used. Create identity glossary attributes for applications, entitlements, or roles to suit your business cases.

Create a governance glossary attribute

To access the governance glossary, navigate to Glossary from the left navigation pane in the Advanced Identity Cloud admin console.

Create governance glossary attributes for:

Create an application glossary attribute

To create an application glossary attribute:

  1. Select Application from the left pane in the table.

  2. Select + Application Glossary Item.

  3. Enter details for the item:

    Field Description

    Name

    The backend name of the attribute.

    Display Name

    The name that displays on the Details tab of the target application.

    Description

    The rationale for the attribute.

    Type

    The data type of the attribute. The data type you select changes the way it displays in the application’s Details tab and the actions you can take.

    Select one of the following:

    • String

    • Number

    • Boolean — A checkbox. Checking the box corresponds to true.

    • Date — A date field (mm/dd/yyyy).

    • User — Select from existing users.

    • Role — Select from existing roles.

    • Organization — Select from existing organizations.

  4. Depending on the data type chosen, optional settings appear:

    • Multi-Valued — Lets you have more than one value when you populate the attribute, an array. For example, if you select the User type in step 3, you can select multiple users instead of one.

    • Enumerated Values — When you are populating the attribute on the application, create fixed values to choose from:

      • Select the + icon.

      • Fill out the text and value for the item.

        The text displays as the human-readable option to select. The value is the actual value saved to the backend.

      • If desired, add more values.

  5. Click Show advanced settings and optionally select Searchable. This allows an end user to search using this attribute when requesting access to the application.

  6. Click Save.

The application glossary attribute displays in the Details tab of every target application.

The following video shows an example:

Create an entitlement glossary attribute

To create an entitlement glossary attribute:

  1. Select Entitlement from the left pane in the table.

  2. Select + Entitlement Glossary Item.

  3. Enter details for the item:

    Field Description

    Name

    The backend name of the attribute.

    Display Name

    The name that displays on the Details tab of each entitlement.

    Description

    The rationale for the attribute.

    Type

    The data type of the attribute. The data type you select changes the way it displays each entitlement and the actions you can take.

    Select one of the following:

    • String

    • Number

    • Boolean — A checkbox. Checking the box corresponds to true.

    • Date — A date field (mm/dd/yyyy).

    • User — Select from existing users.

    • Role — Select from existing roles.

    • Organization — Select from existing organizations.

  4. Depending on the data type chosen, optional settings appear:

    • Multi-Valued — Lets you have more than one value when you populate the attribute, an array. For example, if you select the User type in step 3, you can select multiple users instead of one.

    • Enumerated Values — When you are populating the attribute on the entitlement, create fixed values to choose from:

      • Select the + icon.

      • Fill out the text and value for the item.

        The text displays as the human-readable option to select. The value is the actual value saved to the backend.

      • If desired, add more values.

  5. Click Show advanced settings and optionally select Searchable. This allows an end user to search using this attribute when requesting access to the entitlement.

  6. Click Save.

The entitlement glossary attribute displays in every onboarded entitlement. From the Advanced Identity Cloud admin console, go to Entitlements > Select entitlement > Details tab to view the newly created entitlement attribute.

The following video shows an example:

Create role glossary attribute

To create a role glossary attribute:

  1. Select Role from the left pane in the table.

  2. Select + Role Glossary Item.

  3. Enter details for the item:

    Field Description

    Name

    The backend name of the attribute.

    Display Name

    The name that displays on the Details tab of each role.

    Description

    The rationale for the attribute.

    Type

    The data type of the attribute. The data type you select changes the way it displays each role and the actions you can take.

    Select one of the following:

    • String

    • Number

    • Boolean — A checkbox. Checking the box corresponds to true.

    • Date — A date field (mm/dd/yyyy).

    • User — Select from existing users.

    • Role — Select from existing roles.

    • Organization — Select from existing organizations.

  4. Depending on the data type chosen, optional settings appear:

    • Multi-Valued — Lets you have more than one value when you populate the attribute, an array. For example, if you select the User type in step 3, you can select multiple users instead of one.

    • Enumerated Values — When you are populating the attribute on the role, create fixed values to choose from:

      • Select the + icon.

      • Fill out the text and value for the item.

        The text displays as the human-readable option to select. The value is the actual value saved to the backend.

      • If desired, add more values.

  5. Click Show advanced settings and select any of the following:

  6. Click Show advanced settings and optionally select Searchable. This allows an end user to search using this attribute when requesting access to the entitlement.

  7. Click Save.

The role glossary attribute displays in every role. From the Advanced Identity Cloud admin console, go to Manage > Identities > Select role > Details tab to view the newly created role attribute.

The following video shows an example:

Delete a governance glossary attribute

To delete a governance glossary attribute:

  1. From the Advanced Identity Cloud admin console, click Glossary.

  2. Select one of the following tabs:

    • Application

    • Entitlement

    • Role

  3. Click ellipsis () next to the governance glossary attribute you want to delete.

  4. Click Delete.

  5. Click Delete again to confirm the deletion.

    This action cannot be undone.

Identity Governance REST API reference

This section describes the endpoints and specific characteristics of Identity Governance REST APIs. You can find an overview of the Ping Identity REST API framework in Advanced Identity Cloud REST.

Access Identity Governance REST APIs using access tokens. You can find information on obtaining a token in Authenticate to Advanced Identity Cloud REST API with access token.

  • Identity Governance-related APIs: Identity Governance has many features, including access requests, the governance glossary (catalog), and entitlements. This page explores the Identity Governance REST API endpoints.

Identity Governance has many features, including access requests, the governance glossary (catalog), and entitlements.

The following sections comprehensively explore the Identity Governance REST API endpoints.

YAML file

The REST APIs contain many parameters and, in some instances, large request bodies. For your convenience, you can view the entire API using a YAML file based on the OpenAPI specification.

To download the YAML file, click here.

Learn more in the API reference documentation.

Adjust the configurations of the file to match your specific details, such as your Advanced Identity Cloud tenant FQDN.

Access token

You need to obtain an access token to authenticate to the Advanced Identity Cloud REST API. Learn more about obtaining an access token in Authenticate to Advanced Identity Cloud REST API with access token.

After you obtain an access token, you can access the Identity Governance API using the specific HTTP methods: GET, POST, PUT, PATCH, and DELETE. You can use client command-line tools, such as cURL or API platforms, such as Postman to transfer data to and from the IGA server.

For example, using cURL:

curl \
--request GET \
--header 'Authorization: Bearer <access token>' \
"https://<tenant-env-fqdn>/iga/governance/application?_pageSize=10&_queryFilter=true"
Show example response 
{
  "result": [
    {
      "application": {
		"authoritative": false,
      "connectorId": "AzureAD",
     		"description": "AzureAD application",
      ...
     	 	"name": "AzureAD",
      "templateName": "azure.ad",
     		 "templateVersion": "2.0",
      "objectTypes": [
        {
          "name": "__ACCOUNT__"
        },
        {
          "name": "__GROUP__",
          "accountAttribute": "memberOf"
        }
      ]
  },
  ...
}
  ],
  "searchAfterKey": "string",
  "resultCount": 0,
  "totalCount": 0
}

Endpoints

The following sections present the Identity Governance endpoints.

The output and examples presented in this section are based on a test dataset and are not real data.

Application

URI HTTP
method		 Description

/iga/governance/application

GET

Query Identity Governance applications. This endpoint is subject to scoped permissions given to the end user.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.
Responses
Code Description

200

OK

500

Server error
Click for an example to get a list of applications

Media type: application/json

GET iga/governance/application?_pageSize=1&_queryFilter=true
{
  "result": [
    {
      "application": {
		"authoritative": false,
      "connectorId": "AzureAD",
     		"description": "AzureAD application",
      ...
     	 	"name": "AzureAD",
      "templateName": "azure.ad",
     		 "templateVersion": "2.0",
      "objectTypes": [
        {
          "name": "__ACCOUNT__"
        },
        {
          "name": "__GROUP__",
          "accountAttribute": "memberOf"
        }
      ]
  },
  ...
}
  ],
  "searchAfterKey": "string",
  "resultCount": 0,
  "totalCount": 0
}

/iga/governance/application/{id}/{objectType}/schema

GET

Returns the schema of a given application’s object type.

This endpoint helps identify the required payload structure for the request endpoint, specifically for the object key that holds the entitlement details. The endpoint is also used in the UI to dynamically generate forms for creating and modifying entitlements.

Parameters
Name Description

id string * required

ID of the application.

objectType string * required

Object type to get the schema.
Responses
Code Description

200

OK

500

Server error
Click for an example to get the object type schema

Media type: application/json

GET iga/governance/application/{applicationId}/{objectType}/schema

For example:

GET iga/governance/application/e35d09cd-2b9b-41bc-8246-dc23d4a36502/Department/schema"
{
  "$schema": "http://json-schema.org/draft-03/schema",
  "id": "department",
  "nativeType": "department",
  "properties": {
    "__NAME__": {
      "flags": [
        "NOT_UPDATEABLE",
        "NOT_CREATABLE"
      ],
      "nativeName": "__NAME__",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 11,
      "displayName": "__NAME__"
    },
    "company": {
      "nativeName": "company",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 4,
      "displayName": "company"
    },
    "cost_center": {
      "nativeName": "cost_center",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 0,
      "displayName": "cost_center"
    },
    "dept_head": {
      "nativeName": "dept_head",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 15,
      "displayName": "dept_head"
    },
    "description": {
      "nativeName": "description",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 7,
      "displayName": "description"
    },
    "head_count": {
      "nativeName": "head_count",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 1,
      "displayName": "head_count"
    },
    "id": {
      "nativeName": "id",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 14,
      "displayName": "id"
    },
    "name": {
      "nativeName": "name",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 3,
      "displayName": "name"
    },
    "parent": {
      "nativeName": "parent",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 8,
      "displayName": "parent"
    },
    "primary_contact": {
      "nativeName": "primary_contact",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 10,
      "displayName": "primary_contact"
    },
    "sys_created_by": {
      "nativeName": "sys_created_by",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 12,
      "displayName": "sys_created_by"
    },
    "sys_created_on": {
      "nativeName": "sys_created_on",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 6,
      "displayName": "sys_created_on"
    },
    "sys_mod_count": {
      "flags": [
        "NOT_UPDATEABLE",
        "NOT_CREATABLE"
      ],
      "nativeName": "sys_mod_count",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 5,
      "displayName": "sys_mod_count"
    },
    "sys_tags": {
      "flags": [
        "NOT_UPDATEABLE",
        "NOT_CREATABLE"
      ],
      "nativeName": "sys_tags",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 13,
      "displayName": "sys_tags"
    },
    "sys_updated_by": {
      "flags": [
        "NOT_UPDATEABLE",
        "NOT_CREATABLE"
      ],
      "nativeName": "sys_updated_by",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 9,
      "displayName": "sys_updated_by"
    },
    "sys_updated_on": {
      "flags": [
        "NOT_UPDATEABLE",
        "NOT_CREATABLE"
      ],
      "nativeName": "sys_updated_on",
      "nativeType": "string",
      "type": "string",
      "userSpecific": true,
      "order": 2,
      "displayName": "sys_updated_on"
    }
  },
  "type": "object",
  "applicationId": "e35d09cd-2b9b-41bc-8246-dc23d4a36502"
}

Certification

URI HTTP
method		 Description

/iga/governance/certification/template

GET

Query existing certification templates.

Parameters
Name Description

queryString string

String to search name and description.

pageSize string

Number of results per page.

pageNumber string

Page number of results to display.

searchAfter string

An alternate of pageNumber, corresponds to the searchAfterKey value sent in the previous page’s results.

sortBy string

Property to sort results by.

sortDesc string

Direction to sort results by.

certificationType string

Filter by certification type. The available values are identity, roleMembership, and entitlement.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

GET /iga/governance/certification/templat?_pageSize=1
{
  "result": [
    {
      "status": "active",
      "certObjectType": "user",
      "name": "Biometrical Identity Scan  v0.1",
      "description": "",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": null,
      "skipInactiveCertifiers": false,
      "allowSelfCertification": false,
      "selfCertificationRule": "none",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 14,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": null,
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "identity",
      "ownerId": "managed/user/d4cdcf1e-9f97-4d50-ad6d-843bdfa47ae5",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/d4cdcf1e-9f97-4d50-ad6d-843bdfa47ae5",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "Luis Ye",
            "id": "d4cdcf1e-9f97-4d50-ad6d-843bdfa47ae5",
            "mail": "awd@asd.asd",
            "sn": "Herrera",
            "userName": "ye"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": "emailTemplate/certificationAssigned",
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": "emailTemplate/certificationReassigned",
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "accountGrant",
          "entitlementGrant",
          "roleMembership",
          "AccountGrant",
          "ResourceGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "EQUALS",
          "operand": {
            "targetName": "authoritative",
            "targetValue": false
          }
        },
        "account": {
          "operator": "ALL",
          "operand": []
        },
        "memberOfOrg": [],
        "entitlement": {
          "operator": "ALL",
          "operand": []
        },
        "role": {
          "operator": "ALL",
          "operand": []
        },
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": true,
        "exceptionAllowed": true
      },
      "ownerInfo": {
        "givenName": "Luis Ye",
        "id": "d4cdcf1e-9f97-4d50-ad6d-843bdfa47ae5",
        "mail": "awd@asd.asd",
        "sn": "Herrera",
        "userName": "ye"
      },
      "id": "afbd1e00-6b17-425b-a7e8-b34816b20174",
      "metadata": {
        "modifiedDate": "2025-03-20T21:47:32.325Z",
        "createdDate": "2025-03-20T21:47:13.329365134Z"
      }
    },
    {
      "status": "active",
      "certObjectType": "user",
      "name": "Bookmark App Test",
      "description": "",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": null,
      "skipInactiveCertifiers": false,
      "allowSelfCertification": true,
      "selfCertificationRule": "all",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 14,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": "BasicRevocation",
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "identity",
      "ownerId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "Abel",
            "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
            "mail": "abel.tuter@example.com",
            "sn": "Tuter",
            "userName": "abel.tuter"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": null,
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": null,
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "accountGrant",
          "AccountGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "OR",
          "operand": [
            {
              "operand": {
                "targetName": "id",
                "targetValue": "06ad7fa8-b0c3-412e-a8af-7d27367dc4d3"
              },
              "operator": "EQUALS"
            }
          ]
        },
        "account": {
          "operator": "ALL",
          "operand": []
        },
        "memberOfOrg": [],
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": true,
        "exceptionAllowed": true
      },
      "ownerInfo": {
        "givenName": "Abel",
        "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
        "mail": "abel.tuter@example.com",
        "sn": "Tuter",
        "userName": "abel.tuter"
      },
      "id": "cf31dc2f-96bc-4b9d-baca-a25b6fcd2b6c",
      "metadata": {
        "modifiedDate": "2025-03-26T16:10:54.979Z",
        "createdDate": "2025-03-26T16:10:48.375561804Z"
      }
    },
    {
      "status": "pending",
      "certObjectType": "user",
      "name": "Bookmark App Test (copy)",
      "description": "",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": null,
      "skipInactiveCertifiers": false,
      "allowSelfCertification": true,
      "selfCertificationRule": "all",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 14,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": "BasicRevocation",
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "identity",
      "ownerId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "Abel",
            "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
            "mail": "abel.tuter@example.com",
            "sn": "Tuter",
            "userName": "abel.tuter"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": null,
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": null,
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "accountGrant",
          "AccountGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "OR",
          "operand": [
            {
              "operand": {
                "targetName": "id",
                "targetValue": "06ad7fa8-b0c3-412e-a8af-7d27367dc4d3"
              },
              "operator": "EQUALS"
            }
          ]
        },
        "account": {
          "operator": "ALL",
          "operand": []
        },
        "memberOfOrg": [],
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": true,
        "exceptionAllowed": true
      },
      "ownerInfo": {
        "givenName": "Abel",
        "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
        "mail": "abel.tuter@example.com",
        "sn": "Tuter",
        "userName": "abel.tuter"
      },
      "id": "e92b134a-4843-41e1-89c3-eed7a21061a1",
      "scheduleId": null,
      "metadata": {
        "modifiedDate": "2025-05-09T11:20:37.22Z",
        "createdDate": "2025-03-26T16:45:03.022653856Z"
      }
    },
    {
      "status": "active",
      "certObjectType": "user",
      "name": "EC CV",
      "description": "",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": null,
      "skipInactiveCertifiers": false,
      "allowSelfCertification": false,
      "selfCertificationRule": "none",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 14,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": null,
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "entitlement",
      "ownerId": "managed/user/9dd8eb23-6b5b-4573-b2ea-d9d886a1c43c",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/9dd8eb23-6b5b-4573-b2ea-d9d886a1c43c",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "Carlos",
            "id": "9dd8eb23-6b5b-4573-b2ea-d9d886a1c43c",
            "mail": "carlos.vibancoo@forgerock.com",
            "sn": "Vibanco",
            "userName": "cvibanco"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": "emailTemplate/certificationAssigned",
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": "emailTemplate/certificationReassigned",
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "entitlementGrant",
          "ResourceGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "EQUALS",
          "operand": {
            "targetName": "authoritative",
            "targetValue": false
          }
        },
        "memberOfOrg": [],
        "entitlement": {
          "operator": "ALL",
          "operand": []
        },
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": true,
        "exceptionAllowed": true
      },
      "ownerInfo": {
        "givenName": "Carlos",
        "id": "9dd8eb23-6b5b-4573-b2ea-d9d886a1c43c",
        "mail": "carlos.vibancoo@forgerock.com",
        "sn": "Vibanco",
        "userName": "cvibanco"
      },
      "id": "7526e7b6-6580-497c-817b-64e05e54d1dc",
      "scheduleId": null,
      "metadata": {
        "modifiedDate": "2025-03-27T03:26:27.344Z",
        "createdDate": "2025-03-27T03:25:49.018057675Z"
      }
    },
    {
      "status": "pending",
      "certObjectType": "user",
      "name": "EC CV (copy)",
      "description": "",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": "",
      "skipInactiveCertifiers": false,
      "allowSelfCertification": false,
      "selfCertificationRule": "none",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 14,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": null,
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "entitlement",
      "ownerId": "managed/user/9dd8eb23-6b5b-4573-b2ea-d9d886a1c43c",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/9dd8eb23-6b5b-4573-b2ea-d9d886a1c43c",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "Carlos",
            "id": "9dd8eb23-6b5b-4573-b2ea-d9d886a1c43c",
            "mail": "carlos.vibancoo@forgerock.com",
            "sn": "Vibanco",
            "userName": "cvibanco"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": "emailTemplate/certificationAssigned",
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": "emailTemplate/certificationReassigned",
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "entitlementGrant",
          "ResourceGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "EQUALS",
          "operand": {
            "targetName": "authoritative",
            "targetValue": false
          }
        },
        "memberOfOrg": [],
        "entitlement": {
          "operator": "ALL",
          "operand": []
        },
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": true,
        "exceptionAllowed": true
      },
      "ownerInfo": {
        "givenName": "Carlos",
        "id": "9dd8eb23-6b5b-4573-b2ea-d9d886a1c43c",
        "mail": "carlos.vibancoo@forgerock.com",
        "sn": "Vibanco",
        "userName": "cvibanco"
      },
      "id": "9cd17b0f-6c92-4a2f-842f-dec592b47227",
      "metadata": {
        "modifiedDate": "2025-03-27T16:57:32.813732253Z",
        "createdDate": "2025-03-27T16:57:32.813730761Z"
      }
    },
    {
      "status": "active",
      "certObjectType": "user",
      "name": "EntitlementCert",
      "description": "",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": null,
      "skipInactiveCertifiers": false,
      "allowSelfCertification": false,
      "selfCertificationRule": "none",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 14,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": null,
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "entitlement",
      "ownerId": "managed/user/991cddde-a0ff-4da2-b01b-080e182ff395",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/991cddde-a0ff-4da2-b01b-080e182ff395",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "mike",
            "id": "991cddde-a0ff-4da2-b01b-080e182ff395",
            "mail": "test@test.com",
            "sn": "test",
            "userName": "mikeTest"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": "emailTemplate/certificationAssigned",
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": "emailTemplate/certificationReassigned",
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "entitlementGrant",
          "ResourceGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "EQUALS",
          "operand": {
            "targetName": "authoritative",
            "targetValue": false
          }
        },
        "memberOfOrg": [],
        "entitlement": {
          "operator": "ALL",
          "operand": []
        },
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": true,
        "exceptionAllowed": true
      },
      "ownerInfo": {
        "givenName": "mike",
        "id": "991cddde-a0ff-4da2-b01b-080e182ff395",
        "mail": "test@test.com",
        "sn": "test",
        "userName": "mikeTest"
      },
      "id": "5357fe84-db54-4853-bca7-e28580617830",
      "metadata": {
        "modifiedDate": "2025-03-21T18:20:38.449Z",
        "createdDate": "2025-03-21T18:20:19.686794893Z"
      }
    },
    {
      "status": "active",
      "certObjectType": "user",
      "name": "Entra Groups",
      "description": "",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": null,
      "skipInactiveCertifiers": false,
      "allowSelfCertification": false,
      "selfCertificationRule": "none",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 0,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": null,
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "entitlement",
      "ownerId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "Abel",
            "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
            "mail": "abel.tuter@example.com",
            "sn": "Tuter",
            "userName": "abel.tuter"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": null,
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": null,
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "entitlementGrant",
          "ResourceGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "OR",
          "operand": [
            {
              "operand": {
                "targetName": "id",
                "targetValue": "89feff34-86e3-4c00-b0ff-376c772ba1b7"
              },
              "operator": "EQUALS"
            }
          ]
        },
        "memberOfOrg": [],
        "entitlement": {
          "operator": "ALL",
          "operand": []
        },
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": false,
        "exceptionAllowed": false
      },
      "ownerInfo": {
        "givenName": "Abel",
        "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
        "mail": "abel.tuter@example.com",
        "sn": "Tuter",
        "userName": "abel.tuter"
      },
      "id": "94b71f9e-f5a1-488f-8d9a-fed558ed74d8",
      "metadata": {
        "modifiedDate": "2025-03-25T05:39:42.616Z",
        "createdDate": "2025-03-25T05:39:36.35029936Z"
      }
    },
    {
      "status": "pending",
      "certObjectType": "user",
      "name": "Entra Groups (copy)",
      "description": "",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": "",
      "skipInactiveCertifiers": false,
      "allowSelfCertification": false,
      "selfCertificationRule": "none",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 0,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": null,
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "entitlement",
      "ownerId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "Abel",
            "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
            "mail": "abel.tuter@example.com",
            "sn": "Tuter",
            "userName": "abel.tuter"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": null,
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": null,
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "entitlementGrant",
          "ResourceGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "OR",
          "operand": [
            {
              "operand": {
                "targetName": "id",
                "targetValue": "89feff34-86e3-4c00-b0ff-376c772ba1b7"
              },
              "operator": "EQUALS"
            }
          ]
        },
        "memberOfOrg": [],
        "entitlement": {
          "operator": "ALL",
          "operand": []
        },
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": false,
        "exceptionAllowed": false
      },
      "ownerInfo": {
        "givenName": "Abel",
        "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
        "mail": "abel.tuter@example.com",
        "sn": "Tuter",
        "userName": "abel.tuter"
      },
      "id": "569ccdb3-5583-4d7b-9c10-20ae76dd74ab",
      "metadata": {
        "modifiedDate": "2025-03-25T06:04:33.45811308Z",
        "createdDate": "2025-03-25T06:04:33.458111794Z"
      }
    },
    {
      "status": "active",
      "certObjectType": "user",
      "name": "MikeTest",
      "description": "test",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": null,
      "skipInactiveCertifiers": false,
      "allowSelfCertification": false,
      "selfCertificationRule": "none",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 14,
      "allowBulkCertify": true,
      "allowPartialSignoff": true,
      "remediationRule": null,
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "identity",
      "ownerId": "managed/user/991cddde-a0ff-4da2-b01b-080e182ff395",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/991cddde-a0ff-4da2-b01b-080e182ff395",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "mike",
            "id": "991cddde-a0ff-4da2-b01b-080e182ff395",
            "mail": "test@test.com",
            "sn": "test",
            "userName": "mikeTest"
          }
        }
      ],
      "defaultCertifierId": "managed/user/991cddde-a0ff-4da2-b01b-080e182ff395",
      "assignmentNotification": "emailTemplate/certificationAssigned",
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": "emailTemplate/certificationReassigned",
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "accountGrant",
          "entitlementGrant",
          "roleMembership",
          "AccountGrant",
          "ResourceGrant"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "application": {
          "operator": "EQUALS",
          "operand": {
            "targetName": "authoritative",
            "targetValue": false
          }
        },
        "account": {
          "operator": "ALL",
          "operand": []
        },
        "memberOfOrg": [],
        "entitlement": {
          "operator": "ALL",
          "operand": []
        },
        "role": {
          "operator": "ALL",
          "operand": []
        },
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "expirationNotificationDay": 5,
      "requireJustification": {
        "revoke": true,
        "exceptionAllowed": true
      },
      "ownerInfo": {
        "givenName": "mike",
        "id": "991cddde-a0ff-4da2-b01b-080e182ff395",
        "mail": "test@test.com",
        "sn": "test",
        "userName": "mikeTest"
      },
      "defaultCertifierInfo": {
        "givenName": "mike",
        "id": "991cddde-a0ff-4da2-b01b-080e182ff395",
        "mail": "test@test.com",
        "sn": "test",
        "userName": "mikeTest"
      },
      "id": "f3a5ee0f-975a-443f-8a94-a70bca08f9af",
      "scheduleId": null,
      "metadata": {
        "modifiedDate": "2025-03-20T16:04:26.713Z",
        "createdDate": "2025-03-18T23:46:41.305877852Z"
      }
    },
    {
      "status": "active",
      "certObjectType": "user",
      "name": "Role Membership Certification",
      "description": "Role Membership Certification",
      "isEventBased": false,
      "stagingEnabled": false,
      "schedule": null,
      "skipInactiveCertifiers": false,
      "allowSelfCertification": true,
      "selfCertificationRule": "all",
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "claim": true,
        "delegate": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "save": true,
        "signoff": true
      },
      "exceptionDuration": 14,
      "allowBulkCertify": true,
      "allowPartialSignoff": false,
      "remediationRule": null,
      "initializeRule": "",
      "finalizeRule": "",
      "certificationType": "roleMembership",
      "ownerId": "managed/user/75982e79-40dc-4ad2-8b85-abe1ebd2e2b9",
      "stageDuration": 14,
      "expirationAction": null,
      "expirationActionDelay": 0,
      "expirationReassignee": null,
      "stages": [
        {
          "certifierType": "user",
          "certifierId": "managed/user/15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
          "certifierScript": null,
          "certifierInfo": {
            "givenName": "Abel",
            "id": "15ed1cdd-8a3b-4b26-82d4-a3eed78e3bfa",
            "mail": "abel.tuter@example.com",
            "sn": "Tuter",
            "userName": "abel.tuter"
          }
        }
      ],
      "defaultCertifierId": null,
      "assignmentNotification": null,
      "assignmentNotificationIncludeManager": false,
      "reassignNotification": null,
      "expirationNotification": null,
      "reminderNotification": null,
      "reminderFrequency": 0,
      "escalationNotification": null,
      "escalationFrequency": null,
      "escalationOwner": null,
      "remediationDelay": 0,
      "targetFilter": {
        "type": [
          "roleMembership"
        ],
        "user": {
          "operator": "ALL",
          "operand": []
        },
        "memberOfOrg": [],
        "role": {
          "operator": "ALL",
          "operand": []
        },
        "decision": {
          "operator": "ALL",
          "operand": []
        }
      },
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "requireJustification": {
        "revoke": true,
        "exceptionAllowed": true
      },
      "ownerInfo": {
        "givenName": "Frank",
        "id": "75982e79-40dc-4ad2-8b85-abe1ebd2e2b9",
        "mail": "fyork@example.com",
        "sn": "York",
        "userName": "fyork"
      },
      "id": "deb85d50-170b-4c5a-abb8-defa3ed8baef",
      "metadata": {
        "modifiedDate": "2025-03-26T15:46:19.528Z",
        "createdDate": "2025-03-26T15:45:57.050282486Z"
      }
    }
  ],
  "resultCount": 10,
  "totalHits": 21,
  "searchAfterKey": [
    "Role Membership Certification",
    "deb85d50-170b-4c5a-abb8-defa3ed8baef"
  ]
}

/iga/governance/certification/template

POST

Create a new certification template.

Parameters

No parameters

Request body * required

Media type: application/json

{
  "name": "Active Directory Certification",
  "description": "Certifying the accounts within active directory applications",
  "stagingEnabled": false,
  "schedule": null,
  "allowSelfCertification": false,
  "selfCertificationRule": "none",
  "enableForward": true,
  "enableReassign": true,
  "reassignPermissions": {
    "certify": true,
    "comment": true,
    "exception": true,
    "forward": true,
    "reassign": true,
    "reset": true,
    "revoke": true,
    "signoff": true
  },
  "exceptionDuration": 7,
  "allowBulkCertify": true,
  "allowPartialSignoff": true,
  "remediationRule": "",
  "initializeRule": "",
  "finalizeRule": "",
  "certificationType": "identity",
  "ownerId": "managed/user/926de311-0949-415d-a9e4-94a87632b0f6",
  "stageDuration": 14,
  "expirationAction": "revoke",
  "expirationActionDelay": 0,
  "expirationReassignee": null,
  "stages": [
   {
     "certifierType": "user",
     "certifierId": "managed/user/79cc9f29-8d89-4958-8074-ce0df88979a2"
   }
  ],
  "defaultCertifierId": null,
  "assignmentNotification": null,
  "reassignNotification": null,
  "expirationNotification": null,
  "reminderNotification": null,
  "reminderFrequency": 0,
  "escalationNotification": null,
  "escalationFrequency": null,
  "escalationOwner": null,
  "remediationDelay": 0,
  "targetFilter": {
    "user": {
      "operator": "ALL",
      "operand": []
    },
    "type": [
      "accountGrant"
    ],
    "application": {
      "operator": "CONTAINS",
      "operand": {
        "targetName": "name",
        "targetValue": "Active Directory"
      }
    }
  },
  "excludeConditionalAccess": true,
  "excludeRoleBasedAccess": true,
  "includeChildOrganizations": true
}
Responses
Code Description

201

Creation success. Returns the saved template object.

400

Invalid data provided.

500

Server error
Click for an example response

Media type: application/json

POST iga/governance/certification/template
{
  "name": "Active Directory Certification",
  "description": "Certifying the accounts within active directory applications",
  "stagingEnabled": false,
  "schedule": null,
  "allowSelfCertification": false,
  "selfCertificationRule": "none",
  "enableForward": true,
  "enableReassign": true,
  "reassignPermissions": {
    "certify": true,
    "comment": true,
    "exception": true,
    "forward": true,
    "reassign": true,
    "reset": true,
    "revoke": true,
    "signoff": true
  },
  "exceptionDuration": 7,
  "allowBulkCertify": true,
  "allowPartialSignoff": true,
  "remediationRule": "",
  "initializeRule": "",
  "finalizeRule": "",
  "certificationType": "identity",
  "ownerId": "managed/user/926de311-0949-415d-a9e4-94a87632b0f6",
  "stageDuration": 14,
  "expirationAction": "revoke",
  "expirationActionDelay": 0,
  "expirationReassignee": null,
  "stages": [
    {
      "certifierType": "user",
      "certifierId": "managed/user/79cc9f29-8d89-4958-8074-ce0df88979a2"
    }
  ],
  "defaultCertifierId": null,
  "assignmentNotification": null,
  "reassignNotification": null,
  "expirationNotification": null,
  "reminderNotification": null,
  "reminderFrequency": 0,
  "escalationNotification": null,
  "escalationFrequency": null,
  "escalationOwner": null,
  "remediationDelay": 0,
  "targetFilter": {
    "user": {
      "operator": "ALL",
      "operand": []
    },
    "type": [
      "accountGrant",
      "AccountGrant"
    ],
    "application": {
      "operator": "CONTAINS",
      "operand": {
        "targetName": "name",
        "targetValue": "Active Directory"
      }
    }
  },
  "excludeConditionalAccess": true,
  "excludeRoleBasedAccess": true,
  "includeChildOrganizations": true,
  "status": "pending",
  "id": "5626c308-250f-4b50-9f92-0c7e122e95c9"
}

/iga/governance/certification/template/{id}/duplicate

POST

Duplicate an existing certification template.

Parameters
Name Description

id string * required

ID of the template object to copy
Responses
Code Description

200

OK

400

Invalid request

404

Template not found

500

Server error
Click for an example response

Media type: application/json

POST /iga/governance/certification/template/afbd1e00-6b17-425b-a7e8-b34816b20174/duplicate
{
  "message": "Cert Template duplicated successfully"
}

/iga/governance/certification/template/{id}

PUT

Update a single certification template.

Parameters
Name Description

id string * required

ID of the template object
Request body

Media type: application/json

{
  "id": "string",
  "name": "string",
  "description": "string",
  "certificationType": "identity",
  "ownerId": "managed/user/926de311-0949-415d-a9e4-94a87632b0f6",
  "ownerId": "string",
  "schedule": {
    "id": "string",
    "type": "simple",
    "startTime": "string",
    "endTime": "string",
    "repeatCount": 0,
    "repeatInterval": 0,
    "schedule": "string",
    "invokeContext": {},
    "enabled": true
  },
  "allowSelfCertification": false,
  "targetFilter": {
    "user": {
      "operator": "EQUALS",
      "operand": {
        "targetName": "accountStatus",
        "targetValue": "active"
      }
    },
    "application": {
      "operator": "CONTAINS",
      "operand": {
        "targetName": "name",
        "targetValue": "SalesForce"
      }
    },
    "type": [
      "accountGrant"
    ],
    "memberOfOrg": [
      "52cf01b4-288e-4c21-aed6-f992be073988"
    ]
  },
  "stages": [
    {
      "name": "string",
      "certifierType": "user",
      "certifierId": "managed/user/79cc9f29-8d89-4958-8074-ce0df88979a"
    }
  ],
  "stageDuration": 0,
  "expirationAction": "certify",
  "expirationActionDelay": 0,
  "expirationReassignee": null,
  "stagingEnabled": true,
  "defaultCertifierId": "string",
  "allowBulkCertify": true,
  "allowPartialSignoff": true,
  "remediationRule": "string",
  "initializeRule": "",
  "finalizeRule": "",
  "ownerId": "managed/user/926de311-0949-415d-a9e4-94a87632b0f6",
  "exceptionDuration": 0,
  "enableForward": true,
  "enableReassign": true,
  "reassignPermissions": {
    "certify": true,
    "comment": true,
    "exception": true,
    "forward": true,
    "reassign": true,
    "reset": true,
    "revoke": true,
    "signoff": true
  },
  "selfCertificationRule": "all",
  "assignmentNotification": "string",
  "reassignNotification": "string",
  "expirationNotification": "string",
  "expirationNotificationDay": "string",
  "reminderNotification": "string",
  "reminderFrequency": 0,
  "escalationNotification": "string",
  "escalationFrequency": 0,
  "escalationOwner": "string",
  "remediationDelay": 0,
  "excludeConditionalAccess": true,
  "excludeRoleBasedAccess": true,
  "includeChildOrganizations": true,
  "parameters": [
    {
      "id": "string",
      "displayName": "string",
      "path": "string"
    }
  ],
  "templateEventType": "user"
}
Responses
Code Description

200

OK

400

Invalid request

404

Template not found

500

Server error
Click for an example response

Media type: application/json

PUT /iga/governance/certification/template/5626c308-250f-4b50-9f92-0c7e122e95c9
[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "certificationType": "identity",
    "ownerId": "managed/user/926de311-0949-415d-a9e4-94a87632b0f6",
    "schedule": {
      "id": "string",
      "type": "simple",
      "startTime": "string",
      "endTime": "string",
      "repeatCount": 0,
      "repeatInterval": 0,
      "schedule": "string",
      "invokeContext": {},
      "enabled": true
    },
    "targetFilter": {
      "user": {
        "operator": "EQUALS",
        "operand": {
          "targetName": "accountStatus",
          "targetValue": "active"
        }
      },
      "application": {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "name",
          "targetValue": "SalesForce"
        }
      },
      "type": [
        "accountGrant"
      ],
      "memberOfOrg": [
        "52cf01b4-288e-4c21-aed6-f992be073988"
      ]
    },
    "stages": [
      {
        "name": "string",
        "certifierType": "user",
        "certifierId": "string"
      }
    ],
    "stageDuration": 0,
    "expirationAction": "certify",
    "expirationActionDelay": "string",
    "expirationReassignee": "string",
    "stagingEnabled": true,
    "defaultCertifierId": "string",
    "allowBulkCertify": true,
    "allowPartialSignoff": true,
    "remediationRule": "string",
    "remediationDelay": 0,
    "exceptionDuration": 0,
    "enableForward": true,
    "enableReassign": true,
    "reassignPermissions": {
      "certify": true,
      "comment": true,
      "exception": true,
      "forward": true,
      "reassign": true,
      "reset": true,
      "revoke": true,
      "signoff": true
    },
    "selfCertificationRule": "all",
    "assignmentNotification": "string",
    "reassignNotification": "string",
    "expirationNotification": "string",
    "expirationNotificationDay": "string",
    "reminderNotification": "string",
    "reminderFrequency": 0,
    "escalationNotification": "string",
    "escalationFrequency": 0,
    "escalationOwner": "string",
    "excludeConditionalAccess": true,
    "excludeRoleBasedAccess": true,
    "includeChildOrganizations": true,
    "parameters": [
      {
        "id": "string",
        "displayName": "string",
        "path": "string"
      }
    ],
    "templateEventType": "user",
    "status": "active",
    "scheduleId": "string",
    "ownerInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "defaultCertifierInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "escalationOwnerInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "expirationReassigneeInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string",
      "name": "string"
    }
  }
]

/iga/governance/certification/template/{id}

DELETE

Delete a single certification template at the requested ID in the path.

Parameters
Name Description

id string * required

ID of the template object
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "certificationType": "identity",
    "ownerId": "string",
    "schedule": {
      "id": "string",
      "type": "simple",
      "startTime": "string",
      "endTime": "string",
      "repeatCount": 0,
      "repeatInterval": 0,
      "schedule": "string",
      "invokeContext": {},
      "enabled": true
    },
    "targetFilter": {
      "user": {
        "operator": "EQUALS",
        "operand": {
          "targetName": "accountStatus",
          "targetValue": "active"
        }
      },
      "application": {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "name",
          "targetValue": "SalesForce"
        }
      },
      "type": [
        "accountGrant"
      ],
      "memberOfOrg": [
        "52cf01b4-288e-4c21-aed6-f992be073988"
      ]
    },
    "stages": [
      {
        "name": "string",
        "certifierType": "user",
        "certifierId": "string"
      }
    ],
    "stageDuration": 0,
    "expirationAction": "certify",
    "expirationActionDelay": "string",
    "expirationReassignee": "string",
    "stagingEnabled": true,
    "defaultCertifierId": "string",
    "allowBulkCertify": true,
    "allowPartialSignoff": true,
    "remediationRule": "string",
    "remediationDelay": 0,
    "exceptionDuration": 0,
    "enableForward": true,
    "enableReassign": true,
    "reassignPermissions": {
      "certify": true,
      "comment": true,
      "exception": true,
      "forward": true,
      "reassign": true,
      "reset": true,
      "revoke": true,
      "signoff": true
    },
    "selfCertificationRule": "all",
    "assignmentNotification": "string",
    "reassignNotification": "string",
    "expirationNotification": "string",
    "expirationNotificationDay": "string",
    "reminderNotification": "string",
    "reminderFrequency": 0,
    "escalationNotification": "string",
    "escalationFrequency": 0,
    "escalationOwner": "string",
    "excludeConditionalAccess": true,
    "excludeRoleBasedAccess": true,
    "includeChildOrganizations": true,
    "parameters": [
      {
        "id": "string",
        "displayName": "string",
        "path": "string"
      }
    ],
    "templateEventType": "user",
    "status": "active",
    "scheduleId": "string",
    "ownerInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "defaultCertifierInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "escalationOwnerInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "expirationReassigneeInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string",
      "name": "string"
    }
  }
]

/iga/governance/certification/get-filter-schema

POST

Get the available schema on which to filter certification templates.

Returns a collection of schema properties that are available to populate the certification templates target filter property, including properties of application, user, entitlement, role, and other objects.

Parameters

No parameters

Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

{
  "application": [
    {
      "key": "application.description",
      "name": "description",
      "displayName": "Description",
      "description": "Application Description",
      "type": "string",
      "isMultiValue": false
    },
    {
      "key": "application.name",
      "name": "name",
      "displayName": "Name",
      "description": "Application name",
      "type": "string",
      "isMultiValue": false
    }
  ],
  "entitlement": [
    {
      "key": "glossary.idx./entitlement.description",
      "allowedValues": [],
      "isIndexed": true,
      "isMultiValue": false,
      "managedObjectType": null,
      "searchable": true,
      "isInternal": true,
      "displayName": "Description",
      "name": "description",
      "description": "Description of entitlement",
      "objectType": "/openidm/managed/assignment",
      "type": "string"
    },
    {
      "key": "entitlement.displayName",
      "name": "displayName",
      "displayName": "Display Name",
      "description": "",
      "type": "text",
      "isMultiValue": false
    },
    {
      "key": "glossary.idx./entitlement.entitlementOwner",
      "allowedValues": [],
      "isIndexed": true,
      "isMultiValue": false,
      "managedObjectType": "/openidm/managed/user",
      "searchable": true,
      "isInternal": true,
      "displayName": "Entitlement Owner",
      "name": "entitlementOwner",
      "description": "Entitlement Owner of Object",
      "objectType": "/openidm/managed/assignment",
      "type": "managedObject"
    },
    {
      "key": "glossary.idx./entitlement.requestable",
      "allowedValues": [],
      "isIndexed": true,
      "isMultiValue": false,
      "managedObjectType": null,
      "searchable": true,
      "isInternal": true,
      "displayName": "Requestable",
      "name": "requestable",
      "description": "Can the entitlement be requested",
      "objectType": "/openidm/managed/assignment",
      "type": "boolean"
    }
  ],
  "role": [
    {
      "key": "role.applications._ref",
      "name": "applications",
      "displayName": "Applications",
      "description": "Role Applications",
      "type": "managedObject",
      "isMultiValue": true,
      "managedObjectType": "/openidm/managed/alpha_application"
    },
    {
      "key": "role.description",
      "name": "description",
      "displayName": "Description",
      "description": "The role description, used for display purposes.",
      "type": "string",
      "isMultiValue": false
    },
    {
      "key": "role.id",
      "name": "_id",
      "displayName": "Name",
      "description": "Role ID",
      "type": "string",
      "isMultiValue": false
    },
    {
      "key": "role.name",
      "name": "name",
      "displayName": "Name",
      "description": "The role name, used for display purposes.",
      "type": "string",
      "isMultiValue": false
    },
    {
      "key": "glossary.idx./role.requestable",
      "allowedValues": [],
      "isIndexed": true,
      "isMultiValue": false,
      "managedObjectType": null,
      "searchable": true,
      "isInternal": true,
      "displayName": "Requestable",
      "name": "requestable",
      "description": "Can the role be requested",
      "objectType": "/openidm/managed/role",
      "type": "boolean"
    },
    {
      "key": "role.members._ref",
      "name": "members",
      "displayName": "Role Members",
      "description": "Role Members",
      "type": "managedObject",
      "isMultiValue": true,
      "managedObjectType": "/openidm/managed/alpha_user"
    }
  ]
}

/iga/governance/certification/admin/certification

GET

Query existing certification campaign instances.

Returns certification campaigns based on a set of query parameters.

Parameters
Name Description

queryString string

String to search against name and description.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to continue searching. Comma-separated for multiple values.

status string

Filter by status of the certification. The available values are active and closed.

certificationType string

Filter by certification type. The available value is identity.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "certificationType": "identity",
      "ownerId": "string",
      "schedule": {
        "id": "string",
        "type": "simple",
        "startTime": "string",
        "endTime": "string",
        "repeatCount": 0,
        "repeatInterval": 0,
        "schedule": "string",
        "invokeContext": {},
        "enabled": true
      },
      "targetFilter": {
        "user": {
          "operator": "EQUALS",
          "operand": {
            "targetName": "accountStatus",
            "targetValue": "active"
          }
        },
        "application": {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "name",
            "targetValue": "SalesForce"
          }
        },
        "type": [
          "accountGrant"
        ],
        "memberOfOrg": [
          "52cf01b4-288e-4c21-aed6-f992be073988"
        ]
      },
      "stages": [
        {
          "name": "string",
          "certifierType": "user",
          "certifierId": "string"
        }
      ],
      "stageDuration": 0,
      "expirationAction": "certify",
      "expirationActionDelay": "string",
      "expirationReassignee": "string",
      "stagingEnabled": true,
      "defaultCertifierId": "string",
      "allowBulkCertify": true,
      "allowPartialSignoff": true,
      "remediationRule": "string",
      "remediationDelay": 0,
      "exceptionDuration": 0,
      "enableForward": true,
      "enableReassign": true,
      "reassignPermissions": {
        "certify": true,
        "comment": true,
        "exception": true,
        "forward": true,
        "reassign": true,
        "reset": true,
        "revoke": true,
        "signoff": true
      },
      "selfCertificationRule": "all",
      "assignmentNotification": "string",
      "reassignNotification": "string",
      "expirationNotification": "string",
      "expirationNotificationDay": "string",
      "reminderNotification": "string",
      "reminderFrequency": 0,
      "escalationNotification": "string",
      "escalationFrequency": 0,
      "escalationOwner": "string",
      "excludeConditionalAccess": true,
      "excludeRoleBasedAccess": true,
      "includeChildOrganizations": true,
      "parameters": [
        {
          "id": "string",
          "displayName": "string",
          "path": "string"
        }
      ],
      "templateEventType": "user",
      "status": "active",
      "scheduleId": "string",
      "ownerInfo": {
        "id": "string",
        "userName": "string",
        "mail": "string",
        "givenName": "string",
        "sn": "string"
      },
      "defaultCertifierInfo": {
        "id": "string",
        "userName": "string",
        "mail": "string",
        "givenName": "string",
        "sn": "string"
      },
      "escalationOwnerInfo": {
        "id": "string",
        "userName": "string",
        "mail": "string",
        "givenName": "string",
        "sn": "string"
      },
      "expirationReassigneeInfo": {
        "id": "string",
        "userName": "string",
        "mail": "string",
        "givenName": "string",
        "sn": "string",
        "name": "string"
      },
      "templateId": "string",
      "startDate": "string",
      "deadline": "string",
      "completionDate": "string",
      "completedBy": {},
      "expirationNotificationDate": "string",
      "reminderNotificationDate": "string",
      "escalationNotificationDate": "string",
      "etlJobId": "string",
      "systemMessages": {
        "info": [
          {}
        ],
        "errors": [
          {}
        ]
      }
    }
  ],
  "totalHits": 0,
  "searchAfterKey": [
    "string"
  ]
}

/iga/governance/certification/admin/certification/{certId}

GET

Read a single certification campaign.

Returns the certification campaign from the provided campaign ID.

Parameters
Name Description

certId string * required

ID of the certification campaign
Responses
Code Description

200

OK

400

Invalid request

404

Certification not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "description": "string",
  "certificationType": "identity",
  "ownerId": "string",
  "schedule": {
    "id": "string",
    "type": "simple",
    "startTime": "string",
    "endTime": "string",
    "repeatCount": 0,
    "repeatInterval": 0,
    "schedule": "string",
    "invokeContext": {},
    "enabled": true
  },
  "targetFilter": {
    "user": {
      "operator": "EQUALS",
      "operand": {
        "targetName": "accountStatus",
        "targetValue": "active"
      }
    },
    "application": {
      "operator": "CONTAINS",
      "operand": {
        "targetName": "name",
        "targetValue": "SalesForce"
      }
    },
    "type": [
      "accountGrant"
    ],
    "memberOfOrg": [
      "52cf01b4-288e-4c21-aed6-f992be073988"
    ]
  },
  "stages": [
    {
      "name": "string",
      "certifierType": "user",
      "certifierId": "string"
    }
  ],
  "stageDuration": 0,
  "expirationAction": "certify",
  "expirationActionDelay": "string",
  "expirationReassignee": "string",
  "stagingEnabled": true,
  "defaultCertifierId": "string",
  "allowBulkCertify": true,
  "allowPartialSignoff": true,
  "remediationRule": "string",
  "remediationDelay": 0,
  "exceptionDuration": 0,
  "enableForward": true,
  "enableReassign": true,
  "reassignPermissions": {
    "certify": true,
    "comment": true,
    "exception": true,
    "forward": true,
    "reassign": true,
    "reset": true,
    "revoke": true,
    "signoff": true
  },
  "selfCertificationRule": "all",
  "assignmentNotification": "string",
  "reassignNotification": "string",
  "expirationNotification": "string",
  "expirationNotificationDay": "string",
  "reminderNotification": "string",
  "reminderFrequency": 0,
  "escalationNotification": "string",
  "escalationFrequency": 0,
  "escalationOwner": "string",
  "excludeConditionalAccess": true,
  "excludeRoleBasedAccess": true,
  "includeChildOrganizations": true,
  "parameters": [
    {
      "id": "string",
      "displayName": "string",
      "path": "string"
    }
  ],
  "templateEventType": "user",
  "status": "active",
  "scheduleId": "string",
  "ownerInfo": {
    "id": "string",
    "userName": "string",
    "mail": "string",
    "givenName": "string",
    "sn": "string"
  },
  "defaultCertifierInfo": {
    "id": "string",
    "userName": "string",
    "mail": "string",
    "givenName": "string",
    "sn": "string"
  },
  "escalationOwnerInfo": {
    "id": "string",
    "userName": "string",
    "mail": "string",
    "givenName": "string",
    "sn": "string"
  },
  "expirationReassigneeInfo": {
    "id": "string",
    "userName": "string",
    "mail": "string",
    "givenName": "string",
    "sn": "string",
    "name": "string"
  },
  "templateId": "string",
  "startDate": "string",
  "deadline": "string",
  "completionDate": "string",
  "completedBy": {},
  "expirationNotificationDate": "string",
  "reminderNotificationDate": "string",
  "escalationNotificationDate": "string",
  "etlJobId": "string",
  "systemMessages": {
    "info": [
      {}
    ],
    "errors": [
      {}
    ]
  },
  "totalTargets": 0,
  "totalItems": 0,
  "totalItemsComplete": 0,
  "percentItemsComplete": 0
}

/iga/governance/certification/admin/certification/{certId}/tasks

GET

Get the actors (certifiers) tasks view for a certification.

Returns the tasks assigned to different actors (certifiers) as part of a certification.

Parameters
Name Description

certId string * required

ID of the certification campaign

queryString string

Search tasks based on reviewer information (userName, sn, givenName, mail)

_pageSize string

Number of response result objects to return

_pageNumber string

Page number of results to show.

sortBy string

Term on which to sort tasks (for example, actor.userName, progress)

_sortDir string

Direction of sort: asc, desc.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "actor": {
        "id": "string",
        "givenName": "string",
        "sn": "string",
        "userName": "string",
        "type": "user",
        "name": "string",
        "key": "string"
      },
      "inProgress": 0,
      "complete": 0,
      "total": 0,
      "progress": 0,
      "status": "staging"
    }
  ]
}

/iga/governance/certification/admin/certification/{certId}/update-deadline

POST

Update a certification’s deadline.

Update a certification’s deadline when you provide a new one.

Parameters
Name Description

certId string * required

ID of the certification campaign
Request body * required

Media type: application/json

{
  "newDeadline": "2023-05-01T12:00:00+00:00"
}
Responses
Code Description

200

OK

400

Invalid request

404

Certification couldn’t be found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "description": "string",
  "certificationType": "identity",
  "ownerId": "string",
  "schedule": {
    "id": "string",
    "type": "simple",
    "startTime": "string",
    "endTime": "string",
    "repeatCount": 0,
    "repeatInterval": 0,
    "schedule": "string",
    "invokeContext": {},
    "enabled": true
  },
  "targetFilter": {
    "user": {
      "operator": "EQUALS",
      "operand": {
        "targetName": "accountStatus",
        "targetValue": "active"
      }
    },
    "application": {
      "operator": "CONTAINS",
      "operand": {
        "targetName": "name",
        "targetValue": "SalesForce"
      }
    },
    "type": [
      "accountGrant"
    ],
    "memberOfOrg": [
      "52cf01b4-288e-4c21-aed6-f992be073988"
    ]
  },
  "stages": [
    {
      "name": "string",
      "certifierType": "user",
      "certifierId": "string"
    }
  ],
  "stageDuration": 0,
  "expirationAction": "certify",
  "expirationActionDelay": "string",
  "expirationReassignee": "string",
  "stagingEnabled": true,
  "defaultCertifierId": "string",
  "allowBulkCertify": true,
  "allowPartialSignoff": true,
  "remediationRule": "string",
  "remediationDelay": 0,
  "exceptionDuration": 0,
  "enableForward": true,
  "enableReassign": true,
  "reassignPermissions": {
    "certify": true,
    "comment": true,
    "exception": true,
    "forward": true,
    "reassign": true,
    "reset": true,
    "revoke": true,
    "signoff": true
  },
  "selfCertificationRule": "all",
  "assignmentNotification": "string",
  "reassignNotification": "string",
  "expirationNotification": "string",
  "expirationNotificationDay": "string",
  "reminderNotification": "string",
  "reminderFrequency": 0,
  "escalationNotification": "string",
  "escalationFrequency": 0,
  "escalationOwner": "string",
  "excludeConditionalAccess": true,
  "excludeRoleBasedAccess": true,
  "includeChildOrganizations": true,
  "parameters": [
    {
      "id": "string",
      "displayName": "string",
      "path": "string"
    }
  ],
  "templateEventType": "user",
  "status": "active",
  "scheduleId": "string",
  "ownerInfo": {
    "id": "string",
    "userName": "string",
    "mail": "string",
    "givenName": "string",
    "sn": "string"
  },
  "defaultCertifierInfo": {
    "id": "string",
    "userName": "string",
    "mail": "string",
    "givenName": "string",
    "sn": "string"
  },
  "escalationOwnerInfo": {
    "id": "string",
    "userName": "string",
    "mail": "string",
    "givenName": "string",
    "sn": "string"
  },
  "expirationReassigneeInfo": {
    "id": "string",
    "userName": "string",
    "mail": "string",
    "givenName": "string",
    "sn": "string",
    "name": "string"
  },
  "templateId": "string",
  "startDate": "string",
  "deadline": "string",
  "completionDate": "string",
  "completedBy": {},
  "expirationNotificationDate": "string",
  "reminderNotificationDate": "string",
  "escalationNotificationDate": "string",
  "etlJobId": "string",
  "systemMessages": {
    "info": [
      {}
    ],
    "errors": [
      {}
    ]
  },
  "totalTargets": 0,
  "totalItems": 0,
  "totalItemsComplete": 0,
  "percentItemsComplete": 0
}

/iga/governance/certification/admin/certification/{certId}/cancel

POST

Cancel a certification campaign.

Cancels a certification campaign at the requested ID in the path. This only cancels existing in-progress action items. It will not revert any decisions that have been signed off and acted on.

Parameters
Name Description

certId string * required

ID of the certification campaign
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "certificationType": "identity",
    "ownerId": "string",
    "schedule": {
      "id": "string",
      "type": "simple",
      "startTime": "string",
      "endTime": "string",
      "repeatCount": 0,
      "repeatInterval": 0,
      "schedule": "string",
      "invokeContext": {},
      "enabled": true
    },
    "targetFilter": {
      "user": {
        "operator": "EQUALS",
        "operand": {
          "targetName": "accountStatus",
          "targetValue": "active"
        }
      },
      "application": {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "name",
          "targetValue": "SalesForce"
        }
      },
      "type": [
        "accountGrant"
      ],
      "memberOfOrg": [
        "52cf01b4-288e-4c21-aed6-f992be073988"
      ]
    },
    "stages": [
      {
        "name": "string",
        "certifierType": "user",
        "certifierId": "string"
      }
    ],
    "stageDuration": 0,
    "expirationAction": "certify",
    "expirationActionDelay": "string",
    "expirationReassignee": "string",
    "stagingEnabled": true,
    "defaultCertifierId": "string",
    "allowBulkCertify": true,
    "allowPartialSignoff": true,
    "remediationRule": "string",
    "remediationDelay": 0,
    "exceptionDuration": 0,
    "enableForward": true,
    "enableReassign": true,
    "reassignPermissions": {
      "certify": true,
      "comment": true,
      "exception": true,
      "forward": true,
      "reassign": true,
      "reset": true,
      "revoke": true,
      "signoff": true
    },
    "selfCertificationRule": "all",
    "assignmentNotification": "string",
    "reassignNotification": "string",
    "expirationNotification": "string",
    "expirationNotificationDay": "string",
    "reminderNotification": "string",
    "reminderFrequency": 0,
    "escalationNotification": "string",
    "escalationFrequency": 0,
    "escalationOwner": "string",
    "excludeConditionalAccess": true,
    "excludeRoleBasedAccess": true,
    "includeChildOrganizations": true,
    "parameters": [
      {
        "id": "string",
        "displayName": "string",
        "path": "string"
      }
    ],
    "templateEventType": "user",
    "status": "active",
    "scheduleId": "string",
    "ownerInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "defaultCertifierInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "escalationOwnerInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string"
    },
    "expirationReassigneeInfo": {
      "id": "string",
      "userName": "string",
      "mail": "string",
      "givenName": "string",
      "sn": "string",
      "name": "string"
    },
    "templateId": "string",
    "startDate": "string",
    "deadline": "string",
    "completionDate": "string",
    "completedBy": {},
    "expirationNotificationDate": "string",
    "reminderNotificationDate": "string",
    "escalationNotificationDate": "string",
    "etlJobId": "string",
    "systemMessages": {
      "info": [
        {}
      ],
      "errors": [
        {}
      ]
    }
  }
]

/iga/governance/certification/certification/items

GET

Query the review items (tasks) that are assigned to you.

Returns the certification tasks that are currently assigned to the logged in end user.

Parameters
Name Description

status * required

Status of the certification campaign. The available values are active, expired, and complete
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

{
  "results": [
    {
      "status": "in-progress",
      "campaignId": "19cf170e-5dd8-4159-a467-c4f018f1a0c8",
      "certifierId": "managed/user/f7089551-b8c6-402f-a4f7-5f8f0724ff30",
      "startDate": "2024-11-19T17:52:30+00:00",
      "deadline": "2024-12-03T17:52:30+00:00",
      "campaignName": "Quarterly Review",
      "totals": {
        "in-progress": 53,
        "total": 53
      },
      "progress": 0,
      "certifier": {
        "givenName": "Bernice",
        "id": "f7089551-b8c6-402f-a4f7-5f8f0724ff30",
        "mail": "Bernice@IGATestQA.onmicrosoft.com",
        "sn": "Hablot",
        "userName": "Bernice@IGATestQA.onmicrosoft.com",
        "type": "user",
        "key": "managed/user/f7089551-b8c6-402f-a4f7-5f8f0724ff30"
      }
    }
  ],
  "totalCount": 0
}

/iga/governance/certification/certification/{certId}/items

GET

Query line items of the certification campaign instance.

Returns the certification line items that belong to this campaign, filtered by parameters. Certifier sign-off is indicated by status. The certifier’s decision is indicated by decision.

Parameters
Name Description

certId string * required

ID of the certification campaign.

targetId string

ID of the target line item.

_pageSize string

Number of response result to return.

_pageNumber string

Number of response result to return.

_searchAfter string

An alternative to pageNumber, corresponds to the searchAfterKey value sent in previous page’s results.

status string

Status of the line item.The available values are in-progress, signed-off, pending, cancelled, and expired.

decision string

Decision taken on the line item. The available values are certify, revoke, exception, and abstain.

ownerId string

Owner ID of the line item.

user string

ID of the user the line items are certifying.

resource string

ID of the resource the line items are certifying.

application string

ID of the application the line items(s) are certifying.

actorId string

ID of any actor (certifier) in the line items actor list.

primaryReviwerId string

ID of the primary reviewer or certifier of the line items.

user.userName string

Username of the user the line items are certifying.

itemType string

Item type of the line item. The available values are Account Grant and Resource Grant.

account string

ID of the account the line items(s) are certifying.

groupBy string

Aggregates the results to allow the frontend to group line items.

appendUserPermissions boolean

Appends the logged in user permissions for each line item. Used by frontend.

taskStatus string

Task level alternative to status (which is item level). The available values are active, complete, closed, cancelled, and expired.

getCount boolean

If true, returns the line item count based on the query.

isAdmin boolean

If true and if the user has permission, returns the results as an admin.
Responses
Code Description

200

OK

400

Invalid request

404

ID or value sent in parameters wasn’t found

500

Server error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "decision": {
        "certification": {
          "campaignId": "string",
          "targetId": "string",
          "status": "in-progress",
          "decision": "certify",
          "completionDate": "string",
          "completedBy": {},
          "decisionDate": "string",
          "decisionBy": {},
          "remediationDate": "string",
          "remediated": true,
          "remediationStatus": "pending",
          "confidenceScore": 0,
          "stageIndex": 0,
          "deadline": "string",
          "isExpired": true,
          "comments": [
            {
              "user": {
                "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                "userName": "asmith",
                "mail": "asmith01@forgerock.com",
                "givenName": "Aaron",
                "sn": "Smith"
              },
              "comment": "I need to find out more information before approving.  Will check back later.",
              "action": "comment",
              "timeStamp": "2023-09-11T12:00:00+00:00",
              "phase": "ManagerApproval"
            }
          ],
          "actors": [
            {
              "id": "string",
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true,
                "certify": true,
                "exception": true,
                "forward": true,
                "reset": true,
                "revoke": true,
                "signoff": true
              },
              "userName": "string",
              "mail": "string",
              "givenName": "string",
              "sn": "string",
              "name": "string"
            }
          ]
        }
      }
    }
  ],
  "resultCount": 0,
  "totalHits": 0,
  "searchAfterKey": [
    "string"
  ]
}

/iga/governance/certification/certification/{certId}/items/search

POST

Query line items of the certification campaign instance.

Returns the certification line items that belong to the specified campaign, filtered by parameters.

Parameters
Name Description

certId string * required

ID of the certification campaign

_fields string

The list of fields to return for each entry in the response result. Comma-separated for multiple values

_pageSize integer

Number of response result objects to return

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

appendUserPermissions boolean

Appends the logged in user permissions for each line item.

taskStatus string

Task level status search. The available values are active, complete, closed, cancelled, and expired.
Request body example

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "decision.certification.primaryReviewer.id",
          "targetValue": "managed/user/c1147059-b6ab-4cf6-937c-b93202c6cec8"
        }
      },
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "item.type",
           "targetValue": "accountGrant"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Invalid request

404

ID or value sent in parameters wasn’t found

500

Server error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "decision": {
        "certification": {
          "campaignId": "string",
          "targetId": "string",
          "status": "in-progress",
          "decision": "certify",
          "completionDate": "string",
          "completedBy": {},
          "decisionDate": "string",
          "decisionBy": {},
          "remediationDate": "string",
          "remediated": true,
          "remediationStatus": "pending",
          "confidenceScore": 0,
          "stageIndex": 0,
          "deadline": "string",
          "isExpired": true,
          "comments": [
            {
              "user": {
                "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                "userName": "asmith",
                "mail": "asmith01@forgerock.com",
                "givenName": "Aaron",
                "sn": "Smith"
              },
              "comment": "I need to find out more information before approving.  Will check back later.",
              "action": "comment",
              "timeStamp": "2023-09-11T12:00:00+00:00",
              "phase": "ManagerApproval"
            }
          ],
          "actors": [
            {
              "id": "string",
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true,
                "certify": true,
                "exception": true,
                "forward": true,
                "reset": true,
                "revoke": true,
                "signoff": true
              },
              "userName": "string",
              "mail": "string",
              "givenName": "string",
              "sn": "string",
              "name": "string"
            }
          ]
        }
      }
    }
  ],
  "resultCount": 0,
  "totalCount": 0,
  "searchAfterKey": [
    "string"
  ]
}

/iga/governance/certification/certification/{certId}/items/{action}

POST

Take action on line items.

Parameters
Name Description

certId string * required

ID of the certification campaign.

action string * required

The specific action to take. The available values are certify, revoke, exception, comment, forward, and signoff.

selectAllActorId string

When provided, the action targets all decision items the given actor is the primary reviewer for. The IDs array can be left empty.
Request body * required

Media type: application/json

{
  "ids": [
    "e9e4d260-1b55-4331-8468-5824344b8bc3",
    "01d8ccf0-e132-49f1-9c82-c52a6fea0154"
  ]
}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

{
  "message": "string",
  "idsNotActedOn": [
    "string"
  ]
}

/iga/governance/certification/certification/{certId}/items/{lineItemId}/{action}

POST

Take action on a single line item.

Parameters
Name Description

certId string * required

ID of the certification campaign.

lineItemId string * required

ID of the line item.

action string * required

The specific action to take. The available values are certify, revoke, exception, comment, reassign, and forward.
Request body * required

Example: certify
Media type: application/json

{}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

{
  "message": "string",
  "idsNotActedOn": [
    "string"
  ]
}

Access request

In Identity Governance, end users can request access to resources. Resources are target applications, entitlements, or roles. You define which resources are requestable.

Learn more in access requests.

URI HTTP
method		 Description

/iga/governance/requests

POST

Create or validate a new access request for a list of users. When submitting a new request for access, the system validates the request’s contents. If no issues are found, IGA creates a request for each pairing of user and catalog items included in the request.

You can choose to only validate the request by using the validate action. This action displays any errors in the current request payload without creating any requests.

Parameters
Name Description

action string * required

Action to be performed for the requests endpoint. The available values are create and validate.

runPreventativeScan boolean

Check whether the requested access violates any policies.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body example

Media type: application/json

{
  "users": [
    "52cf01b4-288e-4c21-aed6-f992be073988"
  ],
  "catalogs": [
    {
      "type": "application",
      "id": "ea412dc4804ae80e625fdd8f7b7521d9ae3f7cae30f2401cf8f3be43d985176843404f1022c44537edeedc0bf11b5e5a028082cc05a7d90843b882c7c4b5d988",
      "data": {}
    }
  ],
  "startDate": "2023-09-11T12:00:00+00:00",
  "endDate": "2023-12-11T12:00:00+00:00",
  "expiryDate": "2023-09-05T12:00:00+00:00",
  "priority": "low",
  "justification": "I need this access to start working on a new project.",
  "accessModifier": "add",
  "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
  "requestIdPrefix": "REQ"
}
Responses
Code Description

200

Success

400

Request error
Click for an example response

Media type: application/json

{
  "result": [
    "f70b1565-8d42-4492-93dd-90173fa62635"
  ],
  "errors": [
    {
      "error": "DUPLICATE",
      "message": "Duplicate request already exists.",
      "user": "e7c38019-844f-4b70-93d1-9bdbfa00f1da",
      "requestId": "3cd52fdd-9725-411f-bcae-0f5f3254e24d",
      "catalogId": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1"
    }
  ]
}

/iga/governance/requests/{requestTypeId}

POST

Create request for the given request type.

Parameters
Name Description

requestTypeId string * required

ID of the request type.
Request body * required

Payload for creating the request. Properties must match the request type schema definition. Media type: application/json

{
  "id": "string",
  "requester": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "requestType": "applicationGrant",
  "request": {
    "common": {
      "startDate": "2023-09-11T12:00:00+00:00",
      "endDate": "2023-12-11T12:00:00+00:00",
      "justification": "I need this access to start working on a new project.",
      "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
      "isDraft": false,
      "requestIdPrefix": "REQ"
    }
  },
  "application": {
    "authoritative": false,
    "connectorId": "AzureAD",
    "description": "AzureAD application",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
    "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
    "mappingNames": [
      "systemAzureadUser_managedAlpha_user",
      "systemAzureadDirectoryrole_managedAlpha_assignment",
      "systemAzuread__group___managedAlpha_assignment",
      "managedAlpha_user_systemAzureadUser"
    ],
    "metadata": {
      "entityType": "/openidm/managed/application",
      "created": "2023-08-31T21:23:35.809Z"
    },
    "name": "AzureAD",
    "templateName": "azure.ad",
    "templateVersion": "2.0",
    "objectTypes": [
      {
        "name": "__ACCOUNT__"
      },
      {
        "name": "__GROUP__",
        "accountAttribute": "memberOf"
      }
    ]
  },
  "applicationOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entitlementOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "roleOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "user": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "decision": {
    "status": "in-progress",
    "decision": "approved",
    "outcome": "provisioned",
    "startDate": "2023-09-10T12:00:00+00:00",
    "completionDate": "2023-09-10T12:00:00+00:00",
    "comments": [
      {
        "user": {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        },
        "comment": "I need to find out more information before approving.  Will check back later.",
        "action": "comment",
        "timeStamp": "2023-09-11T12:00:00+00:00",
        "phase": "ManagerApproval"
      }
    ],
    "actors": {
      "active": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ],
      "inactive": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ]
    },
    "phases": [
      {
        "phase": {
          "name": "ManagerApproval",
          "type": "request",
          "status": "in-progress",
          "decision": "approve",
          "startDate": "2023-09-10T12:00:00+00:00",
          "events": {
            "assignment": {
              "notification": "requestAssigned"
            },
            "reassign": {
              "notification": "requestReassigned"
            },
            "expiration": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestExpired",
              "action": "reassign",
              "actors": [
                {
                  "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                  "userName": "asmith",
                  "mail": "asmith01@forgerock.com",
                  "givenName": "Aaron",
                  "sn": "Smith",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                },
                {
                  "id": "string",
                  "name": "string",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                }
              ]
            },
            "escalation": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestEscalated",
              "actors": [
                {
                  "id": "875bbc8f-e868-451f-a690-453473205ca1"
                }
              ],
              "frequency": 3
            },
            "reminder": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestReminder",
              "frequency": 3
            }
          },
          "justification": "string",
          "workflowTaskId": "1025",
          "completedBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "completionDate": "2023-09-10T12:00:00+00:00"
        }
      }
    ]
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "id": "string",
  "requester": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "requestType": "applicationGrant",
  "request": {
    "common": {
      "startDate": "2023-09-11T12:00:00+00:00",
      "endDate": "2023-12-11T12:00:00+00:00",
      "justification": "I need this access to start working on a new project.",
      "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
      "isDraft": false,
      "requestIdPrefix": "REQ"
    }
  },
  "application": {
    "authoritative": false,
    "connectorId": "AzureAD",
    "description": "AzureAD application",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
    "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
    "mappingNames": [
      "systemAzureadUser_managedAlpha_user",
      "systemAzureadDirectoryrole_managedAlpha_assignment",
      "systemAzuread__group___managedAlpha_assignment",
      "managedAlpha_user_systemAzureadUser"
    ],
    "metadata": {
      "entityType": "/openidm/managed/application",
      "created": "2023-08-31T21:23:35.809Z"
    },
    "name": "AzureAD",
    "templateName": "azure.ad",
    "templateVersion": "2.0",
    "objectTypes": [
      {
        "name": "__ACCOUNT__"
      },
      {
        "name": "__GROUP__",
        "accountAttribute": "memberOf"
      }
    ]
  },
  "applicationOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entitlementOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "roleOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "user": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "decision": {
    "status": "in-progress",
    "decision": "approved",
    "outcome": "provisioned",
    "startDate": "2023-09-10T12:00:00+00:00",
    "completionDate": "2023-09-10T12:00:00+00:00",
    "comments": [
      {
        "user": {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        },
        "comment": "I need to find out more information before approving.  Will check back later.",
        "action": "comment",
        "timeStamp": "2023-09-11T12:00:00+00:00",
        "phase": "ManagerApproval"
      }
    ],
    "actors": {
      "active": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ],
      "inactive": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ]
    },
    "phases": [
      {
        "phase": {
          "name": "ManagerApproval",
          "type": "request",
          "status": "in-progress",
          "decision": "approve",
          "startDate": "2023-09-10T12:00:00+00:00",
          "events": {
            "assignment": {
              "notification": "requestAssigned"
            },
            "reassign": {
              "notification": "requestReassigned"
            },
            "expiration": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestExpired",
              "action": "reassign",
              "actors": [
                {
                  "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                  "userName": "asmith",
                  "mail": "asmith01@forgerock.com",
                  "givenName": "Aaron",
                  "sn": "Smith",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                },
                {
                  "id": "string",
                  "name": "string",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                }
              ]
            },
            "escalation": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestEscalated",
              "actors": [
                {
                  "id": "875bbc8f-e868-451f-a690-453473205ca1"
                }
              ],
              "frequency": 3
            },
            "reminder": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestReminder",
              "frequency": 3
            }
          },
          "justification": "string",
          "workflowTaskId": "1025",
          "completedBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "completionDate": "2023-09-10T12:00:00+00:00"
        }
      }
    ]
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requests/{requestId}

GET

Retrieve the details of a single access request using a unique identifier, requestId.

Parameters
Name Description

requestId string * required

Unique identifier of the request.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

404

Request can’t be found
Click for an example response

Media type: application/json

{
  "id": "string",
  "requester": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "requestType": "applicationGrant",
  "request": {
    "common": {
      "startDate": "2023-09-11T12:00:00+00:00",
      "endDate": "2023-12-11T12:00:00+00:00",
      "justification": "I need this access to start working on a new project.",
      "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
      "isDraft": false,
      "requestIdPrefix": "REQ"
    }
  },
  "application": {
    "authoritative": false,
    "connectorId": "AzureAD",
    "description": "AzureAD application",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
    "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
    "mappingNames": [
      "systemAzureadUser_managedAlpha_user",
      "systemAzureadDirectoryrole_managedAlpha_assignment",
      "systemAzuread__group___managedAlpha_assignment",
      "managedAlpha_user_systemAzureadUser"
    ],
    "metadata": {
      "entityType": "/openidm/managed/application",
      "created": "2023-08-31T21:23:35.809Z"
    },
    "name": "AzureAD",
    "templateName": "azure.ad",
    "templateVersion": "2.0",
    "objectTypes": [
      {
        "name": "__ACCOUNT__"
      },
      {
        "name": "__GROUP__",
        "accountAttribute": "memberOf"
      }
    ]
  },
  "applicationOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entitlementOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "roleOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "user": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "decision": {
    "status": "in-progress",
    "decision": "approved",
    "outcome": "provisioned",
    "startDate": "2023-09-10T12:00:00+00:00",
    "completionDate": "2023-09-10T12:00:00+00:00",
    "comments": [
      {
        "user": {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        },
        "comment": "I need to find out more information before approving.  Will check back later.",
        "action": "comment",
        "timeStamp": "2023-09-11T12:00:00+00:00",
        "phase": "ManagerApproval"
      }
    ],
    "actors": {
      "active": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ],
      "inactive": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ]
    },
    "phases": [
      {
        "phase": {
          "name": "ManagerApproval",
          "type": "request",
          "status": "in-progress",
          "decision": "approve",
          "startDate": "2023-09-10T12:00:00+00:00",
          "events": {
            "assignment": {
              "notification": "requestAssigned"
            },
            "reassign": {
              "notification": "requestReassigned"
            },
            "expiration": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestExpired",
              "action": "reassign",
              "actors": [
                {
                  "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                  "userName": "asmith",
                  "mail": "asmith01@forgerock.com",
                  "givenName": "Aaron",
                  "sn": "Smith",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                },
                {
                  "id": "string",
                  "name": "string",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                }
              ]
            },
            "escalation": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestEscalated",
              "actors": [
                {
                  "id": "875bbc8f-e868-451f-a690-453473205ca1"
                }
              ],
              "frequency": 3
            },
            "reminder": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestReminder",
              "frequency": 3
            }
          },
          "justification": "string",
          "workflowTaskId": "1025",
          "completedBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "completionDate": "2023-09-10T12:00:00+00:00"
        }
      }
    ]
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requests/{requestId}

PUT

Replace the content of a request. The only properties that can be changed are properties that are defined in the request schema and not in the nonModifiableProperties.

Parameters
Name Description

requestId string * required

Unique identifier of the request.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

The payload for replacing request content. Properties must match the request type schema definition of this request. Media type: application/json

{
  "id": "string",
  "requester": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "requestType": "applicationGrant",
  "request": {
    "common": {
      "startDate": "2023-09-11T12:00:00+00:00",
      "endDate": "2023-12-11T12:00:00+00:00",
      "justification": "I need this access to start working on a new project.",
      "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
      "isDraft": false,
      "requestIdPrefix": "REQ"
    }
  },
  "application": {
    "authoritative": false,
    "connectorId": "AzureAD",
    "description": "AzureAD application",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
    "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
    "mappingNames": [
      "systemAzureadUser_managedAlpha_user",
      "systemAzureadDirectoryrole_managedAlpha_assignment",
      "systemAzuread__group___managedAlpha_assignment",
      "managedAlpha_user_systemAzureadUser"
    ],
    "metadata": {
      "entityType": "/openidm/managed/application",
      "created": "2023-08-31T21:23:35.809Z"
    },
    "name": "AzureAD",
    "templateName": "azure.ad",
    "templateVersion": "2.0",
    "objectTypes": [
      {
        "name": "__ACCOUNT__"
      },
      {
        "name": "__GROUP__",
        "accountAttribute": "memberOf"
      }
    ]
  },
  "applicationOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entitlementOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "roleOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "user": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "decision": {
    "status": "in-progress",
    "decision": "approved",
    "outcome": "provisioned",
    "startDate": "2023-09-10T12:00:00+00:00",
    "completionDate": "2023-09-10T12:00:00+00:00",
    "comments": [
      {
        "user": {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        },
        "comment": "I need to find out more information before approving.  Will check back later.",
        "action": "comment",
        "timeStamp": "2023-09-11T12:00:00+00:00",
        "phase": "ManagerApproval"
      }
    ],
    "actors": {
      "active": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ],
      "inactive": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ]
    },
    "phases": [
      {
        "phase": {
          "name": "ManagerApproval",
          "type": "request",
          "status": "in-progress",
          "decision": "approve",
          "startDate": "2023-09-10T12:00:00+00:00",
          "events": {
            "assignment": {
              "notification": "requestAssigned"
            },
            "reassign": {
              "notification": "requestReassigned"
            },
            "expiration": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestExpired",
              "action": "reassign",
              "actors": [
                {
                  "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                  "userName": "asmith",
                  "mail": "asmith01@forgerock.com",
                  "givenName": "Aaron",
                  "sn": "Smith",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                },
                {
                  "id": "string",
                  "name": "string",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                }
              ]
            },
            "escalation": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestEscalated",
              "actors": [
                {
                  "id": "875bbc8f-e868-451f-a690-453473205ca1"
                }
              ],
              "frequency": 3
            },
            "reminder": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestReminder",
              "frequency": 3
            }
          },
          "justification": "string",
          "workflowTaskId": "1025",
          "completedBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "completionDate": "2023-09-10T12:00:00+00:00"
        }
      }
    ]
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "id": "string",
  "requester": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "requestType": "applicationGrant",
  "request": {
    "common": {
      "startDate": "2023-09-11T12:00:00+00:00",
      "endDate": "2023-12-11T12:00:00+00:00",
      "justification": "I need this access to start working on a new project.",
      "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
      "isDraft": false,
      "requestIdPrefix": "REQ"
    }
  },
  "application": {
    "authoritative": false,
    "connectorId": "AzureAD",
    "description": "AzureAD application",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
    "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
    "mappingNames": [
      "systemAzureadUser_managedAlpha_user",
      "systemAzureadDirectoryrole_managedAlpha_assignment",
      "systemAzuread__group___managedAlpha_assignment",
      "managedAlpha_user_systemAzureadUser"
    ],
    "metadata": {
      "entityType": "/openidm/managed/application",
      "created": "2023-08-31T21:23:35.809Z"
    },
    "name": "AzureAD",
    "templateName": "azure.ad",
    "templateVersion": "2.0",
    "objectTypes": [
      {
        "name": "__ACCOUNT__"
      },
      {
        "name": "__GROUP__",
        "accountAttribute": "memberOf"
      }
    ]
  },
  "applicationOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entitlementOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "roleOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "user": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "decision": {
    "status": "in-progress",
    "decision": "approved",
    "outcome": "provisioned",
    "startDate": "2023-09-10T12:00:00+00:00",
    "completionDate": "2023-09-10T12:00:00+00:00",
    "comments": [
      {
        "user": {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        },
        "comment": "I need to find out more information before approving.  Will check back later.",
        "action": "comment",
        "timeStamp": "2023-09-11T12:00:00+00:00",
        "phase": "ManagerApproval"
      }
    ],
    "actors": {
      "active": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ],
      "inactive": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ]
    },
    "phases": [
      {
        "phase": {
          "name": "ManagerApproval",
          "type": "request",
          "status": "in-progress",
          "decision": "approve",
          "startDate": "2023-09-10T12:00:00+00:00",
          "events": {
            "assignment": {
              "notification": "requestAssigned"
            },
            "reassign": {
              "notification": "requestReassigned"
            },
            "expiration": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestExpired",
              "action": "reassign",
              "actors": [
                {
                  "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                  "userName": "asmith",
                  "mail": "asmith01@forgerock.com",
                  "givenName": "Aaron",
                  "sn": "Smith",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                },
                {
                  "id": "string",
                  "name": "string",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                }
              ]
            },
            "escalation": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestEscalated",
              "actors": [
                {
                  "id": "875bbc8f-e868-451f-a690-453473205ca1"
                }
              ],
              "frequency": 3
            },
            "reminder": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestReminder",
              "frequency": 3
            }
          },
          "justification": "string",
          "workflowTaskId": "1025",
          "completedBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "completionDate": "2023-09-10T12:00:00+00:00"
        }
      }
    ]
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requests/{requestId}

PATCH

Update the contents of a request. The only properties that can be updated are properties that are defined in the request schema and not in the nonModifiableProperties.

Parameters
Name Description

requestId string * required

Unique identifier of the request.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Payload for updating the request. Media type: application/json

[
  {
    "operation": "add",
    "field": "/type",
    "value": "string"
  }
]
Responses
Code Description

200

OK
Click for an example

Media type: application/json

{
  "id": "string",
  "requester": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "requestType": "applicationGrant",
  "request": {
    "common": {
      "startDate": "2023-09-11T12:00:00+00:00",
      "endDate": "2023-12-11T12:00:00+00:00",
      "justification": "I need this access to start working on a new project.",
      "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
      "isDraft": false,
      "requestIdPrefix": "REQ"
    }
  },
  "application": {
    "authoritative": false,
    "connectorId": "AzureAD",
    "description": "AzureAD application",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
    "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
    "mappingNames": [
      "systemAzureadUser_managedAlpha_user",
      "systemAzureadDirectoryrole_managedAlpha_assignment",
      "systemAzuread__group___managedAlpha_assignment",
      "managedAlpha_user_systemAzureadUser"
    ],
    "metadata": {
      "entityType": "/openidm/managed/application",
      "created": "2023-08-31T21:23:35.809Z"
    },
    "name": "AzureAD",
    "templateName": "azure.ad",
    "templateVersion": "2.0",
    "objectTypes": [
      {
        "name": "__ACCOUNT__"
      },
      {
        "name": "__GROUP__",
        "accountAttribute": "memberOf"
      }
    ]
  },
  "applicationOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entitlementOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "roleOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "user": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "decision": {
    "status": "in-progress",
    "decision": "approved",
    "outcome": "provisioned",
    "startDate": "2023-09-10T12:00:00+00:00",
    "completionDate": "2023-09-10T12:00:00+00:00",
    "comments": [
      {
        "user": {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        },
        "comment": "I need to find out more information before approving.  Will check back later.",
        "action": "comment",
        "timeStamp": "2023-09-11T12:00:00+00:00",
        "phase": "ManagerApproval"
      }
    ],
    "actors": {
      "active": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ],
      "inactive": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        },
        {
          "id": "string",
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          },
          "phase": "ManagerApproval"
        }
      ]
    },
    "phases": [
      {
        "phase": {
          "name": "ManagerApproval",
          "type": "request",
          "status": "in-progress",
          "decision": "approve",
          "startDate": "2023-09-10T12:00:00+00:00",
          "events": {
            "assignment": {
              "notification": "requestAssigned"
            },
            "reassign": {
              "notification": "requestReassigned"
            },
            "expiration": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestExpired",
              "action": "reassign",
              "actors": [
                {
                  "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                  "userName": "asmith",
                  "mail": "asmith01@forgerock.com",
                  "givenName": "Aaron",
                  "sn": "Smith",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                },
                {
                  "id": "string",
                  "name": "string",
                  "permissions": {
                    "approve": true,
                    "comment": true,
                    "modify": true,
                    "reassign": true,
                    "reject": true
                  }
                }
              ]
            },
            "escalation": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestEscalated",
              "actors": [
                {
                  "id": "875bbc8f-e868-451f-a690-453473205ca1"
                }
              ],
              "frequency": 3
            },
            "reminder": {
              "date": "2023-09-04T12:00:00+00:00",
              "notification": "requestReminder",
              "frequency": 3
            }
          },
          "justification": "string",
          "workflowTaskId": "1025",
          "completedBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "completionDate": "2023-09-10T12:00:00+00:00"
        }
      }
    ]
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requests/{requestId}

POST

Perform various actions on a specific request, such as approve, reject, comment, cancel, update, or reassign. Each action could have different payloads depending on the information the caller needs to provide.

Parameters
Name Description

requestId string * required

Unique identifier of the request.

phaseName string

For approval task-specific actions. The name of the task that the action applies to.

_action string * required

Action to be performed on a single request. The available values are cancel, approve, reject, comment, reassign, update, and modify.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Example: modify
Media type: application/json

{
  "common": {
    "priority": "low",
    "justification": "Request justification",
    "roleId": "3030d401-90f2-4219-82ea-4f71b3ed4abc",
    "userId": "f5dcd246-92f6-4e32-a696-7ec3253cec16",
    "externalRequestId": "237",
    "isDraft": false
  }
}
Responses
Code Description

200

OK

400

Invalid action

401

User is not authorized to use this endpoint.

404

Request can’t be found.

/iga/governance/user/{userId}/requests

GET

Get requests for which the authenticated user has permissions to view. For additional search capabilities, use the POST /governance/user/{userId}/requests?_action=search API.

Parameters
Name Description

userId * required

Unique identifier of the user.

_fields string

The list of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "requester": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "requestType": "applicationGrant",
      "request": {
        "common": {
          "startDate": "2023-09-11T12:00:00+00:00",
          "endDate": "2023-12-11T12:00:00+00:00",
          "justification": "I need this access to start working on a new project.",
          "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
          "isDraft": false,
          "requestIdPrefix": "REQ"
        }
      },
      "application": {
        "authoritative": false,
        "connectorId": "AzureAD",
        "description": "AzureAD application",
        "fr": {
          "realm": "alpha"
        },
        "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
        "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
        "mappingNames": [
          "systemAzureadUser_managedAlpha_user",
          "systemAzureadDirectoryrole_managedAlpha_assignment",
          "systemAzuread__group___managedAlpha_assignment",
          "managedAlpha_user_systemAzureadUser"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2023-08-31T21:23:35.809Z"
        },
        "name": "AzureAD",
        "templateName": "azure.ad",
        "templateVersion": "2.0",
        "objectTypes": [
          {
            "name": "__ACCOUNT__"
          },
          {
            "name": "__GROUP__",
            "accountAttribute": "memberOf"
          }
        ]
      },
      "applicationOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "entitlementOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "roleOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "user": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "decision": {
        "status": "in-progress",
        "decision": "approved",
        "outcome": "provisioned",
        "startDate": "2023-09-10T12:00:00+00:00",
        "completionDate": "2023-09-10T12:00:00+00:00",
        "comments": [
          {
            "user": {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith"
            },
            "comment": "I need to find out more information before approving.  Will check back later.",
            "action": "comment",
            "timeStamp": "2023-09-11T12:00:00+00:00",
            "phase": "ManagerApproval"
          }
        ],
        "actors": {
          "active": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ],
          "inactive": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ]
        },
        "phases": [
          {
            "phase": {
              "name": "ManagerApproval",
              "type": "request",
              "status": "in-progress",
              "decision": "approve",
              "startDate": "2023-09-10T12:00:00+00:00",
              "events": {
                "assignment": {
                  "notification": "requestAssigned"
                },
                "reassign": {
                  "notification": "requestReassigned"
                },
                "expiration": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestExpired",
                  "action": "reassign",
                  "actors": [
                    {
                      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                      "userName": "asmith",
                      "mail": "asmith01@forgerock.com",
                      "givenName": "Aaron",
                      "sn": "Smith",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    },
                    {
                      "id": "string",
                      "name": "string",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    }
                  ]
                },
                "escalation": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestEscalated",
                  "actors": [
                    {
                      "id": "875bbc8f-e868-451f-a690-453473205ca1"
                    }
                  ],
                  "frequency": 3
                },
                "reminder": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestReminder",
                  "frequency": 3
                }
              },
              "justification": "string",
              "workflowTaskId": "1025",
              "completedBy": {
                "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                "userName": "asmith",
                "mail": "asmith01@forgerock.com",
                "givenName": "Aaron",
                "sn": "Smith"
              },
              "completionDate": "2023-09-10T12:00:00+00:00"
            }
          }
        ]
      },
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 0,
  "resultCount": 0
}

/iga/governance/user/{userId}/requests

POST

Get requests for which the authenticated user has permissions to view. The targetFilter property in the API payload can be used to filter the requests based on the desired criteria.

Parameters
Name Description

_action * required

Action to be performed on user requests endpoint. The available value is search.

_fields string

The list of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

userId string * required

Unique identifier of the user.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "requester": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "requestType": "applicationGrant",
      "request": {
        "common": {
          "startDate": "2023-09-11T12:00:00+00:00",
          "endDate": "2023-12-11T12:00:00+00:00",
          "justification": "I need this access to start working on a new project.",
          "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
          "isDraft": false,
          "requestIdPrefix": "REQ"
        }
      },
      "application": {
        "authoritative": false,
        "connectorId": "AzureAD",
        "description": "AzureAD application",
        "fr": {
          "realm": "alpha"
        },
        "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
        "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
        "mappingNames": [
          "systemAzureadUser_managedAlpha_user",
          "systemAzureadDirectoryrole_managedAlpha_assignment",
          "systemAzuread__group___managedAlpha_assignment",
          "managedAlpha_user_systemAzureadUser"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2023-08-31T21:23:35.809Z"
        },
        "name": "AzureAD",
        "templateName": "azure.ad",
        "templateVersion": "2.0",
        "objectTypes": [
          {
            "name": "__ACCOUNT__"
          },
          {
            "name": "__GROUP__",
            "accountAttribute": "memberOf"
          }
        ]
      },
      "applicationOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "entitlementOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "roleOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "user": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "decision": {
        "status": "in-progress",
        "decision": "approved",
        "outcome": "provisioned",
        "startDate": "2023-09-10T12:00:00+00:00",
        "completionDate": "2023-09-10T12:00:00+00:00",
        "comments": [
          {
            "user": {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith"
            },
            "comment": "I need to find out more information before approving.  Will check back later.",
            "action": "comment",
            "timeStamp": "2023-09-11T12:00:00+00:00",
            "phase": "ManagerApproval"
          }
        ],
        "actors": {
          "active": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ],
          "inactive": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ]
        },
        "phases": [
          {
            "phase": {
              "name": "ManagerApproval",
              "type": "request",
              "status": "in-progress",
              "decision": "approve",
              "startDate": "2023-09-10T12:00:00+00:00",
              "events": {
                "assignment": {
                  "notification": "requestAssigned"
                },
                "reassign": {
                  "notification": "requestReassigned"
                },
                "expiration": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestExpired",
                  "action": "reassign",
                  "actors": [
                    {
                      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                      "userName": "asmith",
                      "mail": "asmith01@forgerock.com",
                      "givenName": "Aaron",
                      "sn": "Smith",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    },
                    {
                      "id": "string",
                      "name": "string",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    }
                  ]
                },
                "escalation": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestEscalated",
                  "actors": [
                    {
                      "id": "875bbc8f-e868-451f-a690-453473205ca1"
                    }
                  ],
                  "frequency": 3
                },
                "reminder": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestReminder",
                  "frequency": 3
                }
              },
              "justification": "string",
              "workflowTaskId": "1025",
              "completedBy": {
                "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                "userName": "asmith",
                "mail": "asmith01@forgerock.com",
                "givenName": "Aaron",
                "sn": "Smith"
              },
              "completionDate": "2023-09-10T12:00:00+00:00"
            }
          }
        ]
      },
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 0,
  "resultCount": 0
}

/iga/governance/user/{userId}/approvals

POST

Get requests for which the authenticated user is assigned, either directly, through a role, or through a delegate. The targetFilter property in the API payload can be used to filter the requests based on the desired criteria.

Parameters
Name Description

_action * required

Action to be performed on user requests endpoint. The available value is search.

_fields string

The list of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

actorStatus string

Status of the approver to search on, for example, "active", "inactive". Active shows tasks that are currently assigned to the user, while inactive shows tasks that were assigned and have been completed.

userId string * required

Unique identifier of the user.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "requester": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "requestType": "applicationGrant",
      "request": {
        "common": {
          "startDate": "2023-09-11T12:00:00+00:00",
          "endDate": "2023-12-11T12:00:00+00:00",
          "justification": "I need this access to start working on a new project.",
          "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
          "isDraft": false,
          "requestIdPrefix": "REQ"
        }
      },
      "application": {
        "authoritative": false,
        "connectorId": "AzureAD",
        "description": "AzureAD application",
        "fr": {
          "realm": "alpha"
        },
        "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
        "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
        "mappingNames": [
          "systemAzureadUser_managedAlpha_user",
          "systemAzureadDirectoryrole_managedAlpha_assignment",
          "systemAzuread__group___managedAlpha_assignment",
          "managedAlpha_user_systemAzureadUser"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2023-08-31T21:23:35.809Z"
        },
        "name": "AzureAD",
        "templateName": "azure.ad",
        "templateVersion": "2.0",
        "objectTypes": [
          {
            "name": "__ACCOUNT__"
          },
          {
            "name": "__GROUP__",
            "accountAttribute": "memberOf"
          }
        ]
      },
      "applicationOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "entitlementOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "roleOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "user": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "decision": {
        "status": "in-progress",
        "decision": "approved",
        "outcome": "provisioned",
        "startDate": "2023-09-10T12:00:00+00:00",
        "completionDate": "2023-09-10T12:00:00+00:00",
        "comments": [
          {
            "user": {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith"
            },
            "comment": "I need to find out more information before approving.  Will check back later.",
            "action": "comment",
            "timeStamp": "2023-09-11T12:00:00+00:00",
            "phase": "ManagerApproval"
          }
        ],
        "actors": {
          "active": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ],
          "inactive": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ]
        },
        "phases": [
          {
            "phase": {
              "name": "ManagerApproval",
              "type": "request",
              "status": "in-progress",
              "decision": "approve",
              "startDate": "2023-09-10T12:00:00+00:00",
              "events": {
                "assignment": {
                  "notification": "requestAssigned"
                },
                "reassign": {
                  "notification": "requestReassigned"
                },
                "expiration": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestExpired",
                  "action": "reassign",
                  "actors": [
                    {
                      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                      "userName": "asmith",
                      "mail": "asmith01@forgerock.com",
                      "givenName": "Aaron",
                      "sn": "Smith",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    },
                    {
                      "id": "string",
                      "name": "string",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    }
                  ]
                },
                "escalation": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestEscalated",
                  "actors": [
                    {
                      "id": "875bbc8f-e868-451f-a690-453473205ca1"
                    }
                  ],
                  "frequency": 3
                },
                "reminder": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestReminder",
                  "frequency": 3
                }
              },
              "justification": "string",
              "workflowTaskId": "1025",
              "completedBy": {
                "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                "userName": "asmith",
                "mail": "asmith01@forgerock.com",
                "givenName": "Aaron",
                "sn": "Smith"
              },
              "completionDate": "2023-09-10T12:00:00+00:00"
            }
          }
        ]
      },
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      },
      "phases": [
        {
          "name": "string",
          "permissions": {
            "approve": true,
            "comment": true,
            "modify": true,
            "reassign": true,
            "reject": true
          }
        }
      ]
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 0,
  "resultCount": 0
}

Access request form

Identity Governance enables administrators to create custom forms presented to users during request workflows.

URI HTTP
method		 Description

/iga/governance/requestForms

GET

Search request forms.

Parameters
Name Description

_queryFilter string

Search query filter.

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_pageSize integer

Number of response result objects to return.

_sortKeys string

Property on which to sort the results.
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "type": "request",
  "categories": {
    "applicationType": "active.directory",
    "objectType": "__ACCOUNT__",
    "operation": "create"
  },
  "form": {},
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requestForms

POST

Create a request form.

Parameters

No parameters

Request body * required

Media type: application/json

{
  "id": "string",
  "name": "string",
  "type": "request",
  "categories": {
    "applicationType": "active.directory",
    "objectType": "__ACCOUNT__",
    "operation": "create"
  },
  "form": {},
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "type": "request",
  "categories": {
    "applicationType": "active.directory",
    "objectType": "__ACCOUNT__",
    "operation": "create"
  },
  "form": {},
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requestForms/{id}

GET

Get a request form by ID.

Parameters
Name Description

id string * required

ID of the request form.
Responses
Code Description

200

OK

404

Request form not found
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "type": "request",
  "categories": {
    "applicationType": "active.directory",
    "objectType": "__ACCOUNT__",
    "operation": "create"
  },
  "form": {},
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requestForms/{id}

PUT

Replace an existing request form by ID.

Parameters
Name Description

id string * required

ID of the request form.
Request body * required

Media type: application/json

{
  "id": "string",
  "name": "string",
  "type": "request",
  "categories": {
    "applicationType": "active.directory",
    "objectType": "__ACCOUNT__",
    "operation": "create"
  },
  "form": {},
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "type": "request",
  "categories": {
    "applicationType": "active.directory",
    "objectType": "__ACCOUNT__",
    "operation": "create"
  },
  "form": {},
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requestForms/{id}

PATCH

Update an existing request form by ID.

Parameters
Name Description

id string * required

ID of the request form.
Request body * required

Media type: application/json

[
  {
    "operation": "add",
    "field": "/type",
    "value": "string"
  }
]
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "type": "request",
  "categories": {
    "applicationType": "active.directory",
    "objectType": "__ACCOUNT__",
    "operation": "create"
  },
  "form": {},
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/requestFormAssignments

GET

Search the request form assignments.

Parameters
Name Description

_queryFilter string

Search query filter.

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_pageSize integer

Number of response result objects to return.

_sortKeys string

Property on which to sort the results.
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "objectId": "string",
  "formId": "string"
}

/iga/governance/requestFormAssignments

POST

Assign and unassign a request form.

Parameters
Name Description

_action string * required

Action to be taken. The available values are assign and unassign.
Request body * required

Media type: application/json

{
  "objectId": "string",
  "formId": "string"
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "objectId": "string",
  "formId": "string"
}

Access request type

URI HTTP
method		 Description

/iga/governance/requestTypes

GET

Get a list of supported request types.

Parameters
Name Description

_queryFilter string

Search query filter.

_pageSize integer

Number of response result objects to return.

_pageNumber string

Page number of results to show.

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_sortBy string

The property to be sorted by.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "schemas": {
      "custom": [
        {
          "_meta": {
            "type": "string",
            "displayName": "string",
            "properties": {}
          },
          "properties": {}
        }
      ]
    }
  }
]

/iga/governance/requestTypes

POST

Create a new custom request type.

Parameters

No parameters

Request body

Media type: application/json

{
  "id": "string",
  "schemas": {
    "custom": [
      {
        "_meta": {
          "type": "string",
          "displayName": "string",
          "properties": {}
        },
        "properties": {}
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Missing required properties
Click for an example response

Media type: application/json

{
  "id": "string",
  "schemas": {
    "custom": [
      {
        "_meta": {
          "type": "string",
          "displayName": "string",
          "properties": {}
        },
        "properties": {}
      }
    ]
  }
}

/iga/governance/requestTypes/{requestTypeId}

GET

Get a request type by ID.

Parameters
Name Description

requestTypeId string * required

ID of the request type.
Responses
Code Description

200

OK

400

Request type ID not found
Click for an example response

Media type: application/json

{
  "id": "string",
  "schemas": {
    "custom": [
      {
        "_meta": {
          "type": "string",
          "displayName": "string",
          "properties": {}
        },
        "properties": {}
      }
    ]
  }
}

/iga/governance/requestTypes/{requestTypeId}

PUT

Replace an existing request type.

Parameters
Name Description

requestTypeId string * required

ID of the request type.
Request body

Media type: application/json

{
  "id": "string",
  "schemas": {
    "custom": [
      {
        "_meta": {
          "type": "string",
          "displayName": "string",
          "properties": {}
        },
        "properties": {}
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Missing required properties
Click for an example response

Media type: application/json

{
  "id": "string",
  "schemas": {
    "custom": [
      {
        "_meta": {
          "type": "string",
          "displayName": "string",
          "properties": {}
        },
        "properties": {}
      }
    ]
  }
}

/iga/governance/requestTypes/{requestTypeId}

PATCH

Update an existing request type.

Parameters
Name Description

requestTypeId string * required

ID of the request type.
Request body

Media type: application/json

[
  {
    "operation": "add",
    "field": "/type",
    "value": "string"
  }
]
Responses
Code Description

200

OK

400

Missing required properties
Click for an example response

Media type: application/json

{
  "id": "string",
  "schemas": {
    "custom": [
      {
        "_meta": {
          "type": "string",
          "displayName": "string",
          "properties": {}
        },
        "properties": {}
      }
    ]
  }
}

/iga/governance/requestTypes/{requestTypeId}

DELETE

Delete a request type.

Parameters
Name Description

requestTypeId string * required

ID of the request type.
Responses
Code Description

200

OK

404

Request type ID not found

Account

Accounts are user profiles in applications. For example, when you provision an end user to an application, an account is created for them.

URI HTTP
method		 Description

/iga/governance/account

GET

Retrieve all account objects across all applications that have been onboarded as part of any application.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to continue searching. Comma-separated for multiple values.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Responses
Code Description

200

OK

400

Request error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "system/TargetADApp/User/8df77c8b-dac0-4cc5-9f38-b4a467983609",
      "keys": {
        "type": "accountGrant",
        "userId": "041ae68e-c54d-43ae-957d-5bda01d6f259",
        "applicationId": "a87e3d1f-1f9e-4597-bb0a-2ed56d2484a3",
        "accountId": "system/TargetADApp/User/6841028f-2cf7-4439-afa2-51cc3fcb0363"
      },
      "account": {
        "state": "PA",
        "status": "3",
        "isManager": "no",
        "depName": "Human Resources",
        "__UID__": "2014",
        "phone": "555-1212",
        "city": "Allentown",
        "jobCode": "2002",
        "address": "1234 Spruce St",
        "__NAME__": "2014",
        "uid": "2014",
        "lastName": "Hart",
        "firstName": "Jeremy",
        "country": "US",
        "depId": "200",
        "email": "jhart@forgerock.com",
        "empType": "1",
        "postalCode": "12345",
        "_id": "2014"
      },
      "user": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "application": {
        "authoritative": false,
        "connectorId": "AzureAD",
        "description": "AzureAD application",
        "fr": {
          "realm": "alpha"
        },
        "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
        "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
        "mappingNames": [
          "systemAzureadUser_managedAlpha_user",
          "systemAzureadDirectoryrole_managedAlpha_assignment",
          "systemAzuread__group___managedAlpha_assignment",
          "managedAlpha_user_systemAzureadUser"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2023-08-31T21:23:35.809Z"
        },
        "name": "AzureAD",
        "templateName": "azure.ad",
        "templateVersion": "2.0",
        "objectTypes": [
          {
            "name": "__ACCOUNT__"
          },
          {
            "name": "__GROUP__",
            "accountAttribute": "memberOf"
          }
        ]
      },
      "applicationOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "descriptor": {
        "idx": {
          "/account": {
            "displayName": "Example Account"
          }
        }
      },
      "glossary": {
        "idx": {
          "/account": {
            "accountType": "normal",
            "accountStatus": "active"
          },
          "/application": {
            "requestable": true,
            "classification": "internal"
          }
        }
      },
      "item": {
        "decision": {
          "campaignId": "string",
          "completedBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "completionDate": "string",
          "decision": "certify",
          "decisionBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "decisionDate": "string"
        }
      },
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 1,
  "resultCount": 1
}

/iga/governance/account

POST

Retrieve all account objects across all applications that have been onboarded as part of any application. Additional filter criteria can be provided to allow searching by application, user, or glossary data.

Parameters
Name Description

_action * required

Action to be performed on user requests endpoint. The available value is search.

_fields string

The list of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to continue searching. Comma-separated for multiple values.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Request error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "system/TargetADApp/User/8df77c8b-dac0-4cc5-9f38-b4a467983609",
      "keys": {
        "type": "accountGrant",
        "userId": "041ae68e-c54d-43ae-957d-5bda01d6f259",
        "applicationId": "a87e3d1f-1f9e-4597-bb0a-2ed56d2484a3",
        "accountId": "system/TargetADApp/User/6841028f-2cf7-4439-afa2-51cc3fcb0363"
      },
      "account": {
        "state": "PA",
        "status": "3",
        "isManager": "no",
        "depName": "Human Resources",
        "__UID__": "2014",
        "phone": "555-1212",
        "city": "Allentown",
        "jobCode": "2002",
        "address": "1234 Spruce St",
        "__NAME__": "2014",
        "uid": "2014",
        "lastName": "Hart",
        "firstName": "Jeremy",
        "country": "US",
        "depId": "200",
        "email": "jhart@forgerock.com",
        "empType": "1",
        "postalCode": "12345",
        "_id": "2014"
      },
      "user": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "application": {
        "authoritative": false,
        "connectorId": "AzureAD",
        "description": "AzureAD application",
        "fr": {
          "realm": "alpha"
        },
        "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
        "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
        "mappingNames": [
          "systemAzureadUser_managedAlpha_user",
          "systemAzureadDirectoryrole_managedAlpha_assignment",
          "systemAzuread__group___managedAlpha_assignment",
          "managedAlpha_user_systemAzureadUser"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2023-08-31T21:23:35.809Z"
        },
        "name": "AzureAD",
        "templateName": "azure.ad",
        "templateVersion": "2.0",
        "objectTypes": [
          {
            "name": "__ACCOUNT__"
          },
          {
            "name": "__GROUP__",
            "accountAttribute": "memberOf"
          }
        ]
      },
      "applicationOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "descriptor": {
        "idx": {
          "/account": {
            "displayName": "Example Account"
          }
        }
      },
      "glossary": {
        "idx": {
          "/account": {
            "accountType": "normal",
            "accountStatus": "active"
          },
          "/application": {
            "requestable": true,
            "classification": "internal"
          }
        }
      },
      "item": {
        "decision": {
          "campaignId": "string",
          "completedBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "completionDate": "string",
          "decision": "certify",
          "decisionBy": {
            "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
            "userName": "asmith",
            "mail": "asmith01@forgerock.com",
            "givenName": "Aaron",
            "sn": "Smith"
          },
          "decisionDate": "string"
        }
      },
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 1,
  "resultCount": 1
}

/iga/governance/account/{accountId}

GET

Retrieve by details of a single account object using its unique identifier.

Parameters
Name Description

accountId string * required

Unique identifier of the account to get.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

404

Request can’t be found.
Click for an example response

Media type: application/json

{
  "id": "system/TargetADApp/User/8df77c8b-dac0-4cc5-9f38-b4a467983609",
  "keys": {
    "type": "accountGrant",
    "userId": "041ae68e-c54d-43ae-957d-5bda01d6f259",
    "applicationId": "a87e3d1f-1f9e-4597-bb0a-2ed56d2484a3",
    "accountId": "system/TargetADApp/User/6841028f-2cf7-4439-afa2-51cc3fcb0363"
  },
  "account": {
    "state": "PA",
    "status": "3",
    "isManager": "no",
    "depName": "Human Resources",
    "__UID__": "2014",
    "phone": "555-1212",
    "city": "Allentown",
    "jobCode": "2002",
    "address": "1234 Spruce St",
    "__NAME__": "2014",
    "uid": "2014",
    "lastName": "Hart",
    "firstName": "Jeremy",
    "country": "US",
    "depId": "200",
    "email": "jhart@forgerock.com",
    "empType": "1",
    "postalCode": "12345",
    "_id": "2014"
  },
  "user": {
    "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
    "userName": "asmith",
    "mail": "asmith01@forgerock.com",
    "givenName": "Aaron",
    "sn": "Smith"
  },
  "application": {
    "authoritative": false,
    "connectorId": "AzureAD",
    "description": "AzureAD application",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
    "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
    "mappingNames": [
      "systemAzureadUser_managedAlpha_user",
      "systemAzureadDirectoryrole_managedAlpha_assignment",
      "systemAzuread__group___managedAlpha_assignment",
      "managedAlpha_user_systemAzureadUser"
    ],
    "metadata": {
      "entityType": "/openidm/managed/application",
      "created": "2023-08-31T21:23:35.809Z"
    },
    "name": "AzureAD",
    "templateName": "azure.ad",
    "templateVersion": "2.0",
    "objectTypes": [
      {
        "name": "__ACCOUNT__"
      },
      {
        "name": "__GROUP__",
        "accountAttribute": "memberOf"
      }
    ]
  },
  "applicationOwner": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "descriptor": {
    "idx": {
      "/account": {
        "displayName": "Example Account"
      }
    }
  },
  "glossary": {
    "idx": {
      "/account": {
        "accountType": "normal",
        "accountStatus": "active"
      },
      "/application": {
        "requestable": true,
        "classification": "internal"
      }
    }
  },
  "item": {
    "decision": {
      "campaignId": "string",
      "completedBy": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "completionDate": "string",
      "decision": "certify",
      "decisionBy": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "decisionDate": "string"
    }
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  }
}

/iga/governance/account/{accountId}/glossary

GET

Retrieve the glossary-specific details of a single account object using its unique identifier.

Parameters
Name Description

accountId string * required

Unique identifier of the account to get.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

404

Request cannot be found.
Click for an example response

Media type: application/json

{
  "accountType": "normal",
  "accountStatus": "active"
}

/iga/governance/account/{accountId}/glossary

POST

Create glossary entry for a single account object using its unique identifier.

Parameters
Name Description

accountId string * required

Unique identifier of the account to get.

_action string * required

Action to be performed on user requests endpoint. The available value is create.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

Success.

400

Request error.
Click for an example response

Media type: application/json

{
  "accountType": "normal",
  "accountStatus": "active"
}

/iga/governance/account/{accountId}/glossary

PUT

Create or update a glossary entry for a single account object using its unique identifier.

Parameters
Name Description

accountId string * required

Unique identifier of the account to get.

_action string * required

Action to be performed on user requests endpoint. The available value is create.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

Success.

400

Request error.
Click for an example response

Media type: application/json

{
  "accountType": "normal",
  "accountStatus": "active"
}

Audit

Endpoints associated with IDM’s audit functionality.

To use the iga/governance/workflow and iga/governance/audit endpoints, your authorization token must have the following scope:

fr:idc:analytics.*

This is a temporary requirement and will be removed in a future release.
URI HTTP
method		 Description

/iga/governance/audit

GET

Get audit reports.

Parameters
Name Description

objectId string

ID of the object to retrieve the report.

startDate

First date to include in the report.

endDate string

Last date to include in the report.

actor string

Actor associated with the audit events.

objectType string

Type of object involved in the audit events.

eventType string

Type of event to filter by.

action string

Type of action to filter by.

pageSize integer

Number of results per page (default is 20).

order string

Order of results. The available values are asc and desc (default is desc).

page integer

Page number for pagination.

searchAfter string

A JSON-encoded array for deep pagination. Example: [1742976841833].
Responses
Code Description

200

OK

400

Bad request

500

Internal service error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "actor": "string",
      "eventType": "string",
      "objectId": "string",
      "objectType": "string",
      "action": "string",
      "timestamp": "2025-04-19T10:54:08.584Z",
      "changes": [
        {
          "after_value": "string",
          "field_name": "string"
        }
      ],
      "metadata": {
        "modifiedDate": "2025-04-19T10:54:08.585Z",
        "createdDate": "2025-04-19T10:54:08.585Z"
      }
    }
  ],
  "resultCount": 0,
  "totalCount": 0,
  "pagination": {
    "page": 0,
    "pageSize": 0,
    "totalPages": 0,
    "searchAfter": [
      0
    ]
  }
}

/iga/governance/user/{userId}/audit

GET

Get the audit reports for a given user.

Parameters
Name Description

userId string * string

ID of the user to retrieve the report.

queryId

Required parameter for pagination. Use the value from previous response.

dataSetId string

Required parameter for pagination. Use the value from previous response.

pagedResultCookie string

Used for pagination of results.
Responses
Code Description

200

OK

400

Error with provided payload

404

Job not found

500

Server error
Click for an example response

endDate string (query) Last date to include in the report

{
  "result": [
    {
      "actor": "string",
      "eventType": "string",
      "objectId": "string",
      "action": "string",
      "timestamp": "string",
      "changes": [
        {
          "after_value": "New City",
          "before_value": "Old City",
          "field_name": "city"
        }
      ]
    }
  ],
  "resultCount": 0,
  "totalCount": 0,
  "queryId": "string",
  "dataSetId": "string",
  "pageToken": "string"
}

Catalog

The Catalog endpoint provides a list of requestable access items. The current supported types of access that are requestable are application, entitlement, and role.

URI HTTP
method		 Description

/iga/governance/catalog

GET

Get a list of items from the Identity Governance access catalog. Each entry represents a single type of requestable access that can be added to a request. The current supported types of access that are requestable are application, entitlement, and role.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to continue searching. Comma-separated for multiple values.

_ignoreRequestable string

For admin use: allow admin to view catalog items not marked as requestable when set to true.

userId string

For admin use: when provided, returns the scoped catalog access that matches the given user ID.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK
Click for an example response

Example: application
Media type: application/json

{
  "id": "26f2bd6b-3d23-4fbb-92f7-9aecd0183852",
  "item": {
    "type": "accountGrant"
  },
  "application": {
    "_rev": "23b2b11e-3ee6-499d-9e66-88ea2a867f98-50136",
    "authoritative": true,
    "connectorId": "AzureADAuth1",
    "description": "AD Auth App1",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://openam-glossary-fix-0608.forgeblocks.com/platform/img/microsoft.8a785075.svg",
    "id": "26f2bd6b-3d23-4fbb-92f7-9aecd0183852",
    "mappingNames": [
      "systemAzureadauth1User_managedAlpha_user"
    ],
    "metadata": {
      "entityType": "/openidm/managed/application",
      "created": "2023-06-09T15:01:49.259Z"
    },
    "name": "AzureADAuth1",
    "templateName": "azure.ad",
    "templateVersion": "2.0"
  },
  "applicationOwner": [
    {
      "_rev": "23b2b11e-3ee6-499d-9e66-88ea2a867f98-1944",
      "accountStatus": "active",
      "cn": "iga admin",
      "fr": {
        "realm": "alpha"
      },
      "givenName": "iga",
      "id": "b409de90-dc24-42ee-b315-7e133c7cfaca",
      "mail": "iga-admin@fr.net",
      "metadata": {
        "entityType": "/openidm/managed/user",
        "created": "2023-06-08T23:02:15.385Z"
      },
      "sn": "admin",
      "userName": "iga-admin"
    }
  ]
}

/iga/governance/catalog

POST

Get a list of items from the Identity Governance access catalog using additional filter criteria. Each entry represents a single type of requestable access that can be added to a request. The current supported types of access that are requestable are application, entitlement, and role.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to continue searching. Comma-separated for multiple values.

_ignoreRequestable string

For admin use: allow admin to view catalog items not marked as requestable when set to true.

userId string

For admin use: when provided, returns the scoped catalog access that matches the given user ID.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "system_TargetADApp2_directoryRole_08ec32b7-b9c5-4d71-bd72-ea7b8584c5a4",
      "item": {
        "type": "entitlementGrant"
      },
      "descriptor": {
        "idx": {
          "/entitlement": {
            "displayName": "Directory Readers"
          }
        }
      },
      "glossary": {
        "idx": {
          "/entitlement": {
            "requestable": true
          }
        }
      },
      "entitlement": {
        "_id": "08ec32b7-b9c5-4d71-bd72-ea7b8584c5a4",
        "description": "Can read basic directory information. Commonly used to grant directory read access to applications and guests.",
        "displayName": "Directory Readers"
      },
      "assignment": {
        "_rev": "23b2b11e-3ee6-499d-9e66-88ea2a867f98-72216",
        "attributes": [
          {
            "name": "__roles__",
            "value": [
              "08ec32b7-b9c5-4d71-bd72-ea7b8584c5a4"
            ]
          }
        ],
        "description": "Can read basic directory information. Commonly used to grant directory read access to applications and guests.",
        "fr": {
          "realm": "alpha"
        },
        "id": "system_TargetADApp2_directoryRole_08ec32b7-b9c5-4d71-bd72-ea7b8584c5a4",
        "mapping": "managedAlpha_user_systemTargetadapp2User",
        "metadata": {
          "entityType": "/openidm/managed/assignment",
          "created": "2023-06-09T22:09:42.877Z"
        },
        "name": "Directory Readers",
        "type": "__ENTITLEMENT__"
      },
      "application": {
        "_rev": "23b2b11e-3ee6-499d-9e66-88ea2a867f98-67718",
        "authoritative": false,
        "connectorId": "TargetADApp2",
        "description": "Target AD App2",
        "fr": {
          "realm": "alpha"
        },
        "icon": "https://openam-glossary-fix-0608.forgeblocks.com/platform/img/microsoft.8a785075.svg",
        "id": "a4e54fcb-9088-4d42-bb4a-138d69b2486e",
        "mappingNames": [
          "systemTargetadapp2User_managedAlpha_user",
          "systemTargetadapp2Directoryrole_managedAlpha_assignment",
          "systemTargetadapp2__group___managedAlpha_assignment",
          "managedAlpha_user_systemTargetadapp2User"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2023-06-09T20:43:57.74Z"
        },
        "name": "TargetADApp2",
        "ssoIdentities": {
          "oidcId": "TargetADApp2"
        },
        "templateName": "azure.ad",
        "templateVersion": "2.0"
      },
      "applicationOwner": [
        {
          "_rev": "23b2b11e-3ee6-499d-9e66-88ea2a867f98-1944",
          "accountStatus": "active",
          "cn": "iga admin",
          "fr": {
            "realm": "alpha"
          },
          "givenName": "iga",
          "id": "b409de90-dc24-42ee-b315-7e133c7cfaca",
          "mail": "iga-admin@fr.net",
          "metadata": {
            "entityType": "/openidm/managed/user",
            "created": "2023-06-08T23:02:15.385Z"
          },
          "sn": "admin",
          "userName": "iga-admin"
        }
      ],
      "metadata": {
        "firstCreated": "2024-01-11T12:00:00+00:00",
        "created": "2024-04-24T12:00:00+00:00"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 1,
  "resultCount": 1
}

/iga/governance/search/schema

GET

Retrieve all currently configured properties eligible to be used for search or sort when searching against the catalog API. Each property includes some additional metadata about the property, such as whether it is multivalued or not and its datatype.

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Responses
Code Description

201

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

{
  "application": [
    {
      "key": "application.description",
      "name": "description",
      "displayName": "Description",
      "description": "Application Description",
      "type": "string",
      "isMultiValue": false
    },
    {
      "key": "application.name",
      "name": "name",
      "displayName": "Name",
      "description": "Application name",
      "type": "string",
      "isMultiValue": false
    }
  ],
  "entitlement": [
    {
      "key": "glossary.idx./entitlement.description",
      "allowedValues": [],
      "isIndexed": true,
      "isMultiValue": false,
      "managedObjectType": null,
      "searchable": true,
      "isInternal": true,
      "displayName": "Description",
      "name": "description",
      "description": "Description of entitlement",
      "objectType": "/openidm/managed/assignment",
      "type": "string"
    },
    {
      "key": "entitlement.displayName",
      "name": "displayName",
      "displayName": "Display Name",
      "description": "",
      "type": "text",
      "isMultiValue": false
    },
    {
      "key": "glossary.idx./entitlement.entitlementOwner",
      "allowedValues": [],
      "isIndexed": true,
      "isMultiValue": false,
      "managedObjectType": "/openidm/managed/user",
      "searchable": true,
      "isInternal": true,
      "displayName": "Entitlement Owner",
      "name": "entitlementOwner",
      "description": "Entitlement Owner of Object",
      "objectType": "/openidm/managed/assignment",
      "type": "managedObject"
    },
    {
      "key": "glossary.idx./entitlement.requestable",
      "allowedValues": [],
      "isIndexed": true,
      "isMultiValue": false,
      "managedObjectType": null,
      "searchable": true,
      "isInternal": true,
      "displayName": "Requestable",
      "name": "requestable",
      "description": "Can the entitlement be requested",
      "objectType": "/openidm/managed/assignment",
      "type": "boolean"
    }
  ],
  "role": [
    {
      "key": "role.applications._ref",
      "name": "applications",
      "displayName": "Applications",
      "description": "Role Applications",
      "type": "managedObject",
      "isMultiValue": true,
      "managedObjectType": "/openidm/managed/alpha_application"
    },
    {
      "key": "role.description",
      "name": "description",
      "displayName": "Description",
      "description": "The role description, used for display purposes.",
      "type": "string",
      "isMultiValue": false
    },
    {
      "key": "role.id",
      "name": "_id",
      "displayName": "Name",
      "description": "Role ID",
      "type": "string",
      "isMultiValue": false
    },
    {
      "key": "role.name",
      "name": "name",
      "displayName": "Name",
      "description": "The role name, used for display purposes.",
      "type": "string",
      "isMultiValue": false
    },
    {
      "key": "glossary.idx./role.requestable",
      "allowedValues": [],
      "isIndexed": true,
      "isMultiValue": false,
      "managedObjectType": null,
      "searchable": true,
      "isInternal": true,
      "displayName": "Requestable",
      "name": "requestable",
      "description": "Can the role be requested",
      "objectType": "/openidm/managed/role",
      "type": "boolean"
    },
    {
      "key": "role.members._ref",
      "name": "members",
      "displayName": "Role Members",
      "description": "Role Members",
      "type": "managedObject",
      "isMultiValue": true,
      "managedObjectType": "/openidm/managed/alpha_user"
    }
  ]
}

/iga/governance/search/schema/{objectType}

GET

Retrieve all currently configured properties eligible to be used for search or sort for a single object when searching against the catalog API. For example, you can use the endpoint to search for all specific entitlement properties. Each property includes some additional metadata about the property, such as whether it is multivalued or not and its datatype.

Parameters
Name Description

objectType string * required

Type of object involved in the audit events. The available values are application, entitlement, and role.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "key": "application.description",
    "name": "description",
    "displayName": "Description",
    "description": "Application Description",
    "type": "string",
    "isMultiValue": false
  },
  {
    "key": "application.name",
    "name": "name",
    "displayName": "Name",
    "description": "Application name",
    "type": "string",
    "isMultiValue": false
  }
]

Config

Identity Governance has overarching configurations, such as requiring a justification when rejecting an access request.

URI HTTP
method		 Description

/commons/config

GET

Reads and returns all Identity Governance configuration properties across all categories.

Only access request-related properties are available. These properties are used to determine the behavior behind functionality. For example, access request features contain configuration on whether justification is required to reject a request or whether a user can approve their own access.

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Responses
Code Description

200

OK

400

IGA configuration settings can’t be read.
Click for an example response

Media type: application/json

{
  "iga_access_request": {
    "requireRequestJustification": true,
    "requireRejectJustification": true,
    "requireApproveJustification": true,
    "preventRequestWithViolation": true,
    "requireRequestJustificationWithViolation": true,
    "defaultApprover": "managed/role/0e3de08d-fb8f-4f7f-91a8-4e65576fcac4",
    "allowSelfApproval": true
  },
  "iga_global": {
    "enableScoping": false
  },
  "iga_autoid_integration": {
    "enableAutoId": true,
    "highScorePercentThreshold": 0,
    "mediumScorePercentThreshold": 0,
    "lowScorePercentThreshold": 0,
    "training_features_filter": [
      "user.managerId"
    ]
  },
  "iga_ui_config": {}
}

/commons/config

PUT

Update all Identity Governance configuration properties across all categories. Only access request-related properties are available.

You must include all current configurations when saving changes, Identity Governance replaces any omitted keys with default values.
Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Request body

Media type: application/json

{
  "iga_access_request": {
    "requireRequestJustification": true,
    "requireRejectJustification": true,
    "requireApproveJustification": true,
    "preventRequestWithViolation": true,
    "requireRequestJustificationWithViolation": true,
    "defaultApprover": "managed/role/0e3de08d-fb8f-4f7f-91a8-4e65576fcac4",
    "allowSelfApproval": true
  },
  "iga_global": {
    "enableScoping": false
  },
  "iga_autoid_integration": {
    "enableAutoId": true,
    "highScorePercentThreshold": 0,
    "mediumScorePercentThreshold": 0,
    "lowScorePercentThreshold": 0,
    "training_features_filter": [
      "user.managerId"
    ]
  },
  "iga_ui_config": {}
}
Responses
Code Description

200

OK

400

Invalid settings or error saving.

401

User is not authorized to use this endpoint.
Click for an example response 
{
  "iga_access_request": {
    "requireRequestJustification": true,
    "requireRejectJustification": true,
    "requireApproveJustification": true,
    "preventRequestWithViolation": true,
    "requireRequestJustificationWithViolation": true,
    "defaultApprover": "managed/role/0e3de08d-fb8f-4f7f-91a8-4e65576fcac4",
    "allowSelfApproval": true
  },
  "iga_global": {
    "enableScoping": false
  },
  "iga_autoid_integration": {
    "enableAutoId": true,
    "highScorePercentThreshold": 0,
    "mediumScorePercentThreshold": 0,
    "lowScorePercentThreshold": 0,
    "training_features_filter": [
      "user.managerId"
    ]
  },
  "iga_ui_config": {}
}

/commons/config/{key}

GET

Get Identity Governance configuration settings for a given category (for example, iga_access_request).

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.

key string * required

 
Responses
Code Description

200

OK

400

IGA configuration settings can’t be read
Click for an example response

Media type: application/json

{
  "requireRequestJustification": true,
  "requireRejectJustification": true,
  "requireApproveJustification": true,
  "preventRequestWithViolation": true,
  "requireRequestJustificationWithViolation": true,
  "defaultApprover": "managed/role/0e3de08d-fb8f-4f7f-91a8-4e65576fcac4",
  "allowSelfApproval": true
}

/commons/config/{key}

PUT

Update Identity Governance configuration settings for a given category (for example, iga_access_request).

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.

key string * required

 
Request body

Example: iga_access_request
Media type: application/json

{
  "requireRequestJustification": true,
  "requireRejectJustification": true,
  "requireApproveJustification": true,
  "preventRequestWithViolation": true,
  "requireRequestJustificationWithViolation": true,
  "defaultApprover": "managed/role/0e3de08d-fb8f-4f7f-91a8-4e65576fcac4",
  "allowSelfApproval": true
}
Responses
Code Description

200

OK

400

Invalid settings or error saving.

401

User is not authorized to use this endpoint
Click for an example response

Media type: application/json

{
  "requireRequestJustification": true,
  "requireRejectJustification": true,
  "requireApproveJustification": true,
  "preventRequestWithViolation": true,
  "requireRequestJustificationWithViolation": true,
  "defaultApprover": "managed/role/0e3de08d-fb8f-4f7f-91a8-4e65576fcac4",
  "allowSelfApproval": true
}

Entitlement

All users can access the query entitlements endpoint, but the results they see are filtered automatically based on their granted authorizations.

For example, administrators can see all entitlements. A user who is an application owner can see all entitlements that belong to their applications but not other applications' entitlements. A user who is the entitlement owner of three entitlements can see the entitlements that they own. A user who has been scoped permissions to view or act on a subset of entitlements can access that subset.

This endpoint also supports all standard pagination and query filtering abilities of other search APIs.

Every entitlement object in Identity Governance now includes an additional property at the item.objectType path. This attribute stores the object type of the entitlement and can be used in searching and filtering options.
URI HTTP
method		 Description

/iga/governance/entitlement

GET

Search for all entitlements provided by the query parameters.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter
Responses
Code Description

200

OK

400

Error with request

500

Server error
Click for an example to query entitlements

Media type: application/json

GET iga/governance/entitlement?_pageSize=10&_queryFilter=true
{
  "result": [
    {
      "application": {
        "authoritative": false,
        "connectorId": "SNOW",
        "description": "Sanjay's SNOW",
        "icon": "",
        "id": "e35d09cd-2b9b-41bc-8246-dc23d4a36502",
        "name": "SNOW",
        "objectTypes": [
          {
            "name": "Role",
            "accountAttribute": "__user_role_ids__"
          },
          {
            "name": "Group",
            "accountAttribute": "__user_group_ids__"
          },
          {
            "name": "Department",
            "accountAttribute": "department"
          },
          {
            "name": "Company",
            "accountAttribute": "company"
          },
          {
            "name": "User"
          },
          {
            "name": "CostCenter",
            "accountAttribute": "costCenter"
          },
          {
            "name": "Location",
            "accountAttribute": "location"
          }
        ],
        "templateName": "servicenow",
        "templateVersion": "3.3"
      },
      "applicationOwner": [
        {
          "id": "75982e79-40dc-4ad2-8b85-abe1ebd2e2b9",
          "userName": "fyork",
          "givenName": "Frank",
          "sn": "York",
          "mail": "fyork@example.com"
        }
      ],
      "descriptor": {
        "idx": {
          "/entitlement": {
            "displayName": "web_analytics_viewer"
          }
        }
      },
      "entitlement": {
        "can_delegate": true,
        "sys_package": "3b5ad2be150022104f3415f71eacd930",
        "grantable": true,
        "sys_name": "web_analytics_viewer",
        "description": "Web Analytics Viewer",
        "sys_scope": "global",
        "__NAME__": "0a7f57c053101010d69cddeeff7b12b7",
        "elevated_privilege": false,
        "_id": "0a7f57c053101010d69cddeeff7b12b7",
        "sys_class_name": "sys_user_role"
      },
      "glossary": {
        "idx": {
          "/application": {
            "num": 0
          }
        }
      },
      "id": "system_SNOW_Role_0a7f57c053101010d69cddeeff7b12b7",
      "item": {
        "type": "entitlementGrant",
        "objectType": "Role",
        "accountAttribute": "__user_role_ids__"
      },
      "metadata": {
        "modifiedDate": "2025-04-23T17:30:52.031Z",
        "createdDate": "2025-03-24T16:35:34.005468359Z"
      },
      "permissions": {
        "modifyEntitlement": true,
        "viewGrants": true
      }
    }
  ],
  "searchAfterKey": [
    "10240914227d6fbbd85000df72f39d812975f30825f1eb4bf847c1a222fc7a96c58baffb7a31fbf0eee6e40ab3add5f73c87d2e7ead7915e06daec7cd2311d18"
  ],
  "totalCount": 400,
  "resultCount": 1
}

An important part of the response is the permissions key. This key provides additional details for each entitlement in the list, indicating the specific permissions the authorized user has been granted. This allows the UI and other API consumers to understand what actions the user is allowed to perform.

/iga/governance/entitlement

POST

Create a new entitlement.

Users can submit a request using the Create Entitlement request type. The request type accepts four properties when submitting a new request, all under the entitlement key payload:

  • applicationID: type string. Displays the application ID to which the entitlement belongs.

  • objectType: type string. Displays the object type of the entitlement (for example, GROUP).

  • object: type object. Displays the contents of the entitlement that follows the object type schema as defined in the application.

  • glossary: type object. Displays the contents of the entitlement’s glossary data, if present.

This endpoint creates the entitlement in the target system, creates the associated entry (if required), and ensures the entitlement is available in Identity Governance.

Parameters
Name Description

_action string * required

Action to be performed on a single request. The available value is create.
Request body

Example: create
Media type: application/json

{
  "applicationId": "7174f301-dc29-4cbe-bf95-a1cba356fc6c",
  "objectType": "__GROUP__",
  "object": {
    "description": "HR Approvers",
    "displayName": "HR Approvers",
    "id": "8989f1f4-1518-49bf-8a45-7a84d3c6b17f",
    "mailEnabled": false,
    "proxyAddresses": [],
    "securityEnabled": true
  },
  "glossary": {
    "requestable": true,
    "entitlementOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
  }
}
Responses
Code Description

200

OK

400

Error with provided payload

404

Entitlement not found

500

Server error
Click for an example to submit a Create entitlement request

Media type: application/json

POST iga/governance/requests/createEntitlement?_action=publish
{
   "common": {
       "justification": "Need to create this new entitlement"
   },
   "entitlement": {
       "objectType": "Role",
       "applicationId": "825c6e15-b860-4be4-bef9-55d28a0cd2de",
       "object": {
           "can_delegate": true,
           "sys_package": "b1c465bee8c2121087debb3e47d14f22",
           "grantable": true,
           "sys_name": "entitlement_lcm_role",
           "description": "Entitlement Demo Role 333",
           "sys_scope": "global",
           "elevated_privilege": false,
           "sys_class_name": "sys_user_role"
       },
       "glossary": {
           "requestable": true,
           "entitlementOwner": "managed/user/8d24a6ff-bd37-4e49-bbb6-52168bf2a69c"
       }
   }
}

By default, the workflow for Create Entitlement is set to the out-of-the-box example workflow, CreateEntitlement. After the workflow’s approval process is completed, it calls the Identity Governance API directly creating the entitlement within a scripted task.

/iga/governance/entitlement/{id}

GET

Return a single entitlement object by ID.

Reading an entitlement specifically by ID returns the full object type scheme under the entitlement key. For normal query use cases, the entitlement key only shows the keys that have actual values persisted. For get entitlement by ID, the response has all object type schema keys present. If no value is stored, the keys display a null value.
Parameters
Name Description

id string * required

ID of the entitlement
Responses
Code Description

200

OK

404

Entitlement not found

500

Server error
Click for an example response

Media type: application/json

{
  "application": {
    "_rev": "ffe3f7ed-1022-425c-845e-210b35f392e8-819546",
    "authoritative": false,
    "connectorId": "TargetApp",
    "description": "Testing 3",
    "fr": {
      "realm": "alpha"
    },
    "icon": "https://img.freepik.com/free-vector/vector-logo-unique-letter-e-colorful-gradient-design-illustration_474888-2292.jpg",
    "id": "825c6e15-b860-4be4-bef9-55d28a0cd2de",
    "name": "TargetApp",
    "objectTypes": [
      {
        "name": "Role",
        "accountAttribute": "__user_role_ids__"
      },
      {
        "name": "Group",
        "accountAttribute": "__user_group_ids__"
      },
      {
        "name": "Department",
        "accountAttribute": "department"
      },
      {
        "name": "Company",
        "accountAttribute": "company"
      },
      {
        "name": "User"
      },
      {
        "name": "CostCenter",
        "accountAttribute": "costCenter"
      },
      {
        "name": "Location",
        "accountAttribute": "location"
      }
    ],
    "templateName": "servicenow",
    "templateVersion": "3.3"
  },
  "applicationOwner": [
    {
      "id": "d09f3dda-bd62-4c73-95fa-b1cb8daa438e",
      "userName": "fyork",
      "givenName": "Frank",
      "sn": "York",
      "mail": "fyork@example.com"
    }
  ],
  "descriptor": {
    "idx": {
      "/entitlement": {
        "displayName": "tracked_file_reader"
      }
    }
  },
  "entitlement": {
    "can_delegate": true,
    "sys_package": "16ccd5fee802121087debb3e47d14fbf",
    "grantable": true,
    "description": "Read role for tracked configuration files",
    "sys_name": "tracked_file_reader",
    "sys_scope": "global",
    "__NAME__": "80b4cd57c3013300daa79624a1d3aea1",
    "elevated_privilege": false,
    "_id": "80b4cd57c3013300daa79624a1d3aea1",
    "sys_class_name": "sys_user_role"
  },
  "entitlementOwner": [
    {
      "id": "bfd816e1-b9fe-4ea9-90f5-45e2e906cdfc",
      "userName": "christian.marnell",
      "givenName": "Christian",
      "sn": "Marnell",
      "mail": "christian.marnell@example.com"
    }
  ],
  "glossary": {
    "idx": {
      "/entitlement": {
        "complianceObjective": "HIPAA",
        "entitlementOwner": "managed/user/bfd816e1-b9fe-4ea9-90f5-45e2e906cdfc",
        "lob": "Finance",
        "requestable": true
      },
      "/application": {
        "requestable": true
      }
    }
  },
  "id": "system_TargetApp_Role_80b4cd57c3013300daa79624a1d3aea1",
  "item": {
    "type": "entitlementGrant",
    "objectType": "Role"
  },
  "permissions": {
    "modifyEntitlement": true,
    "viewGrants": true
  },
  "metadata": {
    "modifiedDate": "2025-01-29T14:33:09.168Z",
    "createdDate": "2025-01-22T18:15:48.763702117Z"
  }
}

/iga/governance/entitlement/{id}

PUT

Modify an existing entitlement.

Users can submit a request using the Modify Entitlement request type. The request type accepts three properties when submitting a new request, all under the entitlement key payload. The endpoint takes the entitlementId for the existing entitlement:

  • object: type object. Displays the contents of the entitlement that follows the object type schema as defined in the application.

  • glossary: type object. Displays the contents of the entitlement’s glossary data, if present.

To modify an entitlement, you must include the full technical and glossary details in the request API call, as the entire object provided is used as the contents.
Parameters
Name Description

id string * required

ID of the entitlement
Request body

Media type: application/json

{
  "object": {
    "description": "HR Approvers",
    "displayName": "HR Approvers",
    "id": "8989f1f4-1518-49bf-8a45-7a84d3c6b17f",
    "mailEnabled": false,
    "proxyAddresses": [],
    "securityEnabled": true
  },
  "glossary": {
    "requestable": true,
    "entitlementOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
  }
}
Responses
Code Description

200

OK

400

Error with provided payload

404

Entitlement not found

500

Server error
Click for an example to submit a Modify entitlement request

Media type: application/json

POST iga/governance/requests/modifyEntitlement?_action=publish
{
   "common": {
       "justification": "Need to modify this entitlement"
   },
   "entitlement": {
       "entitlementId": "system_TargetApp_Role_80b4cd57c3013300daa79624a1d3aea1",
       "object": {
           "can_delegate": true,
           "sys_package": "b1c465bee8c2121087debb3e47d14f22",
           "grantable": true,
           "sys_name": "entitlement_lcm_role",
           "description": "Entitlement Demo Role 333",
           "sys_scope": "global",
           "elevated_privilege": false,
           "sys_class_name": "sys_user_role"
       },
       "glossary": {
           "requestable": true,
           "entitlementOwner": "managed/user/8d24a6ff-bd37-4e49-bbb6-52168bf2a69c"
       }
   }
}

By default, the workflow for the Create Entitlement is set to the out-of-the-box example workflow, CreateEntitlement. After the workflow’s approval process is completed, it calls the Identity Governance modify API directly using the entitlementId, object, and glossary contents in the payload.
Click for an example to modify an entitlement directly

Media type: application/json

PUT iga/governance/entitlement/\{entitlementId}  (example: system_TargetApp_Role_80b4cd57c3013300daa79624a1d3aea1)
{
     "object": {
         "can_delegate": true,
         "sys_package": "b1c465bee8c2121087debb3e47d14f22",
         "grantable": true,
         "sys_name": "entitlement_lcm_role",
         "description": "Entitlement Demo Role 333",
         "sys_scope": "global",
         "elevated_privilege": false,
         "sys_class_name": "sys_user_role"
     },
     "glossary": {
         "requestable": true,
         "entitlementOwner": "managed/user/8d24a6ff-bd37-4e49-bbb6-52168bf2a69c"
     }
}

/iga/governance/entitlement/{id}/grants

GET

Returns the entitlement grants for the given entitlement ID.

Users who have the permissions to do so can view the users who are currently granted a given entitlement. Administrators, application owners, and entitlement owners are granted this privilege implicitly. Additional end users can be scoped to have this permission also.

Parameters
Name Description

id string * required

ID of the entitlement.

_fields string

The list of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter
Responses
Code Description

200

OK

500

Server error
Click for an example to view grants

Media type: application/json

GET iga/governance/entitlement/\{entitlementId}/grants?_pageSize=10&_queryFilter=true
{
   "result": [
       {
           "account": {
               "calendar_integration": "1",
               "user_name": "guillermo.frohich",
               "sys_updated_on": "2025-01-02 21:29:47",
               "__user_group_ids__": [
                   "0a52d3dcd7011200f2d224837e6103f2"
               ],
               "title": "Chief Financial Officer",
               "sys_class_name": "sys_user",
               "notification": "2",
               "sys_updated_by": "developer.program.hop@snc",
               "sys_created_on": "2024-11-30 15:04:03",
               "sys_domain": "global",
               "__NAME__": "62526fa1d701120035ae23c7ce6103c6",
               "vip": false,
               "department": "221f3db5c6112284009f4becd3039cc9",
               "first_name": "Guillermo",
               "sys_created_by": "admin",
               "email": "guillermo.frohlich@example.com",
               "__user_role_ids__": [
                   "cc6f85b5ebc31300a210a2505206fec0",
                   "45af8773d7002200c1ed0fbc5e61037a",
                   "20d2eaa35320330030c3ddeeff7b1213",
                   "ba4509c60a00070400cc0f3a60a0d30a",
                   "a47f56c15310330030c3ddeeff7b1295",
                   "7423767053ef0010763eddeeff7b12c0",
                   "408934d18733320025fbd1a936cb0b88",
                   "d18b9793c0a80a6b00ac0456923a1c0f",
                   "fc32695d73e3a410960c6039faf6a7f1",
                   "b523f1d037001300a213a7f07e41f15b",
                   "8536f54bc713330072b211d4d8c26080",
                   "6d3c40d33b981300ad3cc9bb34efc415",
                   "b3dd3ccec32203003e76741e81d3ae95",
                   "959c82e3535201109ea3ddeeff7b1227",
                   "d8e675e8532323008ef67c2c0fc587f6",
                   "ceb92b8153c833004558ddeeff7b12df",
                   "a731753ee886121087debb3e47d14f00",
                   "260c203a870033000e56d61e36cb0bbc",
                   "20803f15870033000e56d61e36cb0b7d",
                   "64c3259d73e3a410960c6039faf6a7d6",
                   "edd0b83353520110610bddeeff7b12e8",
                   "f98446040f103300402c6b198b767e1e",
                   "3bf8d5b65344130084acddeeff7b122b",
                   "f3feb8a577831010d7159b71a9106123",
                   "80b4cd57c3013300daa79624a1d3aea1",
                   "0956f6390a0a0bc50064623d5d51c556",
                   "14fa2dc39f230200ee6219eb552e7006",
                   "3c4bc8f5534330108e4dddeeff7b12a7",
                   "0d6c490a3b2010108ed00d8044efc40e",
                   "ca27b5e8532323008ef67c2c0fc5879c",
                   "f13ae18b3bc63300c869c2c703efc418",
                   "a5d7367c5b5320104db40a8a3d81c771",
                   "ab250967b31213005e3de13516a8dc26",
                   "71cb2cf2530033004558ddeeff7b126a",
                   "e776c6af531201109ea3ddeeff7b12aa",
                   "553b1f166723220097eeff5557415a6a",
                   "89d4c6040f103300402c6b198b767e3c",
                   "c627309e53722010af64ddeeff7b1232",
                   "282bf1fac6112285017366cb5f867469",
                   "1bc156f3771000101ecaff046910619e",
                   "8a454be00a0a0b8c00de7dae26869165"
               ],
               "locked_out": "false",
               "sys_mod_count": "3",
               "active": "true",
               "last_name": "Frohlich",
               "time_zone": "Europe/London",
               "name": "Guillermo Frohlich",
               "_id": "62526fa1d701120035ae23c7ce6103c6"
           },
           "application": {
               "name": "TargetApp",
               "description": "Testing 3",
               "objectTypes": [
                   {
                       "name": "Role",
                       "accountAttribute": "__user_role_ids__"
                   },
                   {
                       "name": "Group",
                       "accountAttribute": "__user_group_ids__"
                   },
                   {
                       "name": "Department",
                       "accountAttribute": "department"
                   },
                   {
                       "name": "Company",
                       "accountAttribute": "company"
                   },
                   {
                       "name": "User"
                   },
                   {
                       "name": "CostCenter",
                       "accountAttribute": "costCenter"
                   },
                   {
                       "name": "Location",
                       "accountAttribute": "location"
                   }
               ]
           },
           "catalog": {
               "id": "1195eadf8cf40105f2c91976f32834b31bfdb1661e8c8680b7d7f59c27f9978dedd53b8171237ff6d056c79b6e77679ccc1da21ec611b3ac6c6d4ffda5e90827"
           },
           "compositeId": "ae4dc3705eab9887753a2b6027748979d789ffc4b34cb28872613600764c75d74dad6802db54f3841cc7341c9a0c1b7a61eb25cf3d99f4d9b6161ed422330b96",
           "descriptor": {
               "idx": {
                   "/entitlement": {
                       "displayName": "tracked_file_reader"
                   },
                   "/account": {
                       "displayName": "guillermo.frohich"
                   }
               }
           },
           "entitlement": {
               "can_delegate": true,
               "sys_package": "16ccd5fee802121087debb3e47d14fbf",
               "grantable": true,
               "description": "Read role for tracked configuration files",
               "sys_name": "tracked_file_reader",
               "sys_scope": "global",
               "__NAME__": "80b4cd57c3013300daa79624a1d3aea1",
               "elevated_privilege": false,
               "_id": "80b4cd57c3013300daa79624a1d3aea1",
               "sys_class_name": "sys_user_role"
           },
           "glossary": {
               "idx": {
                   "/entitlement": {
                       "complianceObjective": [
                           "HIPAA",
                           "test"
                       ],
                       "entitlementOwner": "managed/user/bfd816e1-b9fe-4ea9-90f5-45e2e906cdfc",
                       "lob": "Finance",
                       "multiUser": "managed/user/95648547-febc-4757-9b31-7b24fe36db24",
                       "requestable": true
                   },
                   "/application": {
                       "requestable": true
                   }
               },
               "types": [
                   {
                       "attrKey": "/assignment",
                       "modified": "2025-02-07T17:58:12.384Z",
                       "type": "entityType/id/realm"
                   },
                   {
                       "attrKey": "/application",
                       "modified": "2025-02-03T22:08:38.874Z",
                       "type": "entityType/id/realm"
                   }
               ]
           },
           "item": {
               "type": "entitlementGrant",
               "objectType": "Role"
           },
           "keys": {
               "type": "entitlementGrant",
               "userId": "ff1d2def-b44e-468f-9079-3b5a2a7dd219",
               "applicationId": "825c6e15-b860-4be4-bef9-55d28a0cd2de",
               "accountId": "system/TargetApp/User/62526fa1d701120035ae23c7ce6103c6",
               "entitlementId": "system/TargetApp/Role/80b4cd57c3013300daa79624a1d3aea1"
           },
           "relationship": {
               "id": "55f1f1d0-fc1f-4d69-a550-e6f354aefb5e-61186",
               "properties": {
                   "grantTypes": [
                       {
                           "id": "55f1f1d0-fc1f-4d69-a550-e6f354aefb5e-61186",
                           "grantType": "recon"
                       }
                   ]
               }
           },
           "user": {
               "_rev": "ffe3f7ed-1022-425c-845e-210b35f392e8-20187",
               "accountStatus": "active",
               "assignedDashboard": [
                   "TargetApp"
               ],
               "cn": "Guillermo Frohlich",
               "fr": {
                   "realm": "alpha"
               },
               "givenName": "Guillermo",
               "id": "ff1d2def-b44e-468f-9079-3b5a2a7dd219",
               "mail": "guillermo.frohlich@example.com",
               "metadata": {
                   "created": "2025-01-22T18:17:03.931Z",
                   "entityType": "/openidm/managed/user",
                   "version": 10
               },
               "scopes": {
                   "view": [
                       {
                           "id": "e8abd5fb-64c2-493d-8415-e7a0e4a35984",
                           "timestamp": "2025-01-28T14:45:52.119497214Z"
                       }
                   ]
               },
               "sn": "Frohlich",
               "userId": "ff1d2def-b44e-468f-9079-3b5a2a7dd219",
               "userName": "guillermo.frohich"
           },
           "metadata": {
               "modifiedDate": "2025-02-08T01:35:24.671Z",
               "createdDate": "2025-01-22T18:16:04.268082497Z"
           }
       }
   ],
   "searchAfterKey": [
       "ae4dc3705eab9887753a2b6027748979d789ffc4b34cb28872613600764c75d74dad6802db54f3841cc7341c9a0c1b7a61eb25cf3d99f4d9b6161ed422330b96"
   ],
   "totalCount": 1,
   "resultCount": 1
}

/iga/governance/entitlement/{id}/grants/glossary

GET

Get an entitlement’s glossary metadata by ID.

Parameters
Name Description

entitlementId string * required

Unique identifier of the entitlement for which to get glossary information.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

404

Request can’t be found
Click for an example response

Media type: application/json

{
  "requestable": true,
  "entitlementOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
}

/iga/governance/entitlement/{id}/grants/glossary

POST

Create a glossary entry for a single entitlement using its unique identifier.

Parameters
Name Description

entitlementId string * required

Unique identifier of the entitlement for which to get glossary information.

__action string *required

Action to be performed for entitlement glossary endpoint. The available value is create.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "requestable": true,
  "entitlementOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
}
Responses
Code Description

200

Success

400

Request error
Click for an example response

Media type: application/json

{
  "requestable": true,
  "entitlementOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
}

/iga/governance/entitlement/{id}/grants/glossary

PUT

Create or update a glossary entry for a single entitlement using its unique identifier.

Parameters
Name Description

entitlementId string * required

Unique identifier of the entitlement to get.

__action string *required

Action to be performed for entitlement glossary endpoint. The available values is create.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "requestable": true,
  "entitlementOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
}
Responses
Code Description

200

Success

400

Request error
Click for an example response

Media type: application/json

{
  "requestable": true,
  "entitlementOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
}

/iga/governance/entitlement/{id}/grants/glossary

DELETE

Delete a glossary entry for a single entitlement using its unique identifier.

Parameters
Name Description

entitlementId string * required

Unique identifier of the entitlement to get.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

Success

400

Request error
Click for an example response

Media type: application/json

{
  "requestable": true,
  "entitlementOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
}

Event

Events are rules defined to detect a change in the IGA system. Each rule has two core parts: a condition for the event and the action taken when that event occurs. For example, a rule might define that whenever someone creates a user in IGA, they should also generate a certification for that user.

URI HTTP
method		 Description

/iga/governance/event

GET

Get and search for a list of event rules defined in IGA. Each entry represents a single event rule defined to detect a change in the system.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc or desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Error with request

500

Server error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "name": "User Creation Event",
      "description": "This event will create an identity certification for a new user upon creation",
      "owners": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "entityType": "user",
      "mutationType": "create",
      "condition": {
        "version": "v2",
        "filter": {
          "and": [
            {
              "equals": {
                "left": "user.after.country",
                "right": {
                  "literal": "USA"
                }
              }
            }
          ]
        }
      },
      "action": {
        "type": "orchestration",
        "template": {
          "id": "8baa49a4-2c22-40e1-a2b9-5cbe4930f8da-46357"
        },
        "name": "IdentityCertificationKickOff",
        "parameters": {}
      },
      "status": "active",
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      },
      "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
    }
  ],
  "resultCount": 0,
  "totalCount": 0,
  "searchAfterKey": [
    "string"
  ]
}

/iga/governance/event

POST

Create a single IGA event rule. A single event rule is defined to detect a change in the system.

Parameters
Name Description

_action string * required

Action to be performed for the event endpoint. The available value is create.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Example: orchestration
Media type: application/json

{
  "name": "User Creation Event",
  "description": "This event will kick off an orchestration for a new user upon creation.",
  "entityType": "user",
  "mutationType": "create",
  "condition": {
    "version": "v2",
    "filter": {
      "and": [
        {
          "equals": {
            "left": "user.after.country",
            "right": {
              "literal": "USA"
            }
          }
        }
      ]
    }
  },
  "action": {
    "type": "orchestration",
    "name": "IdentityCertificationKickOff"
  },
  "status": "active",
  "owners": [
    {
      "id": "managed/user/02612d23-2f7e-4fd0-98f2-3c3d0988df27",
      "mail": "aparsons@frgov.net",
      "givenName": "Alvin",
      "sn": "Parsons",
      "userName": "aparsons"
    }
  ]
}
Responses
Code Description

200

OK

400

Error with provided payload

404

Event not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "User Creation Event",
  "description": "This event will create an identity certification for a new user upon creation",
  "owners": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entityType": "user",
  "mutationType": "create",
  "condition": {
    "version": "v2",
    "filter": {
      "and": [
        {
          "equals": {
            "left": "user.after.country",
            "right": {
              "literal": "USA"
            }
          }
        }
      ]
    }
  },
  "action": {
    "type": "orchestration",
    "template": {
      "id": "8baa49a4-2c22-40e1-a2b9-5cbe4930f8da-46357"
    },
    "name": "IdentityCertificationKickOff",
    "parameters": {}
  },
  "status": "active",
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/event/{id}

GET

Get a single IGA event by ID. The response is a single event rule defined to detect a change in the system.

Parameters
Name Description

id string * required

ID of the event.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Event not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "User Creation Event",
  "description": "This event will create an identity certification for a new user upon creation",
  "owners": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entityType": "user",
  "mutationType": "create",
  "condition": {
    "version": "v2",
    "filter": {
      "and": [
        {
          "equals": {
            "left": "user.after.country",
            "right": {
              "literal": "USA"
            }
          }
        }
      ]
    }
  },
  "action": {
    "type": "orchestration",
    "template": {
      "id": "8baa49a4-2c22-40e1-a2b9-5cbe4930f8da-46357"
    },
    "name": "IdentityCertificationKickOff",
    "parameters": {}
  },
  "status": "active",
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/event/{id}

PUT

Update a single IGA event by ID. This call requires that the entire object be provided and that it replaces the entire existing event definition.

Parameters
Name Description

id string * required

ID of the event.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "name": "User Creation Event",
  "description": "This event will create an identity certification for a new user upon creation",
  "owners": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entityType": "user",
  "mutationType": "create",
  "condition": {
    "version": "v2",
    "filter": {
      "and": [
        {
          "equals": {
            "left": "user.after.country",
            "right": {
              "literal": "USA"
            }
          }
        }
      ]
    }
  },
  "action": {
    "type": "orchestration",
    "template": {
      "id": "8baa49a4-2c22-40e1-a2b9-5cbe4930f8da-46357"
    },
    "name": "IdentityCertificationKickOff",
    "parameters": {}
  },
  "status": "active"
}
Responses
Code Description

200

OK

400

Error with provided payload

404

Event not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "User Creation Event",
  "description": "This event will create an identity certification for a new user upon creation",
  "owners": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entityType": "user",
  "mutationType": "create",
  "condition": {
    "version": "v2",
    "filter": {
      "and": [
        {
          "equals": {
            "left": "user.after.country",
            "right": {
              "literal": "USA"
            }
          }
        }
      ]
    }
  },
  "action": {
    "type": "orchestration",
    "template": {
      "id": "8baa49a4-2c22-40e1-a2b9-5cbe4930f8da-46357"
    },
    "name": "IdentityCertificationKickOff",
    "parameters": {}
  },
  "status": "active",
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/event/{id}

PATCH

Update a single IGA event by ID. This call allows the caller to update specific properties of the event only without providing the entire object.

Parameters
Name Description

id string * required

ID of the event.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Example: patchArray
Media type: application/json

[
  {
    "operation": "replace",
    "field": "/status",
    "value": "active"
  }
]
Responses
Code Description

200

OK

400

Error with provided payload

404

Event not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "User Creation Event",
  "description": "This event will create an identity certification for a new user upon creation",
  "owners": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entityType": "user",
  "mutationType": "create",
  "condition": {
    "version": "v2",
    "filter": {
      "and": [
        {
          "equals": {
            "left": "user.after.country",
            "right": {
              "literal": "USA"
            }
          }
        }
      ]
    }
  },
  "action": {
    "type": "orchestration",
    "template": {
      "id": "8baa49a4-2c22-40e1-a2b9-5cbe4930f8da-46357"
    },
    "name": "IdentityCertificationKickOff",
    "parameters": {}
  },
  "status": "active",
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/event/{id}

DELETE

Delete a single IGA event by ID.

Parameters
Name Description

id string * required

ID of the event.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

404

Event not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "User Creation Event",
  "description": "This event will create an identity certification for a new user upon creation",
  "owners": [
    {
      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
      "userName": "asmith",
      "mail": "asmith01@forgerock.com",
      "givenName": "Aaron",
      "sn": "Smith"
    }
  ],
  "entityType": "user",
  "mutationType": "create",
  "condition": {
    "version": "v2",
    "filter": {
      "and": [
        {
          "equals": {
            "left": "user.after.country",
            "right": {
              "literal": "USA"
            }
          }
        }
      ]
    }
  },
  "action": {
    "type": "orchestration",
    "template": {
      "id": "8baa49a4-2c22-40e1-a2b9-5cbe4930f8da-46357"
    },
    "name": "IdentityCertificationKickOff",
    "parameters": {}
  },
  "status": "active",
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/event/entity

GET

Get the list of available event entities from which you can define a condition.

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

500

Server error
Click for an example response

Media type: application/json

{
  "entities": [
    "user"
  ]
}

/iga/governance/event/entity/{object}

GET

Get the available schema for defining a condition on a given object. For example, user returns the attributes available for defining an event for users in IGA.

Parameters
Name Description

object string * required

Type of object for which to return the schema.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

404

Event rule schema not found

500

Server error
Click for an example response

Media type: application/json

{
  "schema": {
    "user.after.profileImage": {
      "class": "json",
      "type": "string"
    },
    "user.before.description": {
      "class": "json",
      "type": "string"
    },
    "user.before._id": {
      "class": "json",
      "type": "string"
    },
    "user.after.manager": {
      "class": "json",
      "reference": "/openidm/managed/alpha_user",
      "type": "reference"
    },
    "user.before.postalAddress": {
      "class": "json",
      "type": "string"
    },
    "user.after.applications": {
      "class": "json",
      "item": {
        "type": "reference",
        "reference": "/openidm/managed/alpha_application"
      },
      "type": "array"
    },
    "user.before.accountStatus": {
      "class": "json",
      "type": "string"
    },
    "user.before.groups": {
      "class": "json",
      "item": {
        "type": "reference",
        "reference": "/openidm/managed/alpha_group"
      },
      "type": "array"
    },
    "user.before.adminOfOrg": {
      "class": "json",
      "item": {
        "type": "reference",
        "reference": "/openidm/managed/alpha_organization"
      },
      "type": "array"
    },
    "user.after.country": {
      "class": "json",
      "type": "string"
    },
    "user.after.telephoneNumber": {
      "class": "json",
      "type": "string"
    },
    "user.after.reports": {
      "class": "json",
      "item": {
        "type": "reference",
        "reference": "/openidm/managed/alpha_user"
      },
      "type": "array"
    },
    "user.before.frUnindexedMultivalued4": {
      "class": "json",
      "item": {
        "type": "string"
      },
      "type": "array"
    },
    "user.before.ownerOfApp": {
      "class": "json",
      "item": {
        "type": "reference",
        "reference": "/openidm/managed/alpha_application"
      },
      "type": "array"
    },
    "user.before.frUnindexedMultivalued5": {
      "class": "json",
      "item": {
        "type": "string"
      },
      "type": "array"
    },
    "user.before.frUnindexedMultivalued2": {
      "class": "json",
      "item": {
        "type": "string"
      },
      "type": "array"
    },
    "user.after.givenName": {
      "class": "json",
      "type": "string"
    },
    "user.before.frUnindexedMultivalued3": {
      "class": "json",
      "item": {
        "type": "string"
      },
      "type": "array"
    },
    "user.before.manager": {
      "class": "json",
      "reference": "/openidm/managed/alpha_user",
      "type": "reference"
    },
    "user.after.mail": {
      "class": "json",
      "type": "string"
    }
  }
}

Job

You can manually trigger a governance job.

URI HTTP
method		 Description

/iga/governance/jobs/{id}

POST

Manually trigger a governance job by ID.

Parameters
Name Description

id string * required

ID of the scope. The available value is autoIdTraining.

_action string * required

Action to be taken. The available value is trigger.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{}
Responses
Code Description

200

OK

400

Bad request

404

Workflow with ID wasn’t found

500

Internal service error
Click for an example response

Media type: application/json

{
  "message": "string"
}

Provisioning

In the Advanced Identity Cloud admin console, you can add or remove, or provision, resources from end users. You can do the same through REST APIs.

URI HTTP
method		 Description

/iga/governance/user/{userId}/applications

POST

Provision or de-provision applications for an end user.

Parameters
Name Description

userId string * required

Unique identifier of the user.

action string * required

Action to be performed for the requests endpoint. The available values are add and remove.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body example

Media type: application/json

{
  "applicationId": "0c067d47-f07c-46d6-9162-14476d18d87a",
  "startDate": "2023-09-11T12:00:00+00:00",
  "endDate": "2023-12-11T12:00:00+00:00",
  "grantType": "request"
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{}

/iga/governance/user/{userId}/roles

POST

Provision or de-provision roles for an end user.

Parameters
Name Description

userId string * required

Unique identifier of the user.

action string * required

Action to be performed for the requests endpoint. The available values are add and remove.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body example

Media type: application/json

{
  "roleId": "0c067d47-f07c-46d6-9162-14476d18d87a",
  "startDate": "2023-09-11T12:00:00+00:00",
  "endDate": "2023-12-11T12:00:00+00:00",
  "grantType": "request"
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{}

/iga/governance/user/{userId}/entitlements

POST

Provision or de-provision entitlements for an end user.

Parameters
Name Description

userId string * required

Unique identifier of the user.

action string * required

Action to be performed for the requests endpoint. The available values are add and remove.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body example

Media type: application/json

{
  "entitlementId": "0c067d47-f07c-46d6-9162-14476d18d87a",
  "startDate": "2023-09-11T12:00:00+00:00",
  "endDate": "2023-12-11T12:00:00+00:00",
  "grantType": "request"
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{}

Scope

Scope determines which specific users are able to view or interact with particular target objects. Scoping rules comprise of two core parts: a condition for the source object (who or what the scope applies to) and a condition for the target object that can be viewed or acted upon.

URI HTTP
method		 Description

/iga/governance/scope

GET

Get and search for a list of scoping rules defined in IGA. Each entry represents a single scoping rule defined to assign a set of conditions that allows a subset of users visibility on a subset of target objects.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to continue searching. Comma-separated for multiple values.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

Success

400

Error with request

500

Server error
Click for an example response

Media type: application/json

{
  "result": [
    {
      "name": "Contractor Scope",
      "description": "This event will create a scoping rule for users who are contractors",
      "status": "active",
      "sourceCondition": {
        "user": {
          "version": "v2",
          "filter": {
            "and": [
              {
                "equals": {
                  "left": "user.employeeType",
                  "right": {
                    "literal": "contractor"
                  }
                }
              }
            ]
          }
        }
      },
      "targetCondition": {
        "application": {
          "version": "v2",
          "filter": {
            "and": [
              {
                "equals": {
                  "left": "application.templateName",
                  "right": {
                    "literal": "azure.ad"
                  }
                }
              }
            ]
          }
        },
        "role": {
          "version": "v2",
          "filter": {
            "and": [
              {
                "contains": {
                  "search_string_array": [
                    {
                      "literal": "contractor"
                    },
                    {
                      "literal": "temp"
                    }
                  ],
                  "in_string": "role.name"
                }
              }
            ]
          }
        },
        "entitlement": {
          "version": "v2",
          "filter": {
            "and": [
              {
                "equals": {
                  "left": "entitlement.name",
                  "right": {
                    "literal": "Directory Admin"
                  }
                }
              }
            ]
          }
        }
      },
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      },
      "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
    }
  ],
  "resultCount": 0,
  "totalCount": 0,
  "searchAfterKey": [
    "string"
  ]
}

/iga/governance/scope

POST

Create a single scoping rule in IGA. Each scoping rule is defined to assign a set of conditions that allows a subset of users visibility on a subset of target objects. IGA scoping rules consist of two core parts: a condition for the source object (who/what the scope applies to) and a condition for the target object that can be viewed or acted upon.

Parameters
Name Description

_action string * required

Action to be performed on a single request. The available value is create.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "name": "Contractor Scope",
  "description": "This event will create a scoping rule for users who are contractors",
  "status": "active",
  "sourceCondition": {
    "user": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "user.employeeType",
              "right": {
                "literal": "contractor"
              }
            }
          }
        ]
      }
    }
  },
  "targetCondition": {
    "application": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "application.templateName",
              "right": {
                "literal": "azure.ad"
              }
            }
          }
        ]
      }
    },
    "role": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "contains": {
              "search_string_array": [
                {
                  "literal": "contractor"
                },
                {
                  "literal": "temp"
                }
              ],
              "in_string": "role.name"
            }
          }
        ]
      }
    },
    "entitlement": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "entitlement.name",
              "right": {
                "literal": "Directory Admin"
              }
            }
          }
        ]
      }
    }
  }
}
Responses
Code Description

200

OK

400

Error with provided payload

404

Scope not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "Contractor Scope",
  "description": "This event will create a scoping rule for users who are contractors",
  "status": "active",
  "sourceCondition": {
    "user": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "user.employeeType",
              "right": {
                "literal": "contractor"
              }
            }
          }
        ]
      }
    }
  },
  "targetCondition": {
    "application": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "application.templateName",
              "right": {
                "literal": "azure.ad"
              }
            }
          }
        ]
      }
    },
    "role": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "contains": {
              "search_string_array": [
                {
                  "literal": "contractor"
                },
                {
                  "literal": "temp"
                }
              ],
              "in_string": "role.name"
            }
          }
        ]
      }
    },
    "entitlement": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "entitlement.name",
              "right": {
                "literal": "Directory Admin"
              }
            }
          }
        ]
      }
    }
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/scope/{id}

GET

Get a single scoping rule in IGA by ID. Each scoping rule is defined to assign a set of conditions that allows a subset of users visibility on a subset of target objects.

Parameters
Name Description

id string * required

ID of the scope.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Responses
Code Description

200

OK

404

Scope not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "Contractor Scope",
  "description": "This event will create a scoping rule for users who are contractors",
  "status": "active",
  "sourceCondition": {
    "user": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "user.employeeType",
              "right": {
                "literal": "contractor"
              }
            }
          }
        ]
      }
    }
  },
  "targetCondition": {
    "application": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "application.templateName",
              "right": {
                "literal": "azure.ad"
              }
            }
          }
        ]
      }
    },
    "role": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "contains": {
              "search_string_array": [
                {
                  "literal": "contractor"
                },
                {
                  "literal": "temp"
                }
              ],
              "in_string": "role.name"
            }
          }
        ]
      }
    },
    "entitlement": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "entitlement.name",
              "right": {
                "literal": "Directory Admin"
              }
            }
          }
        ]
      }
    }
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/scope/{id}

PUT

Update a single IGA scope by ID. This call expects the entire object to be provided and replaces the entire existing scope definition.

Parameters
Name Description

id string * required

ID of the scope.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Request body

Media type: application/json

{
  "name": "Contractor Scope",
  "description": "This event will create a scoping rule for users who are contractors",
  "status": "active",
  "sourceCondition": {
    "user": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "user.employeeType",
              "right": {
                "literal": "contractor"
              }
            }
          }
        ]
      }
    }
  },
  "targetCondition": {
    "application": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "application.templateName",
              "right": {
                "literal": "azure.ad"
              }
            }
          }
        ]
      }
    },
    "role": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "contains": {
              "search_string_array": [
                {
                  "literal": "contractor"
                },
                {
                  "literal": "temp"
                }
              ],
              "in_string": "role.name"
            }
          }
        ]
      }
    },
    "entitlement": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "entitlement.name",
              "right": {
                "literal": "Directory Admin"
              }
            }
          }
        ]
      }
    }
  }
}
Responses
Code Description

200

OK

404

Error with provided payload

404

Scope not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "Contractor Scope",
  "description": "This event will create a scoping rule for users who are contractors",
  "status": "active",
  "sourceCondition": {
    "user": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "user.employeeType",
              "right": {
                "literal": "contractor"
              }
            }
          }
        ]
      }
    }
  },
  "targetCondition": {
    "application": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "application.templateName",
              "right": {
                "literal": "azure.ad"
              }
            }
          }
        ]
      }
    },
    "role": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "contains": {
              "search_string_array": [
                {
                  "literal": "contractor"
                },
                {
                  "literal": "temp"
                }
              ],
              "in_string": "role.name"
            }
          }
        ]
      }
    },
    "entitlement": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "entitlement.name",
              "right": {
                "literal": "Directory Admin"
              }
            }
          }
        ]
      }
    }
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/scope/{id}

PATCH

Update a single IGA scope by ID. This call allows the caller to update specific properties of the scope only without providing the entire object.

Parameters
Name Description

id string * required

ID of the scope.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Request body

Example: patchArray
Media type: application/json

[
  {
    "operation": "replace",
    "field": "/status",
    "value": "active"
  }
]
Responses
Code Description

200

OK

404

Error with provided payload

404

Scope not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "Contractor Scope",
  "description": "This event will create a scoping rule for users who are contractors",
  "status": "active",
  "sourceCondition": {
    "user": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "user.employeeType",
              "right": {
                "literal": "contractor"
              }
            }
          }
        ]
      }
    }
  },
  "targetCondition": {
    "application": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "application.templateName",
              "right": {
                "literal": "azure.ad"
              }
            }
          }
        ]
      }
    },
    "role": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "contains": {
              "search_string_array": [
                {
                  "literal": "contractor"
                },
                {
                  "literal": "temp"
                }
              ],
              "in_string": "role.name"
            }
          }
        ]
      }
    },
    "entitlement": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "entitlement.name",
              "right": {
                "literal": "Directory Admin"
              }
            }
          }
        ]
      }
    }
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/scope/{id}

DELETE

Delete a single IGA scope by ID.

Parameters
Name Description

id string * required

ID of the scope.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Responses
Code Description

200

OK

404

Scope not found

500

Server error
Click for an example response

Media type: application/json

{
  "name": "Contractor Scope",
  "description": "This event will create a scoping rule for users who are contractors",
  "status": "active",
  "sourceCondition": {
    "user": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "user.employeeType",
              "right": {
                "literal": "contractor"
              }
            }
          }
        ]
      }
    }
  },
  "targetCondition": {
    "application": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "application.templateName",
              "right": {
                "literal": "azure.ad"
              }
            }
          }
        ]
      }
    },
    "role": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "contains": {
              "search_string_array": [
                {
                  "literal": "contractor"
                },
                {
                  "literal": "temp"
                }
              ],
              "in_string": "role.name"
            }
          }
        ]
      }
    },
    "entitlement": {
      "version": "v2",
      "filter": {
        "and": [
          {
            "equals": {
              "left": "entitlement.name",
              "right": {
                "literal": "Directory Admin"
              }
            }
          }
        ]
      }
    }
  },
  "metadata": {
    "createdDate": "2024-01-11T12:00:00+00:00",
    "modifiedDate": "2024-04-24T12:00:00+00:00"
  },
  "id": "100a7fba-fd8b-47ca-bc6e-16fbec3a578d"
}

/iga/governance/scope/entity

GET

Get a list of available entities on which a condition can be defined.

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Responses
Code Description

200

OK

500

Server error
Click for an example response

Media type: application/json

{
  "entities": [
    "user",
    "catalog"
  ]
}

/iga/governance/scope/entity/{object}

GET

Get the available schema for defining a condition on a given object. For example, 'user' returns the attributes available for defining a scope for users in IGA.

Parameters
Name Description

object string * required

Type of object for which to return the schema.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Responses
Code Description

200

OK

404

Scope schema not found

500

Server error
Click for an example response

Media type: application/json

{
  "schema": {
    "user.userName": {
      "class": "json",
      "type": "string"
    },
    "user.description": {
      "class": "json",
      "type": "string"
    },
    "user._id": {
      "class": "json",
      "type": "string"
    },
    "user.givenName": {
      "class": "json",
      "type": "string"
    },
    "user.sn": {
      "class": "json",
      "type": "string"
    }
  }
}

Segregation of Duty

Segregation of Duties (SoD) is an internal control process ensuring no single individual is granted privileges that could lead to a conflict of interest or fraud. Administrators can configure SoD using policies and policy rules that let them identify violations and run actions, such as create an exception, allow or remediate the violation, and others.

You can view the entire API using a YAML file based on the OpenAPI specification.

Adjust the configurations of the file to match your specific details, such as your Advanced Identity Cloud tenant FQDN.
URI HTTP
method		 Description

/iga/governance/policy

GET

Search policies. The endpoint returns policies stored within the Identity Governance store, based on a set of query parameters.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
    "name": "string",
    "description": "string",
    "policyOwner": {
      "id": "string"
    },
    "policyRuleIds": [
      "string"
    ]
  }
]

/iga/governance/policy

POST

Create a new policy object within Identity Governance.

Parameters
Name Description

_action string * required

Action to be taken. The available values are create and duplicate.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "name": "string",
  "description": "string",
  "policyOwner": {
    "id": "string"
  },
  "policyRuleIds": [
    "string"
  ],
  "schedule": {
    "type": "simple",
    "scheduled": true,
    "schedule": "string",
    "repeatInterval": 864000000,
    "repeatCount": -1,
    "startTime": "2023-12-21T22:41:00.000Z",
    "endTime": "2024-01-01T22:41:00.000Z"
  }
}
Responses
Code Description

201

Creation success. Returns the saved policy object.

400

Invalid data provided.

500

Server error on save.
Click for an example response

Media type: application/json

{
  "id": "string",
  "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
  "name": "string",
  "description": "string",
  "policyOwner": {
    "id": "string"
  },
  "policyRuleIds": [
    "string"
  ]
}

/iga/governance/policy/search

POST

Query policy objects using a targeted search filter.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_searchAfter string

Sort property values of the last entry to continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
    "name": "string",
    "description": "string",
    "policyOwner": {
      "id": "string"
    },
    "policyRuleIds": [
      "string"
    ]
  }
]

/iga/governance/policy/{id}

GET

Get policy by ID. The endpoint returns the policy with the provided ID.

Parameters
Name Description

id string * required

ID of the policy.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

404

Policy does not exist

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
  "name": "string",
  "description": "string",
  "policyOwner": {
    "id": "string"
  },
  "policyRuleIds": [
    "string"
  ]
}

/iga/governance/policy/{id}

PUT

Update an existing policy object within Identity Governance.

Parameters
Name Description

id string * required

ID of the event.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "name": "string",
  "description": "string",
  "policyOwner": {
    "id": "string"
  },
  "policyRuleIds": [
    "string"
  ]
}
Responses
Code Description

200

Update success. Returns the saved policy object.

400

Invalid data provided.

404

Policy does not exist.

500

Server error on save.
Click for an example response

Media type: application/json

{
  "id": "string",
  "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
  "name": "string",
  "description": "string",
  "policyOwner": {
    "id": "string"
  },
  "policyRuleIds": [
    "string"
  ]
}

/iga/governance/policy/{id}

DELETE

Delete an existing policy object within Identity Governance.

Parameters
Name Description

id string * required

ID of the policy.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid data provided

404

Policy does not exist

500

Server error on save
Click for an example response

Media type: application/json

{
  "id": "string",
  "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
  "name": "string",
  "description": "string",
  "policyOwner": {
    "id": "string"
  },
  "policyRuleIds": [
    "string"
  ]
}

/iga/governance/policy/{id}/scan

POST

Run a scan on all given rules of a policy and create violations if desired.

Parameters
Name Description

id string * required

ID of the policy.

simulate string

Indicates if this scan is a simulation, true means no violation tasks are created; false or not present creates violations.

waitForCompletion string

Specifies if you should wait for the completion of the scan before returning. true waits; false or not present returns after scan creation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{}
Responses
Code Description

201

Policy scan started

400

Invalid data provided

404

Policy does not exist

500

Server error on save
Click for an example response

Media type: application/json

{
  "id": "string",
  "policy": {
    "id": "string",
    "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
    "name": "string",
    "description": "string",
    "policyOwner": {
      "id": "string"
    },
    "policyRuleIds": [
      "string"
    ]
  },
  "policyRule": {
    "name": "string",
    "description": "string",
    "documentationUrl": "string",
    "policyRuleOwner": {
      "id": "string"
    },
    "violationOwner": {
      "id": "string"
    },
    "active": true,
    "scanTypes": {
      "preventative": true,
      "detective": true
    },
    "maxExceptionDuration": 0,
    "decisionOptions": {
      "allow": true,
      "exception": true,
      "remediate": true
    },
    "remediation": {
      "type": "string",
      "id": "string",
      "schemas": [
        "string"
      ]
    },
    "userFilter": {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    },
    "ruleDefinition": [
      {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      }
    ],
    "workflow": {
      "type": "bpmn",
      "id": "BasicViolationProcess"
    },
    "violationOwnerType": "user",
    "id": "string",
    "ruleDefinitionTags": [
      "targetName=entitlement.displayName&targetValue=IT%20Admin",
      "targetValue=IT%20Admin&targetName=entitlement.displayName"
    ]
  },
  "isSimulation": true,
  "status": "string",
  "startDate": "string",
  "completionDate": "string",
  "scanTarget": "string",
  "results": [
    {}
  ]
}

/iga/governance/policy/{id}/rules

GET

Get policy rules associated with a policy ID.

Parameters
Name Description

id string * required

ID of the policy rule.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid data provided

404

Policy doesn’t exist

500

Server error on save
Click for an example response

Media type: application/json

{
  "result": [
    {
      "name": "string",
      "description": "string",
      "documentationUrl": "string",
      "policyRuleOwner": {
        "id": "string"
      },
      "violationOwner": {
        "id": "string"
      },
      "active": true,
      "scanTypes": {
        "preventative": true,
        "detective": true
      },
      "maxExceptionDuration": 0,
      "decisionOptions": {
        "allow": true,
        "exception": true,
        "remediate": true
      },
      "remediation": {
        "type": "string",
        "id": "string",
        "schemas": [
          "string"
        ]
      },
      "userFilter": {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      },
      "ruleDefinition": [
        {
          "operator": "AND",
          "operand": [
            {
              "operator": "EQUALS",
              "operand": {
                "targetName": "user.userName",
                "targetValue": "ljones"
              }
            },
            {
              "operator": "CONTAINS",
              "operand": {
                "targetName": "application.name",
                "targetValue": "Active Directory"
              }
            }
          ]
        }
      ],
      "workflow": {
        "type": "bpmn",
        "id": "BasicViolationProcess"
      },
      "violationOwnerType": "user",
      "id": "string",
      "ruleDefinitionTags": [
        "targetName=entitlement.displayName&targetValue=IT%20Admin",
        "targetValue=IT%20Admin&targetName=entitlement.displayName"
      ]
    }
  ]
}

/iga/governance/policy/rule

GET

Query policy rules based on a set of query parameters.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "name": "string",
    "description": "string",
    "documentationUrl": "string",
    "policyRuleOwner": {
      "id": "string"
    },
    "violationOwner": {
      "id": "string"
    },
    "active": true,
    "scanTypes": {
      "preventative": true,
      "detective": true
    },
    "maxExceptionDuration": 0,
    "decisionOptions": {
      "allow": true,
      "exception": true,
      "remediate": true
    },
    "remediation": {
      "type": "string",
      "id": "string",
      "schemas": [
        "string"
      ]
    },
    "userFilter": {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    },
    "ruleDefinition": [
      {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      }
    ],
    "workflow": {
      "type": "bpmn",
      "id": "BasicViolationProcess"
    },
    "violationOwnerType": "user",
    "id": "string",
    "ruleDefinitionTags": [
      "targetName=entitlement.displayName&targetValue=IT%20Admin",
      "targetValue=IT%20Admin&targetName=entitlement.displayName"
    ]
  }
]

/iga/governance/policy/rule

POST

Create a new policy rule object within Identity Governance.

Parameters
Name Description

_action string * required

Action to be performed on a single request. The available values are create and duplicate.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "name": "string",
  "description": "string",
  "documentationUrl": "string",
  "policyRuleOwner": {
    "id": "string"
  },
  "violationOwner": {
    "id": "string"
  },
  "active": true,
  "scanTypes": {
    "preventative": true,
    "detective": true
  },
  "maxExceptionDuration": 0,
  "decisionOptions": {
    "allow": true,
    "exception": true,
    "remediate": true
  },
  "remediation": {
    "type": "string",
    "id": "string",
    "schemas": [
      "string"
    ]
  },
  "userFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  },
  "ruleDefinition": [
    {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    }
  ],
  "workflow": {
    "type": "bpmn",
    "id": "BasicViolationProcess"
  },
  "violationOwnerType": "user"
}
Responses
Code Description

201

Creation success. Returns the saved policy rule object.

400

Invalid data provided

500

Server error on save.
Click for an example response

Media type: application/json

{
  "name": "string",
  "description": "string",
  "documentationUrl": "string",
  "policyRuleOwner": {
    "id": "string"
  },
  "violationOwner": {
    "id": "string"
  },
  "active": true,
  "scanTypes": {
    "preventative": true,
    "detective": true
  },
  "maxExceptionDuration": 0,
  "decisionOptions": {
    "allow": true,
    "exception": true,
    "remediate": true
  },
  "remediation": {
    "type": "string",
    "id": "string",
    "schemas": [
      "string"
    ]
  },
  "userFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  },
  "ruleDefinition": [
    {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    }
  ],
  "workflow": {
    "type": "bpmn",
    "id": "BasicViolationProcess"
  },
  "violationOwnerType": "user",
  "id": "string",
  "ruleDefinitionTags": [
    "targetName=entitlement.displayName&targetValue=IT%20Admin",
    "targetValue=IT%20Admin&targetName=entitlement.displayName"
  ]
}

/iga/governance/policy/rule/search

POST

Query the policy rule objects using a targeted search filter.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of the API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "name": "string",
    "description": "string",
    "documentationUrl": "string",
    "policyRuleOwner": {
      "id": "string"
    },
    "violationOwner": {
      "id": "string"
    },
    "active": true,
    "scanTypes": {
      "preventative": true,
      "detective": true
    },
    "maxExceptionDuration": 0,
    "decisionOptions": {
      "allow": true,
      "exception": true,
      "remediate": true
    },
    "remediation": {
      "type": "string",
      "id": "string",
      "schemas": [
        "string"
      ]
    },
    "userFilter": {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    },
    "ruleDefinition": [
      {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      }
    ],
    "workflow": {
      "type": "bpmn",
      "id": "BasicViolationProcess"
    },
    "violationOwnerType": "user",
    "id": "string",
    "ruleDefinitionTags": [
      "targetName=entitlement.displayName&targetValue=IT%20Admin",
      "targetValue=IT%20Admin&targetName=entitlement.displayName"
    ]
  }
]

/iga/governance/policy/rule/{id}

GET

Get policy rule by ID.

Parameters
Name Description

id string * required

ID of the policy rule.

resolveSchemas string

When true, enrich the remediation.schemas property with the full schema objects rather than just the IDs.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

404

Policy doesn’t exist

500

Server error
Click for an example response

Media type: application/json

{
  "name": "string",
  "description": "string",
  "documentationUrl": "string",
  "policyRuleOwner": {
    "id": "string"
  },
  "violationOwner": {
    "id": "string"
  },
  "active": true,
  "scanTypes": {
    "preventative": true,
    "detective": true
  },
  "maxExceptionDuration": 0,
  "decisionOptions": {
    "allow": true,
    "exception": true,
    "remediate": true
  },
  "remediation": {
    "type": "string",
    "id": "string",
    "schemas": [
      "string"
    ]
  },
  "userFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  },
  "ruleDefinition": [
    {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    }
  ],
  "workflow": {
    "type": "bpmn",
    "id": "BasicViolationProcess"
  },
  "violationOwnerType": "user",
  "id": "string",
  "ruleDefinitionTags": [
    "targetName=entitlement.displayName&targetValue=IT%20Admin",
    "targetValue=IT%20Admin&targetName=entitlement.displayName"
  ]
}

/iga/governance/policy/rule/{id}

POST

Duplicate a given policy rule. The rule will be set as inactive by default.

Parameters
Name Description

_action string * required

Action to be performed on a single request. The available values are create and duplicate

id string * required

ID of the policy rule.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{}
Responses
Code Description

201

Returns new policy rule. NOTE: Rule is set to inactive by default.

400

Invalid request

404

Policy doesn’t exist

500

Server error
Click for an example response

Media type: application/json

{
  "name": "string",
  "description": "string",
  "documentationUrl": "string",
  "policyRuleOwner": {
    "id": "string"
  },
  "violationOwner": {
    "id": "string"
  },
  "active": true,
  "scanTypes": {
    "preventative": true,
    "detective": true
  },
  "maxExceptionDuration": 0,
  "decisionOptions": {
    "allow": true,
    "exception": true,
    "remediate": true
  },
  "remediation": {
    "type": "string",
    "id": "string",
    "schemas": [
      "string"
    ]
  },
  "userFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  },
  "ruleDefinition": [
    {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    }
  ],
  "workflow": {
    "type": "bpmn",
    "id": "BasicViolationProcess"
  },
  "violationOwnerType": "user"
}

/iga/governance/policy/rule/{id}

PUT

Update an existing policy rule object.

Parameters
Name Description

id string * required

ID of the policy rule to update.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "name": "string",
  "description": "string",
  "documentationUrl": "string",
  "policyRuleOwner": {
    "id": "string"
  },
  "violationOwner": {
    "id": "string"
  },
  "active": true,
  "scanTypes": {
    "preventative": true,
    "detective": true
  },
  "maxExceptionDuration": 0,
  "decisionOptions": {
    "allow": true,
    "exception": true,
    "remediate": true
  },
  "remediation": {
    "type": "string",
    "id": "string",
    "schemas": [
      "string"
    ]
  },
  "userFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  },
  "ruleDefinition": [
    {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    }
  ],
  "workflow": {
    "type": "bpmn",
    "id": "BasicViolationProcess"
  },
  "violationOwnerType": "user"
}
Responses
Code Description

200

Update success. Returns the saved policy rule object.

400

Invalid data provided

404

Policy doesn’t exist

500

Server error on save
Click for an example response

Media type: application/json

{
  "name": "string",
  "description": "string",
  "documentationUrl": "string",
  "policyRuleOwner": {
    "id": "string"
  },
  "violationOwner": {
    "id": "string"
  },
  "active": true,
  "scanTypes": {
    "preventative": true,
    "detective": true
  },
  "maxExceptionDuration": 0,
  "decisionOptions": {
    "allow": true,
    "exception": true,
    "remediate": true
  },
  "remediation": {
    "type": "string",
    "id": "string",
    "schemas": [
      "string"
    ]
  },
  "userFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  },
  "ruleDefinition": [
    {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    }
  ],
  "workflow": {
    "type": "bpmn",
    "id": "BasicViolationProcess"
  },
  "violationOwnerType": "user",
  "id": "string",
  "ruleDefinitionTags": [
    "targetName=entitlement.displayName&targetValue=IT%20Admin",
    "targetValue=IT%20Admin&targetName=entitlement.displayName"
  ]
}

/iga/governance/policy/rule/{id}

DELETE

Delete an existing policy rule.

Parameters
Name Description

id string * required

ID of policy rule to delete.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

Delete success. Returns the removed policy rule object

400

Invalid data provided

404

Policy doesn’t exist

500

Server error on save
Click for an example response

Media type: application/json

{
  "name": "string",
  "description": "string",
  "documentationUrl": "string",
  "policyRuleOwner": {
    "id": "string"
  },
  "violationOwner": {
    "id": "string"
  },
  "active": true,
  "scanTypes": {
    "preventative": true,
    "detective": true
  },
  "maxExceptionDuration": 0,
  "decisionOptions": {
    "allow": true,
    "exception": true,
    "remediate": true
  },
  "remediation": {
    "type": "string",
    "id": "string",
    "schemas": [
      "string"
    ]
  },
  "userFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  },
  "ruleDefinition": [
    {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    }
  ],
  "workflow": {
    "type": "bpmn",
    "id": "BasicViolationProcess"
  },
  "violationOwnerType": "user",
  "id": "string",
  "ruleDefinitionTags": [
    "targetName=entitlement.displayName&targetValue=IT%20Admin",
    "targetValue=IT%20Admin&targetName=entitlement.displayName"
  ]
}

/iga/governance/policy/rule/{id}/scan

POST

Run a scan the given policy for violations and create violations if desired.

Parameters
Name Description

id string * required

ID of the policy rule to scan.

simulate string

Indicates if this scan is a simulation: true means no violation tasks are created; false or not present creates violations.

waitForCompletion string

Specifies if you should wait for the completion of the scan before returning: true means wait; false or not present returns after scan creation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

201

Policy rule scan started

400

Invalid data provided

404

Policy doesn’t exist

500

Server error on save
Click for an example response

Media type: application/json

{
  "id": "string",
  "policy": {
    "id": "string",
    "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
    "name": "string",
    "description": "string",
    "policyOwner": {
      "id": "string"
    },
    "policyRuleIds": [
      "string"
    ]
  },
  "policyRule": {
    "name": "string",
    "description": "string",
    "documentationUrl": "string",
    "policyRuleOwner": {
      "id": "string"
    },
    "violationOwner": {
      "id": "string"
    },
    "active": true,
    "scanTypes": {
      "preventative": true,
      "detective": true
    },
    "maxExceptionDuration": 0,
    "decisionOptions": {
      "allow": true,
      "exception": true,
      "remediate": true
    },
    "remediation": {
      "type": "string",
      "id": "string",
      "schemas": [
        "string"
      ]
    },
    "userFilter": {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    },
    "ruleDefinition": [
      {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      }
    ],
    "workflow": {
      "type": "bpmn",
      "id": "BasicViolationProcess"
    },
    "violationOwnerType": "user",
    "id": "string",
    "ruleDefinitionTags": [
      "targetName=entitlement.displayName&targetValue=IT%20Admin",
      "targetValue=IT%20Admin&targetName=entitlement.displayName"
    ]
  },
  "isSimulation": true,
  "status": "string",
  "startDate": "string",
  "completionDate": "string",
  "scanTarget": "string",
  "results": [
    {}
  ]
}

/iga/governance/policy/user/{id}/scan

POST

Run a scan on a given user rule and return potential violations.

Parameters
Name Description

id string * required

ID of the user to scan.

simulate string

Indicate if this scan is a simulation: true means no violation tasks are created; false or not present creates violations.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "additionalAccess": [
    {
      "type": "string",
      "entitlementId": "string",
      "accountId": "string"
    }
  ],
  "policyRuleFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

201

User policy scan started

400

Invalid data provided

500

Server error on save
Click for an example response

Media type: application/json

{
  "id": "string",
  "policy": {
    "id": "string",
    "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
    "name": "string",
    "description": "string",
    "policyOwner": {
      "id": "string"
    },
    "policyRuleIds": [
      "string"
    ]
  },
  "policyRule": {
    "name": "string",
    "description": "string",
    "documentationUrl": "string",
    "policyRuleOwner": {
      "id": "string"
    },
    "violationOwner": {
      "id": "string"
    },
    "active": true,
    "scanTypes": {
      "preventative": true,
      "detective": true
    },
    "maxExceptionDuration": 0,
    "decisionOptions": {
      "allow": true,
      "exception": true,
      "remediate": true
    },
    "remediation": {
      "type": "string",
      "id": "string",
      "schemas": [
        "string"
      ]
    },
    "userFilter": {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    },
    "ruleDefinition": [
      {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      }
    ],
    "workflow": {
      "type": "bpmn",
      "id": "BasicViolationProcess"
    },
    "violationOwnerType": "user",
    "id": "string",
    "ruleDefinitionTags": [
      "targetName=entitlement.displayName&targetValue=IT%20Admin",
      "targetValue=IT%20Admin&targetName=entitlement.displayName"
    ]
  },
  "isSimulation": true,
  "status": "string",
  "startDate": "string",
  "completionDate": "string",
  "scanTarget": "string",
  "results": [
    {}
  ]
}

/iga/governance/policy/scan

GET

Query policy scans with the Identity Governance store based on a set of query parameters.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "policy": {
      "id": "string",
      "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
      "name": "string",
      "description": "string",
      "policyOwner": {
        "id": "string"
      },
      "policyRuleIds": [
        "string"
      ]
    },
    "policyRule": {
      "name": "string",
      "description": "string",
      "documentationUrl": "string",
      "policyRuleOwner": {
        "id": "string"
      },
      "violationOwner": {
        "id": "string"
      },
      "active": true,
      "scanTypes": {
        "preventative": true,
        "detective": true
      },
      "maxExceptionDuration": 0,
      "decisionOptions": {
        "allow": true,
        "exception": true,
        "remediate": true
      },
      "remediation": {
        "type": "string",
        "id": "string",
        "schemas": [
          "string"
        ]
      },
      "userFilter": {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      },
      "ruleDefinition": [
        {
          "operator": "AND",
          "operand": [
            {
              "operator": "EQUALS",
              "operand": {
                "targetName": "user.userName",
                "targetValue": "ljones"
              }
            },
            {
              "operator": "CONTAINS",
              "operand": {
                "targetName": "application.name",
                "targetValue": "Active Directory"
              }
            }
          ]
        }
      ],
      "workflow": {
        "type": "bpmn",
        "id": "BasicViolationProcess"
      },
      "violationOwnerType": "user",
      "id": "string",
      "ruleDefinitionTags": [
        "targetName=entitlement.displayName&targetValue=IT%20Admin",
        "targetValue=IT%20Admin&targetName=entitlement.displayName"
      ]
    },
    "isSimulation": true,
    "status": "string",
    "startDate": "string",
    "completionDate": "string",
    "scanTarget": "string",
    "results": [
      {}
    ]
  }
]

/iga/governance/policy/scan/search

POST

Query policy scan objects using a targeted search filter.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "policy": {
      "id": "string",
      "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
      "name": "string",
      "description": "string",
      "policyOwner": {
        "id": "string"
      },
      "policyRuleIds": [
        "string"
      ]
    },
    "policyRule": {
      "name": "string",
      "description": "string",
      "documentationUrl": "string",
      "policyRuleOwner": {
        "id": "string"
      },
      "violationOwner": {
        "id": "string"
      },
      "active": true,
      "scanTypes": {
        "preventative": true,
        "detective": true
      },
      "maxExceptionDuration": 0,
      "decisionOptions": {
        "allow": true,
        "exception": true,
        "remediate": true
      },
      "remediation": {
        "type": "string",
        "id": "string",
        "schemas": [
          "string"
        ]
      },
      "userFilter": {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      },
      "ruleDefinition": [
        {
          "operator": "AND",
          "operand": [
            {
              "operator": "EQUALS",
              "operand": {
                "targetName": "user.userName",
                "targetValue": "ljones"
              }
            },
            {
              "operator": "CONTAINS",
              "operand": {
                "targetName": "application.name",
                "targetValue": "Active Directory"
              }
            }
          ]
        }
      ],
      "workflow": {
        "type": "bpmn",
        "id": "BasicViolationProcess"
      },
      "violationOwnerType": "user",
      "id": "string",
      "ruleDefinitionTags": [
        "targetName=entitlement.displayName&targetValue=IT%20Admin",
        "targetValue=IT%20Admin&targetName=entitlement.displayName"
      ]
    },
    "isSimulation": true,
    "status": "string",
    "startDate": "string",
    "completionDate": "string",
    "scanTarget": "string",
    "results": [
      {}
    ]
  }
]

/iga/governance/policy/scan/{id}

GET

Get policy scan by ID.

Parameters
Name Description

id string * required

ID of the policy to scan.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

404

ID not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "policy": {
    "id": "string",
    "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
    "name": "string",
    "description": "string",
    "policyOwner": {
      "id": "string"
    },
    "policyRuleIds": [
      "string"
    ]
  },
  "policyRule": {
    "name": "string",
    "description": "string",
    "documentationUrl": "string",
    "policyRuleOwner": {
      "id": "string"
    },
    "violationOwner": {
      "id": "string"
    },
    "active": true,
    "scanTypes": {
      "preventative": true,
      "detective": true
    },
    "maxExceptionDuration": 0,
    "decisionOptions": {
      "allow": true,
      "exception": true,
      "remediate": true
    },
    "remediation": {
      "type": "string",
      "id": "string",
      "schemas": [
        "string"
      ]
    },
    "userFilter": {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    },
    "ruleDefinition": [
      {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      }
    ],
    "workflow": {
      "type": "bpmn",
      "id": "BasicViolationProcess"
    },
    "violationOwnerType": "user",
    "id": "string",
    "ruleDefinitionTags": [
      "targetName=entitlement.displayName&targetValue=IT%20Admin",
      "targetValue=IT%20Admin&targetName=entitlement.displayName"
    ]
  },
  "isSimulation": true,
  "status": "string",
  "startDate": "string",
  "completionDate": "string",
  "scanTarget": "string",
  "results": [
    {}
  ]
}

/iga/governance/policy/scan/{id}

DELETE

Delete an existing policy scan object within Identity Governance.

Parameters
Name Description

id string * required

ID of the policy to scan to delete.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

Delete success. Returns the removed policy scan object

400

Invalid data provided

404

ID not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "policy": {
    "id": "string",
    "scheduleId": "policySchedule1a5cefd6a67f4303b16f1b5d5740cfd1",
    "name": "string",
    "description": "string",
    "policyOwner": {
      "id": "string"
    },
    "policyRuleIds": [
      "string"
    ]
  },
  "policyRule": {
    "name": "string",
    "description": "string",
    "documentationUrl": "string",
    "policyRuleOwner": {
      "id": "string"
    },
    "violationOwner": {
      "id": "string"
    },
    "active": true,
    "scanTypes": {
      "preventative": true,
      "detective": true
    },
    "maxExceptionDuration": 0,
    "decisionOptions": {
      "allow": true,
      "exception": true,
      "remediate": true
    },
    "remediation": {
      "type": "string",
      "id": "string",
      "schemas": [
        "string"
      ]
    },
    "userFilter": {
      "operator": "AND",
      "operand": [
        {
          "operator": "EQUALS",
          "operand": {
            "targetName": "user.userName",
            "targetValue": "ljones"
          }
        },
        {
          "operator": "CONTAINS",
          "operand": {
            "targetName": "application.name",
            "targetValue": "Active Directory"
          }
        }
      ]
    },
    "ruleDefinition": [
      {
        "operator": "AND",
        "operand": [
          {
            "operator": "EQUALS",
            "operand": {
              "targetName": "user.userName",
              "targetValue": "ljones"
            }
          },
          {
            "operator": "CONTAINS",
            "operand": {
              "targetName": "application.name",
              "targetValue": "Active Directory"
            }
          }
        ]
      }
    ],
    "workflow": {
      "type": "bpmn",
      "id": "BasicViolationProcess"
    },
    "violationOwnerType": "user",
    "id": "string",
    "ruleDefinitionTags": [
      "targetName=entitlement.displayName&targetValue=IT%20Admin",
      "targetValue=IT%20Admin&targetName=entitlement.displayName"
    ]
  },
  "isSimulation": true,
  "status": "string",
  "startDate": "string",
  "completionDate": "string",
  "scanTarget": "string",
  "results": [
    {}
  ]
}

/iga/governance/user/violation

GET

Query the signed-in user’s violation objects.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "user": {},
    "policyRule": {},
    "decision": {
      "status": "pending",
      "decision": "exception",
      "comments": [
        {}
      ],
      "events": {
        "assignment": {},
        "expiration": {},
        "escalation": {},
        "reminder": {}
      },
      "actors": {
        "active": [
          {}
        ],
        "inactive": [
          {}
        ]
      },
      "completionDate": "string",
      "completedBy": {}
    }
  }
]

/iga/governance/violation

GET

Query the violation objects.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "user": {},
    "policyRule": {},
    "decision": {
      "status": "pending",
      "decision": "exception",
      "comments": [
        {}
      ],
      "events": {
        "assignment": {},
        "expiration": {},
        "escalation": {},
        "reminder": {}
      },
      "actors": {
        "active": [
          {}
        ],
        "inactive": [
          {}
        ]
      },
      "completionDate": "string",
      "completedBy": {}
    }
  }
]

/iga/governance/violation

POST

Creates a violation with the given body.

Parameters
Name Description

_action string * required

Action to be taken. The available values are create and duplicate.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "id": "string",
    "user": {},
    "policyRule": {},
    "decision": {
      "status": "pending",
      "decision": "exception",
      "comments": [
        {}
      ],
      "events": {
        "assignment": {},
        "expiration": {},
        "escalation": {},
        "reminder": {}
      },
      "actors": {
        "active": [
          {}
        ],
        "inactive": [
          {}
        ]
      },
      "completionDate": "string",
      "completedBy": {}
    }
  }
}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "user": {},
    "policyRule": {},
    "decision": {
      "status": "pending",
      "decision": "exception",
      "comments": [
        {}
      ],
      "events": {
        "assignment": {},
        "expiration": {},
        "escalation": {},
        "reminder": {}
      },
      "actors": {
        "active": [
          {}
        ],
        "inactive": [
          {}
        ]
      },
      "completionDate": "string",
      "completedBy": {}
    }
  }
]

/iga/governance/violation/allow

POST

Once a phase (or phases) have chosen to allow a violation, close and complete the violations with the outcome of allow.

Parameters
Name Description

waitForCompletion string

Specifies if you should wait the completion of the scan before returning. true waits; false or not present returns after scan creation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "ids": [
    "e9e4d260-1b55-4331-8468-5824344b8bc3",
    "01d8ccf0-e132-49f1-9c82-c52a6fea0154"
  ],
  "comment": "Justification for this action."
}
Responses
Code Description

200

OK

400

Invalid request

403

User is not authorized to allow violations

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "message": "Action 'allow' complete.",
  "idsNotActedOn": [
    {
      "id": "09e01632-b22f-407b-bacb-aa1e2cac8214",
      "errorMessage": "This violation is not eligible to be allowed.",
      "errorCode": 400
    }
  ]
}

/iga/governance/violation/cancel-exception

POST

As a user who can take action on violations, cancel existing exceptions, reverting the violations to in-progress.

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "ids": [
    "e9e4d260-1b55-4331-8468-5824344b8bc3",
    "01d8ccf0-e132-49f1-9c82-c52a6fea0154"
  ],
  "comment": "Justification for this action."
}
Responses
Code Description

200

OK

400

Invalid request

403

User is not authorized to comment violations

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "message": "Action 'allow' complete.",
  "idsNotActedOn": [
    {
      "id": "09e01632-b22f-407b-bacb-aa1e2cac8214",
      "errorMessage": "This violation is not eligible to be allowed.",
      "errorCode": 400
    }
  ]
}

/iga/governance/violation/comment

POST

As a user who can take action on violations, add a comment to the violation objects.

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "ids": [
    "e9e4d260-1b55-4331-8468-5824344b8bc3",
    "01d8ccf0-e132-49f1-9c82-c52a6fea0154"
  ],
  "comment": "Justification for this action."
}
Responses
Code Description

200

OK

400

Invalid request

403

User is not authorized to comment violations

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "message": "Action 'allow' complete.",
  "idsNotActedOn": [
    {
      "id": "09e01632-b22f-407b-bacb-aa1e2cac8214",
      "errorMessage": "This violation is not eligible to be allowed.",
      "errorCode": 400
    }
  ]
}

/iga/governance/violation/exception

POST

As a user who can take action on violations, grant an exception to the violating access.

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "ids": [
    "e9e4d260-1b55-4331-8468-5824344b8bc3",
    "01d8ccf0-e132-49f1-9c82-c52a6fea0154"
  ],
  "comment": "Justification for this action.",
  "exceptionExpirationDate": "2024-04-24T20:36:14+00:00"
}
Responses
Code Description

200

OK

400

Invalid request

403

User is not authorized to comment violations

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "message": "Action 'allow' complete.",
  "idsNotActedOn": [
    {
      "id": "09e01632-b22f-407b-bacb-aa1e2cac8214",
      "errorMessage": "This violation is not eligible to be allowed.",
      "errorCode": 400
    }
  ]
}

/iga/governance/violation/reassign

POST

As a user who can take action on violations, edit the list of active actors on the violation tasks.

Parameters
Name Description

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "ids": [
    "e9e4d260-1b55-4331-8468-5824344b8bc3",
    "01d8ccf0-e132-49f1-9c82-c52a6fea0154"
  ],
  "comment": "Justification for this action.",
  "updatedActors": [
    {
      "id": {
        "value": "string",
        "isExpression": true
      },
      "permissions": {
        "approve": true,
        "reject": true,
        "reassign": true,
        "modify": true,
        "comment": true,
        "allow": true,
        "exception": true,
        "remediate": true
      }
    }
  ]
}
Responses
Code Description

200

OK

400

Invalid request

403

User is not authorized to comment violations

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "message": "Action 'allow' complete.",
  "idsNotActedOn": [
    {
      "id": "09e01632-b22f-407b-bacb-aa1e2cac8214",
      "errorMessage": "This violation is not eligible to be allowed.",
      "errorCode": 400
    }
  ]
}

/iga/governance/violation/search

POST

Query the violation objects using a targeted search filter.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_searchAfter string

The sort property values of the last entry to continue searching from. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "user": {},
    "policyRule": {},
    "decision": {
      "status": "pending",
      "decision": "exception",
      "comments": [
        {}
      ],
      "events": {
        "assignment": {},
        "expiration": {},
        "escalation": {},
        "reminder": {}
      },
      "actors": {
        "active": [
          {}
        ],
        "inactive": [
          {}
        ]
      },
      "completionDate": "string",
      "completedBy": {}
    }
  }
]

/iga/governance/user/violation/search

POST

Query the signed-in user’s violation object using a targeted search filter.

Parameters
Name Description

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_searchAfter string

The sort property values of the last entry to continue searching from. Comma-separated for multiple values.

_queryFilter string

Search query filter.

actorStatus string

Actor status to search. Comma-separated for multiple values. For example: active, inactive, or active, inactive.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

!_searchAfter string !The sort property values of the last entry to continue searching from. Comma-separated for multiple values.

{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: `application/json`å

[
  {
    "id": "string",
    "user": {},
    "policyRule": {},
    "decision": {
      "status": "pending",
      "decision": "exception",
      "comments": [
        {}
      ],
      "events": {
        "assignment": {},
        "expiration": {},
        "escalation": {},
        "reminder": {}
      },
      "actors": {
        "active": [
          {}
        ],
        "inactive": [
          {}
        ]
      },
      "completionDate": "string",
      "completedBy": {}
    }
  }
]

/iga/governance/violation/{id}

GET

Query the contents of a single violation object.

Parameters
Name Description

id string * required

ID of the violation.

resolveSchemas string

When true, enrich the policyRule remediation schemas property with the full schema objects rather than just the IDs.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

404

Violation doesn’t exist

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}

PUT

Updates a given violation with the given body.

Parameters
Name Description

id string * required

ID of the violation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "targetFilter": {
    "id": "string",
    "user": {},
    "policyRule": {},
    "decision": {
      "status": "pending",
      "decision": "exception",
      "comments": [
        {}
      ],
      "events": {
        "assignment": {},
        "expiration": {},
        "escalation": {},
        "reminder": {}
      },
      "actors": {
        "active": [
          {}
        ],
        "inactive": [
          {}
        ]
      },
      "completionDate": "string",
      "completedBy": {}
    }
  }
}
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

[
  {
    "id": "string",
    "user": {},
    "policyRule": {},
    "decision": {
      "status": "pending",
      "decision": "exception",
      "comments": [
        {}
      ],
      "events": {
        "assignment": {},
        "expiration": {},
        "escalation": {},
        "reminder": {}
      },
      "actors": {
        "active": [
          {}
        ],
        "inactive": [
          {}
        ]
      },
      "completionDate": "string",
      "completedBy": {}
    }
  }
]

/iga/governance/violation/{id}

DELETE

Deletes a violation with a given ID.

Parameters
Name Description

id string * required

ID of the violation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example response

Media type: application/json

"string"

/iga/governance/violation/{id}/allow

POST

Once a phase (or phases) have chosen to allow a violation, close and complete the violation with an outcome of allow.

Parameters
Name Description

id string * required

ID of the violation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{}
Responses
Code Description

200

OK

400

Invalid request

403

User is not authorized to allow violation

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/#{id}/comment

POST

As an actor on a violation, add a comment to a violation object.

Parameters
Name Description

id string * required

ID of the violation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "comment": "string"
}
Responses
Code Description

201

Comment added

400

Invalid request

403

User is not authorized to comment on violation

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/remediate

POST

Once a phase (or phases) have chosen to remediate a violation, complete the violation with an outcome of remediate and continue the workflow on to either the automated or manual process for fulfilling the remediation.

Parameters
Name Description

id string * required

ID of the violation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "id": "string"
}
Responses
Code Description

200

Remediation process begun

400

Invalid request

403

User is not authorized to remediate violation

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/remediation/status/{status}

POST

For violations with an outcome of remediate, allow the remediationStatus key to be updated. For example, from in-progress to complete and finalize the violation when appropriate.

Parameters
Name Description

id string * required

ID of the violation.

status string * required

Status to update remediationStatus to.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{}
Responses
Code Description

200

OK

400

Invalid request

404

Violation ID not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{violationId}/phases

POST

Add a phase to a violation. A phase is a task that must be completed to move the violation forward, which depends on the task configuration, such as expiration, assignee, notifications, and others. For type=violation, the task allows users to select allow or remediate.

Parameters
Name Description

violationId string * required

ID of the violation.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "phase": {
    "phase": {
      "name": "ManagerApproval",
      "type": "request",
      "status": "in-progress",
      "decision": "approve",
      "startDate": "2023-09-10T12:00:00+00:00",
      "events": {
        "assignment": {
          "notification": "requestAssigned"
        },
        "reassign": {
          "notification": "requestReassigned"
        },
        "expiration": {
          "date": "2023-09-04T12:00:00+00:00",
          "notification": "requestExpired",
          "action": "reassign",
          "actors": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              }
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              }
            }
          ]
        },
        "escalation": {
          "date": "2023-09-04T12:00:00+00:00",
          "notification": "requestEscalated",
          "actors": [
            {
              "id": "875bbc8f-e868-451f-a690-453473205ca1"
            }
          ],
          "frequency": 3
        },
        "reminder": {
          "date": "2023-09-04T12:00:00+00:00",
          "notification": "requestReminder",
          "frequency": 3
        }
      },
      "justification": "string",
      "workflowTaskId": "1025",
      "completedBy": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "completionDate": "2023-09-10T12:00:00+00:00"
    }
  },
  "actors": [
    {
      "id": {
        "value": "string",
        "isExpression": true
      },
      "permissions": {
        "approve": true,
        "reject": true,
        "reassign": true,
        "modify": true,
        "comment": true,
        "allow": true,
        "exception": true,
        "remediate": true
      }
    }
  ]
}
Responses
Code Description

200

OK

400

Invalid request

404

Violation not found

500

Server error

/iga/governance/violation/{id}/phases/{phaseName}/allow

POST

As an actor on a violation, allow the user to continue to violate the defined rule in perpetuity.

Parameters
Name Description

id string * required

ID of the violation.

phaseName string * required

Name of the phase.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "comment": "string"
}
Responses
Code Description

200

OK

400

Invalid request

403

User not authorized to take action

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/phases/{phaseName}/cancel-exception

POST

As an actor on a violation, cancel an existing exception, reverting the violation to in-progress.

Parameters
Name Description

id string * required

ID of the violation.

phaseName string * required

Name of the phase.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "comment": "string"
}
Responses
Code Description

200

Exception canceled

400

Invalid request

403

User is not authorized to take action

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/phases/{phaseName}/comment

POST

Add a comment to a violation object.

Parameters
Name Description

id string * required

ID of the violation.

phaseName string * required

Name of the phase.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "comment": "string"
}
Responses
Code Description

200

Comment added

400

Invalid request

403

User is not authorized to take action

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/phases/{phaseName}/exception

POST

As an actor on a violation, grant an exception to the violating access.

Parameters
Name Description

id string * required

ID of the violation.

phaseName string * required

Name of the phase.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "exceptionExpirationDate": "string",
  "comment": "string"
}
Responses
Code Description

200

Exception granted

400

Invalid request

401

User is not authorized to make exception on violation

403

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/phases/{phaseName}/reassign

POST

As an actor on a violation, edit the actors and permissions on a violation task.

Parameters
Name Description

id string * required

ID of the violation.

phaseName string * required

Name of the phase.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * string

Media type: application/json

{
  "updatedActors": [
    {
      "id": {
        "value": "string",
        "isExpression": true
      },
      "permissions": {
        "approve": true,
        "reject": true,
        "reassign": true,
        "modify": true,
        "comment": true,
        "allow": true,
        "exception": true,
        "remediate": true
      }
    }
  ]
}
Responses
Code Description

200

Actors reassigned

400

Invalid request

403

User is not authorized to take action

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/phases/{phaseName}/remediate

POST

As an actor on a violation, choose to remediate the access, kicking off the remediation workflow assigned to the violation.

Parameters
Name Description

id string * required

ID of the violation.

phaseName string * required

Name of the phase.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body * required

Media type: application/json

{
  "id": "string"
}
Responses
Code Description

200

Remediation process begun

400

Invalid request

403

User is not authorized to take action

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/phases/{phaseName}/complete

POST

As an actor on a manual provisioning task to handle the violation remediation, mark the action as completed.

Parameters
Name Description

id string * required

ID of the violation.

phaseName string * required

Name of the phase.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "comment": "string"
}
Responses
Code Description

200

OK

400

Invalid request

403

User is not authorized to take action

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

/iga/governance/violation/{id}/phases/{phaseName}/cancel

POST

As an actor on a manual provisioning task to handle the violation remediation, mark the action as canceled (not completed).

Parameters
Name Description

id string * required

ID of the violation.

phaseName string * required

Name of the phase.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body

Media type: application/json

{
  "comment": "string"
}
Responses
Code Description

200

OK

400

Invalid request

403

User is not authorized to take action

404

Violation not found

500

Server error
Click for an example response

Media type: application/json

{
  "id": "string",
  "user": {},
  "policyRule": {},
  "decision": {
    "status": "pending",
    "decision": "exception",
    "comments": [
      {}
    ],
    "events": {
      "assignment": {},
      "expiration": {},
      "escalation": {},
      "reminder": {}
    },
    "actors": {
      "active": [
        {}
      ],
      "inactive": [
        {}
      ]
    },
    "completionDate": "string",
    "completedBy": {}
  }
}

Task

Endpoints for fulfillment tasks.

URI HTTP
method		 Description

/iga/governance/user/{userId}/tasks

GET

Get the tasks for which the authenticated user has permissions to view.

Parameters
Name Description

userId string * required

Unique identifier of the user.

Type string

The type of task to filter by. The available values are request, violation, and fulfillment

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "requester": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "requestType": "applicationGrant",
      "request": {
        "common": {
          "startDate": "2023-09-11T12:00:00+00:00",
          "endDate": "2023-12-11T12:00:00+00:00",
          "justification": "I need this access to start working on a new project.",
          "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
          "isDraft": false,
          "requestIdPrefix": "REQ"
        }
      },
      "application": {
        "authoritative": false,
        "connectorId": "AzureAD",
        "description": "AzureAD application",
        "fr": {
          "realm": "alpha"
        },
        "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
        "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
        "mappingNames": [
          "systemAzureadUser_managedAlpha_user",
          "systemAzureadDirectoryrole_managedAlpha_assignment",
          "systemAzuread__group___managedAlpha_assignment",
          "managedAlpha_user_systemAzureadUser"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2023-08-31T21:23:35.809Z"
        },
        "name": "AzureAD",
        "templateName": "azure.ad",
        "templateVersion": "2.0",
        "objectTypes": [
          {
            "name": "__ACCOUNT__"
          },
          {
            "name": "__GROUP__",
            "accountAttribute": "memberOf"
          }
        ]
      },
      "applicationOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "entitlementOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "roleOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "user": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "decision": {
        "status": "in-progress",
        "decision": "approved",
        "outcome": "provisioned",
        "startDate": "2023-09-10T12:00:00+00:00",
        "completionDate": "2023-09-10T12:00:00+00:00",
        "comments": [
          {
            "user": {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith"
            },
            "comment": "I need to find out more information before approving.  Will check back later.",
            "action": "comment",
            "timeStamp": "2023-09-11T12:00:00+00:00",
            "phase": "ManagerApproval"
          }
        ],
        "actors": {
          "active": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ],
          "inactive": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ]
        },
        "phases": [
          {
            "phase": {
              "name": "ManagerApproval",
              "type": "request",
              "status": "in-progress",
              "decision": "approve",
              "startDate": "2023-09-10T12:00:00+00:00",
              "events": {
                "assignment": {
                  "notification": "requestAssigned"
                },
                "reassign": {
                  "notification": "requestReassigned"
                },
                "expiration": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestExpired",
                  "action": "reassign",
                  "actors": [
                    {
                      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                      "userName": "asmith",
                      "mail": "asmith01@forgerock.com",
                      "givenName": "Aaron",
                      "sn": "Smith",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    },
                    {
                      "id": "string",
                      "name": "string",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    }
                  ]
                },
                "escalation": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestEscalated",
                  "actors": [
                    {
                      "id": "875bbc8f-e868-451f-a690-453473205ca1"
                    }
                  ],
                  "frequency": 3
                },
                "reminder": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestReminder",
                  "frequency": 3
                }
              },
              "justification": "string",
              "workflowTaskId": "1025",
              "completedBy": {
                "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                "userName": "asmith",
                "mail": "asmith01@forgerock.com",
                "givenName": "Aaron",
                "sn": "Smith"
              },
              "completionDate": "2023-09-10T12:00:00+00:00"
            }
          }
        ]
      },
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 0,
  "resultCount": 0
}

/iga/governance/user/{userId}/tasks

POST

Get the tasks for which the authenticated user has permissions to view. The targetFilter property in the payload can be used to filter requests based on the desired criteria.

Parameters
Name Description

userId string * required

Unique identifier of the user.

Type string

The type of task to filter by. The available values are request, violation, and fulfillment

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

userId string * string

Unique identifier of the user.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Request body 
{
  "targetFilter": {
    "operator": "AND",
    "operand": [
      {
        "operator": "EQUALS",
        "operand": {
          "targetName": "user.userName",
          "targetValue": "ljones"
        }
      },
      {
        "operator": "CONTAINS",
        "operand": {
          "targetName": "application.name",
          "targetValue": "Active Directory"
        }
      }
    ]
  }
}
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "result": [
    {
      "id": "string",
      "requester": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "requestType": "applicationGrant",
      "request": {
        "common": {
          "startDate": "2023-09-11T12:00:00+00:00",
          "endDate": "2023-12-11T12:00:00+00:00",
          "justification": "I need this access to start working on a new project.",
          "externalRequestId": "c926c10f-300a-4222-876f-348e0ca07d63",
          "isDraft": false,
          "requestIdPrefix": "REQ"
        }
      },
      "application": {
        "authoritative": false,
        "connectorId": "AzureAD",
        "description": "AzureAD application",
        "fr": {
          "realm": "alpha"
        },
        "icon": "https://example.forgeblocks.com/platform/img/microsoft.8a785075.svg",
        "id": "a09030e6-f4d1-4442-9c7c-1a51ce4683c1",
        "mappingNames": [
          "systemAzureadUser_managedAlpha_user",
          "systemAzureadDirectoryrole_managedAlpha_assignment",
          "systemAzuread__group___managedAlpha_assignment",
          "managedAlpha_user_systemAzureadUser"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2023-08-31T21:23:35.809Z"
        },
        "name": "AzureAD",
        "templateName": "azure.ad",
        "templateVersion": "2.0",
        "objectTypes": [
          {
            "name": "__ACCOUNT__"
          },
          {
            "name": "__GROUP__",
            "accountAttribute": "memberOf"
          }
        ]
      },
      "applicationOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "entitlementOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "roleOwner": [
        {
          "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
          "userName": "asmith",
          "mail": "asmith01@forgerock.com",
          "givenName": "Aaron",
          "sn": "Smith"
        }
      ],
      "user": {
        "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
        "userName": "asmith",
        "mail": "asmith01@forgerock.com",
        "givenName": "Aaron",
        "sn": "Smith"
      },
      "decision": {
        "status": "in-progress",
        "decision": "approved",
        "outcome": "provisioned",
        "startDate": "2023-09-10T12:00:00+00:00",
        "completionDate": "2023-09-10T12:00:00+00:00",
        "comments": [
          {
            "user": {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith"
            },
            "comment": "I need to find out more information before approving.  Will check back later.",
            "action": "comment",
            "timeStamp": "2023-09-11T12:00:00+00:00",
            "phase": "ManagerApproval"
          }
        ],
        "actors": {
          "active": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ],
          "inactive": [
            {
              "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
              "userName": "asmith",
              "mail": "asmith01@forgerock.com",
              "givenName": "Aaron",
              "sn": "Smith",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            },
            {
              "id": "string",
              "name": "string",
              "permissions": {
                "approve": true,
                "comment": true,
                "modify": true,
                "reassign": true,
                "reject": true
              },
              "phase": "ManagerApproval"
            }
          ]
        },
        "phases": [
          {
            "phase": {
              "name": "ManagerApproval",
              "type": "request",
              "status": "in-progress",
              "decision": "approve",
              "startDate": "2023-09-10T12:00:00+00:00",
              "events": {
                "assignment": {
                  "notification": "requestAssigned"
                },
                "reassign": {
                  "notification": "requestReassigned"
                },
                "expiration": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestExpired",
                  "action": "reassign",
                  "actors": [
                    {
                      "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                      "userName": "asmith",
                      "mail": "asmith01@forgerock.com",
                      "givenName": "Aaron",
                      "sn": "Smith",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    },
                    {
                      "id": "string",
                      "name": "string",
                      "permissions": {
                        "approve": true,
                        "comment": true,
                        "modify": true,
                        "reassign": true,
                        "reject": true
                      }
                    }
                  ]
                },
                "escalation": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestEscalated",
                  "actors": [
                    {
                      "id": "875bbc8f-e868-451f-a690-453473205ca1"
                    }
                  ],
                  "frequency": 3
                },
                "reminder": {
                  "date": "2023-09-04T12:00:00+00:00",
                  "notification": "requestReminder",
                  "frequency": 3
                }
              },
              "justification": "string",
              "workflowTaskId": "1025",
              "completedBy": {
                "id": "a3ad098f-93b1-47dc-a31d-f37bbb4c15d1-160761",
                "userName": "asmith",
                "mail": "asmith01@forgerock.com",
                "givenName": "Aaron",
                "sn": "Smith"
              },
              "completionDate": "2023-09-10T12:00:00+00:00"
            }
          }
        ]
      },
      "metadata": {
        "createdDate": "2024-01-11T12:00:00+00:00",
        "modifiedDate": "2024-04-24T12:00:00+00:00"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 0,
  "resultCount": 0
}

User

Endpoint for a user’s grants and recommendations.

URI HTTP
method		 Description

/iga/governance/user/{userId}/privileges

GET

Get the privileges a user currently has.

The endpoint returns the Identity Governance-related authorization details for the authenticated users and includes the following information:

  • userInfo: Displayable information of the user.

  • owner: Identity Governance entities for which the user is an owner.

  • groups: Groups the user belongs to (via their authorization token).

  • permissions: List of Identity Governance permissions that apply to the user

  • scopes: List of scopes that currently apply to this user.

Parameters
Name Description

userId string * required

Unique identifier of the user.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example to get a user’s privileges

Media type: application/json

GET iga/governance/user/{userId}/privileges
{
   "userInfo": {
       "userName": "christian.marnell",
       "id": "bfd816e1-b9fe-4ea9-90f5-45e2e906cdfc",
       "givenName": "Christian",
       "sn": "Marnell",
       "mail": "christian.marnell@example.com"
   },
   "owner": {
       "certification": false,
       "entitlement": true,
       "policy": false
   },
   "groups": [],
   "permissions": [
       "createEntitlement",
       "modifyEntitlement"
   ],
   "scopes": [
       "e8abd5fb-64c2-493d-8415-e7a0e4a35984"
   ]
}

/iga/governance/user/{userId}/grants

GET

Get the grants a user currently has.

Parameters
Name Description

userId string * required

Unique identifier of the user.

queryString string * required

Search term. Searches against display names of the grant being targeted.

grantType string

Type of grant being searched for. The available values are entitlement, account, and role

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK

400

Invalid request

500

Server error
Click for an example to get a user’s privileges

Media type: application/json

{
  "result": [
    {
      "account": {
        "calendar_integration": "1",
        "user_name": "guillermo.frohich",
        "sys_updated_on": "2025-01-02 21:29:47",
        "__user_group_ids__": [
          "0a52d3dcd7011200f2d224837e6103f2"
        ],
        "title": "Chief Financial Officer",
        "sys_class_name": "sys_user",
        "notification": "2",
        "sys_updated_by": "developer.program.hop@snc",
        "sys_created_on": "2024-11-30 15:04:03",
        "sys_domain": "global",
        "__NAME__": "62526fa1d701120035ae23c7ce6103c6",
        "vip": false,
        "department": "221f3db5c6112284009f4becd3039cc9",
        "first_name": "Guillermo",
        "sys_created_by": "admin",
        "email": "guillermo.frohlich@example.com",
        "__user_role_ids__": [
          "cc6f85b5ebc31300a210a2505206fec0",
          "8a454be00a0a0b8c00de7dae26869165"
        ],
        "locked_out": "false",
        "sys_mod_count": "3",
        "active": "true",
        "last_name": "Frohlich",
        "time_zone": "Europe/London",
        "name": "Guillermo Frohlich",
        "_id": "62526fa1d701120035ae23c7ce6103c6"
      },
      "application": {
        "name": "TargetApp",
        "description": "Testing 3",
        "objectTypes": [
          {
            "name": "Role",
            "accountAttribute": "__user_role_ids__"
          },
          {
            "name": "Group",
            "accountAttribute": "__user_group_ids__"
          },
          {
            "name": "User"
          }
        ]
      },
      "catalog": {
        "id": "16758965550a4cf40f25c0f6a8bb7a5b347292785141e7f4e59644f77cf0811010cd55da8f1f27e3401676ada5b57734682167d3ef5fb26c98acb660390f44b4"
      },
      "compositeId": "12b505cfad20126bf03f49106aeeff3d85a9cb8fe4f882e5422e408a82d85a75dcb78ef282cc90a32259c64b0a4990eb55cec5adfbf22817aabe43152c2e183",
      "descriptor": {
        "idx": {
          "/entitlement": {
            "displayName": "interaction_agent"
          },
          "/account": {
            "displayName": "guillermo.frohich"
          }
        }
      },
      "entitlement": {
        "can_delegate": true,
        "sys_package": "7db62d76e806121087debb3e47d14f20",
        "grantable": true,
        "description": "A required role to perform interaction agent and interaction queue transfer",
        "sys_name": "interaction_agent",
        "sys_scope": "global",
        "__NAME__": "b523f1d037001300a213a7f07e41f15b",
        "elevated_privilege": false,
        "_id": "b523f1d037001300a213a7f07e41f15b",
        "sys_class_name": "sys_user_role"
      },
      "glossary": {
        "idx": {
          "/entitlement": {
            "entitlementOwner": "managed/user/e8e8636e-33ad-4764-8c13-feba9a973bb1"
          },
          "/application": {
            "requestable": true
          }
        },
        "types": [
          {
            "attrKey": "/assignment",
            "modified": "2025-02-04T14:22:27.287176855Z",
            "type": "entityType/id/realm"
          },
          {
            "attrKey": "/application",
            "modified": "2025-02-03T22:08:38.874Z",
            "type": "entityType/id/realm"
          }
        ]
      },
      "item": {
        "type": "entitlementGrant",
        "objectType": "Role"
      },
      "keys": {
        "type": "entitlementGrant",
        "userId": "ff1d2def-b44e-468f-9079-3b5a2a7dd219",
        "applicationId": "825c6e15-b860-4be4-bef9-55d28a0cd2de",
        "accountId": "system/TargetApp/User/62526fa1d701120035ae23c7ce6103c6",
        "entitlementId": "system/TargetApp/Role/b523f1d037001300a213a7f07e41f15b"
      },
      "relationship": {
        "id": "55f1f1d0-fc1f-4d69-a550-e6f354aefb5e-60718",
        "properties": {
          "grantTypes": [
            {
              "id": "55f1f1d0-fc1f-4d69-a550-e6f354aefb5e-60718",
              "grantType": "recon"
            }
          ]
        }
      },
      "user": {
        "_rev": "ffe3f7ed-1022-425c-845e-210b35f392e8-20187",
        "accountStatus": "active",
        "assignedDashboard": [
          "TargetApp"
        ],
        "cn": "Guillermo Frohlich",
        "fr": {
          "realm": "alpha"
        },
        "givenName": "Guillermo",
        "id": "ff1d2def-b44e-468f-9079-3b5a2a7dd219",
        "mail": "guillermo.frohlich@example.com",
        "metadata": {
          "created": "2025-01-22T18:17:03.931Z",
          "entityType": "/openidm/managed/user",
          "version": 8
        },
        "scopes": {
          "view": [
            {
              "id": "e8abd5fb-64c2-493d-8415-e7a0e4a35984",
              "timestamp": "2025-01-28T14:45:52.119497214Z"
            }
          ]
        },
        "sn": "Frohlich",
        "userId": "ff1d2def-b44e-468f-9079-3b5a2a7dd219",
        "userName": "guillermo.frohich"
      },
      "metadata": {
        "modifiedDate": "2025-02-04T14:30:59.277Z",
        "createdDate": "2025-01-22T18:16:03.576225515Z"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 0,
  "resultCount": 0
}

/iga/governance/user/{userId}/recommendations

GET

Get the access recommendations for a given user.

Parameters
Name Description

userId string * required

Unique identifier of the user.

_fields string

List of fields to return for each entry in the response result. Comma-separated for multiple values.

_pageSize integer

Number of response result objects to return.

_pagedResultsOffset integer

Offset number of the record from which to start the paginated results.

_sortKeys string

Property on which to sort the results.

_sortDir string

Direction of sort: asc, desc.

_sortType string

Type of sort value. Special types of fields need to use this parameter to sort properly. Currently, the supported special types are date and integer. This can be omitted for other fields.

_searchAfter string

Sort property values of the last entry to which continue searching. Comma-separated for multiple values.

_queryFilter string

Search query filter.

Accept-API-Version string

API version to use for the request. If no value is provided, the latest version of API is used to process the request.
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "result": [
    {
      "prediction": {
        "usr_id": "44aac3af-23ae-47ad-a760-e5f4d94da54b",
        "ent_id": "system_Targettestigaautom1___GROUP___ac77bdcb-659f-4276-beb9-14604d62986e",
        "confidence": 0.75,
        "rule": [
          "12_CHIEF_YES_NO_Yes",
          "12_USR_EMP_TYPE_Employee",
          "14_USR_MANAGER_ID_benjamin.rosenfield",
          "19_USR_DEPARTMENT_NAME_Customer Operations South"
        ],
        "freq": 5,
        "freqUnion": 4
      },
      "glossary": {
        "idx": {
          "/application": {
            "requestable": true,
            "testInt": "0"
          }
        },
        "types": [
          {
            "attrKey": "/application",
            "modified": "2024-06-05T22:12:51.892Z",
            "type": "entityType/id/realm"
          }
        ]
      },
      "descriptor": {
        "idx": {
          "/entitlement": {
            "displayName": "Customer Support - QA"
          }
        }
      },
      "entitlement": {
        "__NAME__": "Customer Support - QA",
        "_id": "ac77bdcb-659f-4276-beb9-14604d62986e",
        "displayName": "Customer Support - QA",
        "id": "ac77bdcb-659f-4276-beb9-14604d62986e",
        "mailEnabled": false,
        "securityEnabled": true
      },
      "assignment": {
        "_rev": "c528ae0a-b382-424a-8af1-f08c11af5abc-21526",
        "attributes": [
          {
            "name": "memberOf",
            "value": [
              "ac77bdcb-659f-4276-beb9-14604d62986e"
            ]
          }
        ],
        "description": "ac77bdcb-659f-4276-beb9-14604d62986e",
        "fr": {
          "realm": "alpha"
        },
        "id": "system_Targettestigaautom1___GROUP___ac77bdcb-659f-4276-beb9-14604d62986e",
        "mapping": "managedAlpha_user_systemTargettestigaautom1User",
        "metadata": {
          "entityType": "/openidm/managed/assignment",
          "created": "2024-04-17T00:50:43.452Z"
        },
        "name": "Customer Support - QA",
        "type": "__ENTITLEMENT__"
      },
      "application": {
        "_rev": "c528ae0a-b382-424a-8af1-f08c11af5abc-21516",
        "authoritative": false,
        "connectorId": "Targettestigaautom1",
        "description": "Target AD App",
        "fr": {
          "realm": "alpha"
        },
        "icon": "",
        "id": "bb97f388-8c11-4314-9691-22a9f1a799df",
        "mappingNames": [
          "systemTargettestigaautom1User_managedAlpha_user",
          "systemTargettestigaautom1__group___managedAlpha_assignment",
          "managedAlpha_user_systemTargettestigaautom1User",
          "systemTargettestigaautom1Directoryrole_managedAlpha_assignment"
        ],
        "metadata": {
          "entityType": "/openidm/managed/application",
          "created": "2024-06-05T22:12:40.911Z"
        },
        "name": "Targettestigaautom1",
        "templateName": "azure.ad",
        "templateVersion": "2.2"
      },
      "catalog": {
        "id": "81cbcb5edbb422f68b5407ccf0987714c6418051fffdb132649eafaa4b436d02f4402a9820d48af843230186cfb033ec4e21431778ef1796fef2ad47423957e0"
      },
      "keys": {
        "usr_id": "44aac3af-23ae-47ad-a760-e5f4d94da54b",
        "ent_id": "system_Targettestigaautom1___GROUP___ac77bdcb-659f-4276-beb9-14604d62986e"
      },
      "compositeId": "bae206ad1fa95d701344e2a7050cd2ee54e607d4fe1da2cdcd2b07b6522b5deafb1ab03326d95f18b6ca659fa0a84539ce3cb54a80ddbf6f7284e73e4caec274",
      "latestCreationTime": 1731096658.93
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 0,
  "resultCount": 0
}

Workflow

To use the iga/governance/workflow and iga/governance/audit endpoints, your authorization token must have the following scope:

fr:idc:analytics.*

This is a temporary requirement and will be removed in a future release.

5

URI HTTP
method		 Description

/iga/governance/workflow

GET

Get the workflow definitions.

Parameters
Name Description

_searchAfter string

Elasticsearch after key. Used for pageNumber.

_pagedResultsOffset string

Offset number of the record from which to start the paginated results.

_pageSize string

Number of documents to return.

_queryString string

String to filter the workflows. Matches the workflow displayName, description, and name keys.
Responses
Code Description

201

Creation success. Returns the saved workflow object.

/iga/governance/workflow

Post

Create and/or publish workflow definitions.

Parameters
Name Description

_action string * required

Action to be performed for the workflow endpoint. The available values are create, validate, publish, and execute.
Request body * required

Media type: application/json

{
  "id": "string",
  "name": "string",
  "displayName": "string",
  "description": "string",
  "type": "provisioning",
  "steps": [
    {
      "name": "string",
      "displayName": "string",
      "type": "scriptTask",
      "scriptTask": {
        "language": "javascript",
        "gatewayType": "inclusive",
        "script": "logger.info(\"Auto-Deprovisioning\");\n\nvar content = execution.getVariables();\nvar requestId = content.get('id');\nvar failureReason = null;\n\ntry {\n var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});\n logger.info(\"requestObj: \" + requestObj);\n}\ncatch (e) {\n failureReason = \"Deprovisioning failed: Error reading request with id \" + requestId;\n}\n\nif(!failureReason) {\n try {\n var request = requestObj.request;\n var payload = {\n \"roleId\": request.common.roleId,\n \"startDate\": request.common.startDate,\n \"endDate\": request.common.endDate,\n \"auditContext\": {},\n \"grantType\": \"request\"\n };\n var queryParams = {\n \"_action\": \"remove\"\n }\n\n var result = openidm.action('iga/governance/user/' + request.common.userId + '/roles' , 'POST', payload,queryParams);\n }\n catch (e) {\n failureReason = \"Deprovisioning failed: Error deprovisioning role to user \" + request.common.userId + \" for role \" + request.common.roleId + \". Error message: \" + e.message;\n }\n \n var decision = {'status': 'complete'};\n if (failureReason) {\n decision.outcome = 'not provisioned';\n decision.comment = failureReason;\n decision.failure = true;\n }\n else {\n decision.outcome = 'provisioned';\n }\n\n var queryParams = { '_action': 'update'};\n openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);\n logger.info(\"Request \" + requestId + \" completed.\");\n}",
        "nextStep": [
          {
            "condition": "string",
            "outcome": "string",
            "step": "string"
          }
        ]
      }
    },
    {
      "name": "string",
      "displayName": "string",
      "type": "approvalTask",
      "nextStep": [
        {
          "condition": "string",
          "outcome": "string",
          "step": "string"
        }
      ],
      "actors": [
        {
          "id": {
            "value": "string",
            "isExpression": true
          },
          "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
          }
        }
      ],
      "events": {
        "assignment": {
          "notification": "string"
        },
        "reassign": {
          "notification": "string"
        },
        "reminder": {
          "notification": "string",
          "frequency": 0,
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "escalation": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "expiration": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              },
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          },
          "action": "string"
        }
      }
    },
    {
      "name": "string",
      "displayName": "string",
      "type": "approvalTask",
      "nextStep": [
        {
          "condition": "string",
          "outcome": "string",
          "step": "string"
        }
      ],
      "actors": [
        {
          "id": {
            "value": "string",
            "isExpression": true
          },
          "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
          }
        }
      ],
      "events": {
        "assignment": {
          "notification": "string"
        },
        "reassign": {
          "notification": "string"
        },
        "reminder": {
          "notification": "string",
          "frequency": 0,
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "escalation": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "expiration": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              },
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          },
          "action": "string"
        }
      }
    }
  ]
}
Responses
Code Description

200

OK

400

Invalid data provided.

500

Server error on save.
Click for an example response

Media type: application/json

{}

/iga/governance/workflow/{id}/{status}

GET

Get the workflow definition.

Parameters
Name Description

id string * required

ID of the workflow.

status string * required

Status of the workflow.
Responses
Code Description

200

OK

400

Bad request

404

Workflow with ID wasn’t found

500

Internal service error
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "displayName": "string",
  "description": "string",
  "type": "provisioning",
  "steps": [
    {
      "name": "string",
      "displayName": "string",
      "type": "scriptTask",
      "scriptTask": {
        "language": "javascript",
        "gatewayType": "inclusive",
        "script": "logger.info(\"Auto-Deprovisioning\");\n\nvar content = execution.getVariables();\nvar requestId = content.get('id');\nvar failureReason = null;\n\ntry {\n var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});\n logger.info(\"requestObj: \" + requestObj);\n}\ncatch (e) {\n failureReason = \"Deprovisioning failed: Error reading request with id \" + requestId;\n}\n\nif(!failureReason) {\n try {\n var request = requestObj.request;\n var payload = {\n \"roleId\": request.common.roleId,\n \"startDate\": request.common.startDate,\n \"endDate\": request.common.endDate,\n \"auditContext\": {},\n \"grantType\": \"request\"\n };\n var queryParams = {\n \"_action\": \"remove\"\n }\n\n var result = openidm.action('iga/governance/user/' + request.common.userId + '/roles' , 'POST', payload,queryParams);\n }\n catch (e) {\n failureReason = \"Deprovisioning failed: Error deprovisioning role to user \" + request.common.userId + \" for role \" + request.common.roleId + \". Error message: \" + e.message;\n }\n \n var decision = {'status': 'complete'};\n if (failureReason) {\n decision.outcome = 'not provisioned';\n decision.comment = failureReason;\n decision.failure = true;\n }\n else {\n decision.outcome = 'provisioned';\n }\n\n var queryParams = { '_action': 'update'};\n openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);\n logger.info(\"Request \" + requestId + \" completed.\");\n}",
        "nextStep": [
          {
            "condition": "string",
            "outcome": "string",
            "step": "string"
          }
        ]
      }
    },
    {
      "name": "string",
      "displayName": "string",
      "type": "approvalTask",
      "nextStep": [
        {
          "condition": "string",
          "outcome": "string",
          "step": "string"
        }
      ],
      "actors": [
        {
          "id": {
            "value": "string",
            "isExpression": true
          },
          "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
          }
        }
      ],
      "events": {
        "assignment": {
          "notification": "string"
        },
        "reassign": {
          "notification": "string"
        },
        "reminder": {
          "notification": "string",
          "frequency": 0,
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "escalation": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "expiration": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              },
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          },
          "action": "string"
        }
      }
    },
    {
      "name": "string",
      "displayName": "string",
      "type": "approvalTask",
      "nextStep": [
        {
          "condition": "string",
          "outcome": "string",
          "step": "string"
        }
      ],
      "actors": [
        {
          "id": {
            "value": "string",
            "isExpression": true
          },
          "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
          }
        }
      ],
      "events": {
        "assignment": {
          "notification": "string"
        },
        "reassign": {
          "notification": "string"
        },
        "reminder": {
          "notification": "string",
          "frequency": 0,
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "escalation": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "expiration": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              },
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          },
          "action": "string"
        }
      }
    }
  ]
}

/iga/governance/workflow/{id}/{status}

DELETE

Delete the workflow definition. If the status is published, it will try to delete the workflow model and process the definition in IDM.

Parameters
Name Description

id string * required

ID of the workflow.

status string * required

Status of the workflow.
Responses
Code Description

200

OK
Click for an example response

Media type: application/json

{
  "result": [
    {
      "role": {
        "_rev": "9b32dc1c-c0fe-4cf6-a24c-2b9374dd15ad-820870",
        "description": "Test",
        "fr": {
          "realm": "alpha"
        },
        "id": "7136a3c4-0c12-488a-8cfd-2fd71a24e4bd",
        "metadata": {
          "entityType": "/openidm/managed/role",
          "created": "2024-09-09T15:28:28.887Z"
        },
        "name": "Approver Role"
      },
      "user": {
        "_rev": "9b32dc1c-c0fe-4cf6-a24c-2b9374dd15ad-1200974",
        "accountStatus": "active",
        "cn": "Ariela Stonuary",
        "custom_debugObj": {
          "task-started": "2024-09-04T21:08:01.019057006"
        },
        "custom_debugObjTwo": {
          "task-completed": "2024-09-04T21:08:01.290865442"
        },
        "description": "updateNow1",
        "fr": {
          "realm": "alpha"
        },
        "givenName": "Ariela",
        "id": "e8224d8b-a5b6-4120-83d4-fd9b69844aca",
        "mail": "Ariela@IGATestQA.onmicrosoft.com",
        "metadata": {
          "created": "2024-09-06T15:31:18.399Z",
          "entityType": "/openidm/managed/user",
          "version": 7
        },
        "preferences": {
          "marketing": false,
          "updates": false
        },
        "sn": "Stonuary",
        "userId": "e8224d8b-a5b6-4120-83d4-fd9b69844aca",
        "userName": "Ariela@IGATestQA.onmicrosoft.com"
      },
      "catalog": {
        "id": "87b51036e699e772f9e4f81617f5e3adb6c012974a594e6aa4bc50254419be7ccf7d26c85b42df8fa7147798a75966cad432528eef9e9f32f4f78c4a4607c4c"
      },
      "compositeId": "e546e458a04626344e478139309b21f35fcba24e1f9429a19c769897d3928c66408cdd50f9e08170fb810751bd70ca929840c894e346d11126c57326e7d9a33d",
      "glossary": {
        "idx": {
          "/role": {
            "requestable": true,
            "roleOwner": "managed/user/153e48df-12fa-4499-9078-4bdf5c62c3ea"
          }
        },
        "types": [
          {
            "attrKey": "/role",
            "modified": "2024-09-12T12:51:42.108Z",
            "type": "entityType/id/realm"
          }
        ]
      },
      "item": {
        "type": "roleMembership"
      },
      "keys": {
        "type": "roleMembership",
        "roleId": "7136a3c4-0c12-488a-8cfd-2fd71a24e4bd",
        "userId": "e8224d8b-a5b6-4120-83d4-fd9b69844aca"
      },
      "relationship": {
        "id": "7065a955-275f-4e70-969b-4cf19c479af6-8621418",
        "conditional": false
      },
      "metadata": {
        "modifiedDate": "2024-09-12T12:57:46.847Z",
        "createdDate": "2024-09-03T13:08:13.306772183Z"
      }
    }
  ],
  "searchAfterKey": [
    "a321329c-a7e6-47ad-8349-99b6e38f9a59"
  ],
  "totalCount": 0,
  "resultCount": 0
}

/iga/governance/workflow/{id}

PUT

Update or publish the workflow definition.

Parameters
Name Description

id string * required

ID of the workflow.
Request body * required 
{
  "id": "string",
  "name": "string",
  "displayName": "string",
  "description": "string",
  "type": "provisioning",
  "steps": [
    {
      "name": "string",
      "displayName": "string",
      "type": "scriptTask",
      "scriptTask": {
        "language": "javascript",
        "gatewayType": "inclusive",
        "script": "logger.info(\"Auto-Deprovisioning\");\n\nvar content = execution.getVariables();\nvar requestId = content.get('id');\nvar failureReason = null;\n\ntry {\n var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});\n logger.info(\"requestObj: \" + requestObj);\n}\ncatch (e) {\n failureReason = \"Deprovisioning failed: Error reading request with id \" + requestId;\n}\n\nif(!failureReason) {\n try {\n var request = requestObj.request;\n var payload = {\n \"roleId\": request.common.roleId,\n \"startDate\": request.common.startDate,\n \"endDate\": request.common.endDate,\n \"auditContext\": {},\n \"grantType\": \"request\"\n };\n var queryParams = {\n \"_action\": \"remove\"\n }\n\n var result = openidm.action('iga/governance/user/' + request.common.userId + '/roles' , 'POST', payload,queryParams);\n }\n catch (e) {\n failureReason = \"Deprovisioning failed: Error deprovisioning role to user \" + request.common.userId + \" for role \" + request.common.roleId + \". Error message: \" + e.message;\n }\n \n var decision = {'status': 'complete'};\n if (failureReason) {\n decision.outcome = 'not provisioned';\n decision.comment = failureReason;\n decision.failure = true;\n }\n else {\n decision.outcome = 'provisioned';\n }\n\n var queryParams = { '_action': 'update'};\n openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);\n logger.info(\"Request \" + requestId + \" completed.\");\n}",
        "nextStep": [
          {
            "condition": "string",
            "outcome": "string",
            "step": "string"
          }
        ]
      }
    },
    {
      "name": "string",
      "displayName": "string",
      "type": "approvalTask",
      "nextStep": [
        {
          "condition": "string",
          "outcome": "string",
          "step": "string"
        }
      ],
      "actors": [
        {
          "id": {
            "value": "string",
            "isExpression": true
          },
          "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
          }
        }
      ],
      "events": {
        "assignment": {
          "notification": "string"
        },
        "reassign": {
          "notification": "string"
        },
        "reminder": {
          "notification": "string",
          "frequency": 0,
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "escalation": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "expiration": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              },
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          },
          "action": "string"
        }
      }
    },
    {
      "name": "string",
      "displayName": "string",
      "type": "approvalTask",
      "nextStep": [
        {
          "condition": "string",
          "outcome": "string",
          "step": "string"
        }
      ],
      "actors": [
        {
          "id": {
            "value": "string",
            "isExpression": true
          },
          "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
          }
        }
      ],
      "events": {
        "assignment": {
          "notification": "string"
        },
        "reassign": {
          "notification": "string"
        },
        "reminder": {
          "notification": "string",
          "frequency": 0,
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "escalation": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "expiration": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              },
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          },
          "action": "string"
        }
      }
    }
  ]
}
Responses
Code Description

200

OK

400

Bad request

404

Workflow with ID wasn’t found

500

Internal service error
Click for an example response

Media type: application/json

{
  "id": "string",
  "name": "string",
  "displayName": "string",
  "description": "string",
  "type": "provisioning",
  "steps": [
    {
      "name": "string",
      "displayName": "string",
      "type": "scriptTask",
      "scriptTask": {
        "language": "javascript",
        "gatewayType": "inclusive",
        "script": "logger.info(\"Auto-Deprovisioning\");\n\nvar content = execution.getVariables();\nvar requestId = content.get('id');\nvar failureReason = null;\n\ntry {\n var requestObj = openidm.action('iga/governance/requests/' + requestId, 'GET', {}, {});\n logger.info(\"requestObj: \" + requestObj);\n}\ncatch (e) {\n failureReason = \"Deprovisioning failed: Error reading request with id \" + requestId;\n}\n\nif(!failureReason) {\n try {\n var request = requestObj.request;\n var payload = {\n \"roleId\": request.common.roleId,\n \"startDate\": request.common.startDate,\n \"endDate\": request.common.endDate,\n \"auditContext\": {},\n \"grantType\": \"request\"\n };\n var queryParams = {\n \"_action\": \"remove\"\n }\n\n var result = openidm.action('iga/governance/user/' + request.common.userId + '/roles' , 'POST', payload,queryParams);\n }\n catch (e) {\n failureReason = \"Deprovisioning failed: Error deprovisioning role to user \" + request.common.userId + \" for role \" + request.common.roleId + \". Error message: \" + e.message;\n }\n \n var decision = {'status': 'complete'};\n if (failureReason) {\n decision.outcome = 'not provisioned';\n decision.comment = failureReason;\n decision.failure = true;\n }\n else {\n decision.outcome = 'provisioned';\n }\n\n var queryParams = { '_action': 'update'};\n openidm.action('iga/governance/requests/' + requestId, 'POST', decision, queryParams);\n logger.info(\"Request \" + requestId + \" completed.\");\n}",
        "nextStep": [
          {
            "condition": "string",
            "outcome": "string",
            "step": "string"
          }
        ]
      }
    },
    {
      "name": "string",
      "displayName": "string",
      "type": "approvalTask",
      "nextStep": [
        {
          "condition": "string",
          "outcome": "string",
          "step": "string"
        }
      ],
      "actors": [
        {
          "id": {
            "value": "string",
            "isExpression": true
          },
          "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
          }
        }
      ],
      "events": {
        "assignment": {
          "notification": "string"
        },
        "reassign": {
          "notification": "string"
        },
        "reminder": {
          "notification": "string",
          "frequency": 0,
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "escalation": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "expiration": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              },
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          },
          "action": "string"
        }
      }
    },
    {
      "name": "string",
      "displayName": "string",
      "type": "approvalTask",
      "nextStep": [
        {
          "condition": "string",
          "outcome": "string",
          "step": "string"
        }
      ],
      "actors": [
        {
          "id": {
            "value": "string",
            "isExpression": true
          },
          "permissions": {
            "approve": true,
            "reject": true,
            "reassign": true,
            "modify": true,
            "comment": true
          }
        }
      ],
      "events": {
        "assignment": {
          "notification": "string"
        },
        "reassign": {
          "notification": "string"
        },
        "reminder": {
          "notification": "string",
          "frequency": 0,
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "escalation": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          }
        },
        "expiration": {
          "notification": "string",
          "actors": [
            {
              "id": {
                "value": "string",
                "isExpression": true
              },
              "permissions": {
                "approve": true,
                "reject": true,
                "reassign": true,
                "modify": true,
                "comment": true
              }
            }
          ],
          "date": {
            "isExpression": true,
            "value": "string"
          },
          "action": "string"
        }
      }
    }
  ]
}

Evolving APIs

The APIs referenced in this section are evolving, which means they can change or become deprecated at any time.

The current evolving APIs focus on entitlements. You can find more information in Manage entitlements.

URI HTTP
method		 Description

/iga/governance/resource/{id}

GET

Get an entitlement by an ID.

/iga/governance/resource/search

POST

Search for a list of all entitlements that match the target filter.

/iga/governance/resource/{id}/assignments/user

GET

Gets the users assigned to a specific entitlement.

Deprecated

These endpoints are no longer being updated and might be removed in a future release.

URI HTTP
method		 Description

/iga/governance/resource/{id}

GET

Returns the entitlement with the provided ID.

/iga/governance/resource/search

POST

Searches for entitlements that match a query.

/iga/governance/resource/{id}/assignments/user

GET

Returns users assigned the given entitlement.

Supported browsers

The following browsers are supported in PingOne Advanced Identity Cloud:

Browser Version

Google Chrome

Latest stable version of full-desktop browser

Firefox

Latest stable version of full-desktop browser

Safari

Latest stable version of full-desktop browser

Microsoft Edge

Latest stable version of full-desktop browser

Ping Identity does not provide support for these browsers:

  • Internet Explorer 11

  • Microsoft Edge in Internet Explorer compatibility mode

  • Embedded browsers within any application (for example, within Citrix environments or Office 365)

Ping Identity optimizes its platform for modern browsers to ensure the best user experience, security, and performance. If you encounter issues while using the Ping Identity platform, ensure you use a supported, up-to-date browser for the optimal experience.

While Advanced Identity Cloud works with all supported browsers, administrative activity works best using Google Chrome.

Security and compliance

PingOne Advanced Identity Cloud provides full tenant isolation in a multi-tenant cloud service by using individual trust zones. Each customer’s environment is a dedicated trust zone that shares no code, data, or identities with other customers’ environments. This prevents any accidental or malicious commingling. All data is encrypted, at rest and in transmission, to prevent unauthorized access and data breaches.

Certifications and compliance

SOC 2 Type 2

soc2 logo

Ping Identity is SOC 2 Type 2-certified. This confirms that Ping Identity’s information security practices, policies, procedures, and operations meet the SOC 2 standards for security, availability, and confidentiality. Our adherence to these standards is externally validated by an independent third party annually.

Our SOC 2 report is available to customers under an NDA on the Ping Identity Support Portal.

ISO 27001, 27017 and 27018

iso logo

Ping Identity’s information security management system (ISMS) has been independently assessed and certified to the ISO 27001 standard. Ping Identity has included ISO 27017 and ISO 27018 into its certified ISMS and has also achieved independent certifications validating that the controls and implementation guidance relevant to those standards are in place and operational.

The scope of Ping Identity’s ISMS covers all major offices used in the development of Ping Identity products, all of our product offerings, both standalone on-premises products and our cloud services (PingOne, PingOne Advanced Services, and Advanced Identity Cloud), as well as all supporting infrastructure, systems, and internal processes.

Our ISO 27001 certificate is available in the Shellman Certificate Directory by searching for Ping Identity.

CSA STAR (Level 2)

csa logo

Ping Identity’s cloud offerings are certified as meeting the criteria of the Cloud Security Alliance Cloud Controls Matrix (Version 4). Our CSA STAR (Level 2) Attestation demonstrates Ping Identity’s commitment to high standards and industry-accepted cloud security controls and transparency of our security posture.

Our attestation and the CSA Consensus Assessments Initiative Questionnaire are available on the CSA STAR (Level 2) Registry Page.

HIPAA and HITECH

hipaa logo

The Health Insurance Portability and Accountability Act (HIPAA) is the US national standard for health information security and privacy that governs the use and disclosure of sensitive protected health information (PHI).

Advanced Identity Cloud complies with HIPAA security standards, as well as the breach notification requirements of the Health Information Technology for Economic and Clinical Health (HITECH) Act. Learn more about how Ping Identity supports HIPAA compliance.

Trusted Information Security Assessments Exchange

tisax logo

The Trusted Information Security Assessment Exchange (TISAX) is an assessment and exchange mechanism for the information security of enterprises governed by ENX on behalf of the German VDA. The exchange allows recognition of assessment results among the participants. TISAX can be accessed by active participants through https://enx.com/tisax. TISAX and TISAX results are not intended for general public use.

ForgeRock Inc. and ForgeRock Ltd. (Ping Identity) are active TISAX participants with assessment results available through the ENX portal - Tisax assessment results, under scope ID: SZZMC3 and assessment ID: AZ5YYL-1.

Security white paper

Learn more about our security practices in our security white paper.

Identity Cloud product lifecycle and releases

PingOne Advanced Identity Cloud releases new features, updates functionality and fixes bugs on a continual cadence. Ping Identity aims to deliver features and functionality that will be the most useful, complete and intuitive for customers. In order to deliver on this goal we have several stages to our release lifecycle.

Early access

Participating in Early Access programs allow customers to provide feedback and collaborate with Ping Identity in designing future capabilities in the product.

Select customers are invited to provide feedback on new features. Customers are encouraged to give feedback and have an active say in product direction; product management and customer success will work with you to gather feedback. Features may be unstable, changed in backward-incompatible ways, and are not guaranteed to be released. We will use all reasonable efforts to communicate breaking changes to customers participating in the program.

Beta

Beta features give customers advanced insights into up-and-coming product capabilities with extra time to prepare to adopt the feature and provide design feedback to the product team. Generally speaking, functionality is stable and meets security and quality expectations but please note that a beta feature is not officially supported for production use.

Upcoming features

Customers receive notifications of new and upcoming features at least a week in advance of a release. The notifications provide customers with high-level information on changes or new functionality.

Limited availability

Features are available for production use and are fully functional and supported; however, they are available only to a select set of customers.

General availability

Features are available for production use and are fully functional and supported. They are available to all customers.

Migration dependent features

Features are not backward compatible and require a tenant migration before they can be used. Learn more in Migration dependent features.

Bug fixes and low impact changes

On an ongoing basis, Ping Identity makes bug fixes and low impact changes as necessary to Advanced Identity Cloud. These types of fixes are deployed as necessary. You can monitor these in the Regular channel changelog and Rapid channel changelog. You can also subscribe to the RSS feeds mentioned at the start of the two changelog pages.

Deprecation and end of life

To maintain both security and quality in Advanced Identity Cloud, we periodically have to modify or remove functionality.

Learn more in Deprecation Notices.

Deprecated features

A feature or behavior (or API endpoint) flagged for deprecation means it is no longer actively enhanced and is minimally maintained. Tenants using the feature at the time of deprecation will continue to have access to the feature until it reaches end of life, at which point customers will no longer have access to the feature. We know deprecation disruptions are inconvenient, and as such, we attempt to limit the frequency of deprecations and to pair them with alternative options and migration recommendations where available.

Deprecation notification

Deprecation information is posted to the Advanced Identity Cloud documentation. Deprecation notices typically include a date the feature or behavior reaches end of life. Our policy is to flag a feature for deprecation with at least 12 months advance notice prior to end of life whenever possible to allow a 12 month migration window.

Periodically, and in case of emergency (critical vulnerabilities or changes required by applicable law or third-party certification standards), we may accelerate this time frame. In such cases, we will provide as much prior notice as is reasonable under the circumstances.

During deprecation

Customers should engage in a migration to move away from the deprecated feature or behavior.

End of life

Features that reach the end of life stage are removed from the platform. Continued use of these features will likely result in errors.

Tenant administrator mandatory 2-step verification FAQ

How is 2-step verification changing?

Ping Identity is making 2-step verification mandatory for all PingOne Advanced Identity Cloud tenant administrators.

The option to skip registration for 2-step verification is deprecated and will be removed a year after the deprecation notification date (Friday, February 3, 2023), following the Advanced Identity Cloud deprecation and end of life policy.

idcloudui tenant administrator set up 2 step verification skip deprecated

After the option to skip registration is removed, any tenant administrator that has not already set up 2-step verification will be forced to do so the next time they sign in. Advanced Identity Cloud guides the tenant administrator through the device registration process, with no assistance needed from Ping Identity support.

Will the change to mandatory 2-step verification affect me?

Yes, this change affects all customers. You have until the deprecation end-of-life date (Tuesday, April 2, 2024) to update your tenants to make 2-step verification mandatory for all tenant administrators.

How do I prepare my tenants to support 2-step verification?

If you have any automation that relies on the skip option to authenticate to Advanced Identity Cloud APIs, it must be updated to use a service account to get an access token.

After 2-step verification is enforced, any automation that depends on the skip option will fail authentication.

How do I enable mandatory 2-step verification for my tenants?

  1. Make sure you have updated any automation that authenticates to Advanced Identity Cloud APIs to use a service account. Learn more in How do I prepare my tenants to support 2-step verification?.

  2. Open a support case with Ping Identity support:

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

    2. Click Create a case.

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

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

      Field Value

      What product family is experiencing the issue?

      Select PingOne Advanced Identity Cloud

      What specific product is experiencing the issue?

      Select Configuration

      What version of the product are you using?

      Select NA

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

      Field Value

      Provide a descriptive title for your issue

      Enter Enforce 2-step verification for tenant administrators

      Describe the issue below

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

    6. Click Submit.

  3. Ping Identity support turns on the enforcement of 2-step verification for your tenant administrators and then asks you to verify that everything is working as expected.

Application management migration FAQ

Application management allows you to manage the security and access of common and custom relying-party applications and SAML 2.0 applications directly from PingOne Advanced Identity Cloud. This functionality is most commonly used to manage data and system access for employees within an organization, commonly referred to as workforce identity and access management.

How is application management changing?

Ping Identity has improved application management by introducing a single UI interface to the Advanced Identity Cloud admin console that manages all aspects of an application relevant to Advanced Identity Cloud. This replaces the previous arrangement, which required a combination of actions across the Advanced Identity Cloud admin console, AM admin console, and IDM admin console. In addition, Ping Identity has introduced an application catalog to speed up application configuration for common use cases.

How is the improved application management UI being introduced?

The improved application management UI is only available in tenants created on or after January 12, 2023.

What documentation should I use?

How can I upgrade my tenants?

There are no instructions yet on how to upgrade your tenants.

Group identity migration FAQ

What has changed?

Ping Identity has introduced a group identity to PingOne Advanced Identity Cloud to simplify the management of permissions and authorizations for collections of users.

How is the group identity being introduced?

Tenants created on or after November 29, 2022 have the group identity enabled by default. Tenants created before that date can follow an upgrade path to enable it; learn more in Enable groups.

Does this affect any other features?

Yes. If you have not upgraded your tenant, event hooks are not available for group identities.

What documentation should I use?

Learn more in Group management.

Deprecation notices

For information about the PingOne Advanced Identity Cloud product lifecycle and deprecation, learn more in Deprecation and end of life.

IDC.CLI OAuth 2.0 client

Notification date

June 24, 2025

Ping Identity is no longer provisioning the IDC.CLI OAuth 2.0 client in new tenants and has deprecated it in existing tenants.

If you have any automation or scripts that rely on using the IDC.CLI OAuth 2.0 client in existing tenants, you must update them to use a service account before the end-of-life date when the client will be removed.

End-of-life date

June 26, 2026

Access to ESV REST API endpoints using resource version 1.0

Notification date

June 24, 2025

Ping Identity has deprecated the use of resource version 1.0 to access ESV REST API endpoints in Advanced Identity Cloud.

In the short term, you can continue to use the 1.0 resource version to access to ESV REST API endpoints, but this won’t be possible after the end-of-life date.

If you have any automation or scripts that rely on using the 1.0 resource version for ESV REST API endpoints, you must update them to use resource version 2.0 before the end-of-life date.

End-of-life date

June 26, 2026

Access to ESV REST API endpoints using fr:idm:* scope

Notification date

June 24, 2025

Ping Identity has deprecated use of the fr:idm:* scope to access ESV REST API endpoints in Advanced Identity Cloud.

In the short term, you can continue to use the scope to access ESV REST API endpoints, but this won’t be possible after the end-of-life date.

If you have any automation or scripts that rely on using the scope for ESV REST API endpoints, you must update them to use the fr:idc:esv:* scope or an appropriate child scope (fr:idc:esv:read, fr:idc:esv:update, or fr:idc:esv:restart) before the end-of-life date.

End-of-life date

June 26, 2026

Autonomous Access

Notification date

November 18, 2024

Ping Identity has deprecated Autonomous Access. The product will reach end of life on October 31, 2025. During the deprecation period, Ping Identity will not provide new patches, updates, or new features for Autonomous Access.

To support our Autonomous Access customers, we’re providing migration assistance to PingOne Protect. This advanced threat detection solution leverages machine learning to analyze authentication signals and detect abnormal online behavior. PingOne Protect is a well-established product trusted by hundreds of customers worldwide.

The Autonomous Access documentation has moved to the documentation archive at https://docs.pingidentity.com/archive/.

End-of-life date

October 31, 2025

Duo authentication node

Notification date

March 5, 2024

ForgeRock has deprecated the Duo authentication node because Duo has deprecated Traditional Duo Prompt that is used by the Duo node.

ForgeRock created Duo Universal Prompt node in anticipation of this depreciation. You should use Duo Universal Prompt node instead of Duo node (Deprecated).

End-of-life date

September 30, 2024

Introspect endpoint GET requests and URL query string parameters

Notification date

July 19, 2023

ForgeRock has deprecated the following behaviors of the OAuth 2.0 introspect endpoint in Advanced Identity Cloud:

  • Accept GET requests

  • Accept data in POST requests from URL query string parameters

You can continue to use these behaviors, but they will be removed on July 19, 2024. Instead, when using the OAuth 2.0 introspect endpoint, you should use POST requests and pass data in the POST request body.

End-of-life date

July 19, 2024

Health check endpoints

Notification date

June 13, 2023

ForgeRock has deprecated the following Advanced Identity Cloud health check endpoints:

  • /am/isAlive.jsp

  • /am/json/health/live

  • /am/json/health/ready

  • /openidm/info/ping

You can continue to use the endpoints, but they will be removed on June 13, 2024. You should update any external monitoring to use the Advanced Identity Cloud /monitoring/health endpoint instead. Learn more in Monitor using health check endpoint.

End-of-life date

June 13, 2024

Skip option for 2-step verification registration for Advanced Identity Cloud tenant administrators

Notification date

February 3, 2023

ForgeRock has deprecated the option to let Advanced Identity Cloud tenant administrators skip 2-step verification. You can continue to use the skip option in your tenants, but this functionality will be removed from Advanced Identity Cloud on April 2, 2024. Learn more in Tenant administrator mandatory 2-step verification FAQ.

End-of-life date

April 2, 2024

ForgeRock Identity Cloud Email Server Service

Notification date

April 12, 2021

Built-in Email Server Service

ForgeRock no longer supports the default email provider settings for use in production. The default email provider settings will only be available for testing purposes. Current customers can continue to use the default email provider settings for production purposes, but this functionality will reach end of life on April 12, 2022. Customers should move to using their own email provider.

End-of-life date

April 12, 2022

Groovy OIDC Custom Claims Script

Notification date

April 20, 2021

ForgeRock will continue to support the Groovy version of the OIDC custom claims script until it is end of lifed on April 20th 2022. Current customers can continue to use the Groovy version of the OIDC custom claims script for production purposes, but this functionality will reach end of life on April 20, 2022.

End-of-life date

April 20, 2022

Release process

Ping Identity continuously provides general availability (GA) releases to PingOne Advanced Identity Cloud to introduce new features, fix known issues, and address security issues.

GA releases are delivered through two channels:

  • Rapid channel releases contain the newest GA release features and fixes and are deployed to sandbox[1] environments.

  • Regular channel releases contain established GA release features and fixes and are deployed to development, UAT[2], staging, and production environments.

Optionally, you can defer releases from the regular channel to your production environment to let you test and validate regular channel releases.

Release versions

Ping Identity gives each release in each channel a unique release version. The release version is numeric (for example, 15158.7) and increases with each successive release. A greater release version includes the changes from lesser release versions.

The release version is displayed in your tenant environments and in each published changelog entry to let you track which features are in your tenant environments.

Rapid channel

If you have a sandbox[1] environment, a continuous stream of the newest features and fixes are deployed there as soon as they are ready for GA release. This lets you test and evaluate GA releases to make sure they are compatible with your Advanced Identity Cloud implementation. It also lets Ping Identity qualify and establish GA releases through cumulative usage and soak testing, typically over a two-week period. When a GA release has been established, it is allocated to the regular channel and deployed into your development, UAT[2], staging, and production environments.

For early access to documentation about features in the rapid channel, learn more in Rapid channel features.

Track rapid channel releases

You can track rapid channel releases in these ways:

Regular channel

Only established GA releases are deployed to your development, UAT[2], staging, and production environments. Typically, two weeks' worth of GA releases in the rapid channel are rolled up into one release to the regular channel 2–4 weeks later[17].

Track regular channel releases

You can track regular channel releases in these ways:

Release deferral

Release deferral is a limited availability feature. It is also an opt-in feature. Contact your Ping Identity representative if you are interested.

Ping Identity lets you defer regular channel releases to your production tenant environments for up to seven days. This allows you to test and validate new regular channel releases in your lower environments (development, UAT[2], and staging) using your most up-to-date configuration.

Deployment options

During this seven-day deferral window, you have several options for managing the production release:

  • Default option: At the end of the seven-day deferral period, the regular channel release is automatically deployed to your production environment.

  • Self-service option:

    • Trigger the deployment of the new regular channel release to your production environment at any time by running a promotion from your staging environment to your production environment.

      The deployment of the new regular channel release to your production environment is triggered by the first promotion to that environment during the seven-day deferral period. This means that you must pause promotions to your production environment until you have validated the new release in your lower environments.

  • Support-assisted options:

    • Upgrade without promotion: Upgrade your production environment without promotion changes from staging. To do this, create a support case in the Ping Identity Support Portal to request an upgrade.

    • Promote without an upgrade: Promote configuration changes to production but wait to apply the release upgrade. To do this, create a support case in the Ping Identity Support Portal to request the configuration promotion. This option is only available if the configuration changes you’re promoting are compatible with the release version currently in your production environment.

      Learn more about configuration promotion and version compatibility

      If your changes were made after your staging environment was upgraded, they might depend on the new release and can’t be promoted without also upgrading production.

      Examples

      • Scenario 1: Compatible changes

        You made configuration changes before your staging environment was upgraded to the new release.

        The changes can be promoted to production without the release upgrade because they’re compatible with the older version.

      • Scenario 2: Incompatible changes

        You made configuration changes after your staging environment was upgraded.

        The changes can’t be promoted to production without the release upgrade because they could depend on features only available in the new version.

Additional considerations

  • If you’ve recently promoted an upgrade to production on a deferred release, you can roll back both the upgrade and the promotion by creating a support case in the Ping Identity Support Portal.

  • In the rare event that Ping Identity applies a hotfix to the regular channel release while you are testing it in the lower environments, the seven-day deferral period in your production environment is not extended. This ensures that Ping Identity can apply security updates quickly and effectively, without impacting the cadence of scheduled regular channel releases.

  • You can use the release information from your production environment to track the seven-day deferral period.

Hotfixes

In general, Ping Identity applies critical hotfixes to both the rapid and regular channels.

On occasion, Ping Identity can apply hotfixes as necessary to the rapid channel only. These hotfixes will be released to the regular channel at a later time.

Release notes

Advanced Identity Cloud provides the following changelogs as part of its release process:

speed
Rapid channel changelog

Newest GA release features and fixes, deployed to sandbox environments.
schedule
Regular channel changelog

Established GA release features and fixes, deployed to development, UAT, staging, and production environments.
Sandbox and UAT environments are add-on capabilities.

Scheduled release freezes

Rapid channel release freezes (all dates inclusive):

  • Tuesday, November 25, 2025 - Friday, November 28, 2025

  • Monday, December 22, 2025 - Friday, January 2, 2026

Regular channel release freezes (all dates inclusive):

  • Friday, November 21, 2025 - Tuesday, December 2, 2025

  • Monday, December 15, 2025 - Monday, January 5, 2026

During a release freeze, Ping Identity only makes critical updates.

Regular channel changelog

Subscribe to get automatic updates: Regular channel changelog RSS feed

For release notes published before December 2024, refer to the Regular channel changelog archive.

September 2025

03 Sept 2025

Version 18712.7

Enhancements

  • FRAAS-24857: CNAME verification is no longer required when creating a custom domain.

  • FRAAS-25547: The sender address for emails sent to Advanced Identity Cloud tenant administrators is now saas@pingidentity.com.

  • FRAAS-26063: You can now override the samlErrorPageUrl. To do so, configure an ESV variable named esv-global-saml-error-page-url and set its value to your SAML error page URL. If you don’t set this variable, Advanced Identity Cloud uses the default value of /saml2/jsp/saml2error.jsp.

Fixes

  • FRAAS-25734: Exception stacktraces in access management and identity management logs are now truncated to approximately 300-400 lines.

  • FRAAS-25821[18]: Fixed an issue that prevented IP rules in Proxy Connect from being disabled.

01 Sept 2025

Version 18368.14

Fixes

  • AME-32756: Fixed an issue with policy evaluation returning results from a stale policy index cache.

  • OPENDJ-11634: Advanced Identity Cloud now prevents searches with many results and no applicable index from overloading the system.

August 2025

19 Aug 2025

Version 18368.10

Enhancements

  • OPENAM-24384: Added javax.crypto.SecretKeyFactory, javax.crypto.spec.PBEKeySpec, and com.sun.crypto.provider.PBKDF2KeyImpl classes to the allowlist for the OAUTH2_ACCESS_TOKEN_MODIFICATION scripting context.

Fixes

  • OPENAM-24393[19]: Fixed an issue where the InnerTreeEvaluator node failed for authentication journeys initially accessed using REST without an authId.

12 Aug 2025

Version 18368.8

Key features
Policy binding for next-generation scripting (AME-26150)

The next-generation policy binding lets you access the policy engine API and evaluate policies from within scripts. The policy binding works in a similar way to the Request policy decisions for a specific resource API call.

Set Error Details node (AME-30968)

The Set Error Details node adds details to the JSON response when a journey ends in an error.

Monitor log entries in the admin console (FRAAS-25665)

Advanced Identity Cloud now provides a console for monitoring log entries in development and sandbox[1] environments. You can view, filter, and search log entries for specific log sources within a timeframe to quickly identify issues, track events, and ensure system security.

Learn more in Monitor log entries in the admin console.

This is a beta feature and is limited to development and sandbox[1] environments. It’s not available in production environments.
Custom WS-Fed applications (IAM-8261)

You can now create custom WS-Fed[6] applications for single sign-on (SSO).

Try In SDK button (IAM-8618)

A Try In SDK button has been added to the Details page for Native / SPA applications. This lets developers quickly test SDKs with dynamic configuration code snippets.

Enhancements

  • AME-31372[20]: An Agent journey is now available by default in both Alpha and Bravo realms. The Agent journey makes it easier to integrate with Ping Identity agents and gateways. It validates the agent credentials with an Agent Data Store Decision node.

  • AME-30050: You can now enable a next-generation script in the AM admin console native console to run after a Dynamic Client Registration request is processed.

  • AME-30716: Removed Failed to create SSO Token from logs at warning level. To observe these warnings, increase the log level to debug.

  • AME-30801: The Inner Tree Evaluator node now has an optional Error Outcome that lets you capture exception details if an exception occurs during the evaluation of the child journey.

  • FRAAS-25818: The built-in SMTP server in new tenants now has a limit of 10 emails per minute and a fixed email sender address with the format noreply@<tenant-fqdn>.

  • IAM-7581: Text wrapping in table views has been improved for readability.

  • IAM-8573: IDM now includes an endpoint to retrieve individual themes from the /themerealm configuration using either an ID or a _queryFilter by name. This improves performance and ensures reliable theme loading, even on slow networks.

  • IAM-8610: When you create an SSO application for Microsoft 365, the application now generates a signing certificate, which you can download or rotate as needed.

  • IAM-8633: You can now add, remove, and rearrange table columns for managed identities and application provisioning tables.

  • IAM-8925[21]: In Identity Governance, you can now configure actions that trigger automatically when a form first loads or when a user changes the value of a specific field.

  • OPENAM-22467: Customers can now provide any value in the typ header in JWTs.

  • Greater control over journey session duration and authenticated session timeouts:

    • OPENAM-23265: The Set Session Properties node now lets you customize the Maximum Session Time and Maximum Idle Time of the session granted at the end of the journey.

    • OPENAM-23290: The new Update Journey Timeout node lets you update the timeout of the journey.

    • OPENAM-23291: The Email Suspend node now lets you configure the Suspend Duration in minutes. This duration overrides existing global or realm settings.

    • OPENAM-23515: You can now set the suspend duration in next-generation scripted decision nodes when suspending the journey.

  • OPENAM-23438: Following WebAuthn registration and authentication, new information is added to the transient state.

  • OPENAM-20709: On successful authentication, the WebAuthn Authentication node now adds the UUID of the device (webauthnDeviceUuid) and the name of the device (webauthnDeviceName) to the shared state. This lets you track the use of biometric authentication and the device used to authenticate.

Fixes

  • AME-30969: If the OIDC Claims Plugin Type in the OAuth 2.0 provider is set to SCRIPTED but no script is selected, the userinfo endpoint now returns the sub claim, in compliance with the OIDC specification. Previously, the userinfo endpoint returned an empty JSON object. If you still require this behavior, set the esv-scripting-legacynulloidcclaimsscriptbehaviour ESV to true.

  • IAM-4397: Fixed an issue in the hosted journey pages where the prompt text for the Choice Collector node wasn’t fully visible and the default option wasn’t visible at all.

  • IAM-8632: Fixed an issue where validation errors were incorrectly displayed for pre-populated fields.

  • IAM-8789: Managed identity modals now correctly handle both single-value and array-based enum types.

  • IAM-8871: The hosted account pages no longer freeze and throw an error when editing details if there are empty custom enum array values.

  • IAM-8902: The application username field in SAML 2.0 NameID flows is now correctly set to uid instead of username.

  • IAM-8933: Fixed an issue in the Advanced Identity Cloud admin console when creating or modifying identity objects with a required boolean property. You can now set the value of the required boolean property to false.

  • IAM-9062: Hosted pages themes no longer continuously refresh when trying to set up or confirm two-factor authentication (2FA).

  • OPENAM-20749: For server-side OAuth 2.0 tokens, the /oauth2/introspect response can now overwrite the iss claim of the introspectable token. To enable this behavior, set the esv-enable-oauth2-sync-refresh-token-issuer ESV to false.

  • OPENAM-22928: When agents authenticate to Advanced Identity Cloud, the session created no longer expires.

  • OPENAM-23303[20]: Fixed an issue where access management scripts were failing to load because they contained strings that resembled configuration placeholders. The code that parses these scripts now correctly ignores configuration placeholders and any strings that resemble them.

    If you have access management scripts that reference ESVs, ensure that they use the correct syntax for ESVs. For example, for a script that references an ESV named esv-my-variable, use the syntax systemEnv.getProperty("esv.my.variable").

  • OPENAM-23334: You can now use the mergeShared and mergeTransient methods to add nested objects to ObjectAttributes.

  • OPENAM-23519: Improved error handling during WebAuthn registration when the Android lock screen isn’t enabled.

  • OPENAM-24159: Fixed an issue with Identity Assertion nodes failing if there are more than one in a journey.

Removed
Modules and chains (AME-30762)

The legacy PingAM authentication mechanism using modules and chains is enabled by default in Advanced Identity Cloud but has never been supported. Modules and chains remain enabled but have been removed from the Advanced Identity Cloud admin console.

Modules and chains will be removed entirely in the near future. If you’re using them for authentication, you must migrate to nodes and journeys as soon as possible.

Advanced Identity Cloud provides default journeys that replace the corresponding default modules and chains. Any default authentication processes that relied on modules and chains are unaffected by their removal.

July 2025

16 Jul 2025

Version 18076.4

No customer-facing features, enhancements, or fixes released.[22]

08 Jul 2025

Version 18076.3

Enhancements

  • AME-31379: Setting the new ESV esv-oauth2-provider-request-object-processing-enforced to true now lets admins enforce which validation rules are applied when processing OAuth 2.0 request objects.

  • FRAAS-25437: Tenant administrators with the tenant-auditor role can now use federated access to authenticate to Advanced Identity Cloud.

  • IAM-3441: Added pagination to all list views.

  • IAM-7265: You can now right-click a node in the journey editor to access a context menu.

  • IAM-7266: Added an action bar to the journey editor that lets you deselect or delete currently selected nodes.

  • IAM-7580: Pages now span the full width of the screen, improving navigation and usability.

  • IAM-8260: Advanced Identity Cloud now supports multiple WS-Fed[6] applications.

  • IAM-8640: The Release Notes link in Tenant Settings now opens the release notes for the tenant’s specific version.

  • IAM-8714[15]: You can now configure columns in the Identity Governance access review page.

  • OPENIDM-21206: Usernames and application names must now be unique, as enforced by the datastore.

Fixes

  • IAM-7413: The reCAPTCHA Enterprise node is now fully supported.

  • IAM-8489: Fixed an issue with the display of application logos in the hosted account pages.

  • IAM-8770: Fixed an issue with the calendar icon position in date fields.

  • IAM-8773: Fixed an issue where key actions such as realm login were blocked in older tenants with an unmodified original theme.

    The impact of the fix for IAM-8773 is that unmodified original themes in older tenants have been purposefully updated to add any missing theme properties that are present on the latest themes. This has been done to make them compatible with recent efficiency improvements to themes in the hosted account pages, but without changing their appearance.

    The missing properties will appear in your promotion reports, but this is expected and does not require you to take any action.

This section contains information about releases of other Ping Identity products that are often deployed as part of an Advanced Identity Cloud implementation. To take advantage of these updates, you must manually upgrade your RCS and PingGateway implementations.

03 Jul 2025

Version 17889.11

Fixes

  • IAM-8314[19]: Fixed an issue where setting ESVs in connector or provisioner configuration stops the Advanced Identity Cloud admin console from being able to update connectors or run a liveSync operation.

June 2025

29 Jun 2025

Version 17889.10

No customer-facing features, enhancements, or fixes released.[22]

24 Jun 2025

Version 17889.7

Key features
Tenant auditors (IAM-8086)

Advanced Identity Cloud now lets you invite tenant auditors to access the Advanced Identity Cloud admin console. Tenant auditors can view settings, configuration, and data but cannot modify them.

Learn more in Tenant administrator groups.

Enhancements

  • FRAAS-25155: Increased log batching size to avoid truncation of large JSON log entries.

  • ANALYTICS-868: The Tenant Admin Activity report has been changed to the Tenant Admin Initiated Entity Type Changes report. The new report provides more detailed and business-friendly insights into changes made by tenant administrators:

    • Field names added, deleted, or modified.

    • Before and after values of changed attributes (if applicable).

    • Business-friendly entity name and entity type changes to custom attributes and custom objects.

    Learn more in Tenant admin initiated entity type changes report.

  • IAM-8405: You can now duplicate out-of-the-box reports.

  • IAM-8591: Dynamic sorting for report results. You can now sort report results directly in the Advanced Identity Cloud admin console after running a report.

Fixes

  • FRAAS-25142: Fixed a memory issue in the ESV service.

  • FRAAS-25434: Fix issue causing source to sometimes be defined as unknown in /monitoring/logs/* endpoints.

  • FRAAS-25226: Allow a higher threshold for large JSON log entries before splitting them into smaller plaintext log entries.

Deprecations

  • FRAAS-23329: Access to ESV REST API endpoints using the fr:idm:* scope is now deprecated.

  • FRAAS-23330: Access to ESV REST API endpoints using resource version 1.0 is now deprecated.

  • FRAAS-25269: The IDC.CLI OAuth 2.0 client is now deprecated in existing tenants and no longer provisioned in new tenants.

Learn more in Deprecation notices.

17 Jun 2025

Version 17713.10

No customer-facing features, enhancements, or fixes released.[22]

16 Jun 2025

Version 17713.9

Fixes

FRAAS-25514: Addressed a security issue.

12 Jun 2025

Version 17713.8

No customer-facing features, enhancements, or fixes released.[22]

10 Jun 2025

Version 17713.5

Key features
Akamai Account Protector node (TNTP-227)[20]

Use the Akamai Account Protector node to inject the Akamai risk score into your authentication journey. When the Akamai Account Protector feature is enabled for your application, the Akamai Edge service provides the risk score in an HTTP header, which is consumed by the Akamai Account Protector node.

Learn more in Akamai Account Protector node.

Enhancements

  • FRAAS-25205: Consolidated End User UI, Login UI, Administrator Registration UI, and Administrator UI status page components into a single Administrator UI component as they were all reporting the same service.

  • IAM-2453[20]: Hosted pages themes now show the loading spinner until they are fully loaded.

  • IAM-4769[20]: Hosted journey pages now fall back to the default theme if a journey is configured with a deleted theme.

  • IAM-6781[20]: Password policy hints now show all policy conditions when creating a new user identity in the Advanced Identity Cloud admin console.

  • IAM-7615[20]: The Certificate Collector node now validates the value set in the HTTP Header Name for Client Certificate field based on the value selected in the Certificate Choice Method field.

  • IAM-8358[20][15]: Hosted account pages now display a New User button in the Users list view for delegated administrators.

  • OPENIDM-15771: You can now set locales in identity management scripts with the _locale parameter.

  • OPENIDM-17680: Advanced Identity Cloud now supports enumerations in string and number attributes of its identity schema. To make an attribute an enumeration, add "enum" : [ "one", "two", "three" ] to the attribute. Advanced Identity Cloud requires create and update privileges to use one of the enumerated values.

  • OPENIDM-19918: You can now choose whether synchronization detects identity array changes using ordered or unordered comparisons. Set the comparison configuration property in the schema. Unordered JSON array comparison ignores the order of elements and can negate the need for certain custom scripts within mappings. Relationship and virtual property array fields default to unordered comparisons. All other fields default to ordered comparisons.

  • OPENIDM-20023: RCS communication with Advanced Identity Cloud can now use stricter authorization. Learn more in Secure RCS access and Migration dependent features.

Fixes

  • FRAAS-25256: Fixed an issue that was causing missing data in analytics dashboards.

  • IAM-1479[20]: Email field validation in the Advanced Identity Cloud admin console now runs only when typing stops or the field is unfocused.

  • IAM-7858[20]: Hosted account pages now use the access management maxIdleExpirationTime value to prompt the You will be signed out soon modal.

  • IAM-8382[20]: Fixed an issue in the bookmark app where the URL field validation stopped the Create Application button working the first time it was clicked.

  • IAM-8383[20]: Fixed an issue in the bookmark app where the URL field accepted ESV secrets.

  • IAM-8398[20]: Field labels positioned above a field now remain left aligned when autofill is triggered.

  • IAM-8441[20]: Fixed a display issue in the Advanced Identity Cloud admin console where connector servers and connector server clusters with long names went off the edge of the screen.

  • OPENAM-21783: Improved token management for OAuth 2.0 clients that override the Use Client-Side Access & Refresh Tokens setting. The OAuth 2.0 applications endpoint now correctly shows all tokens issued to these clients. Additionally, administrators can now successfully revoke any of the tokens issued to these clients.

  • OPENDJ-11486[20]: Fixed an exception caused by identity management user queries with a filter containing wildcards and specific object classes.

May 2025

27 May 2025

Version 17584.6

Enhancements

  • ANALYTICS-1004[23]: Support for custom attributes and relationships in the organization entity for advanced reports.

  • OPENAM-23218: Legacy SAML 2.0 IDP attribute mapper scripts now have access to the httpClient binding.

  • OPENAM-23710: Legacy SAML 2.0 IDP adapter scripts now have access to the httpClient binding.

Fixes

  • OPENIDM-20995: Fixed an issue that prevented error reports during certain operations on groups or users. For example, trying to remove a non-existing attribute or null value now correctly results in an exception message to the client if these operations are not supported by the target system.

16 May 2025

Version N/A

Integrate with Microsoft 365 (FRAAS-21607)

Ping Identity introduces Microsoft 365 integration, a new add-on capability for Advanced Identity Cloud. The new Microsoft 365 application lets you set up SSO using the WS-Federation identity protocol.

Learn more in Register an SSO application.

13 May 2025

Version 17436.7

Enhancements

  • IAM-987: Added support for enums (drop-down lists) to hosted account pages.

  • IAM-1116: Added support for enums (drop-down lists) to the Advanced Identity Cloud admin console.

  • IAM-2103: Added support for enums (drop-down lists) to hosted journey pages.

  • IAM-6822: Added the ability to manage cookie domains in the Advanced Identity Cloud admin console.

  • IAM-7412: Updated the password policy feature in the Advanced Identity Cloud admin console. Added the ability to specify a minimum substring length between 3 - 64 to use when validating passwords against user attribute values. The default is still 5 characters, but can now be reduced to as few as 3 characters to catch shorter string matches.

  • IAM-7794[15]: Added support for using custom identity objects in the form builder.

  • IAM-7919: Improved color contrast ratio of the Delete Account button text when focused.

  • IAM-7934: Improved color contrast ratio of date fields when focused.

  • IAM-7957: Improved color contrast ratio of the Deselect button text when focused.

  • IAM-7966: Improved color contrast ratio of In Progress text.

  • IAM-8016[15]: Allow form authors to specify a user filter when dynamic enums are selected.

  • IAM-8085: Updated the Add a Parameter reports modal to use entity attributes for input.

Fixes

  • FRAAS-15518: Fixed issue that prevented localization of Session timed out message in certain locales.

  • FRAAS-24449: Enhanced the reliability of metrics collection under high-load conditions.

  • FRAAS-24990: Fixed an issue where requests to the /monitoring/logs and /monitoring/logs/tail endpoints timed out after 15 seconds rather than the expected 60 seconds.

  • IAM-5834: Fixed a double-encoding issue in the SAML app that affected IdP-initiated sign on.

  • IAM-6796: Jobs are now prevented from being scheduled with frequencies that cause invalid date errors.

  • IAM-7855: Fixed a typo in the help text returned when there are no results to display.

  • IAM-8237: Corrected floating labels in the date picker in the hosted journey pages.

  • IAM-8361: The Save button in the Edit Bookmark application is now inactive while checking if the ESV exists.

  • IAM-8364: Fixed issues in SAML end-to-end scenarios.

  • IAM-8378: Fixed an issue that stripped HTML elements from email templates.

  • IAM-8403: Fixed border focus location and floating label issues in Tag fields.

  • IAM-8434: Fixed an issue that prevented duplication of new themes that contain special characters.

03 May 2025

Version 17274.5

No customer-facing features, enhancements, or fixes released.[22]

April 2025

30 Apr 2025

Version 17274.2

Enhancements

  • AME-31141: Multiple Java libraries added to SAML SP Adapter scripting allowlist.

  • OPENDJ-11175: The password validation mechanism has been enhanced to include checks for attribute values shorter than the min-substring-length (the default is 5).

    For example, if the password contains Bob for a user named Bob, the password is rejected, even if min-substring-length is set to 5.

15 Apr 2025

Version 17106.8

Enhancements

  • ANALYTICS-846: You can now select the attribute type and value for report entity attributes.

  • ANALYTICS-983[23]: You can now use regular expression operators in Advanced Reporting.

  • OPENAM-23718: Added additional Java classes to the SAML 2.0 SP adapter scripting allowlist.

Fixes

  • FRAAS-24631: Fixed a promotions issue where ESVs mapped to secret labels aren’t identified as available in the upper environment.

  • FRAAS-24648: Fixed an issue with loading ESVs with values containing leading blank spaces.

  • IAM-7202: In the custom application modal, the native apps link now correctly points to the SDKs documentation.

14 Apr 2025

Version 16955.15

No customer-facing features, enhancements, or fixes released.[22]

09 Apr 2025

Version 16955.13

Fixes

  • FRAAS-24646[19]: Fixed an issue where ESVs mapped to AM secret labels could block configuration promotions.

03 April 2025

Version 16955.12

Key Features
OIDC application journeys (AME-28650)

You can now configure OAuth 2.0 / OIDC client applications to redirect authentication requests to a specified journey. Learn more in Client application journeys.

Flow Control node (AME-30017)

You can now randomly direct users down different journey paths. Learn more in Flow Control node.

Advanced sync (IAM-8090)

Many of the mapping synchronization features available in the IDM admin console are now exposed in the Advanced Sync tab when viewing an application. You can create additional mappings between applications or between applications and identity profiles. Learn more in Advanced sync.

Enhancements

  • AME-27705: Extend the utils binding for all next-generation scripts to support low-level cryptographic operations. These operations include encryption, decryption, hashing, signing, verification, and key generation.

    Find more information in Access utility functions.

  • AME-28780: Added an IDM policy condition that can assert conditions against an IDM resource type such as user identities.

  • AME-28954: Modified the import metadata endpoint to support updating signing and encryption certificates for existing SAML service providers (SPs) without requiring the deletion or recreation of SP configurations.

  • AME-28954: Modified the import metadata endpoint to support updating signing and encryption certificates for existing SAML service providers (SPs) without requiring the deletion or recreation of SP configurations.

  • AME-29307: You can now use DER-encoded certificates for OAuth 2.0 client authentication.

  • AME-29810: The realm default authentication service can no longer be a journey with mustRun enabled. Also, mustRun can no longer be enabled on journeys that are set as the realm default authentication service.

  • AME-29835: Configuration Provider Node scripts can now use the next-generation scripting engine, which gives them access to common bindings such as openidm and httpClient.

  • AME-30076: New getApplicationId() method provides a consistent way to retrieve the application ID from both SAML and OAuth 2.0 applications.

  • IAM-7967[15]: Added an image description for the approvals Low Priority icon.

  • OPENIDM-20139: Applications can now use postAction scripts for the ONBOARD action.

  • FRAAS-24020[20]: Consolidated End User UI, Login UI, Administrator Registration UI, and Administrator UI status page components into a single Administrator UI component as they were all reporting the same service.

  • IAM-7229[20]: Added none as a client authentication method when configuring an OIDC federation IdP.

  • IAM-8419[20]: Added icons to all nodes in the journey editor. The icons are applied based on the node category, improving consistency and visual clarity in the editor.

  • SDKS-3774[20]: Added script input configuration for the PingOne Verify Completion Decision node. This can be used to specify the node state required by a script within the node.

  • FRAAS-24371[20]: New ESVs now load into AM and IDM only when the restart is initiated using the ESV restart API endpoint or the ESV update banner in the admin console. Other restarts (for example, after a promotion) won’t load the ESVs. This makes it easier to identify issues caused by ESV changes.

  • IAM-6996: Added the ability to create a specific OAuth 2.0 client when creating a connector server, rather than relying on the default RCSClient.

  • IAM-7109: You can now use an ESV to set the From Address in the email provider configuration.

  • IAM-7827/ANALYTICS-835[23]: In the analytics report editor in Advanced Reporting, you can now reorder columns by dragging and dropping them.

  • IAM-7841/ANALYTICS-840[23]: The reports page in Advanced Reporting is now a list view with pagination and search.

  • IAM-8321: In the journey editor, the node titles now wrap within the left nodes panel.

Fixes

  • AME-29504: The scriptName and logger bindings in library scripts referenced the same default script name and ID. Their previous behavior has now been restored by inheriting values from the referencing script.

  • AME-29965: The Configuration Provider node now works with the Inner Tree Evaluator for nested inner journeys.

  • AME-30377: The following two warning level log messages have been reduced to debug level because they’re rarely useful and appear frequently, drowning out more useful log entries:

    • No users have been identified.

    • Ignoring the new universal id as that is empty and the current universal id is already set.

  • IAM-7719[15]: Users are now redirected back to the compliance Policy Rules tab after creating or editing a policy rule.

  • IAM-7977: Improved the font color contrast ratio of the email address displayed in Advanced Identity Cloud admin console user profiles.

  • IAM-8053: The Advanced Identity Cloud end-user UI can now use defaultText value as a fallback value when the actual value of a field returns empty.

  • OPENAM-22120: Back-channel logout tokens now include the exp claim.

  • OPENAM-23077: The access_token endpoint now responds with the correct error code when the code_verifier isn’t supplied (for example, invalid_grant).

  • FRAAS-24042[20]: Fixed an issue where Proxy Connect could be unintentionally deactivated.

  • FRAAS-24058[20]: Increased max HTTP header size accepted by access management endpoints.

  • IAM-1504: User no longer needs to click the cancel button twice in some journey dialogs.

  • IAM-8111: Schedules can no longer be disabled when running.

March 2025

25 Mar 2025

Version 16747.9

This version was partially deployed but has now been reverted. All associated changes have been withdrawn.

21 Mar 2025

Enhancements

  • ANALYTICS-789[24]: Change the 'Status' parameter input type to combo box along with drop down list in out-of-the-box reports.

Fixes

  • ANALYTICS-904[24]: Fixed report tab keep loading in end user UI.

20 Mar 2025

Reversions

Version 16747.7 has been reverted. All changes associated with this version have been withdrawn. This affects the following changelog entry:

18 Mar 2025

Version 16747.7

This version has been reverted and all associated changes withdrawn.
Key Features
OIDC application journeys (AME-28650)

You can now configure OAuth 2.0 / OIDC client applications to redirect authentication requests to a specified journey. Learn more in Client application journeys.

Flow Control node (AME-30017)

You can now randomly direct users down different journey paths. Learn more in Flow Control node.

Advanced sync (IAM-8090)

Many of the mapping synchronization features available in the IDM admin console are now exposed in the Advanced Sync tab when viewing an application. You can create additional mappings between applications or between applications and identity profiles. Learn more in Advanced sync.

Enhancements

  • AME-27705: Extend the utils binding for all next-generation scripts to support low-level cryptographic operations. These operations include encryption, decryption, hashing, signing, verification, and key generation.

    Find more information in Access utility functions.

  • AME-28780: Added an IDM policy condition that can assert conditions against an IDM resource type such as user identities.

  • AME-28954: Modified the import metadata endpoint to support updating signing and encryption certificates for existing SAML service providers (SPs) without requiring the deletion or recreation of SP configurations.

  • AME-28954: Modified the import metadata endpoint to support updating signing and encryption certificates for existing SAML service providers (SPs) without requiring the deletion or recreation of SP configurations.

  • AME-29307: You can now use DER-encoded certificates for OAuth 2.0 client authentication.

  • AME-29810: The realm default authentication service can no longer be a journey with mustRun enabled. Also, mustRun can no longer be enabled on journeys that are set as the realm default authentication service.

  • AME-29835: Configuration Provider Node scripts can now use the next-generation scripting engine, which gives them access to common bindings such as openidm and httpClient.

  • AME-30076: New getApplicationId() method provides a consistent way to retrieve the application ID from both SAML and OAuth 2.0 applications.

  • IAM-7967[15]: Added an image description for the approvals Low Priority icon.

  • OPENIDM-20139: Applications can now use postAction scripts for the ONBOARD action.

  • FRAAS-24020[20]: Consolidated End User UI, Login UI, Administrator Registration UI, and Administrator UI status page components into a single Administrator UI component as they were all reporting the same service.

  • IAM-7229[20]: Added none as a client authentication method when configuring an OIDC federation IdP.

  • IAM-8419[20]: Added icons to all nodes in the journey editor. The icons are applied based on the node category, improving consistency and visual clarity in the editor.

  • SDKS-3774[20]: Added script input configuration for the PingOne Verify Completion Decision node. This can be used to specify the node state required by a script within the node.

Fixes

  • AME-29504: The scriptName and logger bindings in library scripts referenced the same default script name and ID. Their previous behavior has now been restored by inheriting values from the referencing script.

  • AME-29965: The Configuration Provider node now works with the Inner Tree Evaluator for nested inner journeys.

  • AME-30377: The following two warning level log messages have been reduced to debug level because they’re rarely useful and appear frequently, drowning out more useful log entries:

    • No users have been identified.

    • Ignoring the new universal id as that is empty and the current universal id is already set.

  • IAM-7719[15]: Users are now redirected back to the compliance Policy Rules tab after creating or editing a policy rule.

  • IAM-7977: Improved the font color contrast ratio of the email address displayed in Advanced Identity Cloud admin console user profiles.

  • IAM-8053: The Advanced Identity Cloud end-user UI can now use defaultText value as a fallback value when the actual value of a field returns empty.

  • OPENAM-22120: Back-channel logout tokens now include the exp claim.

  • OPENAM-23077: The access_token endpoint now responds with the correct error code when the code_verifier isn’t supplied (for example, invalid_grant).

  • FRAAS-24042[20]: Fixed an issue where Proxy Connect could be unintentionally deactivated.

  • FRAAS-24058[20]: Increased max HTTP header size accepted by access management endpoints.

17 Mar 2025

Version 16583.9

No customer-facing features, enhancements, or fixes released.[22]

05 Mar 2025

Version 16583.6

Enhancements

  • FRAAS-23002: Improvements to OATH support for MFA authenticators

    • Update the default OATH shared secret length from 32 to 40 for existing and new tenants so that tenant administrators can use Google Authenticator with MFA when signing on using their Advanced Identity Cloud native accounts.

    • Make the OATH shared secret length configurable (using a support request) to support other MFA authenticators.

  • IAM-4692: Managed identity boolean fields now use a checkbox instead of a toggle.

  • IAM-6581: SAML 2.0 application journeys can now be configured in the Advanced Identity Cloud admin console.

  • IAM-7248[15]: In IGA sources, the displayName and logo can now be obtained from the CDN.

  • IAM-7874[15]: The Governance > Requests > Settings tab now lets you activate or deactivate Governance LCM.

Fixes

  • IAM-1262: Clicking the Toggle Sidebar button now collapses the sidebar.

  • IAM-5801: For applications that mandate a minimum page size, the page size selector on the Data tab and the Reconciliation Results tab has been removed.

Corrections

February 2025

26 Feb 2025

Version 16368.14

Fixes

  • FRAAS-24058 [20]: Increased the maximum HTTP header size accepted by access management endpoints.

24 Feb 2025

Reversions

Version 16508.8 has been reverted. All changes associated with this version have been withdrawn. This affects the following changelog entry:

18 Feb 2025

Version 16508.8

This version has been reverted and all associated changes withdrawn.
Enhancements

  • FRAAS-23002: Improvements to OATH support for MFA authenticators

    • Update the default OATH shared secret length from 32 to 40 for existing and new tenants so that tenant administrators can use Google Authenticator with MFA when signing on using their Advanced Identity Cloud native accounts.

    • Make the OATH shared secret length configurable (using a support request) to support other MFA authenticators.

  • IAM-4692: Managed identity boolean fields now use a checkbox instead of a toggle.

  • IAM-6581: SAML 2.0 application journeys can now be configured in the Advanced Identity Cloud admin console.

  • IAM-7248[15]: In IGA sources, the displayName and logo can now be obtained from the CDN.

  • IAM-7874[15]: The Governance > Requests > Settings tab now lets you activate or deactivate Governance LCM.

Fixes

  • IAM-1262: Clicking the Toggle Sidebar button now collapses the sidebar.

  • IAM-5801: For applications that mandate a minimum page size, the page size selector on the Data tab and the Reconciliation Results tab has been removed.

12 Feb 2025

Version 16368.11

No customer-facing features, enhancements, or fixes released.[22]

10 Feb 2025

Version 16368.9

Fixes

  • FRAAS-23812: You can now deactivate the header ruleset after deactivating the IP ruleset when configuring Proxy Connect.

04 Feb 2025

Version 16368.7

Enhancements

  • FRAAS-23375: You can now obtain the HTTP client location from the X-Client-City & X-Client-City-Lat-Long HTTP headers in Advanced Identity Cloud scripts and journeys.

  • IAM-6833 : Made existing synchronization tokens editable for incremental reconciliations.

  • IAM-7223[15]: Added the ability to set user, role, organization, application, or entitlement objects to provide predefined values for select and multiselect fields in request forms.

  • IAM-7454: The inbound mapping for all application templates and scripted application templates has now been configured to make fewer connector requests.

Fixes

  • FRAAS-23780[19]: Optimized network utilization to distribute workloads more effectively.

  • IAM-5242: The Previous link in the New Script modal now always shows the previous step.

  • IAM-5482: Password policy no longer allows Password length to be set as an empty string.

  • IAM-7799: Identity attributes with Time and DateTime format now trigger change events only when a change occurs.

January 2025

21 Jan 2025

Version 16139.9

No customer-facing features, enhancements, or fixes released.[22]

09 Jan 2025

Version 16100.4

Key features
UI support for managing certificates [25] (IAM-5813)

You can now use the Advanced Identity Cloud admin console to generate CSRs and upload SSL certificates in your tenant environments.

Learn more in Manage server certificates using the admin console.

PingOne Authorize node (TNTP-183)

Use this node to send a decision request to a specified decision endpoint in your PingOne Authorize environment.

PingOne node improvements (SDKS-3468)
PingOne Create, Identify, and Delete Nodes

The following PingOne nodes are now available:

PingOne Identity Match node

Use the PingOne Identity Match node to identify if a user exists both in the user repository and in PingOne, using defined attributes.

PingOne Create User node

Create new users in the PingOne platform using the PingOne Create User node. Create users based on an existing user’s properties or choose to create the user anonymously. For example, when used in conjunction with PingOne Verify.

PingOne Delete User node

Delete users from the PingOne platform with the PingOne Delete User node.

PingOne Verify nodes

Use the following PingOne Verify nodes in conjunction with the PingOne Identity Match node, PingOne Create User node, and PingOne Delete User node to create a seamless verification process in your journey:

PingOne Verify Evaluation node

Use PingOne Verify to initiate or continue a verification transaction with the PingOne Verify Evaluation Node.

PingOne Verify Completion Decision node

Determine the completion status of the most recent identity verification transaction for an end user.

Use before the PingOne Verify Evaluation node to determine the status of the verification process or after the PingOne Verify Evaluation node using a script to evaluate the transaction.

For example, you can evaluate if the transaction was completed using a passport and route your journey accordingly.

Use these nodes in place of the PingOne Verify Marketplace nodes.
reCAPTCHA Enterprise node (SDKS-3322)

The reCAPTCHA Enterprise node node adds Google reCAPTCHA Enterprise support to your journeys.

Set Failure Details node (AME-27871)

Use the Set Failure Details node to configure a localized error message on journey failure. You can also configure extra details in the response body of the failure request.

Set Success Details node (OPENAM-12335)

Use the Set Success Details node to add additional details to the success response of a journey.

Reports for IGA data sources (ANALYTICS-571)

Advanced Reporting[26] now supports various IGA[21] data sources and relationships. This lets IGA administrators create customer-friendly report templates.

Enhancements

  • ANALYTICS-459: Report query data is now retained for 30 days for customers using OOTB reports and 90 days for customers with Advanced Reporting[26].

  • ANALYTICS-495: Replace email with username in User Last Login report.

  • ANALYTICS-817[23]: Report authors can now query on "Password Last Changed Time" for user entity.

  • ANALYTICS-818[23]: Report authors can now query on "Password Expiration Time" for user entity.

  • AME-26050: You can now create Next-generation Policy Condition scripts that have access to all common bindings, such as openidm and httpClient. Additionally, some existing bindings have been wrapped to improve usability in scripts.

  • AME-28228: OAuth 2.0 audit logs now include the OAuth 2.0 client ID and any journey associated with the client.

  • AME-29009: When using the new FIDO Metadata Service, if you link to the FIDO metadata using a URL, Advanced Identity Cloud periodically downloads and updates the latest FIDO metadata based on the nextUpdate date specified in the downloaded data.

  • AME-29093: Added configuration for integration with WebAuthn Metadata Services (such as the FIDO Metadata Service). This includes a realm-level WebAuthn Metadata service and a new FIDO Certification Level configuration attribute in the WebAuthn Registration Node.

  • FRAAS-22321: You can now obtain the HTTP client location from the X-Client-Region HTTP header within your scripts and journeys. The X-Client-Region header contains the country (or region) associated with the client’s IP address in the form of a Unicode CLDR region code, such as US or FR. For most countries, these codes correspond directly to ISO-3166-2 codes.

  • FRAAS-23073: The SAML scripting adapter now lets scripts access org.forgerock.http.protocol.*.

  • IAM-3323: You can now use XPath transformation functions with additional Workday application template attributes.

  • IAM-4540: You can now change the border color of a selected input field in journey and end-user pages.

  • IAM-6397: The Advanced Identity Cloud admin console now lets you page through the list of OAuth 2.0 client profiles.

  • OPENAM-20314: Added the ability to indicate whether an OIDC provider doesn’t return a unique value for the sub claim.

  • OPENAM-22966: Social IDPs now support NONE as a client authentication method. This option should be used if the provider doesn’t require client authentication at the token endpoint.

  • OPENAM-23109: During a WebAuthn registration flow, if Store data in transient state is enabled, the Authenticator Attestation Global Unique Identifier (AAGUID) is now added to the node state under the webauthnData key.

  • OPENIDM-20542: Added a feature service named am/2fa/profiles to expose certain multi-factor attributes on alpha and bravo users.

Fixes

  • ANALYTICS-474: The User Journey Stats report now provides aggregates by outcome in the report result when more than one outcome is selected.

  • ANALYTICS-837: The User Count by Status report now provides aggregates by status in the report result when more than one outcome is selected

  • ANALYTICS-585[23]: Remove Report Admin and Report Owner group selection when creating a new report.

  • AME-28016: When an invalid redirect URI is provided to the /par endpoint, the URI mismatch error is now redirect_uri_mismatch instead of invalid_request.

  • AME-28017: Advanced Identity Cloud now accepts the requested OAuth 2.0 endpoint as a valid JWT audience claim, as per RFC 7519 and RFC 9126.

  • AME-28906: The stack trace of an authentication exception generated on login failure is now logged only when debug level logging is enabled.

  • AME-29170: On LDAP Decision node login failure, stack traces are now logged at debug level.

  • AME-29504: Fixed issue with script names not displaying in next-generation script logs.

  • AME-29965: The Configuration Provider node now works with the Inner Tree Evaluator node for nested inner journeys.

  • IAM-1782: Long gateway and agent IDs no longer overflow in the Advanced Identity Cloud admin console.

  • IAM-7523[15]: A user receiving a forwarded fulfillment task now has permission to approve or reject the task.

  • IAM-7537[15]: Governance functionality is now only shown for the alpha realm.

  • IAM-7689[15]: The Advanced Identity Cloud admin console now displays the Assigned To value in the task list for a user assigned to a role who receives a forwarded fulfillment task.

  • OPENAM-18252: Journeys acting on multiple identities now successfully update universalId in the journey context during the authentication flow.

07 Jan 2025

Version 15726.9

Enhancements

  • OPENDJ-9287: The password validation mechanism has been enhanced to include checks for portions of attribute values within passwords. This improvement ensures that even partial matches between portions of passwords and portions of attribute values are identified and restricted, thereby enhancing security.

    For example, if the password is abcdef and the attribute value is abcdef123, the password is rejected. Similarly, if the password is abcdefAZERTY and the attribute value is abcdef123, the password is rejected.

December 2024

12 Dec 2024

Version 15726.7

Enhancements

  • AME-29769: The Social Provider Handler node has a new configuration option, Store Tokens, that allows access and refresh tokens to be stored in the transient state.

04 Dec 2024

Version 15726.4

Key features
Configure journey to always run (AME-27848)

Added a new setting for journeys to always run regardless of existing user sessions.

Learn more in Configure an authentication journey to always run.

SAML application journeys (AME-27850)

Added support for SAML application journeys with a new setting on the remote SP. Configure a specific authentication journey that always runs for users authenticating with your SAML 2.0 app, regardless of existing sessions or configured authentication context.

Learn more in Configure a SAML 2.0 application journey.

SAML application script binding (AME-28012)

Added a new samlApplication binding for querying the SAML 2.0 authentication request properties and IdP and SP configuration attributes.

Learn more in Query SAML application and authentication request.

Suspend and resume journeys (OPENAM-21806)

Next-generation decision node scripts can now use the new action.suspend() method to suspend the current authentication session and send a message to the user. Implement custom logic with the resume URI, for example, to send an email or SMS using the HTTP client service.

Learn more in Suspend and resume journeys.

Enhancements

  • AME-27074: Added a new configProviderScript action to each authentication node endpoint to generate a configuration provider template script For example, authentication/authenticationtrees/nodes/MessageNode?_action=configProviderScript.

  • AME-28258: Added a new "webAuthnExtensions" input to the WebAuthn Registration and Authentication nodes. This can be set via a Scripted Decision node. It is expected to contain a map of extension name to input. Output is currently not available.

  • AME-28384: The outcome of a Scripted Decision node can now also be a CharSequence type.

  • AME-28777: The refresh token grace period now applies to both client-side refresh tokens and server-side refresh tokens.

  • AME-29157: Authentication nodes with limited possible outcomes are now available to the Configuration Provider node, including:

    The Identity Assertion node, Push Wait node, and Enable Device Management node nodes with fixed outcomes are also now available to the Configuration Provider node.

  • OPENAM-22601: You can now use the next-generation script binding, utils, to generate secure random numbers.

  • OPENAM-22811: NodeState has two new methods: mergeShared(Map<String, Object>) and mergeTransient(Map<String, Object>). Use them to merge keys into the shared/transient state, including objectAttributes keys.

  • OPENDJ-11012: Added support for Microsoft Identity Cloud PBKDF2-SHA512 password scheme in Advanced Identity Cloud.

Fixes

  • AME-25491: The Configuration Provider node script now correctly reads node state after an inner tree callback.

  • AME-28786: Removed several unused UI properties from default social identity provider profiles.

  • AME-29027: WebAuthN attestations containing a self-signed root CA are now rejected instead of silently removed.

  • OPENAM-22465: Fixed error to return invalid_resource_uri when request_uri client doesn’t match request parameter client in PAR authorize request.

  • OPENAM-22675: In next-generation scripting, you can now set a default name correctly when creating a NameCallback.

  • OPENAM-22688: Page node localization now defaults to correct locale when the incoming accepted-language header doesn’t match the node’s language configuration.

Rapid channel changelog

Subscribe to get automatic updates: Rapid channel changelog RSS feed

For release notes published before December 2024, refer to the Rapid channel changelog archive.

September 2025

03 Sept 2025

Versions 18859.0, 18878.0

No customer-facing features, enhancements, or fixes released.[22]

01 Sept 2025

Version 18842.0

Key features
Reports API endpoints to import and export report templates (ANALYTICS-1195[27])

Added the ability to import and export report templates using reports API endpoints.

Custom objects as data sources for reporting (ANALYTICS-582[27][23])

Custom objects can now be used as data sources for reporting. The system uses an object’s configured title for the data source name, makes its properties available as attributes, and represents all object relationships.

Enhancements

  • ANALYTICS-1165[27]: Added the capability to change a report name.

  • IAM-7547: Access policy modal now validates IPv4 or IPv6 format for IP addresses.

  • IAM-8687: The PingOne Verification node now supports same device verification by letting you configure a Continue on this device? button.

  • IAM-8922: The Advanced Identity Cloud admin console now accepts ESV placeholders for the following federation fields:

    • Authorization Endpoint

    • Well-Known Endpoint

    • Token Endpoint

    • Issuer

  • IAM-8982[15]: Add event function for setting the query filter/select options of a select field.

  • IAM-9099, IAM-9146, IAM-9167: Many table views now support column resizing and customization.

Fixes

  • IAM-5488: Terms and Conditions now respects target attribute in anchor tags.

  • IAM-6588: The Advanced Identity Cloud admin console now correctly displays journey status for journeys disabled and enabled using ESVs.

  • IAM-8887: Prevent browsers auto-filling passwords in user registration journeys.

  • IAM-8940: Managed identity number property now accepts float values.

  • IAM-8956: Deselecting the Personal Information option now disables the section containing the user avatar in hosted account pages.

  • IAM-9066: Added Tenant Auditor option to Advanced Identity Cloud admin console federation groups claim.

  • IAM-9169: Fixed styling for responsive table layouts with sticky action column in Identities table views.

August 2025

29 Aug 2025

Version 18823.0

Enhancements

  • FRAAS-25919: You can now use the API to configure custom domains for the Advanced Identity Cloud admin console.

  • OPENIDM-21372: Advanced Identity Cloud now prevents access to the identity repository endpoint, /openidm/repo. This prevents uncontrolled and potentially incompatible schema changes.

Fixes

  • AME-32756: Fixed an issue with policy evaluation returning results from a stale policy index cache.

  • FRAAS-26287: Advanced Identity Cloud now correctly authenticates the sender address for emails sent to Advanced Identity Cloud tenant administrators, saas@pingidentity.com.

  • OPENDJ-11634: Advanced Identity Cloud now prevents searches with many results and no applicable index from overloading the system.

26 Aug 2025

Version N/A

Key features
Log event exporter (FRAAS-19963)

Advanced Identity Cloud now lets you export log event data to an external monitoring tool, such as an OpenTelemetry-compatible SIEM or Splunk. This helps you monitor events and troubleshoot issues in near real time.

Learn more in Export log events to an external monitoring tool.

19 Aug 2025

Version 18712.0

Fixes

  • OPENAM-24393: Fixed an issue where the InnerTreeEvaluator node failed for authentication journeys initially accessed using REST without an authId.

18 Aug 2025

Version 18700.0

Enhancements

  • FRAAS-25547: The sender address for emails sent to Advanced Identity Cloud tenant administrators is now saas@pingidentity.com.

15 Aug 2025

Versions 18678.0, 18684.0

Enhancements

  • OPENAM-24384: Added javax.crypto.SecretKeyFactory, javax.crypto.spec.PBEKeySpec, and com.sun.crypto.provider.PBKDF2KeyImpl classes to the allowlist for the OAUTH2_ACCESS_TOKEN_MODIFICATION scripting context.

Fixes

  • FRAAS-#25734: Exception stacktraces in access management and identity management logs are now truncated to approximately 300-400 lines.

12 Aug 2025

Version 18623.0

No customer-facing features, enhancements, or fixes released.[22]

07 Aug 2025

Versions 18559.0, 18570.0

Fixes

  • FRAAS-25821[18]: Fixed an issue that prevented IP rules in the Proxy Connect add-on from being disabled.

  • OPENAM-24159: Fixed an issue with Identity Assertion nodes failing if there are more than one in a journey.

06 Aug 2025

Version 18550.0

Enhancements

  • FRAAS-24857: CNAME verification is no longer required when creating a custom domain.

  • FRAAS-26063: You can now override the samlErrorPageUrl. To do so, configure an ESV variable named esv-global-saml-error-page-url and set its value to your SAML error page URL. If you don’t set this variable, Advanced Identity Cloud uses the default value of /saml2/jsp/saml2error.jsp.

August 2025

12 Aug 2025

Version 18623.0

No customer-facing features, enhancements, or fixes released.[22]

July 2025

31 Jul 2025

Version 18483.0

Fixes

  • IAM-9062: Hosted pages themes no longer continuously refresh when trying to set up or confirm two-factor authentication (2FA).

30 Jul 2025

Version 18468.0

No customer-facing features, enhancements, or fixes released.[22]

29 Jul 2025

Version 18451.0

No customer-facing features, enhancements, or fixes released.[22]

28 Jul 2025

Versions 18435.0, 18444.0

No customer-facing features, enhancements, or fixes released.[22]

24 Jul 2025

Version 18395.0

No customer-facing features, enhancements, or fixes released.[22]

23 Jul 2025

Version 18382.0

No customer-facing features, enhancements, or fixes released.[22]

22 Jul 2025

Version 18368.0

No customer-facing features, enhancements, or fixes released.[22]

21 Jul 2025

Version 18347.0, 18351.0

No customer-facing features, enhancements, or fixes released.[22]

18 Jul 2025

Version 18331.0

Key features
Try In SDK button (IAM-8618)

A Try In SDK button has been added to the Details page for Native / SPA applications. This lets developers quickly test SDKs with dynamic configuration code snippets.

Custom WS-Fed applications (IAM-8261)

You can now create custom WS-Fed[6] applications for single sign-on (SSO).

Enhancements

  • FRAAS-25818: The built-in SMTP server in new tenants now has a limit of 10 emails per minute and a fixed email sender address with the format noreply@<tenant-fqdn>.

  • IAM-7581: Text wrapping in table views has been improved for readability.

  • IAM-8573: IDM now includes an endpoint to retrieve individual themes from the /themerealm configuration using either an ID or a _queryFilter by name. This improves performance and ensures reliable theme loading, even on slow networks.

  • IAM-8610: When you create an SSO application for Microsoft 365, the application now generates a signing certificate, which you can download or rotate as needed.

  • IAM-8633: You can now add, remove, and rearrange table columns for managed identities and application provisioning tables.

  • IAM-8925[21]: In Identity Governance, you can now configure actions that trigger automatically when a form first loads or when a user changes the value of a specific field.

  • IGA-3674[21]: A Wait node is now available for IGA workflows. This node pauses the workflow until a specified date and time, for example, if you need to seek approvals.

  • IGA-3700[21]: Improved UI for suspended requests in table and request view.

  • IGA-3742[21]: The form editor now includes icons in the list of fields in the left panel.

Fixes

  • IAM-8789: Managed identity modals now correctly handle both single-value and array-based enum types.

  • IAM-4397: Fixed an issue in the hosted journey pages where the prompt text for the Choice Collector node wasn’t fully visible and the default option wasn’t visible at all.

  • IAM-8632: Fixed an issue where validation errors were incorrectly displayed for pre-populated fields.

  • IAM-8871: The hosted account pages no longer freeze and throw an error when editing details if there are empty custom enum array values.

  • IAM-8902: The application username field in SAML 2.0 NameID flows is now correctly set to uid instead of username.

17 Jul 2025

Version 18311.0

No customer-facing features, enhancements, or fixes released.[22]

16 Jul 2025

Version 18295.0

Key features
Monitor log entries in the admin console (FRAAS-25665)

Advanced Identity Cloud now provides a console for monitoring log entries in development and sandbox[1] environments. You can view, filter, and search log entries for specific log sources within a timeframe to quickly identify issues, track events, and ensure system security.

This is a beta feature and is limited to development and sandbox[1] environments. It’s not available in production environments.

14 Jul 2025

Version 18274.0

Fixes

  • IAM-8933: Fixed an issue in the Advanced Identity Cloud admin console when creating or modifying identity objects with a required boolean property. You can now set the value of the required boolean property to false.

01 Jul 2025

Version 18170.0

Key features
Policy binding for next-generation scripting (AME-26150)

The next-generation policy binding lets you access the policy engine API and evaluate policies from within scripts. The policy binding works in a similar way to the Request policy decisions for a specific resource API call.

Set Error Details node (AME-30968)

The Set Error Details node adds details to the JSON response when a journey ends in an error.

Enhancements

  • AME-31372: An Agent journey is now available by default in both Alpha and Bravo realms. The Agent journey makes it easier to integrate with Ping Identity agents and gateways. It validates the agent credentials with an Agent Data Store Decision node.

  • AME-30050: You can now enable a next-generation script in the AM admin console native console to run after a Dynamic Client Registration request is processed.

  • AME-30716: Removed Failed to create SSO Token from logs at warning level. To observe these warnings, increase the log level to debug.

  • AME-30801: The Inner Tree Evaluator node now has an optional Error Outcome that lets you capture exception details if an exception occurs during the evaluation of the child journey.

  • OPENAM-22467: Customers can now provide any value in the typ header in JWTs.

  • Greater control over journey session duration and authenticated session timeouts:

    • OPENAM-23265: The Set Session Properties node now lets you customize the Maximum Session Time and Maximum Idle Time of the session granted at the end of the journey.

    • OPENAM-23290: The new Update Journey Timeout node lets you update the timeout of the journey.

    • OPENAM-23291: The Email Suspend node now lets you configure the Suspend Duration in minutes. This duration overrides existing global or realm settings.

    • OPENAM-23515: You can now set the suspend duration in next-generation scripted decision nodes when suspending the journey.

  • OPENAM-23438: Following Webauthn Registration and Authentication, new information is added to the transient state.

  • OPENAM-20709: On successful authentication, the WebAuthn Authentication node now adds the UUID of the device (webauthnDeviceUuid) and the name of the device (webauthnDeviceName) to the shared state. This lets you track the use of biometric authentication and the device used to authenticate.

Fixes

  • AME-30969: If the OIDC Claims Plugin Type in the OAuth 2.0 provider is set to SCRIPTED but no script is selected, the userinfo endpoint now returns the sub claim, in compliance with the OIDC specification. Previously, the userinfo endpoint returned an empty JSON object. If you still require this behavior, set the esv-scripting-legacynulloidcclaimsscriptbehaviour ESV to true.

  • OPENAM-20749: For server-side OAuth 2.0 tokens, the /oauth2/introspect response can now overwrite the iss claim of the introspectable token. To enable this behavior, set the esv-enable-oauth2-sync-refresh-token-issuer ESV to false.

  • OPENAM-22928: When agents authenticate to Advanced Identity Cloud, the session created no longer expires.

  • OPENAM-23334: You can now use the mergeShared and mergeTransient methods to add nested objects to ObjectAttributes.

  • OPENAM-23519: Improved error handling during WebAuthn registration when the Android lock screen isn’t enabled.

Removed
Modules and chains (AME-30762)

The legacy PingAM authentication mechanism using modules and chains is enabled by default in Advanced Identity Cloud but has never been supported. Modules and chains remain enabled but have been removed from the Advanced Identity Cloud admin console.

Modules and chains will be removed entirely in the near future. If you’re using them for authentication, you must migrate to nodes and trees as soon as possible.

Advanced Identity Cloud provides default journeys that replace the corresponding default modules and chains. Any default authentication processes that relied on modules and chains are unaffected by their removal.

June 2025

30 June 2025

Reversions

Version 18094.0 has been reverted. All changes associated with this version have been withdrawn. This affects the following changelog entry:

25 Jun 2025

This version has been reverted and all associated changes withdrawn.

Version 18094.0

Fixes

  • IAM-8314: Fixed an issue where setting ESVs in connector or provisioner configuration stops the Advanced Identity Cloud admin console from being able to update connectors or run a liveSync operation.

24 Jun 2025

Version 18076.0

No customer-facing features, enhancements, or fixes released.[22]

23 Jun 2025

Version 18045.0

Enhancements

  • AME-31379: Setting the new ESV esv-oauth2-provider-request-object-processing-enforced to true now lets admins enforce which validation rules are applied when processing OAuth 2.0 request objects.

Fixes

  • FRAAS-25226: Allow a higher threshold for large JSON log entries before splitting them into smaller plaintext log entries.

18 Jun 2025

Version 17994.0

Enhancements

  • FRAAS-25437: Tenant administrators with the tenant-auditor role can now use federated access to authenticate to Advanced Identity Cloud.

  • IAM-3441: Added pagination to all list views.

  • IAM-7265: You can now right-click a node in the journey editor to access a context menu.

  • IAM-7266: Added an action bar to the journey editor that lets you deselect or delete currently selected nodes.

  • IAM-7580: Pages now span the full width of the screen, improving navigation and usability.

  • IAM-8260: Advanced Identity Cloud now supports multiple WS-Fed applications[6].

  • IAM-8640: The Release Notes link in Tenant Settings now opens the release notes for the tenant’s specific version.

  • IAM-8714[15]: You can now configure columns in the Identity Governance access review page.

  • IAM-6820: The Email Suspend node now provides a drop-down list of available email templates.

  • OPENIDM-21206[28]: Usernames and application names must now be unique, as enforced by the datastore.

Fixes

  • IAM-7413: The reCAPTCHA Enterprise node is now fully supported.

  • IAM-8489: Fixed an issue with the display of application logos in the hosted account pages.

  • IAM-8770: Fixed an issue with the calendar icon position in date fields.

  • IAM-8773: Fixed an issue where key actions such as realm login were blocked in older tenants with an unmodified original theme.

16 Jun 2025

Version 17959.0

No customer-facing features, enhancements, or fixes released.[22]

13 Jun 2025

Versions 17949.0

No customer-facing features, enhancements, or fixes released.[22]

10 Jun 2025

Version 17889.0

Enhancements

  • ANALYTICS-868: The Tenant Admin Activity report has been changed to the Tenant Admin Initiated Managed Objects Changes report. The new report provides more detailed and business-friendly insights into changes made by tenant administrators:

    • Field names added, deleted, or modified.

    • Before and after values of changed attributes (if applicable).

    • Business-friendly entity name and entity type changes to custom attributes and custom objects.

Fixes

  • OPENAM-21783: Improved token management for OAuth 2.0 clients that override the Use Client-Side Access & Refresh Tokens setting. The OAuth 2.0 applications endpoint now correctly shows all tokens issued to these clients. Additionally, administrators can now successfully revoke any of the tokens issued to these clients.

06 Jun 2025

Version 17853.0

Enhancements

  • IAM-8405: You can now duplicate out-of-the-box reports.

  • IAM-8591: Dynamic sorting for report results. You can now sort report results directly in the Advanced Identity Cloud admin console after running a report.

    • Sorting is available only when the result set contains fewer than 10,000 rows.

    • Columns with complex data types (for example, JSON) can’t be sorted.

    • Downloaded reports reflect the original data order, not the sorted view from the Advanced Identity Cloud admin console.
Fixes

  • FRAAS-25434: Fix issue causing source to sometimes be defined as unknown in /monitoring/logs/* endpoints.

06 Jun 2025

Version 17836.0

Fixes

  • FRAAS-25269: The IDC.CLI OAuth 2.0 client is now deprecated in existing tenants and no longer provisioned in new tenants. Use a service account instead.

04 Jun 2025

Version 17825.0

No customer-facing features, enhancements, or fixes released.[22]

03 Jun 2025

Versions 17804.0, 17821.0

No customer-facing features, enhancements, or fixes released.[22]

02 Jun 2025

Version 17800.0

No customer-facing features, enhancements, or fixes released.[22]

May 2025

30 May 2025

Version 17779.0

Key features
Tenant auditors (IAM-8086)

Advanced Identity Cloud now lets you invite tenant auditors to access the Advanced Identity Cloud admin console. Tenant auditors can view settings, configuration, and data but cannot modify them.

Tenant auditor role (FRAAS-24460)

Advanced Identity Cloud now supports a tenant auditor role with read-only access to ancillary APIs.

For new tenants, Advanced Identity Cloud doesn’t support non-global realm user access and OAuth2 client access to the ESV API. Access is deprecated for existing tenants.

Enhancements

  • FRAAS-25155: Increased log batching size to avoid truncation of large JSON log entries.

Fixes

  • FRAAS-25142: Fixed a memory issue in the ESV service.

23 May 2025

Versions 17709.0, 17713.0

Enhancements

  • FRAAS-25205: Consolidated End User UI, Login UI, Administrator Registration UI, and Administrator UI status page components into a single Administrator UI component as they were all reporting the same service.

  • OPENIDM-15771: You can now set locales in identity management scripts with the _locale parameter.

  • OPENIDM-17680: Advanced Identity Cloud now supports enumerations in string and number attributes of its identity schema. To make an attribute an enumeration, add "enum" : [ "one", "two", "three" ] to the attribute. Advanced Identity Cloud requires create and update privileges to use one of the enumerated values.

  • OPENIDM-19918: You can now choose whether synchronization detects identity array changes using _ordered or unordered comparisons. Set the comparison configuration property in the schema. Unordered JSON array comparison ignores the order of elements and can negate the need for certain custom scripts within mappings. Relationship and virtual property array fields default to unordered comparisons. All other fields default to ordered comparisons.

  • OPENIDM-20023: RCS communication with Advanced Identity Cloud can now use stricter authorization. Learn more in Secure RCS access and Migration dependent features.

Fixes

  • OPENIDM-20995: Fixed an issue that prevented error reports during certain operations on groups or users. For example, trying to remove a non-existing attribute or null value now correctly results in an exception message to the client if these operations are not supported by the target system.

22 May 2025

Version 17692.0

No customer-facing features, enhancements, or fixes released.[22]

21 May 2025

Version 17680.0

Fixes

  • FRAAS-25256: Fixed an issue that was causing missing data in analytics dashboards.

  • OPENIDM-20995: Fixed an issue that prevented error reports during certain operations on groups or users. For example trying to remove a non-existing attribute or null value now correctly results in an exception message to the client if these operations are not supported by the target system.

15 May 2025

Versions 17600.0

No customer-facing features, enhancements, or fixes released.[22]

13 May 2025

Versions 17581.0, 17584.0

No customer-facing features, enhancements, or fixes released.[22]

12 May 2025

Version 17570.0

Enhancements

  • OPENAM-23218: Legacy SAML 2.0 IDP attribute mapper scripts now have access to the 'httpClient' binding.

  • OPENAM-23710: Legacy SAML 2.0 IDP adapter scripts now have access to the 'httpClient' binding.

09 May 2025

Version 17553.0

No customer-facing features, enhancements, or fixes released.[22]

08 May 2025

Versions 17546.0, 17549.0

Enhancements

  • ANALYTICS-1004[23]: Support for custom attributes and relationships in the organization entity for advanced reports.

06 May 2025

Versions 17513.0, 17514.0

No customer-facing features, enhancements, or fixes released.[22]

05 May 2025

Version 17507.0

Fixes

  • FRAAS-24990: Fixed an issue where requests to the /monitoring/logs and /monitoring/logs/tail endpoints timed out after 15 seconds rather than the expected 60 seconds.

02 May 2025

Version 17488.0

No customer-facing features, enhancements, or fixes released.[22]

April 2025

28 Apr 2025

Versions 17434.0, 17436.0

No customer-facing features, enhancements, or fixes released.[22]

24 Apr 2025

Version 17395.0

No customer-facing features, enhancements, or fixes released.[22]

23 Apr 2025

Version 17384.0

Enhancements

  • IAM-987: Added support for enums (drop-down lists) to hosted account pages.

  • IAM-1116: Added support for enums (drop-down lists) to the Advanced Identity Cloud admin console.

  • IAM-2103: Added support for enums (drop-down lists) to hosted journey pages.

  • IAM-6822: Added the ability to manage cookie domains in the Advanced Identity Cloud admin console.

  • IAM-7412: Updated the password policy feature in the Advanced Identity Cloud admin console. Added the ability to specify a minimum substring length between 3 - 64 to use when validating passwords against user attribute values. The default is still 5 characters, but can now be reduced to as few as 3 characters to catch shorter string matches.

  • IAM-7794[15]: Added support for using custom identity objects in the form builder.

  • IAM-7919: Improved color contrast ratio of the Delete Account button text when focused.

  • IAM-7934: Improved color contrast ratio of date fields when focused.

  • IAM-7957: Improved color contrast ratio of the Deselect button text when focused.

  • IAM-7966: Improved color contrast ratio of In Progress text.

  • IAM-8016[15]: Allow form authors to specify a user filter when dynamic enums are selected.

  • IAM-8085: Updated the Add a Parameter reports modal to use entity attributes for input.

Fixes

  • FRAAS-15518: Fixed issue that prevented localization of Session timed out message in certain locales.

  • IAM-5834: Fixed a double-encoding issue in the SAML app that affected IdP-initiated sign on.

  • IAM-6796: Jobs are now prevented from being scheduled with frequencies that cause invalid date errors.

  • IAM-7855: Fixed a typo in the help text returned when there are no results to display.

  • IAM-8237: Corrected floating labels in the date picker in the hosted journey pages.

  • IAM-8361: The Save button in the Edit Bookmark application is now inactive while checking if the ESV exists.

  • IAM-8364: Fixed issues in SAML end-to-end scenarios.

  • IAM-8378: Fixed an issue that stripped HTML elements from email templates.

  • IAM-8403: Fixed border focus location and floating label issues in Tag fields.

  • IAM-8434: Fixed an issue that prevented duplication of new themes that contain special characters.

22 Apr 2025

Version 17363.0

No customer-facing features, enhancements, or fixes released.[22]

17 Apr 2025

Versions 17317.0

Fixes

  • FRAAS-24449: Enhanced the reliability of metrics collection under high-load conditions.

16 Apr 2025

Versions 17283.0, 17299.0

No customer-facing features, enhancements, or fixes released.[22]

15 Apr 2025

Version 17269.0

No customer-facing features, enhancements, or fixes released.[22]

14 Apr 2025

Version 17255.0

No customer-facing features, enhancements, or fixes released.[22]

11 Apr 2025

Version 17238.0

Fixes

  • FRAAS-24631: Fixed a promotions issue where ESVs mapped to secret labels aren’t identified as available in the upper environment.

10 Apr 2025

Version 17210.0

Fixes

  • FRAAS-24648: Fixed an issue with loading ESVs with values containing leading blank spaces.

  • IAM-7202: In the custom application modal, the native apps link now correctly points to the SDKs documentation.

09 Apr 2025

Versions 17190.0, 17194.0

Fixes

  • FRAAS-24646: Fixed an issue where ESVs mapped to AM secret labels could block configuration promotions.

08 Apr 2025

Versions 17178.0, 17186.0

Enhancements

  • OPENDJ-11175: The password validation mechanism has been enhanced to include checks for attribute values shorter than the min-substring-length (the default is 5).

    For example, if the password contains Bob for a user named Bob, the password is rejected, even if min-substring-length is set to 5.

02 Apr 2025

Version 17111.0

Key Features

  • FRAAS-24546: Tenant-auditor role temporarily disabled in the Advanced Identity Cloud admin console.

Enhancements

  • AME-31141: Multiple Java libraries added to SAML SP Adapter scripting allowlist.

01 Apr 2025

Version 17106.0

No customer-facing features, enhancements, or fixes released.[22]

March 2025

31 Mar 2025

Version 17090.0

No customer-facing features, enhancements, or fixes released.[22]

28 Mar 2025

Versions 17072.0, 17079.0

Enhancements

  • ANALYTICS-846: You can now select the attribute type and value for report entity attributes.

  • ANALYTICS-983[23]: You can now use regular expression operators in Advanced Reporting.

27 Mar 2025

Versions 17055.0

No customer-facing features, enhancements, or fixes released.[22]

26 Mar 2025

Versions 17041.0, 17046.0

Enhancements

  • OPENAM-23718: Added additional Java classes to the SAML 2.0 SP adapter scripting allowlist.

25 Mar 2025

Version 17034.0

No customer-facing features, enhancements, or fixes released.[22]

24 Mar 2025

Versions 17031.0

No customer-facing features, enhancements, or fixes released.[22]

21 Mar 2025

Key Features
Custom attributes for user entity in Advanced Reports (ANALYTICS-863)[23][29]

When a tenant administrator modifies the users identity object from the native console and adds a new custom attribute, the attribute is immediately available on the Create Report page. Administrators can use the custom attribute for their reports and filters.

Learn more in Custom attributes for user objects.

Enhancements

  • ANALYTICS-770[23][29]: Add IN and CONTAINS operators for filtering in Advanced Reporting.

Fixes

  • FRAAS-24435: Fixed an issue with the pagedResultsCookie that prevented some customers from retrieving logs.

20 Mar 2025

Versions 17002.0, 17015.0

No customer-facing features, enhancements, or fixes released.[22]

19 Mar 2025

Versions 16981.0, 16989.0

No customer-facing features, enhancements, or fixes released.[22]

18 Mar 2025

Version 16955.0

No customer-facing features, enhancements, or fixes released.[22]

17 Mar 2025

Version 16940.0

Key Features
Tenant auditors (IAM-8086)

Advanced Identity Cloud now lets you invite tenant auditors to access the Advanced Identity Cloud admin console. Tenant auditors can view settings, configuration, and data but cannot modify them.

Enhancements

  • IAM-6996: Added the ability to create a specific OAuth 2.0 client when creating a connector server, rather than relying on the default RCSClient.

  • IAM-7109: You can now use an ESV to set the From Address in the email provider configuration.

  • IAM-7827/ANALYTICS-835[23]: In the analytics report editor in Advanced Reporting, you can now reorder columns by dragging and dropping them.

  • IAM-7841/ANALYTICS-840[23]: The reports page in Advanced Reporting is now a list view with pagination and search.

  • IAM-8321: In the journey editor, the node titles now wrap within the left nodes panel.

Fixes

  • IAM-1504: User no longer needs to click the cancel button twice in some journey dialogs.

  • IAM-8111: Schedules can no longer be disabled when running.

14 Mar 2025

Version 16919.0

No customer-facing features, enhancements, or fixes released.[22]

13 Mar 2025

Version 16885.0, 16887.0

No customer-facing features, enhancements, or fixes released.[22]

10 Mar 2025

Version 16846.0

No customer-facing features, enhancements, or fixes released.[22]

06 Mar 2025

Version 16832.0

No customer-facing features, enhancements, or fixes released.[22]

February 2025

27 Feb 2025

Version 16747.0

Key Features
Flow Control node (AME-30017)

You can now randomly direct users down different journey paths. Learn more in Flow Control node.

OIDC application journeys (AME-28650)

You can now configure OAuth 2.0 / OIDC client applications to redirect authentication requests to a specified journey. Learn more in Redirect an OAuth 2.0 or OIDC client application to a journey.

Enhancements

  • AME-27705: Extend the utils binding for all next-generation scripts to support low-level cryptographic operations. These operations include encryption, decryption, hashing, signing, verification, and key generation.

    Find more information in Perform low-level cryptographic operations in next-generation scripts.

  • AME-28780: Added an IDM policy condition that can assert conditions against an IDM resource type such as user identities.

  • AME-28954: Modified the import metadata endpoint to support updating signing and encryption certificates for existing SAML service providers (SPs) without requiring the deletion or recreation of SP configurations.

  • AME-29307: You can now use DER-encoded certificates for OAuth 2.0 client authentication.

  • AME-29810: The realm default authentication service can no longer be a journey with mustRun enabled. Also, mustRun can no longer be enabled on journeys that are set as the realm default authentication service.

  • AME-29835: Configuration Provider Node scripts can now use the next-generation scripting engine, which gives them access to common bindings such as openidm and httpClient.

  • AME-30076: New getApplicationId() method provides a consistent way to retrieve the application ID from both SAML and OAuth 2.0 applications.

Fixes

  • AME-29504: The scriptName and logger bindings in library scripts referenced the same default script name and ID. Their previous behavior has now been restored by inheriting values from the referencing script.

  • AME-29965: The Configuration Provider node now works with the Inner Tree Evaluator for nested inner journeys.

  • AME-30377: The following two warning level log messages have been reduced to debug level because they’re rarely useful and appear frequently, drowning out more useful log entries:

    • No users have been identified.

    • Ignoring the new universal id as that is empty and the current universal id is already set.

  • OPENAM-22120: Back-channel logout tokens now include the exp claim.

  • OPENAM-23077: The access_token endpoint now responds with the correct error code when the code_verifier isn’t supplied (for example, invalid_grant).

26 Feb 2025

Version 16726.0

No customer-facing features, enhancements, or fixes released.[22]

25 Feb 2025

Version 16713.0

No customer-facing features, enhancements, or fixes released.[22]

24 Feb 2025

Version 16704.0

No customer-facing features, enhancements, or fixes released.[22]

21 Feb 2025

Version 16686.0

No customer-facing features, enhancements, or fixes released.[22]

20 Feb 2025

Version 16676.0

Key features
Advanced sync (IAM-8090)

Many of the mapping synchronization features available in the IDM admin console are now exposed in the Advanced Sync tab when viewing an application. You can create additional mappings between applications or between applications and identity profiles.

Enhancements

  • IAM-7967[15]: Added an image description for the approvals Low Priority icon.

  • IAM-7977: Improved the font color contrast ratio of the email address displayed in Advanced Identity Cloud admin console user profiles.

  • IAM-8053: The Advanced Identity Cloud end-user UI can now use defaultText value as a fallback value when the actual value of a field returns empty.

  • OPENIDM-20139: Applications can now use postAction scripts for the ONBOARD action.

Fixes

  • IAM-7719[15]: Users are now redirected back to the compliance Policy Rules tab after creating or editing a policy rule.

17 Feb 2025

Version 16639.0

No customer-facing features, enhancements, or fixes released.[22]

13 Feb 2025

Version 16583.0

No customer-facing features, enhancements, or fixes released.[22]

12 Feb 2025

Version 16577.0

No customer-facing features, enhancements, or fixes released.[22]

10 Feb 2025

Version 16552.0

No customer-facing features, enhancements, or fixes released.[22]

07 Feb 2025

Version 16538.0

No customer-facing features, enhancements, or fixes released.[22]

06 Feb 2025

Version 16526.0

Fixes

  • FRAAS-23812: You can now deactivate the header ruleset after deactivating the IP ruleset when configuring Proxy Connect.

04 Feb 2025

Version 16508.0

Enhancements

  • IAM-4692: Managed identity boolean fields now use a checkbox instead of a toggle.

  • IAM-6581: SAML 2.0 application journeys can now be configured in the Advanced Identity Cloud admin console.

  • IAM-7248[15]: In IGA sources, the displayName and logo can now be obtained from the CDN.

  • IAM-7874[15]: The Governance > Requests > Settings tab now lets you activate or deactivate Governance LCM.

Fixes

  • IAM-1262: Clicking the Toggle Sidebar button now collapses the sidebar.

  • IAM-5801: For applications that mandate a minimum page size, the page size selector on the Data tab and the Reconciliation Results tab has been removed.

03 Feb 2025

Version 16492.0

Fixes

  • FRAAS-23780: Optimized network utilization to distribute workloads more effectively.

January 2025

31 Jan 2025

Versions 16460.0, 16466.0

No customer-facing features, enhancements, or fixes released.[22]

30 Jan 2025

Version 16450.0

No customer-facing features, enhancements, or fixes released.[22]

29 Jan 2025

Versions 16437.0, 16441.0

No customer-facing features, enhancements, or fixes released.[22]

27 Jan 2025

Version 16419.0

No customer-facing features, enhancements, or fixes released.[22]

24 Jan 2025

Versions 16410.0, 16412.0

Enhancements

  • FRAAS-23002: Improvements to OATH support for MFA authenticators

    • Update the default OATH shared secret length from 32 to 40 for existing and new tenants so that tenant administrators can use Google Authenticator with MFA when signing on using their Advanced Identity Cloud native accounts.

    • Make the OATH shared secret length configurable (using a support request) to support other MFA authenticators.

23 Jan 2025

Versions 16386.0, 16388.0

No customer-facing features, enhancements, or fixes released.[22]

22 Jan 2025

Versions 16368.0, 16376.0

No customer-facing features, enhancements, or fixes released.[22]

21 Jan 2025

Version 16355.0

No customer-facing features, enhancements, or fixes released.[22]

20 Jan 2025

Versions 16345.0, 16348.0

Enhancements

  • IAM-7454: The inbound mapping for all application templates and scripted application templates has now been configured to make fewer connector requests.

Fixes

  • IAM-5242: The Previous link in the New Script modal now always shows the previous step.

  • IAM-7799: Identity attributes with Time and DateTime format now trigger change events only when a change occurs.

17 Jan 2025

Version 16330.0

No customer-facing features, enhancements, or fixes released.[22]

15 Jan 2025

Versions 16294.0, 16297.0

Enhancements

  • FRAAS-23375: You can now obtain the HTTP client location from the X-Client-City & X-Client-City-Lat-Long HTTP headers in Advanced Identity Cloud scripts and journeys.

    X-Client-City contains the name of the city from which the request originated, for example, Mountain View for Mountain View, California. There is no canonical list of valid values for this variable. The city names can contain US-ASCII letters, numbers, spaces, and the following characters: "!#$%&'*+-.^_`|~".

    X-Client-City-Lat-Long contains the latitude and longitude of the city from which the request originated, for example, 37.386051,-122.083851 for a request from Mountain View.

14 Jan 2025

Versions 16276.0, 16278.0

No customer-facing features, enhancements, or fixes released.[22]

13 Jan 2025

Version 16256.0

No customer-facing features, enhancements, or fixes released.[22]

10 Jan 2025

Versions 16216.0, 16229.0

Enhancements

  • IAM-6833: Made existing synchronization tokens editable for incremental reconciliations.

  • IAM-7223[15]: Added the ability to set user, role, organization, application, or entitlement objects to provide predefined values for select and multiselect fields in request forms.

Fixes

  • IAM-5482: Password policy no longer allows Password length to be set as an empty string.

08 Jan 2025

Version 16166.0

No customer-facing features, enhancements, or fixes released.[22]

06 Jan 2025

Version 16139.0

No customer-facing features, enhancements, or fixes released.[22]

03 Jan 2025

Version 16128.0

No customer-facing features, enhancements, or fixes released.[22]

03 Jan 2025

Version 15989.0

Key features
Reports for IGA data sources (ANALYTICS-571)[30]

Advanced Reporting[26] now supports various IGA[21] data sources and relationships. This lets IGA administrators create customer-friendly report templates.

Enhancements

  • ANALYTICS-459[30]: Report query data is now retained for 30 days for customers using OOTB reports and 90 days for customers with Advanced Reporting[26].

  • ANALYTICS-495[30]: Replace email with username in User Last Login report.

  • ANALYTICS-817[30][23]: Report authors can now query on "Password Last Changed Time" for user entity.

  • ANALYTICS-818[30][23]: Report authors can now query on "Password Expiration Time" for user entity.

Fixes

  • ANALYTICS-474[30]: The User Journey Stats report now provides aggregates by outcome in the report result when more than one outcome is selected.

  • ANALYTICS-837[30]: The User Count by Status report now provides aggregates by status in the report result when more than one outcome is selected

  • ANALYTICS-585[30][23]: Remove Report Admin and Report Owner group selection when creating a new report.

December 2024

21 Dec 2024

Version 16100.0

19 Dec 2024

Version 16070.0

Fixes

  • AME-29504: Fixed issue with script names not displaying in next-generation script logs.

18 Dec 2024

Version 16056.0

Enhancements

  • OPENIDM-20542: Added a feature service named am/2fa/profiles to expose certain multi-factor attributes on alpha and bravo users.

17 Dec 2024

Version 16028.0

Enhancements

  • OPENDJ-9287: The password validation mechanism has been enhanced to include checks for portions of attribute values within passwords. This improvement ensures that even partial matches between portions of passwords and portions of attribute values are identified and restricted, thereby enhancing security.

    For example, if the password is abcdef and the attribute value is abcdef123, the password is rejected. Similarly, if the password is abcdefAZERTY and the attribute value is abcdef123, the password is rejected.

16 Dec 2024

Version 15989.0

This release reintroduces many features, enhancements, and fixes previously present in reverted versions.

Key features
PingOne Authorize node (TNTP-183)

Use this node to send a decision request to a specified decision endpoint in your PingOne Authorize environment.

PingOne node improvements (SDKS-3468)
PingOne Create, Identify, and Delete Nodes

The following PingOne nodes are now available:

PingOne Identity Match node

Use the PingOne Identity Match node to identify if a user exists both in the user repository and in PingOne, using defined attributes.

PingOne Create User node

Create new users in the PingOne platform using the PingOne Create User node. Create users based on an existing user’s properties or choose to create the user anonymously. For example, when used in conjunction with PingOne Verify.

PingOne Delete User node

Delete users from the PingOne platform with the PingOne Delete User node.

PingOne Verify nodes

Use the following PingOne Verify nodes in conjunction with the PingOne Identity Match node, PingOne Create User node, and PingOne Delete User node to create a seamless verification process in your journey:

PingOne Verify Evaluation node

Leverage PingOne Verify to initiate or continue a verification transaction with the PingOne Verify Evaluation Node.

PingOne Verify Completion Decision node

Determine the completion status of the most recent identity verification transaction for an end user.

Use before the PingOne Verify Evaluation node to determine the status of the verification process or after the PingOne Verify Evaluation node using a script to evaluate the transaction.

For example, you can evaluate if the transaction was completed using a passport and route your journey accordingly.

Use these nodes in place of the PingOne Verify Marketplace nodes.
reCAPTCHA Enterprise node (SDKS-3322)

The reCAPTCHA Enterprise node node adds Google reCAPTCHA Enterprise support to your journeys.

SAML application journeys (AME-27850)

Added support for SAML application journeys with a new setting on the remote SP. Configure a specific authentication journey that always runs for users authenticating with your SAML 2.0 app, regardless of existing sessions or configured authentication context.

Learn more in Configure a SAML 2.0 application journey.

Set Failure Details node (AME-27871)

Use the Set Failure Details node to configure a localized error message on journey failure. You can also configure extra details in the response body of the failure request.

Set Success Details node (OPENAM-12335)

Use the Set Success Details node to add additional details to the success response of a journey.

UI support for managing certificates (IAM-5813)

You can now use the Advanced Identity Cloud admin console to generate CSRs and upload SSL certificates in your tenant environments.

Learn more in Manage server certificates using the admin console.

Enhancements

  • AME-26050: You can now create Next-generation Policy Condition scripts that have access to all common bindings, such as openidm and httpClient. Additionally, some existing bindings have been wrapped to improve usability in scripts.

  • AME-28228: OAuth 2.0 audit logs now include the OAuth 2.0 client ID and any journey associated with the client.

  • AME-29009: When using the new FIDO Metadata Service, if you link to the FIDO metadata using a URL, Advanced Identity Cloud periodically downloads and updates the latest FIDO metadata based on the nextUpdate date specified in the downloaded data.

  • AME-29093: Added configuration for integration with WebAuthn Metadata Services (such as the FIDO Metadata Service). This includes a realm-level WebAuthn Metadata service and a new FIDO Certification Level configuration attribute in the WebAuthn Registration Node.

  • FRAAS-22321: You can now obtain the HTTP client location from the X-Client-Region HTTP header within your scripts and journeys. The X-Client-Region header contains the country (or region) associated with the client’s IP address in the form of a Unicode CLDR region code, such as US or FR. For most countries, these codes correspond directly to ISO-3166-2 codes.

  • FRAAS-23073: The SAML scripting adapter now lets scripts access org.forgerock.http.protocol.*.

  • IAM-3323: You can now use XPath transformation functions with additional Workday application template attributes.

  • IAM-4540: You can now change the border color of a selected input field in journey and end-user pages.

  • IAM-6397: The Advanced Identity Cloud admin console now lets you page through the list of OAuth 2.0 client profiles.

  • OPENAM-23109: During a WebAuthn registration flow, if Store data in transient state is enabled, the Authenticator Attestation Global Unique Identifier (AAGUID) is now added to the node state under the webauthnData key.

Fixes

  • AME-28016: When an invalid redirect URI is provided to the /par endpoint, the URI mismatch error is now redirect_uri_mismatch instead of invalid_request.

  • AME-28017: Advanced Identity Cloud now accepts the requested OAuth 2.0 endpoint as a valid JWT audience claim, as per RFC 7519 and RFC 9126.

  • AME-29170: On LDAP Decision node login failure, stack traces are now logged at debug level.

  • AME-29965: The Configuration Provider node now works with the Inner Tree Evaluator node for nested inner journeys.

  • IAM-1782: Long gateway and agent IDs no longer overflow in the Advanced Identity Cloud admin console.

  • IAM-7523[15]: A user receiving a forwarded fulfillment task now has permission to approve or reject the task.

  • IAM-7537[15]: Governance functionality is now only shown for the alpha realm.

  • IAM-7689[15]: The Advanced Identity Cloud admin console now displays the Assigned To value in the task list for a user assigned to a role who receives a forwarded fulfillment task.

  • OPENAM-18252: Journeys acting on multiple identities now successfully update universalId in the journey context during the authentication flow.

  • OPENAM-20314: Added the ability to indicate whether an OIDC provider doesn’t return a unique value for the sub claim.

  • OPENAM-22966: Social IDPs now support NONE as a client authentication method. This option should be used if the provider doesn’t require client authentication at the token endpoint.

03 Dec 2024

Reversions

Versions 15824.0 and 15770.0 have been reverted. All changes associated with these versions have been withdrawn. This affects the following changelog entries:

02 Dec 2024

Version 15824.0

This version has been reverted and all associated changes withdrawn.

This release reintroduces many features, enhancements, and fixes previously present in reverted versions.

Key features
PingOne Authorize node

Use this node to send a decision request to a specified decision endpoint in your PingOne Authorize environment.

PingOne Create, Identify, and Delete Nodes

The following PingOne nodes are now available:

PingOne Identity Match node

Use the PingOne Identity Match node to identify if a user exists both in the user repository and in PingOne, using defined attributes.

PingOne Create User node

Create new users in the PingOne platform using the PingOne Create User node. Create users based off of an existing user’s properties or choose to create the user anonymously. For example, when used in conjunction with PingOne Verify.

PingOne Delete User node

Delete users from the PingOne platform with the PingOne Delete User node.

PingOne Verify Nodes

Use the following PingOne Verify nodes in conjunction with the PingOne Identity Match node, PingOne Create User node, and PingOne Delete User node to create a seamless verification process in your journey:

PingOne Verify Evaluation node

Leverage PingOne Verify to initiate or continue a verification transaction with the PingOne Verify Evaluation Node.

PingOne Verify Completion Decision node

Determine the completion status of the most recent identity verification transaction for an end user.

Use before the PingOne Verify Evaluation node to determine the status of the verification process or after the PingOne Verify Evaluation node using a script to evaluate the transaction.

For example, you can evaluate if the transaction was completed using a passport and route your journey accordingly.

Use these nodes in place of the PingOne Verify Marketplace nodes.
reCAPTCHA Enterprise node

The reCAPTCHA Enterprise node node adds Google reCAPTCHA Enterprise support to your journeys.

SAML application journeys (AME-27850)

Added support for SAML application journeys with a new setting on the remote SP. Configure a specific authentication journey that always runs for users authenticating with your SAML 2.0 app, regardless of existing sessions or configured authentication context.

Learn more in Configure a SAML 2.0 application journey.

Set Failure Details node (AME-27871)

Use the Set Failure Details node to configure a localized error message on journey failure. You can also configure extra details in the response body of the failure request.

Set Success Details node (OPENAM-12335)

Use the Set Success Details node to add additional details to the success response of a journey.

Enhancements

  • AME-26050: You can now create Next-generation Policy Condition scripts that have access to all common bindings, such as openidm and httpClient. Additionally, some existing bindings have been wrapped to improve usability in scripts.

  • AME-28228: OAuth 2.0 audit logs now include the OAuth 2.0 client ID and any journey associated with the client.

  • AME-29009: When using the new FIDO Metadata Service, if you link to the FIDO metadata using a URL, Advanced Identity Cloud periodically downloads and updates the latest FIDO metadata based on the nextUpdate date specified in the downloaded data.

  • AME-29093: Added configuration for integration with WebAuthn Metadata Services (such as the FIDO Metadata Service). This includes a realm-level WebAuthn Metadata service and a new FIDO Certification Level configuration attribute in the WebAuthn Registration Node.

  • AME-29769: The Social Provider Handler node has a new configuration option, Store Tokens, that allows access and refresh tokens to be stored in the transient state.

  • FRAAS-22321: You can now obtain the HTTP client location from the X-Client-Region HTTP header within your scripts and journeys. The X-Client-Region header contains the country (or region) associated with the client’s IP address in the form of a Unicode CLDR region code, such as US or FR. For most countries, these codes correspond directly to ISO-3166-2 codes.

  • IAM-3323: You can now use XPath transformation functions with additional Workday application template attributes.

  • IAM-4540: You can now change the border color of a selected input field in journey and end-user pages.

  • OPENAM-23109: During a WebAuthn registration flow, if Store data in transient state is enabled, the Authenticator Attestation Global Unique Identifier (AAGUID) is now added to the node state under the webauthnData key.

Fixes

  • AME-28016: When an invalid redirect URI is provided to the /par endpoint, the URI mismatch error is now redirect_uri_mismatch instead of invalid_request.

  • AME-28017: Advanced Identity Cloud now accepts the requested OAuth 2.0 endpoint as a valid JWT audience claim, as per RFC 7519 and RFC 9126.

  • AME-28906: The stack trace of an authentication exception generated on login failure is now logged only when debug level logging is enabled.

  • AME-29170: On LDAP Decision node login failure, stack traces are now logged at debug level.

  • IAM-7523[15]: A user receiving a forwarded fulfillment task now has permission to approve or reject the task.

  • IAM-7537[15]: Governance functionality is now only shown for the alpha realm.

  • OPENAM-18252: Journeys acting on multiple identities now successfully update universalId in the journey context during the authentication flow.

  • OPENAM-20314: Added the ability to indicate whether an OIDC provider doesn’t return a unique value for the sub claim.

  • OPENAM-22966: Social IDPs now support NONE as a client authentication method. Use this option if the provider doesn’t require client authentication at the token endpoint.

Rapid channel features

This page links to early access documentation for features available in the rapid channel and not in the regular channel. As these features become available in the regular channel, we update the links to refer to the main body of the PingOne Advanced Identity Cloud documentation.

These topics are draft documentation and subject to change.

Rapid channel changelog archive

2024

26 Nov 2024

Reversions

Version 15726.0 has been reverted. All changes associated with that version have been withdrawn. This affects the following changelog entries:

25 Nov 2024

Version 15770.0

This version has been reverted and all associated changes withdrawn.
Enhancements

  • FRAAS-22321: You can now obtain the HTTP client location from the X-Client-Region HTTP header within your scripts and journeys. The X-Client-Region header contains the country (or region) associated with the client’s IP address in the form of a Unicode CLDR region code, such as US or FR. For most countries, these codes correspond directly to ISO-3166-2 codes.

21 Nov 2024

Version 15726.0 (supplementary)

This version has been reverted and all associated changes withdrawn.
Key features
PingOne Create, Identify, and Delete Nodes [31]

The following PingOne nodes are now available:

PingOne Identity Match node

Use the PingOne Identity Match node to identify if a user exists both in the user repository as well as in PingOne, using defined attributes.

PingOne Create User node

Create new users in the PingOne platform using the PingOne Create User node. Create users based off of an existing user’s properties or choose to create the user anonymously. For example, when used in conjunction with PingOne Verify.

PingOne Delete User node

Delete users from the PingOne platform with the PingOne Delete User node.

PingOne Verify Nodes [31]

Use the following PingOne Verify nodes in conjunction with the PingOne Identity Match node, PingOne Create User node, and PingOne Delete User node to create a seamless verification process in your journey:

PingOne Verify Evaluation node

Leverage PingOne Verify to initiate or continue a verification transaction with the PingOne Verify Evaluation Node.

PingOne Verify Completion Decision node

Determine the completion status of the most recent identity verification transaction for an end user.

Use before the PingOne Verify Evaluation node to determine the status of the verification process, or after the PingOne Verify Evaluation node using a script to evaluate the transaction.

For example, you can evaluate if the transaction was completed using a passport and route your journey accordingly.

Use these nodes in place of the PingOne Verify Marketplace nodes.
reCAPTCHA Enterprise node [31]

The reCAPTCHA Enterprise node node adds Google reCAPTCHA Enterprise support to your journeys.

20 Nov 2024

Version 15726.0

This version has been reverted and all associated changes withdrawn.
Key features
Set Success Details node (OPENAM-12335)

Use the Set Success Details node to add additional details to the success response of a journey.

Set Failure Details node (AME-27871)

Use the Set Failure Details node to configure a localized error message on journey failure. You can also configure extra details in the response body of the failure request.

Enhancements

  • AME-29769: The Social Provider Handler node has a new configuration option, Store Tokens, that allows access and refresh tokens to be stored in the transient state.

  • AME-29009: When using the new FIDO Metadata Service, if you link to the FIDO metadata using a URL, Advanced Identity Cloud periodically downloads and updates the latest FIDO metadata based upon the nextUpdate date specified in the downloaded data.

  • AME-29093: Added configuration for integration with WebAuthn Metadata Services (such as the FIDO Metadata Service). This includes a realm-level WebAuthn Metadata service and a new FIDO Certification Level configuration attribute in the WebAuthn Registration Node.

  • AME-26050: You can now create Next-generation Policy Condition scripts that have access to all common bindings, such as openidm and httpClient. Additionally, some existing bindings have been wrapped to improve usability in scripts.

  • OPENAM-23109: During a WebAuthn registration flow, if Store data in transient state is enabled, the Authenticator Attestation Global Unique Identifier (AAGUID) is now added to the node state under the webauthnData key.

Fixes

  • AME-28016: When an invalid redirect URI is provided to the /par endpoint, the URI mismatch error is now redirect_uri_mismatch instead of invalid_request.

  • AME-28017: Advanced Identity Cloud now accepts the requested OAuth 2.0 endpoint as a valid JWT audience claim, as per RFC 7519 and RFC 9126.

  • AME-28906: The stack trace of an authentication exception generated on login failure is now logged only when debug level logging is enabled.

  • AME-29170: On LDAP Decision node login failure, stack traces are now logged at debug level.

  • OPENAM-18252: Journeys acting on multiple identities now successfully update universalId in the journey context during the authentication flow.

  • OPENAM-22966: Social IDPs now support NONE as a client authentication method. Use this option if the provider doesn’t require client authentication at the token endpoint.

  • OPENAM-20314: Added the ability to indicate whether an OIDC provider doesn’t return a unique value for the sub claim.

20 Nov 2024

Version 15723.0

No customer-facing features, enhancements, or fixes released.[22]

19 Nov 2024

Versions 15711.0, 15715.0

No customer-facing features, enhancements, or fixes released.[22]

18 Nov 2024

Versions 15703.0, 15708.0

No customer-facing features, enhancements, or fixes released.[22]

15 Nov 2024

Versions 15687.0, 15696.0, 15699.0

No customer-facing features, enhancements, or fixes released.[22]

14 Nov 2024

Version 15682.0

Enhancements

  • OPENDJ-11012: Added support for Microsoft Identity Cloud PBKDF2-SHA512 password scheme in Advanced Identity Cloud.

11 Nov 2024

Version 15618.0

No customer-facing features, enhancements, or fixes released.[22]

08 Nov 2024

Version 15611.0

No customer-facing features, enhancements, or fixes released.[22]

07 Nov 2024

Version 15601.0

No customer-facing features, enhancements, or fixes released.[22]

06 Nov 2024

Version 15572.0

Key features
Configure journey to always run[32] (AME-27848)

Added a new setting for journeys to always run regardless of existing user sessions.

Learn more in Configure an authentication journey to always run.

SAML application journeys (AME-27850)

Added support for SAML application journeys with a new setting on the remote SP. Configure a specific authentication journey that always runs for users authenticating with your SAML 2.0 app, regardless of existing sessions or configured authentication context.

Learn more in Configure a SAML 2.0 application journey.

SAML application script binding[32] (AME-28012)

Added a new samlApplication binding for querying the SAML 2.0 authentication request properties and IdP and SP configuration attributes.

Learn more in Query SAML application and authentication request.

Suspend and resume journeys (OPENAM-21806)

Next-generation decision node scripts can now use the new action.suspend() method to suspend the current authentication session and send a message to the user. Implement custom logic with the resume URI, for example, to send an email or SMS using the HTTP client service.

Learn more in Suspend and resume journeys.

Enhancements

  • AME-27074: Added a new configProviderScript action to each authentication node endpoint to generate a configuration provider template script, for example: authentication/authenticationtrees/nodes/MessageNode?_action=configProviderScript.

  • AME-28258: Added a new "webAuthnExtensions" input to the WebAuthn Registration and Authentication nodes. This can be set via a Scripted Decision node. It is expected to contain a map of extension name to input. Output is currently not available.

  • AME-28384: The outcome of a Scripted Decision node can now also be a CharSequence type.

  • AME-28777: The refresh token grace period now applies to both client-side refresh tokens and server-side refresh tokens.

  • AME-29157: Authentication nodes with limited possible outcomes are now available to the Configuration Provider node, including:

    The Identity Assertion node, Push Wait node, and Enable Device Management node nodes with fixed outcomes are also now available to the Configuration Provider node.

  • OPENAM-22601: You can now use the next-generation script binding, utils, to generate secure random numbers.

  • OPENAM-22811: NodeState has two new methods: mergeShared(Map<String, Object>) and mergeTransient(Map<String, Object>). Use them to merge keys into the shared/transient state, including "objectAttributes" keys.

Fixes

  • AME-25491: The Configuration Provider node script now correctly reads node state after an inner tree callback.

  • AME-28786: Removed several unused UI properties from default social identity provider profiles.

  • AME-29027: WebAuthN attestations containing a self-signed root CA are now rejected instead of silently removed.

  • OPENAM-22465: Fixed error to return invalid_resource_uri when request_uri client doesn’t match request parameter client in PAR authorise request.

  • OPENAM-22675: In next-generation scripting, you can now set a default name correctly when creating a NameCallback.

  • OPENAM-22688: Fixed Page node localization to default to correct locale when the incoming accepted-language header doesn’t match the node’s language configuration.

05 Nov 2024

Version 15570.0

No customer-facing features, enhancements, or fixes released.[22]

04 Nov 2024

Version 15559.0

No customer-facing features, enhancements, or fixes released.[22]

01 Nov 2024

Version 15551.0

No customer-facing features, enhancements, or fixes released.[22]

31 Oct 2024

Version 15532.0

No customer-facing features, enhancements, or fixes released.[22]

30 Oct 2024

Version 15508.0

No customer-facing features, enhancements, or fixes released.[22]

29 Oct 2024

Versions 15466.0, 15472.0

Enhancements

  • IAM-6388: Added the ability to specify that inner journeys can’t be accessed directly.

  • IAM-7185: The mapping tab for application provisioning now shows the inbound or outbound application type without needing to inspect a drop-down.

Fixes

  • IAM-7415: When creating an assignment, the _id is now automatically generated instead of using the name specified.

28 Oct 2024

Version 15453.0

No customer-facing features, enhancements, or fixes released.[22]

25 Oct 2024

Version 15434.0

No customer-facing features, enhancements, or fixes released.[22]

23 Oct 2024

Version 15399.0

No customer-facing features, enhancements, or fixes released.[22]

22 Oct 2024

Version 15374.0

No customer-facing features, enhancements, or fixes released.[22]

17 Oct 2024

Versions 15335.0, 15337.0

No customer-facing features, enhancements, or fixes released.[22]

16 Oct 2024

Versions 15321.0

No customer-facing features, enhancements, or fixes released.[22]

15 Oct 2024

Versions 15310.0, 15312.0

No customer-facing features, enhancements, or fixes released.[22]

14 Oct 2024

Version 15300.0

Enhancements

  • IAM-7187: Integration of SAP app template with IDM scripts.

  • IAM-7243[15]: Added text field to utilities category in IGA access request forms.

Fixes

  • IAM-7385: Unable to create user when required boolean property is set to false.

10 Oct 2024

Version 15258.0

No customer-facing issues released.[22]

07 Oct 2024

Version 15211.0

Enhancements

FRAAS-22177: Renamed "Advanced Gateway" to "Proxy Connect" throughout Advanced Identity Cloud, including URLs, OpenID Connect scopes, autogenerated code snippets, and UI labels.

01 Oct 2024

Versions 15154.0, 15158.0

Enhancements

IAM-4753: Added a toggle to the application catalog to hide deprecated templates.

30 Sept 2024

Versions 15136.0, 15139.0, 15143.0

No customer-facing issues released.[22]

27 Sept 2024

Version 15124.0

No customer-facing issues released.[22]

26 Sept 2024

Versions 15111.0, 15114.0

No customer-facing issues released.[22]

25 Sept 2024

Versions 15084.0, 15096.0

No customer-facing issues released.[22]

24 Sept 2024

Version 15063.0

No customer-facing issues released.[22]

23 Sept 2024

Version 15058.0

No customer-facing issues released.[22]

20 Sept 2024

Versions 15044.0, 15052.0

Key features
Support for LINE as a social identity provider (AME-28672)

You can now configure a social provider authentication with LINE Login when signing in from a browser. There is a separate configuration for authenticating from a mobile app.

Learn more in Social authentication.

Identity Governance request and approval forms[15] (IAM-6358)

Identity Governance now lets you create request and approval forms to make it easier for end users to request access to applications.

Learn more in Identity Governance forms.

Enhancements

  • OPENAM-22666: The well-known endpoint is no longer required when configuring a social identity provider service. If it is not provided, Advanced Identity Cloud uses the client secret for signature verification.

Fixes

  • FRAAS-16228: Promotions are now halted if the AM CORS service is disabled; the service is essential to the correct functioning of promotions.

16 Sept 2024

Version 14975.0

Key features
Additional cloud connectors

The following connectors are now bundled with Advanced Identity Cloud:

  • AWS IAM Identity Center Connector v1.5.20.23 (OPENIDM-20038)

  • Box Connector v1.5.20.23 (OPENIDM-20367)

Learn more in the ICF documentation.

Enhancements

  • OPENIDM-19698: Added ability to use wildcards in the watchedFields property.

Fixes

  • OPENIDM-19336: Fixed an issue where delegated administrators couldn’t add new users to their organization.

  • OPENIDM-20238: Fixed an issue where clustered reconciliation can fail with "Expecting a Map or List" under specific circumstances.

13 Sept 2024

Version 14962.0

Key features
Advanced Reporting[26] (ANALYTICS-763)

Advanced Identity Cloud now offers Advanced Reporting to let you create custom reports on activity in your tenant environments. You can query a number of metrics to create useful reports for your company.

Learn more in Advanced Reporting.

Fixes

  • FRAAS-21715: Environments can now be unlocked if configuration rollback fails because there are no promotions to roll back.

11 Sept 2024

Version 14927.0

No customer-facing issues released.[22]

10 Sept 2024

Versions 14912.0, 14920.0

No customer-facing issues released.[22]

09 Sept 2024

Versions 14868.0, 14888.0

Key features
Scripted SAML 2.0 NameID values(AME-25921)

The NameID mapper script lets you customize SAML 2.0 NameID values per application.

Set State node (AME-26443)

The Set State node lets you add attributes to the journey state.

Http Client service (AME-27936)

The new Http Client service lets you create named instances that you can reference from a next-generation script to make mTLS connections to external services.

Learn more in Access HTTP services.

Enable Device Management node (SDKS-2919)

The new Enable Device Management node lets end users manage devices from their account.

Enhancements

  • FRAAS-21728: Updated the cookie domain API to add default values for GET requests where cookie domain values haven’t been overridden by a PUT request. The default values are derived from the existing tenant cookie domain configuration, so are backward compatible.

  • AME-26594: Added secrets API binding to all next-generation script contexts.

  • AME-27129: Added option to exclude client certificate from SAML hosted SP metadata.

  • AME-27792: Added AM-TREE-LOGIN-COMPLETED audit log event that outputs a result of FAILED. when a journey ends with an error.

  • AME-27839: Added the ability to specify connection and response timeouts for Http Client service instances.

  • AME-28008: You can now disable certificate revocation checks, or all certificate checks entirely, on your Http Client service instances.

Fixes

  • OPENAM-15410: Fixed an issue that prevented customization of claims if profile and openid scopes are requested.

  • OPENAM-20609: Fixed inconsistent error message when generating access token using refresh token after changing username.

  • OPENAM-21974: Adds an OAuth 2.0 client configuration for the new version of the LinkedIn provider.

  • OPENAM-22298: Log unretrieved SP and IdP descriptors in SAML2 Authentication node.

06 Sept 2024

Versions 14851.0, 14858.0

No customer-facing issues released.[22]

05 Sept 2024

Version 14848.0

No customer-facing issues released.[22]

03 Sept 2024

Version 14800.0

No customer-facing issues released.[22]

02 Sept 2024

Version 14781.0

No customer-facing issues released.[22]

30 Aug 2024

Versions 14761.0, 14767.0

Fixes

  • FRAAS-21713: The promotion process now retries getting an access token from the lower environment, preventing promotion failures.

29 Aug 2024

Version 14741.0

Key features
DocuSign application template (IAM-6194)

The DocuSign application lets you manage DocuSign service accounts and synchronize DocuSign accounts and Advanced Identity Cloud identities.

Enhancements

  • IAM-6493: The PingOne application template now supports specifying an LDAP gateway.

  • IAM-6868: Added screen reader label to end-user access approval button.

  • IAM-6870: Added screen reader label to end-user access request button.

  • IAM-6880: Added a toggle in the hosted pages journey settings to disable the error heading fallback that displays if there is no heading in the page content. (FORGEROCK-1582)

Fixes

  • IAM-7033: Unable to save user filter in AD/LDAP app template.

27 Aug 2024

Version 14717.0

No customer-facing issues released.[22]

26 Aug 2024

Version 14683.0

No customer-facing issues released.[22]

22 Aug 2024

Version 14652.0, 14669.0

No customer-facing issues released.[22]

21 Aug 2024

Version 14626.0

Key features
BeyondTrust application template (IAM-6492)

The BeyondTrust application lets you manage and synchronize data from Advanced Identity Cloud to BeyondTrust.

Enhancements

  • IAM-7011: Older app templates are no longer marked "deprecated".

19 Aug 2024

Version 14592.0

No customer-facing issues released.[22]

16 Aug 2024

Versions 14568.0

No customer-facing issues released.[22]

14 Aug 2024

Versions 14530.0, 14538.0

No customer-facing issues released.[22]

13 Aug 2024

Version 14516.0

No customer-facing issues released.[22]

12 Aug 2024

Version 14467.0

No customer-facing issues released.[22]

09 Aug 2024

Version 14465.0

No customer-facing issues released.[22]

08 Aug 2024

Version 14454.0

No customer-facing issues released.[22]

07 Aug 2024

Versions 14443.0, 14450.0

No customer-facing issues released.[22]

06 Aug 2024

Version 14442.0

No customer-facing issues released.[22]

05 Aug 2024

Versions 14425.0, 14432.0

No customer-facing issues released.[22]

02 Aug 2024

Versions 14410.0, 14417.0

Enhancements

  • IAM-5233: Update SAP SuccessFactors app template to support connector version 1.5.20.22.

  • IAM-6874: Update journey analytics to use hourly data.

Fixes

  • FRAAS-21318: Promotion report now categorizes AM session service changes correctly.

25 Jul 2024

Versions 14309.0, 14313.0

No customer-facing issues released.[22]

24 Jul 2024

Versions 14275.0, 14277.0, 14285.0

No customer-facing issues released.[22]

23 Jul 2024

Versions 14257.0, 14260.0

No customer-facing issues released.[22]

22 Jul 2024

Version 14238.0

No customer-facing issues released.[22]

19 Jul 2024

Version 14225.0

Key features
Adobe Admin Console application template (IAM-6195)

The Advanced Identity Cloud Adobe Admin Console application lets you manage users, groups, and user group memberships between Adobe Admin Console and Advanced Identity Cloud.

Enhancements

  • IAM-4279: Display available ESV placeholders in Decision Node script editor.

  • IAM-4654: Enable creation of all script types in Advanced Identity Cloud admin console.

Fixes

  • IAM-5356: Session logout warning not displaying when maximum idle time set to a higher value than maximum session time.

  • IAM-6628: New draft option shouldn’t exist for out-of-the-box workflows.

  • IAM-6779: Pagination for list of apps not working when there are over 4000 apps.

18 Jul 2024

Version 14199.0, 14213.0

No customer-facing issues released.[22]

17 Jul 2024

Version 14175.0, 14187.0

No customer-facing issues released.[22]

16 Jul 2024

Version 14160.0, 14165.0

No customer-facing issues released.[22]

15 Jul 2024

Version 14149.0, 14150.0, 14156.0

No customer-facing issues released.[22]

12 Jul 2024

Versions 14108.0, 14113.0

Fixes

  • FRAAS-20397: The promotion process now retries tagging the lower environment after a network interruption, preventing blocking promotion failures.

11 Jul 2024

Versions 14100.0, 14101.0

No customer-facing issues released.[22]

10 Jul 2024

Version 14093.0

No customer-facing issues released.[22]

09 Jul 2024

Version 14069.0

No customer-facing issues released.[22]

08 Jul 2024

Versions 14062.0, 14063.0

Fixes

  • FRAAS-20983: Promotion reports now list changes to the default OAuth 2.0 provider.

05 Jul 2024

Versions 14046.0, 14047.0

No customer-facing issues released.[22]

03 Jul 2024

Version 14018.0

No customer-facing issues released.[22]

02 Jul 2024

Version 14013.0

Fixes

  • FRAAS-20970: The /monitoring/logs endpoint now returns an X-Ratelimit-Limit header with a fixed value of 60. Previously, the value was misleading due to the way it was calculated when scaling an environment’s resources. The X-Ratelimit-Remaining header continues to report the number of requests that may be sent before receiving a rate limited response.

01 Jul 2024

Versions 13982.0, 14004.0

Fixes

  • OPENIDM-18495: Disable sorting in the connector data tab in the IDM native admin console.

27 Jun 2024

Versions 13964.0, 13966.0

Key features
Additional cloud connectors

The following connectors are now bundled with Advanced Identity Cloud:

  • Adobe Admin Console connector (OPENIDM-19843)

  • DocuSign connector (OPENIDM-20190)

For more information, refer to the ICF documentation.

Fixes

  • OPENIDM-20142: Resolved a communication failure between Advanced Identity Cloud and RCS instances that could result in a prolonged failure to activate remote connectors.

Changed functionality

  • OPENIDM-20178: You can’t use scope private fields in query filters. For more information, refer to link:Security Advisory #202402.

26 Jun 2024

Versions 13953.0, 13956.0

No customer-facing issues released.[22]

25 Jun 2024

Version 13945.0

No customer-facing issues released.[22]

24 Jun 2024

Versions 13937.0

Key features
Product name change for Identity Cloud (FRAAS-20178)

To align ForgeRock products with Ping family names, ForgeRock Identity Cloud has been renamed to PingOne Advanced Identity Cloud. Name and logo changes have been updated throughout the user interfaces, and documentation updates will occur when the UI changes are released to the regular channel.

Enhancements

  • IAM-4785: Synchronize only the modified properties on a target source during reconciliation of applications.

  • IAM-5237[15]: Add ability for B2B business partners to certify access for their users using organizational-based certification.

  • IAM-5487: Correlation rules moved to the top of the reconciliation settings page.

  • IAM-5629[15]: Add ability to create scoping rules in Identity Governance.

  • IAM-6231: Scripted Decision Node now updates the list of scripts when a script is added or edited.

  • IAM-6544[15]: Add reviewer column to administrator list view of compliance violations.

Fixes

  • IAM-6135: ESV values containing accents get corrupted by encoding process.

  • IAM-6562: Label duplicated for OAuth 2.0 access token and ID token endpoints.

  • IAM-6669[15]: Badge count of violations in end-user navigation doesn’t update when an action is performed.

18 Jun 2024

Versions 13896.0, 13900.0

Key features
PingOne Protect nodes[33] (TNTP-180)

The new PingOne Protect nodes replace the deprecated PingOne Protect Marketplace nodes.

Fixes

  • FRAAS-20604: Removed superfluous AM metrics related to token store internals:

    • am_cts_connection_count

    • am_cts_connection_seconds

    • am_cts_connection_seconds_total

    • am_cts_connection_state

    • am_cts_reaper_cache_size

    • am_cts_reaper_deletion

    • am_cts_reaper_deletion_count

    • am_cts_reaper_deletion_total

  • FRAAS-20786: Fix promotion issue where an attempt was made to delete an already deleted application.

17 Jun 2024

Version 13890.0

No customer-facing issues released.[22]

14 Jun 2024

Version 13877.0

No customer-facing issues released.[22]

13 Jun 2024

Version 13865.0

No customer-facing issues released.[22]

12 Jun 2024

Version 13848.0

Key features
New utility binding available for scripting (AME-25519)

You can now use a new utility binding in your scripts to access several common utility classes. For example, the utility binding includes classes for generating random UUIDs and for base64 encoding and decoding.

Enhancements

  • AME-26199: Added the ability to set additional claims, including non-registered claims, during JWT assertion and generation, as per the specification.

  • AME-26820: Provided library scripts with access to all common script bindings.

  • AME-26993: Enhanced secret mapping for agents. Updating a secret label identifier value now causes any corresponding secret mapping for the previous identifier to also be updated, provided no other agent shares that secret mapping. If another agent shares the secret mapping, Advanced Identity Cloud creates a new secret mapping for the updated identifier and copies its aliases from the previously shared secret mapping.

  • AME-27346: Renamed Secret ID Identifier to Secret Label Identifier in the SAML remote entity provider configuration.

  • AME-27478: Renamed Client ID Token Public Encryption Key property to ID Token Encryption Public Key in the OAuth 2.0 client configuration.

  • AME-27775: Added scripting thread pool metrics per script context.

  • OPENAM-16564: Enabled next-generation scripts to access the cookies in incoming requests.

  • OPENAM-21800: Added page node functionality to next-generation scripts.

  • OPENAM-21933: Enabled auto-encoding of the httpClient form body in next-generation scripts.

Fixes

  • FRAAS-19461: Fixed an issue where large audit logs could be missing from IGA events and processing.

  • OPENAM-21748: Restored the missing get wrapper function for HiddenValueCallback in next-generation scripting.

  • OPENAM-21864: Fixed an issue that prevented setting the tracking cookie to resume a journey after returning from a redirect flow.

  • OPENAM-21897: Corrected inconsistent results from the policy evaluateTree endpoint.

  • OPENAM-21951: Enabled setting of the selectedIndex property in a ChoiceCallback in next-generation scripts.

  • OPENAM-22181: Corrected an issue with UMA approve and approveAll requests failing.

05 Jun 2024

Version 13760.0

Enhancements

  • FRAAS-20048: Configuration promotions can now be rolled back using the API. An environment can be rolled back successively to revert as many previous promotion changes as needed.

    This feature can’t be used in sandbox environments; a promotion or a rollback can only be run between development, UAT[2], staging, and production environments.

04 Jun 2024

Version 13741.0

No customer-facing issues released.[22]

03 Jun 2024

Version 13731.0

Fixes

  • FRAAS-20154: ESVs with special characters are now correctly encoded. The workaround of double-encoding ESVs is no longer required.

03 Jun 2024

Fixes

  • FRAAS-11180: Authentication session whitelisting is now enabled by default for new tenants[34]

  • IAM-5593: Adding roles to certain objects no longer breaks readable titles[34]

  • IAM-6537: Journey import now alerts users if they try to import a file containing missing references[34]

22 May 2024

Versions 13570.0

Key features
Oracle E-Business Suite app template (IAM-6342)

The Oracle E-Business Suite (EBS) application lets you manage and synchronize accounts between EBS and Advanced Identity Cloud.

Enhancements

  • IAM-6376: In the applications rules tab, you can now configure custom logic to perform specific actions, such as sending an email, when an account is successfully created or updated.

  • IAM-6380: In the applications rules tab, you can now use the provisioning failure rule to configure custom logic to perform specific actions when provisioning fails.

21 May 2024

Versions 13548.0, 13552.0, 13562.0

Enhancements

  • FRAAS-15404: When updating ESV secrets, the API saves a new secret version only when it differs from the previous value.

20 May 2024

Version 13528.0

Key features
Improved promotion of applications (FRAAS-19241)

It is now possible to promote applications via the API and not just the UI.

Additionally, the provisional report has been improved to only show applications that have changed, rather than always show all applications in the report.

Enhancements

  • FRAAS-19982: Configuration promotion now fails if Advanced Identity Cloud services do not restart successfully with the new configuration.

16 May 2024

Version 13493.0

No customer-facing issues released.[22]

15 May 2024

Versions 13477.0, 13482.0

No customer-facing issues released.[22]

14 May 2024

Versions 13464.0, 13465.0

No customer-facing issues released.[22]

13 May 2024

Versions 13445.0

No customer-facing issues released.[22]

10 May 2024

Versions 13417.0, 13424.0, 13426.0

No customer-facing issues released.[22]

07 May 2024

Versions 13361.0, 13359.0

No customer-facing issues released.[22]

06 May 2024

Versions 13352.0

No customer-facing issues released.[22]

03 May 2024

Key features
Webex application template (IAM-5234[35])

The Advanced Identity Cloud Webex application lets you manage and synchronize data between Webex Control Hub and Advanced Identity Cloud.

Epic EMP application template (IAM-2407)

The Epic EMP application lets you manage and synchronize data between Epic EMP and Advanced Identity Cloud.

Enhancements

  • IAM-2653: Configure object properties with user-friendly display names.

  • IAM-3857: Application list view displays enabled/disabled status of enterprise apps.

  • IAM-5913[15]: Create custom access request workflows.

Fixes

  • IAM-6264: Approval actions display in the UI even when they are not available due to permissions.

  • IAM-6296: UI doesn’t display paginated results on application data and recon tabs.

  • IAM-6409: Logging out of UI generates malformed redirect realm URLs.

01 May 2024

Versions 13317.0

No customer-facing issues released.[22]

30 Apr 2024

Versions 13300.0, 13310.0, 13313.0

No customer-facing issues released.[22]

29 Apr 2024

Version 13293.0, 13294.0

No customer-facing issues released.[22]

26 Apr 2024

Version 13291.0, 13289.0

No customer-facing issues released.[22]

25 Apr 2024

Version 13283.0

No customer-facing issues released.[22]

24 Apr 2024

Version 13281.0

Fixes

  • TNTP-166:

    • Add configuration options to P1 Verify Authentication nodes.

    • Verify code not visible when using QR option.

    • Set claim mapping only in shared state in P1 Proofing node.

23 Apr 2024

Version 13277.0, 13265.0

No customer-facing issues released.[22]

22 Apr 2024

Version 13239.0

Fixes

  • FRAAS-19593: The promotion API incorrectly reports as ready, resulting in a blocking promotion failure when trying to promote. (FORGEROCK-1319)

18 Apr 2024

Version 13237.0

Fixes

  • OPENIDM-19879: Identity Management reconciliation service processes additional source query pages whenever a query returns a pagedResultsCookie.

  • OPENIDM-19924: Unnecessary quotes not being removed from email addresses.

17 Apr 2024

Version 13218.0

Key features
Event-based certification[15] (IAM-5148)

Identity Governance now allows tenant administrators to configure certifications that are triggered by specific governance events, a process referred to as event-based certification. This method offers faster certification resolution compared to scheduled—​and often lengthy—​campaigns spanning weeks or months and involving numerous applications, intricate rules, and hundreds of reviewers.

The event-based certifications feature kicks off an identity certification for the following events:

  • User create. Advanced Identity Cloud detects when a user account has been created.

  • User modify. Advanced Identity Cloud detects when an existing user account has been modified or updated.

  • Attribute change. Advanced Identity Cloud detects changes in the attributes of an existing user account.

  • User delete/deactivate. Advanced Identity Cloud detects if a user account has been deleted or deactivated.

For more information, refer to Certify access by event.

Grant entitlements to users and roles[15] (IAM-5146)

Identity Governance now allows tenant administrators to carry out more fine-grained entitlement grants for their user accounts. Tenant administrators can now:

  • Create a role and grant entitlements to the role.

  • Revoke entitlements in a role.

  • Grant entitlements to a user account.

  • Revoke entitlements from a user account.

For more information, refer to Manage entitlements.

Identity Assertion node (AME-26821)

The new Identity Assertion node provides a secure communication channel for authentication journeys to communicate directly with PingGateway.

PingOne application template (IAM-5232)

The PingOne application lets you manage and synchronize data between PingOne and Advanced Identity Cloud.

Authenticate gateway and agent profiles with a shared secret (IAM-5833)

The Advanced Identity Cloud admin console for gateways and agents now lets you authenticate with a shared secret instead of a password. Use this to set the label for the shared secret.

Authenticate OAuth 2.0 applications with a shared secret (IAM-6028)

The Advanced Identity Cloud admin console for OAuth 2.0 applications now lets you authenticate with a shared secret instead of a password. Use this to set the label for the shared secret.

Enhancements

  • OPENAM-21031: The performance of Google KMS has been improved by the introduction of caching.

  • AME-27126: A SAML SP can now authenticate to IDPs using mutual TLS (mTLS) when making an artifact resolution request.

  • IAM-3199: HTML styling in the Message node journey editor allows you to left justify text.

Fixes

  • FRAAS-19334: Failure to look up service account names following changes applied through the ESV API.

  • IAM-5079[15]: End-user roles page sometimes shows role grants as conditional even when the grants are direct.

  • IAM-5363[15]: Show the total number of approvals and access reviews in the inbox.

  • IAM-5858[15]: Missing support for access request global configuration options.

  • IAM-6138[15]: The governance events filter builder incorrectly validates before and after properties in the user created state.

  • IAM-6176[15]: The end-user access request rejection is missing a justification message.

  • IAM-6203[15]: The governance events filter doesn’t use after temporal values for user created flows.

  • IAM-6209: The Advanced Identity Cloud admin console navigation panel text appears when the panel is collapsed.

  • OPENAM-21473: If you set the collection method of a Certificate Collector node to REQUEST, HEADER, or EITHER, and the certificate is not provided in the request or in the header, the node now returns a status of Not collected.

    This node is currently not supported in Advanced Identity Cloud.

  • SDKS-2935: The Device Binding node now gracefully handles the case of a user being set to inactive.

12 Apr 2024

Version 13162.0

Fixes

  • FRAAS-19596: Configuration promotion report should include changes to realm authentication settings.

11 Apr 2024

Version 13149.0

Enhancements

  • AME-26085: SAML 2.0 NameID mapping can be configured per SP

  • AME-27133: "Secret ID" has been renamed to "Secret Label" for secret mappings

  • The following services now support configuration using the Secrets API:

    • AME-16536: The OAuth 2.0 provider hash salt secret

    • AME-25885: The persistent cookie core authentication attribute

    • AME-26110: The client-side session signing key

    • AME-26134: The social provider service

    • AME-26441: The new CAPTCHA node (replaces the legacy CAPTCHA node)

    • AME-26442: The OIDC Token Validator node now lets you store the client secret in any type of secret store

    • AME-26633: The OAuth 2.0 client clientJwtPublicKey

    • AME-26637: The OAuth 2.0 client idTokenPublicEncryptionKey

    • AME-26639: OAuth 2.0 client mTLS self-signed certificates

    • AME-26668: The post authentication process (PAP) replay password

    • AME-26670: The web agents replay password key

    • AME-26998: The OAuth 2.0 client secret

  • The following services now support rotation of secrets using secret versions:

    • AME-25988: The persistent cookie encryption secret

    • AME-26999: OAuth 2.0 client secrets

    • AME-27000: OAuth 2.0 client clientJwtPublicKey

    • AME-27001: OAuth 2.0 client mTLS self-signed certificates

09 Apr 2024

Version 13122.0

Key features
PingOne Verify service node (TNTP-118)

The PingOne Verify service node lets you configure and use PingOne Verify nodes (PingOne Verify Authentication node and PingOne Verify Proofing node) in your authentication journeys.

08 Apr 2024

Version 12666.0

No customer-facing issues released.[22]

04 Apr 2024

Version 12589.0

No customer-facing issues released.[22]

02 Apr 2024

Version 13009.0

Enhancements

  • FRAAS-19566: Add _sortKeys query parameter to ESV API

01 Apr 2024

Version 12988.0

No customer-facing issues released.[22]

29 Mar 2024

Versions 12974.0, 12960.0, 12957.0

No customer-facing issues released.[22]

28 Mar 2024

Versions 12957.0

No customer-facing issues released.[22]

27 Mar 2024

Versions 12957.0, 12934.0

No customer-facing issues released.[22]

26 Mar 2024

Versions 12899.0

Key features
Social Provider Handler node[36] (OPENAM-20924)

The new Social Provider Handler node adds an outcome to better handle interruptions in a social authentication journey after requesting profile information.

Event-based certification[15] (IGA-2357)

Identity Governance now allows tenant administrators to configure certifications that are triggered by specific governance events, a process referred to as event-based certification. This method offers faster certification resolution compared to scheduled—​and often lengthy—​campaigns spanning weeks or months and involving numerous applications, intricate rules, and hundreds of reviewers.

The event-based certifications feature kicks off an identity certification for the following events:

  • User create. Advanced Identity Cloud detects when a user account has been created.

  • User modify. Advanced Identity Cloud detects when an existing user account has been modified or updated.

  • Attribute change. Advanced Identity Cloud detects changes in the attributes of an existing user account.

  • User delete/deactivate. Advanced Identity Cloud detects if a user account has been deleted or deactivated.

    For more information, refer to Certify access by event.

Grant entitlements to users and roles[15] (IAM-5146)

Identity Governance now allows tenant administrators to carry out more fine-grained entitlement grants for their user accounts. Tenant administrators can now:

  • Create a role and grant entitlements to the role.

  • Revoke entitlements in a role.

  • Grant entitlements to a user account.

  • Revoke entitlements from a user account.

    For more information, refer to Manage entitlements.

Enhancements

  • AME-26130[36]: Updated the PUSH Notification service to store access keys as a secret

  • AME-25906[36]: Updated Identity Gateway agents to store credentials as a secret

  • IAM-4585: Request and approvals page now shows the current and past approvers, their decisions, and the dates

  • IAM-4968: Expose additional top-level parameters in the advanced section of mapping pages

  • IAM-5769: Add grouping logic to journey node items

  • IAM-5674: Target application can use ONBOARD action for FOUND situation

  • IAM-5814: Allow fixed application usernames to be chosen for custom SAML apps

  • OPENAM-21575[36]: Added org.forgerock.json.jose.jwe.JweHeader to the allowlist for Scripted Decision nodes

Fixes

  • AME-25915[36]: Assertion consumer processing fails if NameID format not present in the assertion response

  • IAM-3927[15]: Identity Governance now enforces mandatory comments (if configured) for revoke and allow exceptions

  • IAM-4309: Access reviews no longer display the internal lastSync user attribute

  • IAM-4762: Authoritative apps are now requestable

  • IAM-4986: Platform UI can now determine whether to use a pagedResultsCookie or offset for paging results

  • IAM-5076: "Abstain from action" option no longer displays when a campaign has expired

  • IAM-5362: Marking a property as an authoritative app entitlement no longer causes target app config to be generated

  • IAM-5413: Account deprovisioning now works in AD/LDAP after deleting a user identity

  • IAM-5794: Border color of sign-in input fields in hosted pages can now be overridden in themes

  • IAM-5875: Journey editor no longer orphans deleted nodes

25 Mar 2024

Versions 12899.0, 12894.0

No customer-facing issues released.[22]

22 Mar 2024

Version 12878.0

Enhancements

  • FRAAS-19414: You can now configure custom domains directly in all environments without needing to create ESVs or promote configurations. Existing custom domains will be migrated automatically.

21 Mar 2024

Versions 12899.0, 12863.0, 12855.0

Key features
Additional cloud connectors

The following connectors are now bundled with Advanced Identity Cloud:

  • Dropbox connector (OPENIDM-19838)

  • PingOne connector (OPENIDM-19736)

  • Webex connector (OPENIDM-19920)

For more information, refer to the ICF documentation.

Enhancements

  • OPENIDM-19921: The following connectors included with Advanced Identity Cloud were upgraded to 1.5.20.21:

    • Google Apps connector

    • Microsoft Graph API connector

    • AWS connector

    For details, refer to 1.5.20.21 Connector changes.

19 Mar 2024

Versions 12820.0, 12815.0

No customer-facing issues released.[22]

18 Mar 2024

Versions 12873.0, 12784.0

Enhancements

  • FRAAS-19341: ESV support for AES keys through the base64aes encoding type

    For more information, refer to Encoding format.

15 Mar 2024

Versions 12754.0

Key features
PingOne Service (TNTP-148)

Set up the PingOne Service in your Advanced Identity Cloud tenant so you can add Ping Identity nodes to your authentication journeys.

PingOne nodes (TNTP-119)
PingOne node

The PingOne node establishes trust between PingOne and Advanced Identity Cloud by leveraging a federated connection. Learn more in PingOne node.

PingOne DaVinci API node

The PingOne DaVinci API node lets an Advanced Identity Cloud journey trigger a PingOne DaVinci flow through the API integration method. Learn more in PingOne DaVinci API node.

PingOne Protect nodes (TNTP-127)

Ping Identity’s PingOne Protect is a centralized identity threat protection service, for securing your digital assets against online fraud attempts.

Learn more in PingOne Protect > How it Works.

14 Mar 2024

Versions 12736.0

No customer-facing issues released.[22]

13 Mar 2024

Version 12714.0

Key features
HTTP Client node (TNTP-136)

The HTTP Client node lets you make HTTP(S) requests to APIs and services external to Advanced Identity Cloud from within a journey.

Use the HTTP Client node to simplify the integration with a broad range of external services by making direct HTTP(S) requests.

For more information, refer to HTTP Client node.

Enhancements

  • IAM-5602: Add functionality for viewing and deleting user’s trusted devices in Advanced Identity Cloud admin console

08 Mar 2024

Versions 12666.0

No customer-facing issues released.[22]

04 Mar 2024

Versions 12589.0

No customer-facing issues released.[22]

02 Mar 2024

Version 12580.0

Enhancements

  • The following services now support setting secrets using the secrets API rather than setting secrets in the service configuration:

    • AME-25709: AuthId signing key

    • AME-25907: Java agents

    • AME-25908: Web agents

    • AME-26014: Rotatable secrets for agents

    • AME-26301: SAML remote entities

    • AME-26241: OATH, Push, Web AuthN devices and the device binding, device ID, and Device profile services

  • The following nodes now support setting their secrets using the secrets API rather than setting secrets in the node configuration:

    • AME-26117: OTP SMS Sender and OTP SMTP Sender nodes

    • AME-16535: Set Persistent Cookie node

  • AME-26041: Enhanced handling of agents secret mappings – if you update or delete a secret label identifier, any corresponding secret mapping for the previous identifier is updated or deleted, provided no other agent shares that secret mapping

  • AME-25434: New Request Header node lets you inject values into shared state based on request header values

  • AME-26039: Added LDAP Affinity Level configuration option to the LDAP Decision node, to enable affinity-based load balancing for BIND requests

  • OPENAM-21768: Added org.forgerock.opendj.ldap.Rdn and org.forgerock.opendj.ldap.Dn classes to the allowlist for all script contexts

Fixes

  • AME-24760: Inner nodes of a PageNode don’t independently audit node-login-complete events

  • AME-26158: Exception thrown when generating a Signed JWT with no encryption within a next-gen script called by a Scripted Journey node

  • OPENAM-17315: Scripts used to call 'response.getEntity()' in the past should now use 'response.getEntity().getString()' instead

  • OPENAM-21856: Introspecting stateless token with IG/Web agents causes OAuth2ChfException

01 Mar 2024

Versions 12560.0

No customer-facing issues released.[22]

29 Feb 2024

Version 12560.0

Enhancements

  • IAM-4257: Azure AD app template updates

  • IAM-4342: MSGraphAPI connector includes a new optional licenseCacheExpiryTime configuration property

  • IAM-4892: Salesforce app template updates

  • IAM-4900: UI has been updated to show the Advanced Identity Cloud build number

  • IAM-5033: Added new "Remember my username" checkbox to authentication trees

  • IAM-5287: Updated username, password, and KBA heading size on the profile page to improve accessibility

  • IAM-5334: Expose "Guarded String" as an object type property for Scripted Groovy, ScriptedREST, ScriptedSQL, CSV, Database table, and SCIM connectors

  • IAM-5459: KBA answer field now contains question context

  • IAM-5461: Custom errors sent as TextOutputCallback.ERROR are now rendered as primary login errors, improving screen reader accessibility feature

  • IAM-5503: Rename Orchestrations to Workflows

  • IAM-5563: Google Apps app template updates

  • IAM-5603: Create device details modal for managed user identities

  • IAM-5606: Add "POWERED BY" metadata to marketplace nodes

  • IAM-5748: Make "PingOne" a special case on the federation providers page

Fixes

  • IAM-5598: Styled terms and conditions included in a journey causes authenticate calls to fail

  • IAM-5611: Can’t revoke custom apps from roles or edit them from the role view

  • IAM-5641: Custom endpoints search returns endpoints created by other areas of the UI

  • IAM-5692: Console errors when opening the Add user modal for Bravo realm

  • IAM-5767: SAML SSO is not used when an application is saved from another tab after SSO setup

  • IAM-5873: Hosted page may fail to match user locale

28 Feb 2024

Version 12547.0

Enhancements

15 Feb 2024

Fixes

  • FRAAS-18455: Prevent the latest version of a secret from being deleted

12 Feb 2024

Enhancements

  • FRAAS-18788: Add AWS, GCP, and SAP S/4HANA connectors to Advanced Identity Cloud

07 Feb 2024

Fixes

  • FRAAS-18693: Validation bug prevents use of the base64encodedinlined and keyvaluelist ESV expression types

06 Feb 2024

Fixes

  • FRAAS-18414: Changes to an out-of-the-box journey can be incorrectly reported against both realms

25 Jan 2024

Fixes

  • FRAAS-18526: Script library functionality can’t be used in the UI in certain environments

24 Jan 2024

Enhancements

  • OPENIDM-17878[37]: Allow access to operational attributes in the Advanced Identity Cloud data store

  • OPENIDM-18645[37]: Add ESV support to oauthProxy script

Fixes

  • OPENIDM-18743[37]: Attempts to use connectors fail with null pointer exceptions when operationOptions is defined in the provisioner configuration

23 Jan 2024

Key features
iProov Authentication node (TNTP-131)

The iProov authentication node integrates Advanced Identity Cloud authentication journeys with the Genuine Presence Assurance and Liveness Assurance products from iProov.

22 Jan 2024 (supplementary)

Key features
Fingerprint Profiler and Fingerprint Response nodes (TNTP-130)

The Fingerprint nodes nodes let you integrate your Advanced Identity Cloud environment with the Fingerprint platform to help reduce fraud and improve customer experience.

Enhancements

  • AME-25906: Add the ability to configure the password for authenticating to an Identity Gateway agent as an ESV secret

  • AME-26130: Add the ability to configure the SNS access key secret for the push notification service to use an ESV secret

  • OPENAM-21575: Add org.forgerock.json.jose.jwe.JweHeader to the class allowlist for Scripted Decision node

Fixes

  • AME-25915: SAML flow fails if a NameIDFormat element is not present in an assertion response

  • FRAAS-18464: Sandbox debug logging level set to WARN instead of DEBUG

  • IAM-5656: Fix alignment of text, buttons, and links in Message nodes

  • IAM-5660: Hosted pages not displaying list of themes

  • OPENAM-20924: Social Provider Handler node does not let end user switch to a different IdP

22 Jan 2024

Enhancements
Fixes

  • FRAAS-18271: Added the org.forgerock.opendj.ldap.Dn and org.forgerock.opendj.ldap.Rdn classes to all script contexts

19 Jan 2024

Key features
RSA SecurID node (FRAAS-18037)

The RSA SecurID lets you use the RSA Cloud Authentication Service (RSA ID Plus) or RSA Authentication Manager from within an authentication journey on your Advanced Identity Cloud environment.

Advanced Identity Cloud use case catalog

Introducing the release of the Advanced Identity Cloud use case catalog, a collection of guides that focus on tenant administrator use cases and third-party integrations.

18 Jan 2024

Key features
Create and manage custom relationship properties (OPENIDM-19106, OPENIDM-19109)

You can now create and manage custom relationship properties using the Advanced Identity Cloud admin console.

Schema API improvements (OPENIDM-19107)

You can now directly modify managed object schemas over REST using the schema API. This capability includes configuring custom relationship properties.

Password timestamps (OPENIDM-19262)

Enabling this new feature lets you view or query when a user password was last changed and when it is set to expire.

Enhancements

  • OPENIDM-19674: The relationship-defined virtual property (RDVP) schema editor allows you to edit the flattenProperties property. The managed object schema editor allows you to edit the notifyRelationships property.

Fixes

  • OPENIDM-18957: The scheduler now attempts to release any triggers it attempted to acquire during a timeout due to an unresponsive repository

  • OPENIDM-19141: Workflow engine queries now properly honor tablePrefix and tablePrefixIsSchema configuration options

  • OPENIDM-19279: Resource collection is required to create a relationship

  • OPENIDM-19565: The default apiVersion configuration has been updated with additional resource paths

17 Jan 2024

Fixes

  • FRAAS-18398: Allow the HTTP OPTIONS method on calls to /openidm/config/* endpoints for CORS preflight checks

09 Jan 2024

Fixes

  • OPENAM-21856: Introspecting stateless token with IG/Web agents will cause OAuth2ChfException

2023

19 Dec 2023

Key features
Schedule jobs directly in the Advanced Identity Cloud admin console (IAM-3489)

You can now schedule the following jobs directly in the Advanced Identity Cloud admin console without using the IDM native admin console:

  • Scripts: Execute a script at a regular interval.

  • Task scanner: Execute a scan of identities using a complex query filter at a regular interval. The scan can then execute a script on the identities returned by the query filter.

New Identity Governance capabilities[15] (IAM-4617, IGA-1664)

The Workflow UI lets you define custom workflow definitions for all access request types.

Role membership certification, a new certification type for access reviews, lets you review and certify roles and the users who have access to roles. Primary reviewers are role owners, a single user, or users assigned to a role.

Enhancements

  • FRAAS-7382: Add ability to include JavaScript snippets in login and end-user UIs

  • IAM-4514[15]: Allow reviewers to add user, entitlement, and role columns to an access review

  • IAM-4739: Add read schema option to SCIM application template to discover custom schemas/attributes

  • IAM-5201: Focus on first input field or button automatically upon page load

  • IAM-5268: Add source-missing situation rule to authoritative applications

Fixes

  • FRAAS-16659: ESV mapping updates aren’t captured in promotions report

  • IAM-4810: Custom endpoint UI missing context option

  • IAM-5072: Inbound mapping tab shows in target applications

  • IAM-5171: Azure Active Directory application template doesn’t return a user’s role membership

  • IAM-5187: LDAP v2.1 application template doesn’t clear dc=example,dc=com base DN

  • IAM-5238: LDAP application template is missing the group object classes property

  • IAM-5422[15]: Entitlement owner doesn’t show in the entitlement list

15 Dec 2023

Fixes

  • TNTP-125: Gateway Communication node returns claim values wrapped in double quotes

12 Dec 2023

Enhancements

  • AME-22326[38]: The httpClient available in scripts now automatically adds the current transactionId as an HTTP header. This lets you correlate caller and receiver logs to make requests to other ForgeRock products and services.

  • AME-25392[38]: Add org.forgerock.openam.scripting.api.PrefixedScriptPropertyResolver, used for accessing ESVs from scripts, to the allowlist for SAML2_SP_ADAPTER and SAML2_IDP_ADAPTER script types

  • AME-25433[38]: Add com.sun.crypto.provider.PBKDF2KeyImpl, javax.crypto.SecretKeyFactory, and javax.crypto.spec.PBEKeySpec to the allowlists for Scripted Decision nodes and Configuration Provider nodes

  • AME-25608[38]: Add auditing for opening and closing connections for the LDAP decision node, ID Repo service, and Policy Configuration service

  • AME-25630[38]: Add java.security.spec.InvalidKeySpecException to the allowlist for the Scripted Decision and Configuration Provider nodes

  • OPENAM-16897[38]: The OAuth 2.0 Device grant flow can now return either JSON or HTML

Fixes

  • COMMONS-1397[38]: Audit event log entries not logged due to thread contention

  • FRAAS-17686[39]: Add org.forgerock.json.jose.jwe.JweHeader to the allowlists for the AUTHENTICATION_TREE_DECISION_NODE and CONFIG_PROVIDER_NODE script types

  • IAM-4401[38]: Disabling Clear-Site-Data header breaks realm login

  • OPENAM-17331[38]: Disabled SNS endpoints can now be re-enabled

  • OPENAM-17816[38]: OAuth 2.0 requests without a Content-Type header fail with a 500 error

  • OPENAM-19282[38]: Recovery Code Display node only works immediately after a registration node

  • OPENAM-19889[38]: Policy evaluation fails when subject is agent access token JWT

  • OPENAM-20026[38]: Social IDP with trailing whitespace in the name can’t be deleted using the UI

  • OPENAM-20329[38]: Issuer missing from OAuth 2.0 JARM response

  • OPENAM-21053[38]: Missing userId from access audit log when org.forgerock.security.oauth2.enforce.sub.claim.uniqueness=false in JWT client authentication flow

  • OPENAM-21421[38]: Scripting logger name isn’t based on logging hierarchy convention

  • OPENAM-21476[38]: Persistent cookie is not created when using Configuration Provider node

  • OPENAM-21484[38]: Introspection of a stateful refresh token for claims field for known OAuth2 fields is now a string and not nested in a list

11 Dec 2023

Fixes

  • FRAAS-18108: Add warning to the Set up 2-step verification screen to indicate that 2-step verification will be enforced as of March 1, 2024

30 Nov 2023

Fixes

  • IAM-5275[38]: Advanced Identity Cloud admin console doesn’t add query parameters to the logout URL

Notices

ForgeRock deprecated the option to let Advanced Identity Cloud tenant administrators skip 2-step verification on Friday, February 3, 2023.

The end-of-life date for this deprecation is Friday, March 1, 2024, when the skip option functionality will be removed from Advanced Identity Cloud. You have until this date to update your tenants to make 2-step verification mandatory for all tenant administrators. For more information, refer to Tenant administrator mandatory 2-step verification FAQ.

28 Nov 2023

Key features
Duo Universal Prompt node (FRAAS-15675)

The Duo Universal Prompt node lets you provide two-factor authentication using Duo’s Universal Prompt authentication interface. You can integrate Universal Prompt with your web applications using the Duo Web v4 SDK.

For details, refer to Duo Universal Prompt node.

27 Nov 2023

Enhancements

  • FRAAS-17939[40]: Some connectors included with Advanced Identity Cloud were upgraded to the following versions:

    1.5.20.19

    For details, refer to 1.5.20.19 Connector changes.

    • Microsoft Graph API connector

    • SCIM connector

    1.5.20.18

    For details, refer to 1.5.20.18 Connector changes.

    • Google Apps connector

    • Microsoft Graph API connector

    • Salesforce connector

    • SCIM connector

    • Workday connector

  • OPENIDM-19037: Update property value substitution to reflect boolean value in the UI

Fixes

  • IAM-5289: Fix warning message when maxidletime is greater than 24.8 days

  • OPENIDM-19328: Fix queued sync to recover following node restart

17 Nov 2023

Enhancements

  • IAM-4511: Hide fields in the Users & Roles tab when editing and creating unreadable properties

  • IAM-4615: Add a "Skip to main content" link to page headers

Fixes

  • IAM-4991: When a suspendedId is in use, redirect to failureUrl fails

  • IAM-5075: Login messages are read twice by screen readers

  • IAM-5186: User identity related values aren’t saved after removal

13 Nov 2023

Fixes

  • FRAAS-17883: Tenant administrators cannot save edits to their personal information

  • IAM-5226: Tenant administrator security questions should not be shown when editing personal information

  • IAM-5240: No error message displays when a tenant administrator fails to save edits to their personal information

31 Oct 2023

Key features
next-generation scripting enhancements (AME-25928)

The next-generation scripting engine for journey decision node scripts lets you:

  • Reduce the need to allowlist Java classes with a stable set of enhanced bindings.

  • Simplify scripts with fewer imports and more intuitive return types that require less code.

  • Debug efficiently with clear log messages and a simple logging interface based on SLF4J.

  • Make requests to other APIs from within scripts with a more intuitive HTTP client.

  • Modularize your scripts by reusing common code snippets, including external libraries such as CommonJS, with library scripts.

  • Access identity management information seamlessly through the openidm binding.

The next-generation engine can’t use legacy scripts.

If your Scripted Decision node uses legacy scripts, you must convert them to use updated bindings to take advantage of the benefits of the next-generation scripting engine.

Where possible, you should migrate legacy scripts to take advantage of next-generation stability.

For more information, refer to Next-generation scripts.

Enhancements

  • FRAAS-3841: Activate and deactivate journeys in the Advanced Identity Cloud admin console. Refer to Deactivate journeys.

  • IAM-4191: Allow tenant session cookie name to be configured. Refer to Session cookie name.

  • IAM-4735: Add support for schema discovery in application templates

  • IAM-4806: Show outbound tenant IP addresses in Advanced Identity Cloud admin console. Refer to Access global settings.

  • IAM-4853: Add AS400 application template. Refer to the AS400 section in Provision an application.

Fixes

  • FRAAS-16785: Incorrect positioning of reCAPTCHA v2 elements

  • IAM-2936: Journeys hang indefinitely when using a State Metadata node within a Page node

  • IAM-4521: Screen readers announce field labels twice

  • IAM-4956: Advanced Identity Cloud admin console doesn’t use the current realm when logging out

  • IAM-5113: Unable to remove an NAO assignment from a user in Advanced Identity Cloud admin console

19 Oct 2023

Key features
Gateway Communication node (FRAAS-17380)

Lets Advanced Identity Cloud authentication journeys communicate directly with the PingGateway (PingGateway).

This secure communication channel extends the Advanced Identity Cloud capabilities with PingGateway features, such as validating a Kerberos ticket and performing other certificate handshakes.

For details, refer to Gateway Communication overview.

16 Oct 2023

Key features
New Autonomous Access capabilities[41] (DATASCI-1269)

Autonomous Access User access behavior and tenant access behavior let end users understand their "normal" login behavior for the past six months by graphically displaying key access metrics on a UI. Users can filter the UI to show certain login metrics, like time of day, city, country, day of week, device used for login, operating system, and browser type. Users can also compare an individual user’s login behavior to that of the access attempts for all other users.

Enhancements

  • IAM-4211: Display disaster recovery region in the Advanced Identity Cloud admin console

  • IAM-4369: Remove AM applications from application list view

  • IAM-5045: Display pop-up warning when an end user is about to be logged out of an Advanced Identity Cloud hosted page

Fixes

  • IAM-4812: Correctly save array ESVs containing newline characters

  • IAM-4863: Display ESV buttons properly when the user gives them focus

  • IAM-4877: Display ESV selection button properly while user is modifying a script associated with a Scripted Decision node

  • IAM-4698: Fix accessibility issues with messages in page nodes

13 Oct 2023

Enhancements

  • FRAAS-17373[42]: The following connectors included with Advanced Identity Cloud were upgraded from 1.5.20.15 to 1.5.20.17:

    • Adobe Marketing Cloud connector

    • Google Apps connector

    • Microsoft Graph API connector

    • Salesforce connector

    • SCIM connector

    Some highlights include:

    • OPENICF-900: SCIM connector: Add support for dynamically generated SCIM schemas

    • OPENICF-2453: SCIM connector: Persist optional refresh token upon successful access token renewal

    For a complete list of enhancements and fixes, refer to Connector changes.

Fixes

  • ANALYTICS-311: The USER-LAST-LOGIN report doesn’t show results if the last journey failed

  • FRAAS-17413: Improve IDM service reliability during upgrades and routine maintenance

  • OPENICF-1723: Salesforce connector: Clarify usage of proxyUri configuration property

  • OPENICF-2297: SCIM connector: Roles attribute should be a list of Strings, not a list of Objects

  • OPENICF-2482: SCIM connector: Dynamic schema doesn’t default to static schema on all exceptions

  • OPENICF-2483: SCIM connector: Creating a user with special attributes fails with dynamically generated schema

  • OPENICF-2484: SCIM connector: PUT with schemas attribute fails for providers that support PATCH

  • OPENICF-2448: SCIM connector: HTTP client fails to handle OAuth 2.0 errors

12 Oct 2023

Key features
OneSpan Get User Authenticator node (FRAAS-17378)

Retrieves the authenticators assigned to a user and helps enable user’s authentication and security levels.

For details, refer to OneSpan Get User Authenticator node.

OneSpan Identity Verification node (FRAAS-17378)

Sends request to OneSpan to analyze the image and determine whether the document is genuine or fraudulent.

For details, refer to OneSpan Identity Verification node.

03 Oct 2023

Fixes

  • FRAAS-17283: Tenant status pages not automatically updated during downtime

  • IAM-4235: Passthrough authentication using AD connector fails if set up in UI and user DN includes a space

  • IAM-4903: API calls to IGA endpoints not working with custom domain

  • IAM-4915: User details modal for IGA access review shows manager details as JSON object

  • OPENIDM-19192: Personal information is still editable by end users when User Editable is set to false

25 Sep 2023

Enhancements

  • IAM-4515[43]: Include autocomplete attribute with login form fields

  • IAM-4525[43]: Update profile picture modal with accessibility improvements for screen readers

  • IAM-4576[43]: Increase time on screen for loading spinner so that screen readers can announce it

  • IAM-4616[43]: Include contextual information with the show/hide buttons for improved accessibility

Fixes

  • FRAAS-17278: Health status reports for AM, IDM, and platform-admin services incorrectly reported as available in some situations

  • IAM-4460[43]: Screen readers read show/hide buttons for security questions as show/hide password

  • IAM-4523[43]: Screen readers read avatar alt text when tabbing to action menu

  • IAM-4524[43]: Two buttons with different labels open the same dialog

22 Sep 2023

Fixes

  • FRAAS-17235: Validate ESV values correctly when they are wrapped in white space

20 Sep 2023

Key features
New Identity Governance capabilities[15] (IGA-1691)

Access requests let end users request access to resources and let managers request that access be removed from their delegates. The list of resources an end user can request access to is referred to as the access catalog.

Manage access request workflows is a new feature that lets you optionally define flows to include business logic, decisions, and approvals. For example, decide what happens when an approver rejects an access request for an application. Workflows currently only supports access request-related features.

New options in the Advanced Identity Cloud end-user UI let end users submit access requests, submit requests to remove access, and review assigned request items:

  • The My Requests option lets you view and create access requests to resources (applications, roles, entitlements) for yourself or on behalf of others.

  • The My Directory > Direct Reports option lets managers submit access removal requests.

  • The Inbox > Approvals option lists request items (requests an end user submits) for an approver (designated owner) to act on.

Enhancements

  • IAM-3648: ESV placeholders can now be entered from a drop-down list

  • IAM-3651: ESV placeholders can now be entered from key-value input fields

  • IAM-4236: Improve layout of the applications reconciliation tab

  • IAM-4367: Separate the connection status of OAuth 2.0 client applications into a dedicated list

  • IAM-4662: ESV placeholders can now be entered from tag input fields

  • IAM-4717: Added date, datetime, and time fields to the login UI

  • IAM-4789: Grant roles now show temporal constraints

  • OPENAM-20847: Sanitized HTML can now be added into messages for the Email Suspend node

Fixes

  • IAM-4418: Fix accessibility issues with multi-select input fields

  • IAM-4489: Align checkbox color with other form elements

  • IAM-4491: Correctly label sidebar buttons when expanded or collapsed

  • IAM-4492: Make navigation bars in end-user UI accessible for screen readers

  • IAM-4798: The aria-label is now correctly displayed for all component types on sidebar buttons

  • IAM-4843: The user column in the certification task list now shows a user’s full name instead of only the first name

  • IAM-4528: Outbound reconciliation mapping preview shows generated password value

19 Sep 2023

Enhancements

  • OPENAM-21416: Canada Central AWS region (ca-central-1) enabled for the PingAM push notification service

15 Sep 2023

Key features
Query Parameter node (AME-24069)

Allows you to insert query parameter values from a journey URL into configurable node state properties. This lets you customize journeys based on the query parameter values.

For details, refer to Query Parameter node.

Enhancements

  • OPENAM-21073: Request headers are now accessible in OAuth 2.0/OIDC scripts for OIDC_CLAIMS, OAUTH2_ACCESS_TOKEN_MODIFICATION, and OAUTH2_MAY_ACT script contexts using the requestProperties binding

  • OPENAM-21355: Jakarta AWS region (ap-southeast-3) enabled for the PingAM push notification service

Fixes

  • IAM-4639: String/password field button is highlighted in the UI

  • IAM-4829: Eye icon displays over the password field highlight box in the UI

  • OPENAM-18599: Allow customization of the error message that displays to end users when their account is locked or inactive using .withErrorMessage() in a Scripted Decision node

  • OPENAM-18685: Use the OAuth2 Provider service in the AM admin console to specify if tokens issued should contain the subname claim

  • OPENAM-19261: Errors are incorrectly logged when triggered by introspection of tokens using OAuth 2.0 client credentials grant

  • OPENAM-20451: The WebAuthn Registration node now displays an end user’s userName when registering a device when the identity’s name isn’t human-readable

  • OPENAM-21158: Add support for trusted platform module (TPM) attestation using elliptic curve cryptography (ECC) unique parameter validation starting with Windows 11 version 22H2

  • OPENAM-21304: The request_uris field does not populate when OAuth 2.0 clients register using dynamic client registration

  • OPENAM-21390: Fix caching error to correctly provide data to nodeState when a journey switches server instances

11 Sep 2023

Enhancements
Fixes

  • IAM-4366: Provide browser-specific logic to handle alternative CSS for accessibility

  • IAM-4409: Require at least three characters before running identity searches when there are more than 1000 identities of that type

  • IAM-4478: Only allow certain combinations of properties in a mapping transformation script

  • IAM-4493: Fix the heading hierarchy in the UI

  • IAM-4568: Do not enable the option to change a user association in the UI

  • IAM-4703: Fix display of password fields in some themes

  • IAM-4710: Fix rounded border of password fields in hosted pages

06 Sep 2023

Enhancements

  • OPENAM-21346: Add classes java.util.concurrent.TimeUnit, java.util.concurrent.ExecutionException, and java.util.concurrent.TimeoutException to the scripting allowlist

22 Aug 2023

Key features
Salesforce Community User application template (IAM-4340)

Provision, reconcile, and synchronize Salesforce, Salesforce Portal, and Salesforce Community accounts.

For details, refer to Salesforce application template or Salesforce Community User application template

Add preference-based provisioning to Privacy and Consent settings (IAM-4243)

End users in target applications can share their data with other applications. After the end user configures a preference to share data with other applications, data from the target application is synchronized with Advanced Identity Cloud.

For details, refer to End-user data sharing

18 Aug 2023

Key features
OneSpan Auth VDP User Register node (FRAAS-15426)

Registers users to authenticate using the virtual one-time password (VOTP). For details, refer to OneSpan Auth VDP User Register node.

OneSpan Auth Assign Authenticator node (FRAAS-15426)

Assigns VIR10 authenticator to the user when there’s a VIR10 authenticator available in the tenant and the user isn’t assigned a VIR10 authenticator. For details, refer to OneSpan Auth Assign Authenticator node.

OneSpan Auth Generate VOTP node (FRAAS-15426)

Generates and delivers a virtual one-time password (VOTP) through the delivery method configured in the node if there’s a VIR10 authenticator assigned to the user. For details, refer to OneSpan Auth Generate VOTP node.

14 Aug 2023

Fixes

  • IAM-4533: Journeys do not resume correctly when returning from a social identity provider without a realm identifier

  • IAM-4534: Redirect callbacks for journeys not working correctly

09 Aug 2023

Enhancements

  • AME-25061[44]: Provide additional context information in Marketplace authentication nodes to enable UI improvements

  • OPENAM-20772[44]: Add new option to the CAPTCHA node to let the submit button be disabled until CAPTCHA verification is successful

Fixes

  • OPENAM-18004[44]: Audit logging does not specify transaction IDs correctly for internal requests to certain APIs

  • OPENAM-18709[44]: Calls to the nodeState.get() method in Scripted Decision nodes do not return values in shared state when a variable is stored in both shared state and secure state

  • OPENAM-20230[44]: Calls to classes in the allowlist fail occasionally with access prohibited messages

  • OPENAM-20682[44]: Unable to encrypt id_token error when there are multiple JWKs with the same key ID but different encryption algorithms

  • OPENAM-20691[44]: Session quota reached when oldest session is not destroyed due to race condition

  • OPENAM-20783[44]: Logging is incorrect when the authorization code grant flow is used successfully

  • OPENAM-20920[44]: Null pointer exceptions when a SAML 2.0 binding is null and the SSO endpoint list contains non-SAML 2.0 entries

  • OPENAM-20953[44]: Policy evaluation with a subject type JwtClaim returns HTTP response code 500

  • OPENAM-20980[44]: The OIDC social provider is unable to use an issuer’s comparison check regex

  • OPENAM-21001[44]: Custom scripted SAML 2.0 IDP account mappers are determined incorrectly

  • OPENAM-21004[44]: Invalid session ID error when session management is disabled in an OIDC provider

  • OPENAM-21046[44]: The Create Object and Patch Object nodes do not log exception stack traces when they can’t retrieve the object schema

  • OPENAM-21164[44]: XML string formatted incorrectly when using a custom adapter to get the assertion from a SAML 2.0 response

31 Jul 2023

Enhancements

  • IAM-3502: Add the ability to set and reset a sync token for identity management account object type. For details, refer to Reset the last reconciliation job.

  • IAM-3678: Update error messages and labels in login and signup pages

  • IAM-3962: Improve design of push number challenge page for Push Wait node

  • IAM-4248: Add three additional non-account objects to ServiceNow page

  • IAM-4326: Improve onLink script to handle mapped properties of type array and object

  • IAM-4334: Update SuccessFactors application templates to support Advanced Identity Cloud built-in SuccessFactors connector

Fixes

  • IAM-3877: UI loader spins indefinitely when realm is deactivated

  • IAM-4093: Replace Google Fonts in the login UI to meet GDPR compliancy requirements

  • IAM-4176: Advanced setting query filter does not show all available properties

  • IAM-4240: Accessibility issues in Page node when NVDA readers are used

  • IAM-4261: Accessing end-user UI with query parameter "code" displays empty page

  • IAM-4371: Unable to create applications due to userpassword property set

  • IAM-4384: Platform UI does not resume journeys with custom redirect logic

  • IAM-4427: Platform UI does not show assignments for tenants running deprecated application management

  • IAM-4475: Platform UI does not load after tenant administrator signs into an upper tenant during promotion

25 Jul 2023

Fixes

  • FRAAS-16471: ESV variables and secrets API endpoints slow for large result sets

17 Jul 2023

Fixes

  • OPENIDM-18292[45]: Add support for the _fields request parameter to the sync getTargetPreview endpoint

  • OPENIDM-18898[45]: Add support for the _countOnly parameter in identity management scripts

  • OPENIDM-18980[45]: Add a new metric to measure the duration of a LiveSync event

  • OPENIDM-19098[45]: Enable ES6 support for identity management scripts

13 Jul 2023

Fixes

  • FRAAS-16271: ESV secrets could be incorrectly marked as "not loaded" when tenant has many ESVs

26 Jun 2023

Fixes

  • IAM-4289: Unable to assign non-account object properties to roles

  • IAM-4293: Access reviews and line items not shown for staged campaigns

  • IAM-4295: Reviewer not redirected back to pending reviews after access review sign off

22 Jun 2023

Enhancements

  • DATASCI-1331[46]: Distributed attack heuristics

  • DATASCI-1677[46]: Support the right to access or be forgotten (GDPR compliance)

  • IAM-2026: Support versioning of the application and connector templates

  • IAM-3408: Let provisioners use a range of connector versions

  • IAM-4074: Add a loading animation to the pie chart component

  • IAM-4242: Add "Conflicting changes" category to reconciliation summary

Fixes

  • FRAAS-9230: Sanitize aria-hidden fields

  • FRAAS-16041: Users can choose Basic Auth for Identity Cloud logging endpoints

  • IAM-2972: Route users to the correct realm after granting Salesforce permissions

  • IAM-3719: Modals not showing display access review comments and activity

  • IAM-4116: Don’t let access review users add reviewers with greater privileges than they themselves have

  • IAM-4134: User pop-up is visible in "Entitlement" tab

  • IAM-4200: Last certified date, decision, and actor displaying incorrectly in Governance account details

19 Jun 2023

Enhancements

  • IAM-4051: Improved ADA accessibility for drop-down boxes

  • IAM-4053: Improved ADA accessibility when NVDA readers are used on pages that use the Page node

16 Jun 2023

Fixes

  • FRAAS-15974: Unable to promote empty configuration to reset staging environment

14 Jun 2023

Key features
New Identity Governance capabilities[15] (IGA-1592)

Entitlements are specific permissions given to an account in an onboarded target application. Each entitlement correlates to a permission. Pull in entitlements from all onboarded target applications into Advanced Identity Cloud for use in certifications.

Entitlement assignment certification, a new certification type for access reviews, lets you review and certify entitlements and the users who have access to entitlements on some or all applications. Primary reviewers are entitlement owners, a single user, or users assigned to a role.

The governance glossary lets you attach business-friendly attributes to applications, entitlements, and roles to add more specificity to the data you review in access certifications.

New options in the Advanced Identity Cloud end-user UI let you view your access, your direct reports, and the access your direct reports have:

  • The My Access option lets you view your access in Advanced Identity Cloud and onboarded target applications. This includes accounts from onboarded target applications, roles you are assigned in Advanced Identity Cloud, and entitlements or privileges you have in onboarded target applications.

  • The Direct Reports option lets you get access information for individuals you manage. This includes their profile information, accounts from onboarded target applications, roles they are assigned in Advanced Identity Cloud, and entitlements or privileges they have in onboarded target applications.

Microsoft Graph API email client (OPENIDM-17899)

Configure the email client to use the MS Graph API Client for sending email.

For more information, refer to Microsoft Graph API email client.

Enhancements

  • IAM-2826: Filter the "Assignments" tab for identities so that it does not show overrides, entitlements, or resources

  • IAM-3677: Remove increment/decrement arrows from numeric input fields

  • IAM-3982: Let users filter risk activity using distributed attack as a risk reason

  • IAM-3983: Show distributed attack as a risk reason in the risk dashboard

  • IAM-4136: Use the tab key to move focus and remove tags in multi-select components

Fixes

  • FRAAS-14262: Include changes to group privileges in the configuration promotions report

  • IAM-2713: Prohibit editing of managed application objects

  • IAM-3594: Correctly redirect control to the End User UI after authenticating with itsme

  • IAM-3939: Let end users switch to a different authentication journey

  • IAM-4013: When using a custom domain, originalLoginRealm is set incorrectly

  • OPENIDM-17481: Managed object schema can now describe a field as a nullable array and specify a default value for this field if not provided in a create request

  • OPENIDM-17771: Processing of a large number of scheduled jobs no longer causes all scheduled tasks to continuously misfire

  • OPENIDM-18192: Updating a relationship-defined virtual property (RDVP) on a managed object by signal receipt no longer causes other RDVP state within that object to be lost

  • OPENIDM-18360: Use the full object state when validating requests made by a delegated administrator to modify a relationship

  • OPENIDM-18613: Provide the ability to remove the userPassword attribute

  • OPENIDM-18644: Correctly determine whether it’s possible to configure clustered reconciliation

  • OPENIDM-18895: Fixes support for multi-version concurrency control on managed object patches and updates

13 Jun 2023

Fixes

  • FRAAS-14706: Improve the detection of changes to complex configuration files and IDM script hooks in promotion reports

  • FRAAS-14897: Improve the rate limiting behavior of the /monitoring/logs endpoint

08 Jun 2023

Key features
Lexis-Nexis ThreatMetrix Authentication nodes (FRAAS-15325)

Integrate Lexis-Nexis ThreatMetrix decision tools and enable device intelligence and risk assessment in Advanced Identity Cloud.

For details, refer to ThreatMetrix Authentication nodes.

Fixes

  • FRAAS-14214: Changing an existing ESV type is now denied by the API and new ESVs always require an explicit type

05 Jun 2023

Key features
Filter log results

Use the _queryFilter parameter to filter log results on any field or combination of fields in a payload. For details, refer to Filter log results.

Fixes

  • FRAAS-15378: Add _queryFilter support to /monitoring/logs and /monitoring/logs/tail endpoints

30 May 2023

Key features
Scripted SAML 2.0 SP adapter

Customize the SAML 2.0 SP adapter using a script.

For details, refer to SP adapter.

OIDC ID Token Validator node

The new OIDC ID Token Validator node lets Advanced Identity Cloud rely on an OIDC provider’s ID token to authenticate an end user. The node evaluates whether the ID token is valid according to the OIDC specification.

For details, refer to OIDC ID Token Validator node.

Fixes

  • AME-21638: Customize an SP adapter by using a script

  • AME-24026: Allow specifying inputs required by the provider scripts in the Configuration Provider node

  • AME-24073: Expose the prompt_values_supported parameter of the provider configuration at the OIDC well-known endpoint

  • AME-24175: Provide additional classes in the allowlist that scripts used in the Scripted Decision node

  • OPENAM-12030: Authentication node instances are deleted when journeys containing them are deleted

  • OPENAM-13293: New OIDC ID Token Validator node evaluates whether the ID token is valid according to the OIDC specification

  • OPENAM-13329: Display journeys with spaces in their name in the Authentication Configuration drop-down menu

  • OPENAM-13766: Route user session based on whether policy evaluation is requested or not

  • OPENAM-17179: Correctly delete a script if its referring journey is deleted

  • OPENAM-17566: Display account name instead of UUID in the ForgeRock Authenticator when using MFA

  • OPENAM-18488: Support certificate-based attestation in certificate chains terminating at an intermediate CA

  • OPENAM-18692: Set the minimum value for the Default Max Age property to 0

  • OPENAM-19745: Add support for EdDSA signing algorithm to WebAuthn Registration node

  • OPENAM-20082: Show correct error message to locked out users

  • OPENAM-20104: Fix the fragment response mode for the OAuth 2.0 authorize endpoint

  • OPENAM-20187: Fix the "waiting for response" page so that it fails authentication as configured in the authentication journey

  • OPENAM-20230: Prevent class allowlist from failing for classes already on the allowlist

  • OPENAM-20318: Allow a restricted set of HTML tags to be rendered in page node headers and descriptions

  • OPENAM-20360: Fix default URL encoding to ensure ampersand characters are not double encoded in a SAML assertion

  • OPENAM-20386: Fix authentication node state reconciliation in some complex journeys

  • OPENAM-20396: Preserve ordering of ACR to chain mapping configuration of OIDC provider after a restart

  • OPENAM-20451: Fix WebAuthn registration node to return a human-readable username

  • OPENAM-20457: Route Device Location Match node to "Unknown Device" outcome when the previously stored location of the device is not provided

  • OPENAM-20479: Enhance OIDC authentication to handle unsecured JWS requests

  • OPENAM-20541: Add additional inner classes to scripting allowlist to support RSA keypair generation

24 May 2023

Fixes

  • FRAAS-14956: Promotion preview and report not showing all configuration changes

23 May 2023

Fixes

  • FRAAS-10816: Include thread ID and remove control characters from some Identity Cloud log files for easier log correlation

18 May 2023

Key features
Administrator federation enhancements

Groups support: The new groups feature allows you to add and remove administrators depending on group membership in your identity provider. Using administration groups lets you automate the granting and removing of access for administrators that are being on-boarded, switching roles, or leaving your organization.

OIDC Federation: OIDC is now supported as a federation identity provider, along with Microsoft ADFS and Microsoft Azure.

For more information, refer to Configure federated access for tenant administrators.

Enhancements

  • DATASCI-1267[47]: Autonomous Access dashboard is now realm-based

  • DATASCI-1330[47]: Autonomous Access can use blocklists and allowlists of IP addresses

  • DATASCI-1336[47]: Autonomous Access can avoid putting users in double jeopardy

17 May 2023

Fixes

  • FRAAS-13293: Provide more accurate and granular information in promotion reports

  • FRAAS-14063: Remove orphaned unused scripts during promotion

  • FRAAS-15022: Improve promotion reports

  • FRAAS-15188: Ensure environments can be recreated after deletion

  • IAM-2561: Allow adding applications to a user or role from the Identities > Manage page

  • IAM-3550: When attempting to validate Office 365 applications, a blank screen appears

  • IAM-3580: Improve service accounts UI including error handling

  • IAM-3666: Add alternative text to QR code image

  • IAM-3676: Add keyboard controls to UI to select multiple values in multivalued lists

  • IAM-4030: Improve handling of identity provider and groups claims

  • IAM-4031: Generic OIDC configuration returns HTTP 400 Bad Request

  • IAM-4032: Federation enforcement is missing from the UI

  • IAM-4058: Admin UI routing for locked tenants is no longer working correctly

15 May 2023

Fixes
Issue ID Summary

FRAAS-12469

Automatically create a status page account for new tenants

05 May 2023

Fixes
Issue ID[48] Summary

IAM-3043

CAPTCHA node not behaving properly when false

04 May 2023

Fixes
Issue ID Summary

OPENAM-20815

Auth session timeout causes missing login page footer

03 May 2023

Fixes
Issue ID Summary

IAM-3937

Risky events are not shown in the risk dashboard

IAM-3964

Risk reasons do not display in the risk dashboard

26 Apr 2023

Key features
PowerShell connector

Use the PowerShell Connector Toolkit to register a connector that can provision any Microsoft system.

For details, refer to PowerShell.

SAP SuccessFactors Account or SAP SuccessFactors HR connector

Use the SAP SuccessFactors connectors to synchronize SAP SuccessFactors users with Advanced Identity Cloud users.

For details, refer to SAP SuccessFactors Account or SAP SuccessFactors HR.

Bookmark application

You can now register a bookmark application - for example, OneNote, Evernote, Google Bookmarks, or raindrop.io - to direct users to specific URLs. A bookmark application displays shortcut links on dashboards. When you click one of the links, the browser opens a new tab.

For details, refer to Bookmark.

Resolved issues
Issue ID Summary

IAM-2911

Add support for bookmark apps in application management

IAM-3472

Update promotions UI to set tenant color dynamically based on the tenant name

IAM-3630

Add SuccessFactors template and connector configuration

IAM-3666

Add alt text to QR code

IAM-3667

Add visual indication of keyboard focus on input fields

IAM-3681

Improve accessibility of the Edit personal info profile dialog

IAM-3778

Allow login UI to work when browser session storage is unavailable

IAM-3792

Prevent login UI rendering extra whitespace character in front of text on suspended nodes

IAM-3806

Remove beta indicator from the trends chart in admin UI dashboard

IAM-3840

Change color of radio button changed in Choice Collector node

IAM-3879

Ensure global variable assignmentResCollection is not overwritten when editing scripts

IAM-3910

New PowerShell configuration properties

OPENAM-18895

Fix API request timeout errors for slow connections

OPENIDM-18917

Display last name instead of user ID on user profile when no first name is provided

OPENAM-20815

Add missing footer to Page node when session expired

25 Apr 2023

Resolved issues
Issue ID Summary

OPENIDM-18967

Remove unnecessary &_sortKeys=_id parameter from dataRelationshipArray grid queries

OPENIDM-18988

Prevent repository reads when anonymous users make requests to info and ping endpoints

24 Apr 2023

Key features
Microsoft Intune node

Integrates Microsoft Intune to control features and settings on Android, Android Enterprise, iOS/iPadOS, macOS, and Windows 10/11 devices in your organization.

For details, refer to Microsoft Intune node.

Secret Double Octopus (SDO) nodes

PingOne Advanced Identity Cloud integrates with Secret Double Octopus (SDO) to provide high-assurance, passwordless authentication systems that address the diverse authentication needs of a real-world, working enterprise.

For details, refer to Secret Double Octopus (SDO) nodes.

Resolved issues
Issue ID Summary

IAM-3950

End-user UI fails to load when accessing Advanced Identity Cloud in a new tab

12 Apr 2023

Resolved issues
Issue ID Summary

FRAAS-13247

Set the log API key creation date correctly

06 Apr 2023

Key features
Support for all Google Fonts for hosted pages

Meet your organization’s brand guidelines by using any Google Font in your hosted pages.

Resolved issues
Issue ID Summary

IAM-1686

Allow any Google Font to be used on hosted pages

IAM-3164

Prevent table columns from stacking vertically on smaller viewports

IAM-3313[15]

Additional Options section missing from Identity Certification campaign template

30 Mar 2023

Key features
IP allowlisting

Enterprises often need to ensure that requests entering their network come from trusted sources. PingOne Advanced Identity Cloud now offers outbound static IP addressess for sandbox environments.

Outbound static IP addresses let you implement network security policies by setting up allowlists of IPs originating from Advanced Identity Cloud. This adds an extra layer of security to outbound calls to your APIs or SMTP servers.

For more information, refer to Outbound static IP addresses.

Resolved issues
Issue ID Summary

FRAAS-5995

Outbound request static IP allows IP allowlisting for new customers

29 Mar 2023

Resolved issues
Issue ID Summary

FRAAS-14187

Updated user registration cloud logging to capture events from identity providers

FRAAS-14593

The Configuration Provider node was unable to retrieve ESVs

27 Mar 2023

Resolved issues
Issue ID Summary

FRAAS-14475

Certain searches cause NoSuchElementException errors

20 Mar 2023

Resolved issues
Issue ID Summary

OPENIDM-18476

The IDM admin UI now defaults identity object number fields to 0 instead of an empty value

OPENIDM-18216

IDM admin UI should query recon association data instead of audit data

OPENIDM-18870

Inability to delete an inline reconciliation or schedule script

OPENIDM-18868

Inability to save a schedule when you add or remove a passed variable

OPENIDM-18865

Script changes cannot be saved unless you click outside the Inline Script box

FRAAS-14097

Promotion report should identify journeys by their name

FRAAS-13522

Promotion report does not include changes to custom email provider

FRAAS-14353

Configuration placeholder replacement assumes a string value

17 Mar 2023

Resolved issues
Issue ID Summary

FRAAS-14260

UI displays "Resource 'managed/alpha_application' not found" message

FRAAS-14265

Cannot access ESVs in sandbox tenants

16 Mar 2023

Key features
PingOne® Identity Governance (add-on capability)

PingOne Identity Governance is a new add-on capability of PingOne Advanced Identity Cloud. Identity Governance allows you to centrally administer and manage user access to applications and data across your organization to support regulatory compliance.

With Identity Governance you can:

  • Work with onboarded target applications when reviewing user data. This allows you to review user data for onboarded applications.

  • Define and launch reviews of data using certification campaigns.

  • Review and manage user access to applications. This includes managers reviewing the access their direct reports have.

For more information, refer to About Identity Governance.

To purchase an Identity Governance subscription, contact your ForgeRock representative.

Resolved issues
Issue ID Summary

IGA-1433

Initial release of Identity Governance with identity certifications

15 Mar 2023

Resolved issues
Issue ID Summary

FRAAS-9376

Provide the ability to display a login journey in an iframe for specific custom domains. To implement this feature, you need to open a support ticket.

13 Mar 2023

Resolved issues
Issue ID Summary

FRAAS-14265

Enable access to ESVs in sandbox and demo environments

FRAAS-14276

Add idm-recon as a log source

10 Mar 2023

Key features
Support for Scripted Groovy connector applications

Application management now lets you register, provision, and manage Scripted Groovy connector applications.

For details, refer to Scripted Groovy connector.

Resolved issues
Issue ID[49] Summary

IAM-662

Fixed agent logout in platform UI

IAM-3160

Added ability to configure the scripted Groovy connector

IAM-3180

Hide the SSO tab when an application is authoritative

IAM-3193

Updated SCIM app template to only show the refresh token property for OAuth authentication

IAM-3303

Enable clicking a row to edit entries on the service accounts page

IAM-3304

Added breadcrumbs to the service accounts page

IAM-3305

Added a search field to the service accounts page

IAM-3462

Corrected AD template property from ENABLED to ENABLE

IAM-3478

Addressed accessibility concerns when displaying password policy validation

IAM-3642

Fixed an issue with unselected applications being imported when promoting, and improved the user experience for selecting and deselecting applications in the promotions UI

IAM-3669

Fixed drop-down lists to show the value of the selected option in the form

IAM-3694

Added ability to customize the success color in hosted pages

08 Mar 2023

Key features
Administrator federation

Administrator federation allows administrators to use single sign-on (SSO) to log in to an Advanced Identity Cloud tenant.

By using federation to authenticate your administrators to Advanced Identity Cloud, you can quickly and easily deprovision an administrator by removing their access from your centralized identity provider.

For details, refer to Configure federated access for tenant administrators.

Resolved issues
Issue ID Summary

FRAAS-5416

Administrators can access Advanced Identity Cloud using single sign-on from another identity provider

06 Mar 2023

Resolved issues
Issue ID Summary

IAM-2921

In the Dashboard, the total number of applications that display in the Applications box now includes those applications registered using the new app catalog in tenants created on or after January 12, 2023.

IAM-3760

Apple social authentication works with other authentication methods

03 Mar 2023

Key features
SCIM built-in connector

You can now use the SCIM built-in connector to manage user and group accounts on any SCIM-compliant resource provider.

Promotions API documentation

The promotions API documentation is now publicly available at https://apidocs.id.forgerock.io/#tag/Promotion.

Resolved issues
Issue ID Summary

FRAAS-8225

The promotions API documentation is now publicly available at https://apidocs.id.forgerock.io/#tag/Promotion

FRAAS-8709

Include the log sources in the logged events

FRAAS-12402

Add /platform/oauthReturn route to support authentication for Salesforce and Google Apps

FRAAS-12413

OIDC login from a custom domain results in blank page

OPENICF-400

The LDAP connector now correctly reads the AD Account tokenGroups attribute

OPENICF-1858

Add group owners management support to the Microsoft Graph API connector

OPENICF-2039

Add archived, languages, isEnrolledIn2Sv, and isEnforcedIn2Sv fields to the Google Apps connector

OPENICF-2067

Adjust license assignments as part of the user creation and update operations in the Google Apps connector

OPENICF-2068

The Microsoft Graph API connector now lets you assign and revoke directory roles to an Azure AD user account and query the target instance for roles

OPENICF-2088

The Microsoft Graph API connector now lets you assign and revoke custom roles to an Azure AD user account and query the target instance for roles

OPENICF-2102

Assign and revoke PermissionSets and Groups to Salesforce user accounts in the Salesforce connector

OPENICF-2110

Expose groups and roles through user object in the ServiceNow connector

OPENICF-2111

View, update, and remove a group’s roles through the role object in the ServiceNow connector

OPENICF-2129

The LDAP connector now includes a parameter to use isMemberOf by ldapGroups

OPENICF-2192

In the Google Apps connector, don’t throw an NPE when updating a user with a change to license assignments if _NAME_ is not specified

OPENIDM-17876

Query filter editor no longer removes double quotes from all properties that aren’t of type string

OPENIDM-17936

Saving changes to the authzRoles field on users no longer overrides the field type

OPENIDM-18001

Country codes in locales are no longer ignored when sending emails

OPENIDM-18077

Added new default policy, cannot-contain-others-case-insensitive

OPENIDM-18153

Custom script exception messages are no longer incorrectly truncated in REST responses

OPENIDM-18238

Improved resiliency of clustered reconciliations

OPENIDM-18243

Validate that connector names are alphanumeric

OPENIDM-18260

New sync mapping fields, defaultSourceFields and defaultTargetFields, let you specify which fields to use for read and query requests

OPENIDM-18261

Endpoints within /system now support specifying additional fields when using wildcards

OPENIDM-18275

The groups' name field is now searchable

OPENIDM-18319

An up-to-date target object state is now provided in sync script bindings and sync audit mechanisms

OPENIDM-18336

The default assignment object schema now contains a "condition" field

OPENIDM-18498

Queued sync not triggered if target is a CREST proxy endpoint

OPENIDM-18501

Tenant administrator password policy no longer restricts passwords to a maximum length

OPENIDM-18629

Reconciliation job identifiers now use a more precise timestamp

OPENIDM-18650

Add new SCIM connector; applications now support creating connections to SCIM services

01 Mar 2023

Issue ID Summary

IAM-3089[50]

Unable to exit a social provider and select a different social provider in a journey

28 Feb 2023

Resolved issues
Issue ID Summary

FRAAS-13933

Make managed groups visible in the AM admin UI

FRAAS-13983

Remove OneSpan nodes from the Basic Authentication journey node list

22 Feb 2023

Resolved issues
Issue ID Summary

FRAAS-14069

Add IdPCallback class to scripting allowlist

FRAAS-14030

Add inner classes from java.security and java.crypto packages to scripting allowlist

FRAAS-13974

Add class sun.security.ec.ECPrivateKeyImpl to scripting allowlist

FRAAS-13597

Remove unexpected changes from promotion reports

16 Feb 2023

Resolved issues
Issue ID Summary

FRAAS-13597

Fix inconsistencies between provisional and promotion reports

14 Feb 2023

Key features
Support for REST connector applications

Application management now lets you register, provision, and manage REST connector applications.

For details, refer to Scripted REST connector.

Resolved issues
Issue ID Summary

IAM-2879

Allow properties in forms to be reordered

IAM-3094

Add support for enumerated values in array attributes

IAM-3156

Update the descriptive text in the "Add Property" modal to be more accurate

IAM-3261

Adjust Autonomous Access risk filter to better handle scoring edge cases

IAM-3262

Adjust menu width on the Autonomous Access Risk Administration page

IAM-3461

Fix display of OAuth 2.0 applications with a UUID for a name

IAM-3492

Fix objects ending in application or assignment not appearing in the Privileges tab

13 Feb 2023

Resolved issues
Issue ID Summary

FRAAS-13478

Promotions report shows changes that it shouldn’t

FRAAS-13866

Let Identity Cloud administrators access policy configuration

IAM-3512

Access Management native console incorrect redirect URL

09 Feb 2023

Key features
OneSpan authentication journey nodes

The new OneSpan authentication journey nodes integrate OneSpan Intelligent Adaptive Authentication (IAA) scoring for identity proofing, continuous authentication, and fraud protection.

For details about OneSpan authentication integration set up, refer to OneSpan.

Jumio identity verification

The new Jumio identity verification integrates with Jumio’s NetVerify service to easily and securely verify identity by using facial recognition to authenticate against government issued IDs.

For details about Jumio identity verification, refer to Jumio identity verification.

Logout for all server-side sessions for a user or set of users

Administrators can now invalidate (log out) all server-side sessions for a user by sending a POST request to the json/sessions endpoint with the logoutByUser action, specifying the username in the request payload.

Composite advice with an AuthLevelCondition in journeys

Composite advice gives AM hints about which authentication services to use when logging in a user. Journeys now take into account the AuthLevelCondition composite advice.

For example, you can now use AuthLevelCondition composite advice so that AM uses a journey that provides an authentication level of 10 or higher.

Resolved issues
Issue ID Summary

AME-22942

Log out all server-side sessions for a user or set of users so that they have to reauthenticate

FRAAS-13454

Integrate Jumio identity verification journey nodes

FRAAS-13555

Integrate OneSpan authentication nodes

FRAAS-13809

Autonomous log filters fail in connected environments

OPENAM-11319

Add description key to the JSON response from OAuth2UserApplications#getResourceResponse

OPENAM-16374

Add support for composite advices with a AuthLevelCondition to journeys

OPENAM-18270

Don’t raise errors when calls to the access_token endpoint specify the scope parameter in OAuth2 authorization_code exchange

OPENAM-18488

Handle the CA certificate correctly for Windows Hello attestations

31 Jan 2023

Resolved issues
Issue ID[51] Summary

FRAAS-13011

Security improvements

IAM-2025

Add Uncategorized to the journey category filter

IAM-3107

Remove bitwise filter on Active Directory page

IAM-3108

Update Maintain LDAP Group Membership option to not be selected by default

IAM-3109

Update cn property to be optional in Active Directory target mode

IAM-3110

Update ldapGroups property to be available by default in Active Directory target mode

IAM-3111

Fix password hash algorithm

IAM-3139

Fix Revoke button in users and roles to revoke users, and not be clickable when there are no users to revoke

IAM-3142

Fix Active Directory user filter anomaly when deleting a row

IAM-3146

Update user-specific attributes to be editable by administrators

IAM-3257

Fix escaping of ESV placeholders in the advanced email editor

30 Jan 2023

Resolved issues
Issue ID Summary

FRAAS-13519

Remove unexpected file changes from self-service promotion reports

27 Jan 2023

Resolved issues
Issue ID Summary

FRAAS-13464

Adjust sandbox environment migration to not use development environment migration steps

FRAAS-13478

Remove unrelated AM root realm changes from promotion reports

FRAAS-13620

Improve performance of promotion report generation by removing unrelated data

IAM-2305[51]

Add support for localized logos in end-user UI

IAM-3091[51]

Fix localized headers rendering as [object Object]

26 Jan 2023

Resolved issues
Issue Summary

OPENIDM-16640

Changes to identity objects by onUpdate scripts not triggering relationship property onRetrieve hooks

25 Jan 2023

Key features
Improved access control for hosted pages

You can now block access separately for hosted end user account and journey pages:

  • Advanced Identity Cloud displays account pages after authentication for user profile and delegated administration details.

  • Advanced Identity Cloud displays journey pages during authentication for login, registration, password reset, and more.

By default, Advanced Identity Cloud hosted pages are active and accessible for accounts and journeys.

To disable access through the Advanced Identity Cloud admin console, go to Tenant Settings > Global Settings > End User UI and select the pages to disable.

Resolved issues
Issue ID Summary

IAM-2735

SAML application improvements, including adding ability to update metadata without recreating application and adding ability to download IdP certificate from application

IAM-3044

Applications list overflows when screen size is reduced

IAM-3084

Only allow unique values when adding application owners

IAM-3141

Add the ability to promote dynamic configuration attached to application

IAM-3151

Remove redirect to global settings during administrator login

IAM-3183

Let users filter the trends dashboard by date without resetting the journeys dashboard

IAM-3339

After refreshing the realm settings page, set the current tab using the identifier specified in the URL fragment

FRAAS-7542

Control access to hosted account and journey pages

FRAAS-11599

Don’t allow changes to scripts in staging and production environments

13 Jan 2023

Key features
Service accounts

You can now use service accounts to request access tokens for most Advanced Identity Cloud REST API endpoints without relying on a particular identity in your system:

  • Call Identity Cloud APIs programmatically without needing a human identity.

  • Access AM or IDM APIs in the same way using a signed JWT.

  • Set scopes on each service account to assign only necessary permissions to access tokens.

  • Use for automation and CI/CD tooling.

For details, refer to Service accounts.

Resolved issues
Issue ID Summary

FRAAS-8477

Service accounts

IAM-1939

Fix hCaptcha support in Platform UI

IAM-2224

Replace bullets with checkmarks when validating password policy

IAM-2847

Increase the size of the terms and conditions modal window

IAM-2912

Enable promotions UI to ignore encrypted secrets

IAM-3011

Update risk configuration UI to show only user-modifiable configuration

IAM-3012

Add new userConfig endpoint to the riskConfig API

IAM-3015

Update risk configuration evaluation UI so that updates use the new APIs

IAM-3016

Fix the gotoOnFail query parameter to redirect in case of failure

IAM-3041

Prevent proceeding from the Active Directory modal window without entering base DNs

IAM-3076

Fix Salesforce provisioning connection

IAM-3079

Fix single sign-on (SSO) setup when app name has a space

IAM-3088

Enable suppression of the login failure message from the failure node

IAM-3122

Fix font weight of the title text on provisioning tab

IAM-3145

Fix Active Directory assignment on array attributes to be a merge and not replace

IAM-3177

Add paging back to application list view if workforce feature is not enabled

IAM-3335

Fixed display of localized favicon

11 Jan 2023

Resolved issues
Issue ID Summary

FRAAS-13121

Provisional reports can cause promotion service to run out of memory and restart

FRAAS-13244

Unable to log into tenant to perform self-service promotion

04 Jan 2023

Resolved issues
Issue ID Summary

FRAAS-13242

Improve invalid page size error message

OPENAM-19485[52]

Access multi-tenant social providers without requiring multiple secondary configurations

OPENIDM-17392

Prevent script typos that cause services to fail from being introduced into the system

OPENIDM-17953

Support email addresses that contain non-ASCII UTF-8 characters

2022

21 Dec 2022

Resolved issues
Issue ID Summary

FRAAS-13057

Add only standard placeholders (not user-defined placeholders) prior to enabling placeholder management

20 Dec 2022

Key features
BioCatch authentication nodes

The new BioCatch authentication nodes integrate BioCatch scoring for identity proofing, continuous authentication, and fraud protection.

For details, refer to Marketplace journey nodes.

Resolved issues
Issue ID Summary

FRAAS-12140

Integrate BioCatch authentication journey nodes

FRAAS-12713

Promotions API failed to generate a report

16 Dec 2022

Resolved issues
Issue ID Summary

FRAAS-11964

Avoid potential performance degradation when removing expired token state

FRAAS-12939

Add proxy state to output of lock state endpoint for promotions API

15 Dec 2022

Resolved issues
Issue ID Summary

FRAAS-12545

Remove the option to keep orphaned configuration nodes from the promotions API

09 Dec 2022

Key features
Event hooks

Event hooks let you trigger scripts during various stages of the lifecycle of users, roles, assignments, and organizations.

You can trigger scripts when one of these identity objects is created, updated, retrieved, deleted, validated, or stored in the repository. You can also trigger a script when a change to an identity object triggers an implicit synchronization operation.

Post-action scripts let you manipulate identity objects after they are created, updated, or deleted.

For details, refer to Event hooks.

Resolved issues
Issue ID Summary

IAM-2941

Add the event hooks user interface

08 Dec 2022

Resolved issues
Issue ID Summary

FRAAS-12477

Add list of encrypted secrets to promotion reports

07 Dec 2022

Resolved issues
Issue ID Summary

FRAAS-12494

Unlock the environment and stop checking progress after successfully promoting an environment

FRAAS-12988

Prevent placeholder support being enabled unless a specific migration flag value is set

OPENIDM-17556

Ensure RDVPs are not erased for all types of managed objects for all types of PUT operations

06 Dec 2022

Key features
Workforce application and connector management

In new tenants created on or after January 12, 2023, you can use the improved applications page to integrate Advanced Identity Cloud with external data stores or identity providers. The applications page acts as a one-stop location where you can:

  • Register and provision popular federation-capable applications quickly and easily by choosing from a library of templates, such as Salesforce and Workday.

  • Register and provision your organization’s custom applications.

  • Manage data, properties, rules, SSO, provisioning, users, and groups for an application.

  • View the connection status of each application.

  • Activate and deactivate an application.

For details, refer to Application management improvements (new tenants only).

Daon IdentityX authentication nodes

The new Daon authentication nodes let you integrate with the Daon IdentityX platform for MFA with mobile authentication or out-of-band authentication using a separate, secure channel.

For details, refer to Marketplace journey nodes.

Resolved issues
Issue ID Summary

FRAAS-11574

Integrate Daon authentication journey nodes

IAM-2658

Application management improvements

DATASCI-1548

Update the filter text on the Autonomous Access dashboard from "All Risk Scores" to "Risk Score"

DATASCI-1550

Update text on the Autonomous Access dashboard’s Copy on User Detail page

29 Nov 2022

Key features
Onfido authentication nodes

The new Onfido authentication nodes let you use Onfido’s solution for collecting and sending document identification and, optionally, biometrics to the Onfido backend for verification.

For details, refer to Marketplace journey nodes.

Resolved issues
Issue ID Summary

FRAAS-11575

Add Onfido authentication node

23 Nov 2022

Resolved issues
Issue ID Summary

IAM-2354

Add system notification capability to UI

IAM-2355

Self-service promotions migration UI

IAM-2465

Password policy to force password expiry not working

IAM-2706

Embedding images in the theme editor only displays alternative text

IAM-2739

Email suspend message displayed without line breaks

IAM-2939

Add translation configuration key for "Passwords do not match" message

IAM-2973

Self-service promotions migration UI flow should enable promotions UI features

22 Nov 2022

Resolved issues
Issue ID Summary

FRAAS-12552

Add redirect for custom domain login screen

18 Nov 2022

Resolved issues

Addressed a security issue.

10 Nov 2022

Resolved issues

Addressed a security issue.

08 Nov 2022

Key features
Group management

You can now create and manage groups that are shared across AM and IDM within your Advanced Identity Cloud instance. New tenants have group management enabled by default, and existing tenants can follow an upgrade path to enable it.

For more information, refer to Group management.

Resolved issues
Issue ID Summary

FRAAS-12379

Add support for groups and assigning users to groups

FRAAS-12625

Handle ESVs as string type if no type is set

02 Nov 2022

Key features
ID Cloud Analytics Dashboard enhancements

You can now take advantage of the following enhancements to the analytics dashboard:

  • The journey chart now lets users drill down at specific points on a trend line to view individual journey outcomes for that date/hour. Journeys are sorted by a ranking of percentage failures, but can also be sorted based on number ranking.

  • Two new widgets — Top Five Journeys by Outcome and Top Five Journeys by Usage — that rank trending journeys based on outcomes and usages are now available.

For more information, refer to Advanced Identity Cloud analytics dashboard.

Resolved issues
Issue ID Summary

ANALYTICS-25

Add journey ranking and ability to drill down into journey outcomes to the analytics dashboard

25 Oct 2022

Key features
Self-service promotions

Self-service promotions let you promote configuration between environments without raising a support ticket. You can perform self-service promotions from development to staging tenant environments, and from staging to production tenant environments. You cannot promote sandbox environments.

For more information, refer to Introduction to self-service promotions.

Configuration placeholders visible in all APIs

Configuration placeholders let you set ESVs in your configuration.

For more information, refer to Manage configuration placeholders using the API.

Resolved issues
Issue ID Summary

FRAAS-10979

Configuration placeholders visible in all APIs in new customer environments

FRAAS-12219

Self-service promotions available in new customer environments

19 Oct 2022

Key features
Duo authentication node

The new Duo authentication node lets you use Duo’s solution for adaptive authentication, bring your own device security, cloud security, endpoint security, mobile security, and two-factor authentication.

Twilio authentication node

The new Twilio authentication node allows you to use Twilio for two-factor authentication during account setup, sign-on, and other scenarios. The node lets you integrate Twilio’s APIs to build solutions for SMS and WhatsApp messaging, voice, video, and email. The node uses Twilio’s latest Lookup API, which uses real-time risk signals to detect fraud and trigger step-up authentication when needed.

For details, refer to Marketplace journey nodes.

Resolved issues
Issue ID Summary

ANALYTICS-52

Correct the value in the All Journeys field

DATASCI-1437

Correct prefilled username fields in Filters window

DATASCI-1474

Don’t show explainability if not specified in response after applying Unusual Day of Week filter

DATASCI-1497

Let users see previously selected risk reasons after closing the Filter window

DATASCI-1504

Prevent the truncation of text on the right side of pages

FRAAS-11570

Add Duo authentication node

FRAAS-11571

Add Twilio authentication node

FRAAS-11825

Add translation configuration key for no search results message

FRAAS-12301

Add Marketplace nodes to journey editor menu

FRAAS-12413

Remove blank page shown when user returns to login page following successful login to custom domain

IAM-1935

Expose ESV variable type in the UI

IAM-2038

Prevent theme styles rendering in the hosted pages editor

IAM-2066

Show the entire answer to a long security question after clicking the visibility icon

IAM-2259

Do not let users save email templates that contain JavaScript

IAM-2312

Render SVG images correctly

IAM-2411

ForgeRock favicon displays briefly before the customer’s favicon

IAM-2502

Remove flashing red text from security questions window

IAM-2633

Support localization for radio display fields in Choice Collector node

IAM-2696

Remove legend from Risk Score window

IAM-2869

Update UI regex validation for ESV list type

18 Oct 2022

Resolved issues
Issue ID Summary

FRAAS-12373

Fix Choice Collector nodes so that they can show more than two options

07 Oct 2022

Resolved issues
Issue ID Summary

IAM-2846

Fix login issues caused by allowing non-mandatory login journey attributes to have empty values (reverts IAM-1678)

03 Oct 2022

Resolved issues
Issue ID Summary

IAM-1933

Alter AM XUI to display readonly strings wherever placeholders are in use

OPENAM-19868

Correctly handle multi-line text in Email Suspend nodes

OPENIDM-18272

Save managed object properties correctly in Identity Management native console

22 Sep 2022

Resolved issues
Issue ID Summary

AME-22684

Include grace period configuration in the OAuth2 provider settings

OPENAM-18112

Provide better error message when an LDAP authentication node encounters a TLS connection issue

OPENAM-19196

Do not wait for cache timeout before OAuth2 clients reflect changes to Javascript origins

OPENIDM-16420

Update the default email validation policy to conform with RFC 5322

OPENIDM-17533

Allow configuration changes to the repo.ds.json file to take effect without restarting IDM

OPENIDM-17720

Fix null pointer exception when the repo.ds.json file is misconfigured

OPENIDM-17836

Fix for startup error message caused by ObjectMapping constructor exception

OPENIDM-17911

Fix email validation errors in the IDM admin UI (native console)

20 Sep 2022

Resolved issues
Issue ID Summary

DATASCI-1165

Remove Automated User Agent from the list of risk reasons filters

DATASCI-1358

Let users filter dashboards by date, risk scores and features

DATASCI-1365

Update the Risk Activity page when applying a filter without requiring users to refresh the page

DATASCI-1394

Show the times that events occurred correctly without requiring users to refresh the display

DATASCI-1395

Let users see their last five risky authentication attempts

DATASCI-1397

Remove risk administration options from end users' navigation menus

DATASCI-1406

When filtering activities using a date range, include the activities that occur on the end date

IAM-1678

Allow login journey attributes that are not required to have empty values

IAM-1682

When editing email templates, cut text correctly

IAM-1932

When placeholders are used, display read-only strings in the Platform UI

IAM-2028

Remove excess space from journey editor fields that do not require floating labels

IAM-2064

Replace fields for specifying numeric thresholds with a risk score definition slider in Autonomous Access Decision nodes

IAM-2080

Let users create customized footers on Page nodes

IAM-2141

Add option to customize Page node background color

IAM-2142

Add option to customize Page node button width

IAM-2143

Add option to customize label text for Page node fields

IAM-2227

Remove spurious "No configuration exists for id external.email" pop-up warning

IAM-2249

Add option to display Message node as a link

IAM-2250

After importing journeys, let user delete all imported journeys with a single delete action

IAM-2251

Provide a value when the object.password variable is specified in an email template

IAM-2258

Remove tenant information from the Realm menu

IAM-2285

Make H2, H3, and H4 HTML headings bigger when there’s no higher-level predecessor heading

IAM-2290

Show the correct number of events per country on the Activity Risk dashboard

IAM-2294

Show previous authentication attempts when doing anomaly lookups

IAM-2320

Change the default navigation background color of Account pages without changing the dashboard color

IAM-2329

Change the color of the Autonomous Access event log indicator to red

IAM-2351

Correct pagination on the Autonomous Access Risk page

IAM-2373

Make dashboard analytics pipeline logs in Autonomous Access work as expected

IAM-2468

Wrap long security questions

IAM-2521

Don’t reuse authId during password validation

OPENAM-18933

Do not override the Success URL node’s value

SDKS-1720

Point developers to the ForgeRock SDKs when they create an OAuth2.0 client in the Platform UI

SDKS-1721

Point developers to the ForgeRock SDKs when they configure CORS in the Platform UI
1. A sandbox environment is an add-on capability.
2. A user acceptance testing (UAT) environment is an add-on capability.
3. A tenant auditor is a tenant administrator with read-only permissions. Learn more in Tenant administrator groups.
4. A super administrator is a tenant administrator with elevated permissions for configuring tenant administrators and federated tenant access. Learn more in Tenant administrator groups.
5. Orphaned scripts are a legacy problem that can affect tenants that received support-assisted promotions before the introduction of self-service promotions.
6. WS-Federation is an add-on capability.
7. passwordExpirationTime is an unindexed virtual property that can’t be queried. To achieve the same outcome, query on passwordLastChangedTime while taking the expiration period into account.
8. If you are configuring the connector server in a Docker container, use a comma as the delimiter.
9. This user attribute is indexed.
10. This user attribute contains a JSON object of all custom attributes.
11. IDM authorization roles are not available through an AM attribute. To make role-based decisions in your scripts, use the groups attribute instead.
12. Requires IGA, which is an add-on capability.
13. Not enabled by default. To enable, learn more in Enable additional indexed strings.
14. Not enabled by default. To enable, learn more in Two-factor authentication (2FA) profile attributes.
15. This change applies to a feature only available in PingOne Identity Governance, which is an add-on capability and must be purchased separately.
16. Not configured by default, you must enable this in the template configurations.
17. Exact release schedules depend on multiple factors and are subject to change.
18. Proxy Connect is an add-on capability.
19. This issue is a hotfix so has been released in the rapid and regular channels at the same time.
20. This issue was inadvertently excluded from the rapid changelog.
21. IGA is an add-on capability.
22. This release focuses on internal improvements and technical updates to enhance the overall stability, performance, and maintainability of the platform. While there are no direct customer-facing changes, these updates lay the groundwork for future feature releases and improvements.
23. This change applies to a feature only available in Advanced Reporting, which is an add-on capability and must be purchased separately.
24. This issue was released on March 5, 2025 but inadvertently excluded from the changelog.
25. This issue was released on January 9, 2025 (Version 16100.4) but inadvertently excluded from the changelog.
26. Advanced Reporting is an add-on capability.
27. This issue was added to the changelog on September 4, 2025.
28. This issue was released on June 18, 2025 but inadvertently excluded from the changelog.
29. This issue was released on March 13, 2025 but inadvertently excluded from the changelog.
30. This issue was released on December 16, 2024 (Version 15989.0; ANALYTICS-900) but inadvertently excluded from the changelog.
31. This issue was released on November 20, 2024 (Version 15726.0) but inadvertently excluded from the changelog.
32. This issue was released on September 9, 2024 (Version 14888.0) but inadvertently excluded from the changelog.
33. These nodes were released on June 12, 2024 (Version 13848.0) but inadvertently excluded from the changelog.
34. This issue was released on May 30, 2024 (Version 13664.0) but inadvertently excluded from the changelog.
35. This issue was released on April 17, 2024 (Version 13218.0) but inadvertently excluded from the changelog.
36. This issue was released on January 22, 2024 but inadvertently excluded from the changelog.
37. This issue was released on January 18, 2024 but inadvertently excluded from the changelog.
38. This issue was released on November 27, 2023 but inadvertently excluded from the changelog.
39. This issue was released on November 6, 2023 but inadvertently excluded from the changelog.
40. The updated connectors for FRAAS-17939 originally listed connectors not included with Advanced Identity Cloud.
41. This change applies to a feature only available in PingOne Autonomous Access, which is an add-on capability and must be purchased separately.
42. The updated connectors for FRAAS-17373 were originally listed as: Database Table connector, Microsoft Graph API connector, Oracle EBS connector, Salesforce connector, SCIM connector, ScriptedSQL connector.
43. This issue was released on September 11, 2023 but inadvertently excluded from the changelog.
44. This issue was released on August 2, 2023 but inadvertently excluded from the changelog.
45. This issue was released on June 14, 2023 but inadvertently excluded from the changelog.
46. This issue was released on June 19, 2023 but inadvertently excluded from the changelog.
47. This issue was released on May 5, 2023 but inadvertently excluded from the changelog.
48. This issue was released on May 2, 2023 but inadvertently excluded from the changelog.
49. The issues listed in this table were released on March 6, 2023 but inadvertently excluded from the changelog.
50. This issue was released on February 14, 2023 but inadvertently excluded from the changelog.
51. This issues listed in this table, except FRAAS-13011, were released on January 13, 2023 but inadvertently excluded from the changelog.
52. This issue was released on November 24, 2022 but inadvertently excluded from the changelog.