Identity Cloud

ForgeRock Identity Cloud documentation

Single-page edition

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

Identity Cloud

Overview

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

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

And much more…​

Support and customer success

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

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

Getting started with ForgeRock Identity Cloud

To sign in to Identity Cloud for the first time, you’ll need information in the confirmation email your ForgeRock representative sent you. If you haven’t submitted a registration request and received a confirmation email, then contact your ForgeRock representative.

1 - Sign in to Identity Cloud

  1. In a supported web browser, go to the URL indicated in your registration confirmation email.

  2. Use the username and password in your registration confirmation email.

2 - Know your tenant

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

  2. Take 5 minutes to read about your tenant.

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

4 - Get going

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

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

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

  3. Invite others to be tenant administrators.

  4. Add an application to your tenant.

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

  6. Use the ForgeRock SDK to set up authentication.

  7. Set up a login end-user journey.

Admin UIs

Overview

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

idcloudui admin consoles

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

Identity Cloud admin UI

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

AM admin UI and IDM admin UI (native consoles)

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

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

AM admin UI

Use when you want to register SAML applications, for example.

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

IDM admin UI

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

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

Identity Cloud analytics dashboard

Overview

Identity Cloud analytics dashboard provides a comprehensive snapshot of your 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 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.

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 Identity Cloud Journeys page and includes any custom journeys that you may have configured. For example:

  • EvaluateRisk

  • ForgottenUsername

  • Login (default)

  • PasswordGrant

  • ProgressiveProfile

  • Registration

  • ResetPassword

  • Sample Tree

  • UpdatePassword

The categories are:

  • Authentication

  • Password Reset

  • Progressive Profile

  • Registration

  • Username Reset

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

Filter journeys

  1. On the Journeys chart, click All journeys.

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

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

Access journey pass/fail details

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

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

Analytics Dashboard Metric Breakdown page sorted by percentage success or failures

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

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

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

A

900

630

270 (30%)

2

1

B

100

50

50 (50%)

1

2

C

100

80

20 (20%)

3

3

Timeouts are not displayed in the Journey outcomes.

Access the metric breakdown page

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

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

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

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

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

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

The widgets only display the journey outcomes for the selected time period. The x-axis denotes the percentage outcomes in the journey.

Analytics Dashboard Top Five Journeys by Outcome and Top Five Journeys by Usage Widgets

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

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

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

Notice

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

All data ForgeRock 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 ForgeRock, or any other third-party or system.

Data residency

Overview

When you sign up for 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.

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

Data regions in production tenant URLs

ForgeRock supplies tenant URLs for your development, staging, and production tenant environments. All tenant URLs include the organization name and tenant name you provided when you signed up.

Identity Cloud uses region abbreviations in the production tenant URLs to indicate the region where data resides. Refer to the Regions section for the abbreviations.

For example, "usw1" is the abbreviation for the us-west1 region. Suppose your production tenant environment URL is:

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

The presence of the region abbreviation "usw1" as part of the URL indicates that your data resides in the us-west1 region.

Regions

The tables in this section show all the region abbreviations for the data regions that Identity Cloud uses.

They also indicate secondary backup regions when available.

United States

Region Abbreviation Secondary backup region[1]

Oregon (us-west1)

usw1

A different region within the United States

Los Angeles (us-west2)

usw2

A different region within the United States

Iowa (us-central1)

usc1

A different region within the United States

South Carolina (us-east1)

use1

A different region within the United States

North Virginia (us-east4)

use4

A different region within the United States

Canada

Region Abbreviation Secondary backup region[1]

Montréal (northamerica-northeast1)

nane1

A different region within Canada

Brazil

Region Abbreviation

São Paulo (southamerica-east1)

sae1

Europe

Region Abbreviation Secondary backup region[1]

London (europe-west2)

ew2

A different region within Europe

Belgium (europe-west1)

ew1

A different region within Europe

Netherlands (europe-west4)

ew4

A different region within Europe

Zurich (europe-west6)

ew6

A different region within Europe

Frankfurt (europe-west3)

ew3

A different region within Europe

Finland (europe-north1)

en1

A different region within Europe

Asia

Region Abbreviation

Singapore (asia-southeast1)

ase1

Jakarta (asia-southeast2)

ase2

Hong Kong (asia-east2)

ae2

Australia

Region Abbreviation Secondary backup region[1]

Sydney (australia-southeast1)

ausse1

A different region within Australia

 

Development, staging, and production tenant environments

Overview

Each 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 identities is limited to 10,000.

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.

Promoting configuration

Identity Cloud uses a promotion model to move configuration changes through the three environments.

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

By contrast, the staging and production environments are not mutable. This means that you cannot make 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 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. Refer to Use ESVs in configuration placeholders.

Tenant Environment Mutable Make Configuration Changes

Development

Admin UIs or REST API

Staging

Configuration promotion

Production

Configuration promotion

Sandbox tenant environments

Overview

Sandbox tenant environments are standalone environments that are separate from your development, staging, and production tenant environments. They behave similarly to your development environment, but allow you more freedom to test various use cases. You can run experiments without being concerned about accidentally promoting your changes to your staging or production environments.

For example, perhaps you want to create some 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 these environments is part of the promotion process. This means you don’t need to worry about cleaning up unused user journeys. You can extract any configuration from your sandbox environment using the REST APIs, then post it to your development environment.

Contact your ForgeRock representative if you are interested in adding a sandbox environment to your subscription.

Sandbox usage guidelines

There are some important guidelines to note when using sandbox environments. In particular, these environments should not be used for load testing, and they 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 identities

10,000

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)

Tenant settings

Overview

The Identity Cloud admin UI provides you a unified view of all the customer, workforce, and device profiles in your tenant. Use the Identity Cloud admin UI to manage all aspects of your tenant including: realms, identities, applications, user journeys, and password policy.

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

View tenant details

  1. In the Identity Cloud admin UI, open the Tenant menu (upper right).

    150

  2. Click Tenant Settings.

  3. Click Details.

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

    • Region
      The region where your data resides.

Invite and view administrators

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

Access global settings

  1. In the Identity Cloud admin UI, open the Tenant menu (upper right).

  2. Click Tenant Settings.

  3. Click Global Settings.

    • Cookie
      The name of your tenant’s session cookie.

    • Cross-Origin Resource Sharing (CORS)
      Refer to Configure CORS.

    • Environment Secrets and Variables
      Refer to Manage ESVs using the UI.

    • Log API Keys
      You’ll need this to extract log data.

      • Click On, then click the arrow.

      • In the Log API Keys dialog box, click + New Log API Key.

      • In the New Log API Key dialog box, provide a name, and then click Create key.

      • Identity Cloud generates an api_key_id and an api_key_secret for you to copy and paste.

      • Click Done.

    • End User UI
      Refer to Identity Cloud Identity Cloud hosted pages.

Tenant administrator settings

Overview

The tenant provisioning process initially creates a single administrator, known as the tenant administrator. A tenant administrator is authorized to configure realm and tenant settings, and to invite others to become tenant administrators. All tenant administrator identities get the same realm permissions, and these are not configurable.

You can invite, view, or edit tenant administrators by opening the account menu in the top right of the Identity Cloud admin UI, then navigating to Tenant Settings > Admins.

Tenant administrator sign-in

Tenant administrators access their sign-in page using a URL that specifies the realm as a forward slash:

  • https://<tenant-env-fqdn>/login/?realm=/#/

Upon successful authentication, a tenant administrator is automatically switched to the Alpha realm.

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

Edit your own tenant administrator profile

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

150

On your tenant administrator profile page:

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

  • In the Account Security card:

    • To change your username, click Update.

      • Enter your current password, then click Next.

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

    • To change your password, click Reset.

      • Enter your current password, then click Next.

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

  • By default, 2-Step Verification is enabled.
    For more information, refer to Manage tenant administrator 2-step verification.

Invite tenant administrators

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

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

  2. Click Invite admins.

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

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

After the invitee completes the instructions in the invitation email, the invitee becomes an administrator.

By default, new administrators are authorized with the same permissions as the tenant administrator.

View the tenant administrators list

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

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

  2. Click Tenant Settings > Admins.

    • To invite a new tenant administrator:

    • To deactivate a tenant administrator:

      • Find an administrator with the label Active.

      • Click More (), and select Deactivate.

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

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

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

Unlock a tenant administrator’s account

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

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

  1. In the IDM admin UI, open the Tenant menu (upper right), and click your username.

  2. Click Tenant Settings > Admins.

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

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

If your organization does not have multiple tenant administrators, submit a support ticket. Go to Backstage, and click Support.

Manage tenant administrator 2-step verification

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

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

Register for 2-step verification

You can register for 2-step verification when you sign in as a tenant administrator for the first time:

idcloudui tenant administrator set up 2 step verification

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

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

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

Manage verification codes

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

Be sure to copy the codes and store them in a secure location.
  • You’ll use the verfication codes as recovery codes if you cannot use your registered device to sign in.

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

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

Change 2-step verification options

  1. Open your tenant administrator user profile.
    In the Identity Cloud admin UI, open the Tenant menu and choose your tenant administrator username.

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

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

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

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

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

Introduction to ESVs

Overview

Environment secrets and variables (ESVs) let you individually configure the development, staging, and production environments in your Identity Cloud tenant.

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 Identity Cloud only feature. In particular, ESV secrets should not be confused with secrets in the self-managed AM or IDM products.

ESVs

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.

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

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

Context How to reference Access as soon as set

Configuration placeholders

&{esv.my.variable}

Refer to Use ESVs in configuration placeholders.


(requires restart)

Scripts

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

Refer to Use ESVs in scripts.


(requires restart)

Variable types

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

The type is set when the ESV is created, and cannot be modified after creation. If you do not specify a type, it will default to string.

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

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

string

String value (default)

Name

esv-email-provider-from-email

Placeholder

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

Value

example@forgerock.com

array

JSON array

Name

esv-cors-accepted-origins

Placeholder

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

Value

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

Name

esv-provisioner-base-contexts

Placeholder

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

Value

["dc=example,dc=com"]

object

JSON object

Name

esv-journey-welcome-description

Placeholder

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

Value

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

bool

Boolean value

Name

esv-email-provider-use-ssl

Placeholder

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

Value

true

int

Integer value

Name

esv-email-provider-port

Placeholder

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

Value

465

number

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

Name

esv-journey-captcha-score-threshold

Placeholder

{"$number": "&{esv.journey.captcha.score.threshold}"}

Value

0.5

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

ForgeRock 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 Identity Cloud global configuration

ForgeRock manages 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

Secrets

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

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

You can reference secrets that are signing and encryption keys by mapping them to secret IDs. Secrets referenced by secret ID mappings can be accessed as soon as the ESV is set; restarting 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}

Refer to Use ESVs in configuration placeholders.


(requires restart)

Scripts

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

Refer to Use ESVs in scripts.


(requires restart)

Signing and encryption keys

Map to secret ID

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.

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; refer to 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. Refer to Generate an RSA key pair.

base64hmac

Use this format for symmetric keys; for example, a SHA-512 HMAC key. Refer to Generate a 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; refer to Use ESVs in configuration placeholders.

  2. From scripts; refer to Use ESVs in scripts.

  3. From mapped secret IDs (for signing and encryption keys); refer to 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 Identity Cloud services required

  • Secret not accessible

Scripts

  • Secret accessible

  • Uses latest secret version

  • Restart of Identity Cloud services not required

Mapped secret IDs

  • Secret accessible

  • Uses all enabled secret versions

  • Restart of 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

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-. Identity Cloud uses compatibility behavior to let you still use these legacy ESVs. The compatibility behavior depends on how far the legacy ESVs were promoted through your development, staging, and production tenant environments:

Development, staging, and production environments

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

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

Development and staging environments only

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

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

ESV descriptions

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

Manage ESVs using the API

For background on ESVs, see Introduction to ESVs.

ESV API endpoints

To use the API, see the following Identity Cloud API endpoints:

To authenticate to the API, refer to Authenticate to ESV API endpoints.

Authenticate to ESV API endpoints

To authenticate to ESV API endpoints, use an access token.

In addition to the default fr:idm:* OAuth scope, there are several additional OAuth scopes that can be used with the ESV API endpoints when you create an access token:

Scope Description

fr:idc:esv:*

Read, create, update, delete, and restart access to ESV API endpoints.

fr:idc:esv:read

Read access to ESV API endpoints.

fr:idc:esv:update

Create, update, and delete access to ESV API endpoints.

fr:idc:esv:restart

Restart access to ESV API endpoints.

Manage ESVs using the UI

For background on ESVs, refer to Introduction to ESVs.

Create variables

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

  2. Click the Variables tab.

  3. Click + Add Variable.

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

    Name

    Enter a variable name. Refer to ESV naming.

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

    Type

    Select a variable type. Refer to variable types.

    Description

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

    Value

    Enter a variable value.

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

  5. Click Save to create the variable.

Update variables

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

  2. Click the Variables tab.

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

  4. In the Update Variable modal window:

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

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

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

        Description

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

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

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

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

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

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

        Value

        Enter a new variable value.

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

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

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

  5. Click Done to close the modal.

Delete variables

You cannot delete a variable that is still referenced in a configuration placeholder. You must first remove the placeholder from configuration. Refer to Delete ESVs referenced by configuration placeholders.
  1. In the Identity Cloud admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Variables tab.

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

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

Create secrets

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

  2. Click the Secrets tab.

  3. Click + Add Secret.

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

    Name

    Enter a secret name. Refer to 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 Identity Cloud admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Secrets tab.

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

  4. In the Update Secret modal window:

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

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

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

        Description

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

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

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

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

      idcloudui esv secrets manage versions

      Refer to Secret versions for more information about the rules for enabling, disabling, and deleting 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

You cannot delete a secret that is still referenced in a configuration placeholder. You must first remove the placeholder from configuration. Refer to Delete ESVs referenced by configuration placeholders.
  1. In the Identity Cloud admin UI, go to Tenant Settings > Global Settings > Environment Secrets & Variables.

  2. Click the Secrets tab.

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

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

Apply updates

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

idcloudui esv apply updates banner

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

To apply any pending updates:

  1. Click View Updates.

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

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

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

    idcloudui esv apply updates banner in progress

  5. When the update is complete, the banner will no longer be visible, and the ESV UI will be enabled again.

Use ESVs in configuration placeholders

Overview

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

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.

Secrets and variables defined in configuration placeholders, but with no corresponding ESV set, will cause promotions to fail. Refer to Configuration integrity checks.

Set up configuration placeholders to reference an ESV

  1. Create the ESV in each of the development, staging, and production environments:

  2. Insert the ESV configuration placeholder into your configuration in the development environment. Refer to Manage configuration placeholders using the API.

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

  4. Run a further promotion to move the configuration change from the staging environment to the 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. See the promotion FAQs for more information on what static configuration is, and which areas of configuration are classified as static.

Update an ESV referenced by a configuration placeholder

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

Delete an ESV referenced by a configuration placeholder

  1. Remove the ESV configuration placeholder from your configuration in the development environment. Refer to Manage configuration placeholders using the API.

  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:

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. Refer to 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. Refer to Manage configuration placeholders using the API. For the example variable esv-myurl from step 1, the placeholder would be called &{esv.myurl}.

    Configuration placeholders can only be inserted into static configuration. See the promotion FAQs for more information on what static configuration is, and which areas of configuration are classified as static.
  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

Use ESVs in scripts

Overview

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

AM scripts

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

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

For more information on using the systemEnv binding, refer to ESVs in AM scripts.

IDM scripts

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

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

For more information on using the identityServer variable, refer to The identityServer variable.

Use ESVs for signing and encryption keys

Overview

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

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

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

Secret IDs

Secret IDs (also known as secret purposes) represent authentication features in 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 ID am.services.oauth2.stateless.signing.HMAC.

For a full list of secret IDs, refer to Secret IDs.

Map ESV secrets to secret IDs

In each realm, each secret ID 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 ID 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 ID:

  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, see the following:

    1. Create an access token for the appropriate realm. See 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. See ESV naming.
      2 Replace <access-token> with the access token.
      3 Replace <encoding-format> with pem for asymmetric keys or base64hmac for symmetric keys. See Encoding format.
      4 Ensure that useInPlaceholders is set to false. See 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 Identity Cloud admin UI, click Native Consoles > Access Management.

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

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

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

    Secret ID

    Select a secret ID; 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. See 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 SAML2 certificates using ESVs

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

Generate keys to use in ESVs

Generate an RSA key pair

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

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

    $ openssl genrsa -out private-key.pem
  2. Then, generate a public key using the private key:

    $ openssl req -new -x509 -key private-key.pem -out public-key.pem -days 365 -subj /CN=idcloud
  3. Combine the private key and public key into a key pair:

    $ cat private-key.pem public-key.pem > key-pair.pem
  4. If you intend to use an API request to create the ESV:

    1. Encode the key pair into base64:

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

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

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

Generate a HMAC key

To generate a HMAC key to use in an ESV:

  1. Run the following command:

    $ head -c<bytes> /dev/urandom | openssl enc -base64 -A -out hmac-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 hmac-key.txt -out hmac-key-base64.txt

      The file hmac-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. See step 1b in Map ESV secrets to secret IDs for an example.

Introduction to configuration placeholders

Overview

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

For example, if you created an ESV variable with the name 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.

Manage placeholders

You can view placeholders in the Identity Cloud admin UI; however, they are read only.

You can manage placeholders using the REST API. Refer to Manage configuration placeholders using the API.

Manage configuration placeholders using the API

For background on configuration placeholders, refer to Introduction to configuration placeholders.

Examples

Configure tenant email provider

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

  1. Get an access token. Refer to Get an access token.

  2. Get the email provider configuration:

    Show request
    $ curl \
    --request GET 'https://<tenant-env-fqdn>/openidm/config/external.email
    --header 'Authorization: Bearer <access-token>' \(1)
    --header 'Content-Type: application/json'
    1 Replace <access-token> with the access token created in step 1.
    Show response
    {
        "_id": "external.email",
        "auth": {
            "enable": true,
            "password": "changeit",
            "username": "example.user"
        },
        "connectiontimeout": 30000,
        "debug": false,
        "from": "\"Example User\" <example.user@example.com>",
        "host": "localhost",
        "port": 465,
        "smtpProperties": [],
        "ssl": {
            "enable": true
        },
        "starttls": {
            "enable": false
        },
        "threadPoolSize": 21,
        "timeout": 30000,
        "writetimeout": 30000
    }
  3. Create a local copy of the email provider configuration from step 2, then substitute in ESV placeholders:

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

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

    ESV name ESV type Example value

    esv-email-provider-password

    Secret

    n/a

    esv-email-provider-username

    Variable

    String

    example.user

    esv-email-provider-from-email

    Variable

    String

    example.user@example.com

    esv-email-provider-port

    Variable

    Integer

    465

    esv-email-provider-use-ssl

    Variable

    Boolean

    true

  4. Update the email provider configuration:

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

Configure CORS

This example shows how to configure placeholders in your tenant CORS configuration. Refer to Configure CORS.

  1. Get an access token. Refer to Get an access token.

  2. Get the CORS configuration:

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

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

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

    ESV name ESV type Example value

    esv-cors-accepted-origins

    Variable

    List

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

  4. Update the CORS configuration:

    Show request
    $ curl \
    --request PUT 'https://<tenant-env-fqdn>/am/json/global-config/services/CorsService/configuration/<cors-id>' \(1)
    --header 'Authorization: Bearer <access_token>' \(2)
    --header 'Content-Type: application/json' \
    --data-raw '<cors-configuration>'(3)
    1 Replace <cors-id> with the CORS configuration ID you found in step 2; for example, example-cors-config.
    2 Replace <access-token> with the access token created in step 1.
    3 Replace <cors-configuration> with the local copy of the CORS configuration modified in step 4.
    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": {
            "$list": "&{esv.cors.accepted.origins}"
        },
        "enabled": true,
        "_type": {
            "_id": "configuration",
            "name": "Cors Configuration",
            "collection": true
        }
    }

Configure a journey node

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

  1. Get an access token. Refer to Get an access token.

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

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

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

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

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

    ESV name ESV type Example value

    esv-journey-ldap-primary-servers

    Variable

    List

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

    esv-journey-ldap-heartbeat-interval

    Variable

    Integer

    10

    esv-journey-ldap-heartbeat-unit

    Variable

    String

    SECONDS

    esv-journey-ldap-password

    Secret

    n/a

    changeit

    esv-journey-ldap-username

    Variable

    String

    uid=myadmin

    esv-journey-ldap-behera-enabled

    Variable

    Boolean

    false

  5. Update the configuration of the LDAP decision node:

    Show request
    $ curl \
    --request PUT 'https://<tenant-env-fqdn>/am/json/realms/root/realms/<realm>/realm-config/authentication/authenticationtrees/nodes/LdapDecisionNode/<node-id>' \(1) (2) (3)
    --header 'Authorization: Bearer <access_token>' \(4)
    --header 'Content-Type: application/json' \
    --data-raw '<node-configuration>'(5)
    1 Replace <realm> with the realm that contains the journey that contains the LDAP decision node; for example, alpha.
    2 The node name specified is LdapDecisionNode.
    3 Replace <node-id> with the node ID you found in step 2; for example, 2082c1ad-f5ad-4b6d-aada-dd4fff4dc6f3.
    4 Replace <access-token> with the access token created in step 1.
    5 Replace <node-configuration> with the local copy of the node configuration modified in step 5.
    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"
            }
        ]
    }

Introduction to self-service promotions

Overview

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

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

You can run promotions using the following options:

Videos

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

The Identity Cloud configuration model

How are configuration promotions changing?

Migrating to self-service promotions

Lower and upper environments

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

Development environment Staging environment Production environment

Staging promotion

lower
(configuration source)

upper
(configuration destination)

Production promotion

lower
(configuration source)

upper
(configuration destination)

Environment locking

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

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

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

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

Configuration integrity checks

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

Integrity check for missing ESVs

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

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

Integrity check for encrypted secrets

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

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

Promotion process FAQs (self service)

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

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

What kind of configuration changes can my company make?

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

Dynamic configuration

Dynamic configuration changes occur automatically when your application end users use Identity Cloud features. For example, when they configure applications or add users in the Identity Cloud admin UI, the changes take effect immediately in the development, staging, or production environments.

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

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

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

Static configuration

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

All static configuration is promotable.

The following tables summarize the types of configuration changes possible:

Identity Cloud UI Configuration
Feature Dynamic
(not promoted)
Dynamic
(promoted)
Static
(promoted)

Custom domain names

  • DNS aliases

  • FQDN mappings

  • Cookie domains

  • Base URL service

Gateways & Agents

  • Native/SPA

  • Web (node.js, Java)

  • Service (m2m)

Journeys

Custom themes

Identities

  • Connect (Connector Server)

  • Connect (Server Cluster)

Password policy

AM Configuration
Feature Dynamic
(not promoted)
Dynamic
(promoted)
Static
(promoted)

Applications > Agents

  • IG Agent

  • Java Policy Agents

  • Web Policy Agents

Applications > Federation

  • Circle of Trust

  • SAML v2.0 Entity Provider

Applications > OAuth 2.0 (excluding scripts)

  • Clients

  • Remote Consent

  • Software Publisher

  • Trusted JWT Issuer


(API promotions)


(UI promotions)

Authorization

  • Policy sets

  • Resource types

Scripts (all)

Services (per realm)

  • OAuth 2.0 provider

  • Social IdP services

  • Policy configuration

  • Base URL source

IDM Configuration
Feature Dynamic
(not promoted)
Dynamic
(promoted)
Static
(promoted)

Managed objects

Connector configurations

Sync mappings

Roles & assignments

Email notifications

How do we determine what is static and dynamic configuration?

ForgeRock considers all configuration static, except for the two types of configuration data that may be changed at runtime: applications and access policies. These config data types can be created on the fly, and can be used immediately afterwards.

Applications represented by OAuth2 clients can be registered at runtime through the Dynamic Client Registration Protocol. Access policies are created every time an end user shares access to a resource.

ForgeRock recognizes that other types of applications or access policies might not change at runtime. But ForgeRock products handle each data class consistently, so we can leverage potential usage patterns in the future.

What exactly is promoted and what is not?

These artifacts are NOT promoted. They remain unchanged during the promotion process:

  • Identities:
    Users, things, admins, roles, and assignments

  • Applications:
    Gateways and Agents

  • Access policies:
    AM policy sets and resource types

All other configuration can be promoted between environments.

How do I manage configuration?

You have the choice of using the Identity Cloud admin UI, or using the REST APIs for configuration.

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

  • Changes take effect immediately.

Static configuration
  • You make changes in your development environment.

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

What if I need to roll back a configuration?

ForgeRock can roll back static configuration for you. Configuration data is maintained in Git repositories within your environment. So, configuration data can be restored as a whole to previous settings.

When you request a rollback, ForgeRock reverts your development environment to the point in time you specify. You can then promote that configuration to staging and production environments.

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

How long does the promotion process take?

Promotions normally take 10–45 minutes.

What if some configuration attributes must vary per environment?

We understand that sometimes you have to use a configuration attribute value that is not identical across development, staging, and production environments. For example, you might need one set of credentials for an external service in the development environment, but a different set of credentials in the production environment.

See Define and promote an ESV for an explanation of how this type of configuration is handled.

Manage self-service promotions using the API

For background on self-service promotions, refer to 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. Refer to Lower and upper environments.

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

Dry-run promotions

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

Reports

Dry-run promotion report

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

Promotion report

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

Promotions API endpoints

To use the promotions API, refer to the following Identity Cloud API endpoints:

  • Lock API endpoint

  • Promote API endpoint

  • Report/Reports API endpoint

The following diagram summarizes how promotions API commands are used to run a promotion. Refer to Steps to run a promotion.

self service promotions api states

Check the lock state and the promotion status

You need to check the lock state and the promotion status several times during a promotion, and analyze the responses in order to decide how to proceed.

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 (refer to Get an access token).

Refer to Steps to run a promotion to understand how to analyze the response from this endpoint.

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 (refer to Get an access token).

Refer to Steps to run a promotion to understand how to analyze the response from this endpoint.

Steps to run a promotion

Step1: Check that the environments are unlocked

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

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

Step 2: Lock the environments

  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 (refer to 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 ForgeRock locked the environment:

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

        ForgeRock typically lock an environment to let support engineers investigate an issue or perform maintenance. To resolve this, wait until ForgeRock release 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, raise a support ticket. See Resolve environment errors that are preventing promotions.

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

Step 3: Check that a promotion is not already running

  1. 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": "2022-04-19T17:12:32Z"
    }

Step 4: Run a dry-run promotion

  1. To run a dry-run promotion, follow the steps in Step 5: Run the promotion; however, in step 5.1, set the dryRun flag to true:

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

Step 5: Run the promotion

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

    curl \
    --request POST 'https://<tenant-env-upper-fqdn>/environment/promotion/promote' \(1)
    --header 'Content-Type: application/json' \
    --header 'Accept-API-Version: resource=1.0' \
    --header 'Authorization: Bearer <access-token>' \(2)
    --data-raw '{
        "dryRun": false (3)
    }'
    1 Replace <tenant-env-upper-fqdn> with the FQDN of the upper environment.
    2 Replace <access-token> with an access token for the upper environment (refer to 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": "2022-04-19T17:14:13Z"
    }
  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": "2022-04-19T17:15:51Z"
      }
    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": "2022-04-19T17:19:31Z"
        }

        To resolve this:

        1. Unlock the environments.

        2. Add the missing 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": "2022-04-19T17:19:31Z"
        }

        To resolve this:

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

          1. Unlock the environments.

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

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

          4. Start the promotion steps again.

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

          1. Follow the steps in Step 5: Run the promotion; however, in step 5.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": "2022-04-19T17:19:31Z"
      }

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

      To resolve this, raise a support ticket. See Resolve environment errors that are preventing promotions.

    4. If 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": "2022-04-19T17:32:06Z"
      }

      This part of the promotion can take several minutes. It does not apply to dry-run promotions, where 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": "2022-04-19T17:40:29Z"
      }

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

Step 6: 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 (refer to Get an access token).
    {
        "createdDate": "2022-04-19T17: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_2022-04-19T17-32+00Z_dryrun=false_8acd3a87-2272-450f-a3b3-1eb222108740"
    }

    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, see View previous promotion reports.

Step 7: Unlock the 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 (refer to 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 reports

  1. To view a list of previous promotion 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 (refer to Get an access token).
    [
        {
            "createdDate": "2022-04-19T12:00:29Z",
            "dryRun": true,
            "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
            "reportId": "57aabe7d-4e8c-4fbb-8a13-2fc7d1cb4d52"
        },
        {
            "createdDate": "2022-04-19T17:32:05Z",
            "dryRun": false,
            "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
            "reportId": "c41286bb-30cd-4109-ba9d-dc4788b6a75c"
        },
        {
            "createdDate": "2022-04-19T13:56:10Z",
            "dryRun": true,
            "promotionId": "8acd3a87-2272-450f-a3b3-1eb222108740",
            "reportId": "df893dee-e952-489c-b94d-8c9ebf36e9a5"
        }
    ]
  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.
    3 Replace <access-token> with an access token for the upper environment (refer to Get an access token).
    {
        "createdDate": "2022-04-19T17: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_2022-04-19T17-32+00Z_dryrun=false_8acd3a87-2272-450f-a3b3-1eb222108740"
    }

Revert a promotion

To revert a promotion, raise a support ticket:

  1. Go to the Backstage website, and click Support.

  2. On the ForgeRock Support page, click New Ticket.

  3. On the New Ticket page, choose Identity Cloud: Config Request.

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

    Field Value

    Hostname

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

    What would you like to do?

    Choose Restore from backup

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

    Field Value

    What is the environment name?

    Choose the option that corresponds with the upper environment from the promotion you need to revert:

    • Dev

    • Staging

    • Prod

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

    Enter a date from before the promotion you need to revert, using the format YYYY-MM-DD.

  6. Click Submit.

Resolve environment errors that are preventing promotions

To resolve environment errors that are preventing promotions, raise a support ticket:

  1. Go to the Backstage website, and click Support > Tickets.

  2. On the support tickets page, click New Ticket.

  3. On the New Ticket page, choose How Do I…​?.

  4. Provide values for the following fields:

    Section Field Value

    Product

    Product

    1. ForgeRock Identity Cloud

    2. Configuration

    Details

    What are you trying to achieve?

    Resolve environment errors preventing self-service promotions

    Please provide a short description

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

    Insert error code and message (API users only)

  5. Click Submit.

Manage self-service promotions using the UI

For background on self-service promotions, refer to Introduction to self-service promotions.

Lower and upper environments

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

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

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

Promotions UI functionality in the lower environment

In the lower environment, the promotions UI lets you:

  • View changes awaiting promotion to the upper environment

  • Promote changes to the upper environment

  • View history of promotions sent to the upper environment

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

View changes awaiting promotion to the upper environment

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

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

  3. The Promotion tab shows the following information:

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

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

        idcloudui promotion summary development

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

        idcloudui promotion summary staging

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

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

      idcloudui promotion view changes development

Sign in to the upper environment

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

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

idcloudui promotion screen title sign in development

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

idcloudui promotion screen title sign in staging

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. Enter the credentials of your tenant administrator account for the upper environment.

  3. Click Next.

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

Promote changes to the upper environment

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

  2. Click Promote configuration.

  3. Review the static configuration changes that are awaiting promotion. Refer to View changes awaiting promotion to the upper environment.

  4. Click Promote n Changes.

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

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

    idcloudui promotion lock tenants development

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

  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, Identity Cloud services are restarted in the upper environment, and both environments are automatically unlocked. Allow 10–45 minutes for these combined processes to complete.

      If the UI shows an error message during the promotion process, refer to 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

  9. Trigger the promotion of any application updates:

    Perform this step only if your tenant was created or migrated to after January 12, 2023.
    1. Log into or refresh the Identity Cloud admin UI of the upper environment.

    2. If any of your applications have an associated OAuth 2.0 client, you are presented with the choice to promote the dynamic configuration. Otherwise, you need take no further action. Refer to Load dynamic configuration associated with promoted application configuration.

View history of promotions sent to the upper environment

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

  2. Click Promote configuration.

  3. Click View promotion history.

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

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

idcloudui promotion history development

Promotions UI functionality in the upper environment

In the upper environment, the promotions UI lets you:

  • View a history of promotions received from the lower environment

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

View history of promotions received from the lower environment

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

  2. Click Tenant settings.

  3. Click the Details tab.

  4. Click View updates.

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

Restricted functionality

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

Restricted functionality in the lower environment

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

  • The left menu is hidden.

  • The page header shows Tenant Locked on the left.

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

idcloudui promotion review development

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

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

Restricted functionality in the upper environment

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

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

idcloudui promotion summary tenant locked staging

Troubleshooting

Resolve failed integrity check for missing ESVs

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

idcloudui promotion error esvs

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

To resolve this:

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

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

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

  4. Start the promotion steps again.

Resolve failed integrity check for encrypted secrets

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

idcloudui promotion error encrypted secrets

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

To resolve this:

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

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

  3. For each encrypted secret in the report:

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

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

  4. Start the promotion steps again.

Resolve tenant locked errors

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

idcloudui promotion error tenant locked

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

To resolve environment errors that are preventing promotions, raise a support ticket:

  1. Go to the Backstage website, and click Support > Tickets.

  2. On the support tickets page, click New Ticket.

  3. On the New Ticket page, choose How Do I…​?.

  4. Provide values for the following fields:

    Section Field Value

    Product

    Product

    1. ForgeRock Identity Cloud

    2. Configuration

    Details

    What are you trying to achieve?

    Resolve environment errors preventing self-service promotions

    Please provide a short description

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

    Insert error code and message (API users only)

  5. Click Submit.

Revert a promotion

To revert a promotion, raise a support ticket:

  1. Go to the Backstage website, and click Support.

  2. On the ForgeRock Support page, click New Ticket.

  3. On the New Ticket page, choose Identity Cloud: Config Request.

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

    Field Value

    Hostname

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

    What would you like to do?

    Choose Restore from backup

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

    Field Value

    What is the environment name?

    Choose the option that corresponds with the upper environment from the promotion you need to revert:

    • Dev

    • Staging

    • Prod

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

    Enter a date from before the promotion you need to revert, using the format YYYY-MM-DD.

  6. Click Submit.

Self-service promotions migration FAQ

How are promotions changing?

ForgeRock is replacing support-assisted promotions with self-service promotions. Instead of raising a support ticket to promote configuration to your tenant environments, you’ll be able to promote configuration yourself. In addition, it will be possible for you to view and edit configuration placeholders in all Identity Cloud APIs.

To introduce self-service promotions, ForgeRock needs to migrate the configuration of some customers.

Will this migration affect me?

If your development environment does not have any ESVs by the migration cutoff deadline (Tuesday, November 22, 2022), your configuration will not need to go through a migration process, and your environments will be enabled automatically for self-service promotions. You will not need to take any action, and you do not need to finish reading this FAQ.

Alternatively, if your development environment does have ESVs by the migration cutoff deadline (Tuesday, November 22, 2022), your configuration will need to go through a migration process. You will be given your own specific migration date and time. After the configuration has been migrated, your environments will be enabled for self-service promotions. Please finish reading this FAQ to fully understand the migration process and the actions you may need to take.

Why is a migration needed?

Identity Cloud handles configuration placeholders for support-assisted and self-service promotions differently:

  • For support-assisted promotions, the configuration contains literal values, and placeholders are substituted in by a support engineer before every promotion. This means that adding placeholders is an additional process, and that placeholders are not visible or editable in most API requests.

  • For self-service promotions, the configuration contains the actual placeholders instead of literal values. This means that no additional process is needed to add placeholders, and that placeholders are visible and editable in all API requests.

If your development environment has any ESVs, ForgeRock will assume that your configuration has corresponding placeholders, and that your configuration will need to be migrated so that it is compatible with self-service promotions.

During the migration process, ForgeRock will permanently substitute the actual placeholders into your configuration, then enable self-service placeholder management in your environments.

Scripts that reference ESVs are not affected by the migration and do not need to be updated.

Which environments will need to be migrated?

Your development environment will need to be migrated, as will your sandbox environment, if you have one.

What will change in sandbox environments?

Your sandbox environment will be migrated in the same way as your development environment, to make sure that all environments are consistent.

What happens to my staging and production environments?

Once the migration of your development environment is complete, self-service configuration management will also be enabled for your staging and production environments.

What if I maintain an external copy of my Identity Cloud configuration?

You may maintain an external copy of your Identity Cloud configuration using CI/CD automation, source code management, or simple scripts. If so, there is a danger that after migration, the old external copy of your configuration (which doesn’t contain literal placeholders) could accidentally overwrite the newly migrated Identity Cloud configuration (which contains literal placeholders). You will therefore need to take additional action immediately after your Identity Cloud configuration has been migrated; you will need to replace the external copy of your configuration with a download of the newly migrated Identity Cloud configuration, so that your external copy contains literal placeholders.

If you do not maintain an external copy of your Identity Cloud configuration, then you do not need to take any additional action.

Someone else set this up for me, I think we track our configuration externally, but I don’t know how to make a copy. How can I get help?

ForgeRock recommends that, in the first instance, you reach out to the third party that developed your Identity Cloud service. Failing that, for assistance from ForgeRock professional services, please raise a support ticket.

When will the migration take place?

You will be assigned a date and time for your migration. The notification will appear in a yellow box at the top of the Identity Cloud admin UI in your development and sandbox environments, with this message:

Scheduled Tenant Migration Friday, January 14, 2023 at 10:00 AM PST. View details.

Can I change the date and time of the migration?

Yes, you can raise a support ticket to change the date and time:

  • The day can be Monday–Friday.

  • The time can be from 8 AM GMT until 4 PM PDT

  • The date can be from Tuesday, January 10, 2023 until Friday, March 31, 2023

What happens during the migration?

  1. ForgeRock will lock your development and sandbox environments. In this locked state, you won’t be able to make changes to your environments, but all end-user authentication journeys will continue to operate. The Identity Cloud admin UI will show the message "Tenant Locked" in the top left of the screen.

  2. ForgeRock will perform the migration:

    • Configuration placeholders will be permanently substituted into your Identity Cloud configuration.

    • Self-service placeholder management will be enabled.

    • Identity Cloud services will be restarted.

    The migration will take 30–45 minutes.

  3. You will be notified that the migration is complete. The notification will appear in a modal window in the Identity Cloud admin UI in your development and sandbox environments:

    self service promotions message migration complete

    You will need to choose a migration completion option:

    1. If you maintain an external copy of your Identity Cloud configuration:

      1. You will need to replace the external copy with a download of the newly migrated Identity Cloud configuration, so that your external copy contains literal placeholders.

      2. Then, in the Identity Cloud admin UI:

        1. Select the Configuration is managed externally option.

        2. Check I confirm I have downloaded my configuration.

        3. Click Continue.

    2. If you do not maintain an external copy of your Identity Cloud configuration:

      1. In the Identity Cloud admin UI:

        1. Select the ForgeRock manages configuration option.

        2. Click Continue.

  4. ForgeRock will unlock your development and sandbox environments. You will now be able to run self-service promotions.

How do I know whether my environment is ready for self-service promotion?

The Identity Cloud admin UI will be fully functional again, and will no longer show the message "Tenant Locked" in the top left of the screen.

Is the migration process summarized in a diagram?

How do I insert configuration placeholders once the migration is complete?

Why can I only set up configuration placeholders using APIs, and not UIs?

ForgeRock has listened to Identity Cloud customers, and found that many customers want to define configuration placeholders and run promotions without a support ticket, and consider this of paramount importance. Additionally, ForgeRock found that many customers rely heavily on API, and do not use the UI as frequently.

With this in mind, ForgeRock decided to introduce self-managed promotions using API, before full UI support is available.

How do I perform configuration promotion once the migration is complete?

How can I be assured that the new promotion process will work for me?

ForgeRock has tested the self-service promotions API internally to ensure that the transition to self-service promotions is as seamless as possible. Our support engineers have been using the API for customer promotions since 7th June 2022.

Self-service promotions migration process flow

Overview

For background on the process of migrating to self-service promotions, see Self-service promotions migration FAQ.

Process flow

The following diagram summarizes the migration process flow:

self service promotions migration process

Service accounts

Overview

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 Identity Cloud admin UI, then use the JWT profile for OAuth 2.0 authorization grant flow to obtain an access token from it. You can then use the access token as a bearer token in the Authorization HTTP header for each API request.

Managing service accounts

Only a tenant administrator can create, modify, or delete service accounts, and only by using the Identity Cloud admin UI; refer to Manage service accounts using the UI. It is not possible for any user, even a tenant administrator, to create, modify, or delete service accounts using the REST API.

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.

Scope Purpose

fr:am:*

Access to /am/* API endpoints

fr:idm:*

Access to /openidm/* API endpoints

fr:idc:esv:*

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

Access to ESV API endpoint to restart Identity Cloud services

fr:idc:promotion:*

Access to promotions API endpoints

Get an access token using a service account

To get an access token using a service account, refer to Authenticate to Identity Cloud REST API with access token.

Manage service accounts using the UI

View service accounts

  1. In the Identity Cloud admin UI, open the Tenant menu (upper right).

    150

  2. Click Tenant settings.

  3. Click Settings.

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

Create a new service account

  1. In the Identity Cloud admin UI, open the Tenant menu (upper right).

  2. Click Tenant settings.

  3. Click 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. Refer to 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, refer to Authenticate to Identity Cloud REST API with access token.

Modify a service account

  1. In the Identity Cloud admin UI, open the Tenant menu (upper right).

  2. Click Tenant settings.

  3. Click 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. Refer to 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 Identity Cloud admin UI, open the Tenant menu (upper right).

  2. Click Tenant settings.

  3. Click 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 Identity Cloud admin UI, open the Tenant menu (upper right).

  2. Click Tenant settings.

  3. Click 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

Identity Cloud lets you monitor uptime status and system performance.

Identity Cloud also provides APIs for extracting log data. For more information, see View audit and debug logs.

Monitor uptime status

Tenant status page

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

Production environment

For the production environment, the tenant status page shows individual statuses for these services:

  • Access Management

  • Identity Management

  • End User UI

  • Login UI

  • Registration UI

  • Administrator UI

  • Logs

    400

Staging environment

For the staging environment, the tenant status page combines the individual service statuses into a single status.

Access your tenant status page

  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 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-in page, enter the credentials you received when you registered with Identity Cloud.

    If you don’t have access to this page, submit a support ticket: Go to Backstage, and click Support.

  5. Click Authenticate.

View and filter your tenant status page

You can view real-time status of your staging and production environments, and a listing of service incidents.

400

For more details, click View historical uptime. Then, for the production environment only, click Filter Components to view reports on incidents in selected Identity Cloud services.

400

Add more tenant administrators to the tenant status page

If monitoring Identity Cloud uptime status is part of a particular tenant administrator’s role, submit a support request to give the individual access to the tenant status page.

  • To submit a support request, go to Backstage, and click Support.

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

Monitor system performance

Identity Cloud provides monitoring endpoints you can use with Prometheus.

Endpoint Purpose

/monitoring/prometheus/am

Produces Prometheus-formatted metrics for Access Management

/monitoring/prometheus/idm

Produces Prometheus-formatted metrics for Identity Management

You must obtain API credentials to authenticate to these endpoints. See Obtaining API Credentials.

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

To try the demo:

  1. Download and extract the ForgeRock 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, and then select Manage.

  9. On the Dashboards page, select AM Overview.

    The AM Overview dashboard opens:

    Sample AM Grafana Dashboard

    View the Prometheus dashboard at http://localhost:9090.

Get audit and debug logs

Overview

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.

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

You need to get an API key and secret before you can authenticate to the endpoints.

Sources

Identity Cloud makes browsing the logs easier by storing them in various sources.

The following knowledge base article lists the sources available and describes their purpose: What logging sources are available in Identity Cloud?

View sources

To view a list of the available sources, use the /monitoring/logs/sources endpoint.

Example request:

$ curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
'https://<tenant-env-fqdn>/monitoring/logs/sources'

Example response:

{
  "result": [
    "am-access",
    "am-activity",
    "am-authentication",
    "am-config",
    "am-core",
    "am-everything",
    "idm-access",
    "idm-activity",
    "idm-authentication",
    "idm-config",
    "idm-core",
    "idm-everything",
    "idm-recon",
    "idm-sync"
  ],
  "resultCount": 14,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": 1,
  "remainingPagedResults": 0
}

Identity Cloud returns the available sources in the result array.

Access logs

To access the stored logs for a source, use the /monitoring/logs endpoint, specifying the source as a parameter.

Example request:

$ curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication' \
'https://<tenant-env-fqdn>/monitoring/logs'

Example response:

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

Identity Cloud returns the available logs in the result array.

Results are in JSON format or plaintext, depending on the source you request.

Use the beginTime and endTime query parameters to return records created between the two times.

Specify UTC times in ISO 8601 format.

For example:

$ curl --get \
--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' \
'https://<tenant-env-fqdn>/monitoring/logs'

Update audit configuration

Sometimes a log source is shown in the available sources in Identity Cloud but returns no results when you query the 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 the audit configuration.

    Example request:

    $ curl --GET \
    --header 'Authorization: Bearer <access-token>' \
    --header 'Content-Type: application/json' \
    'https://<tenant-env-fqdn>/openidm/config/audit' | jq

    For more information, refer to 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 \
    --header 'Authorization: Bearer <access-token>' \
    --header 'Content-Type: application/json' \
    --data-raw '
    {
      "_id": "audit",
    ...
      "eventHandlers": [
        {
          "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
          "config": {
            "elasticsearchCompatible": false,
            "enabled": true,
            "name": "json",
            "topics": [
              "access",
              "activity",
              "sync",
              "authentication",
              "config",
              "recon"
            ]
          }
        },
        {
          "class": "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler",
          "config": {
            "enabled": false,
            "name": "repo",
            "topics": [
              "access",
              "activity",
              "sync",
              "authentication",
              "config",
              "recon"
            ]
          }
        }
      ],
    ...
    }' \
    'https://<tenant-env-fqdn>/openidm/config/audit'

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 results from the last 15 minutes. Subsequent calls return logs from:

  • Time of last line from previous call to tail

  • Log timestamp

  • Now

You can request results in JSON format or plaintext. One source can have both JSON and plaintext logs; for example, when you request am-everything.

Example request:

$ curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-everything' \
'https://<tenant-env-fqdn>/monitoring/logs/tail'

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 --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-access,idm-access,idm-sync,idm-activity' \
'https://<tenant-env-fqdn>/monitoring/logs/tail'

To keep tailing, pass the <pagedResultsCookie> from the previous response in your request. This retrieves new records since your request.

Example request:

$ curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-access,idm-access,idm-sync,idm-activity' \
--date '_pagedResultsCookie=<pagedResultsCookie>' \
'https://<tenant-env-fqdn>/monitoring/logs/tail'

View logs for a specific request

All log events for an external request into Identity Cloud are assigned the same unique transaction ID. The x-forgerock-transactionid response header holds the transaction ID:

$ curl \
--request POST \
--include \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Passw0rd!' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
…​
x-forgerock-transactionid: <transaction-id>
…​

To filter the logs for a specific transaction ID, add the transactionId parameter to your API request; for example:

$ curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication' \
--data 'transactionId=<transaction-id>' \
'https://<tenant-env-fqdn>/monitoring/logs'

Example response:

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

Add response fields

The following knowledge base article describes how to add additional fields to an audit request: How do I extend auditing in Identity Cloud to include additional fields?

Rate limiting

To reduce unwanted stresses on the system, 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.

  • 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-Rate-Limit-Limit

The maximum number of requests allowed in the current rate limit window.

X-Rate-Limit-Remaining

The number of requests remaining in the current rate limit window.

X-Rate-Limit-Reset

The time in seconds since Jan. 1, 1970, UTC when the rate limit window resets.

Email provider

Overview

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, 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 configure the email provider with values to connect to your own external SMTP server.

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. Configure the email provider to use your own external SMTP server.

    2. Verify that your email templates work with the external SMTP server.

  4. Promote your configuration changes to your tenant staging environment.

  5. (Optional) 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 SMTP server 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. Identity Cloud provides this ready-to-use server for testing purposes only.

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 SMTP server using the UI or the API.

Using the UI

  1. In the Identity Cloud admin UI, go to Email > Provider.

  2. On the Email Provider page, enable Use my own email provider.

  3. Enter details in the following fields:

    From Address

    Email address of the organization or individual sending the email.

    Example: mycompany@example.com.

    Not set by default, but required.

    From Name

    Name of sending organization.

    Host

    Hostname or IP address of your SMTP server.

    When no hostname is specified, 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 Identity Cloud times out due to unsuccessful socket connection to the SMTP server. A setting of 0 disables this timeout.

    Default is 300000 ms (5 minutes).

    Socket Write Timeout (ms)

    Elapsed time before Identity Cloud times out because client can’t write to the SMTP server. A setting of 0 disables this timeout.

    Default is 300000 (5 minutes).

    Socket Timeout (ms)

    Elapsed time before Identity Cloud times out due to inactivity. A setting of 0 disables this timeout.

    Default is 300000 (5 minutes).

    Use STARTTLS

    • If enabled, and if the SMTP server supports the STARTTLS command, then 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, Identity Cloud uses SSL to connect to the SMTP server.

    Disabled by default.

  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 see 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"
    ],
    "threadPoolSize" : 20
}' \
"https://<tenant-env-fqdn>/openidm/config/external.email"
Email provider configuration properties
host

The hostname or IP address of the SMTP server.

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.
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 mail server.

auth

The authentication details for the mail account from which emails will be sent.

  • enable—indicates whether you need login credentials to connect to the SMTP server.

    If "enable" : false,, you can leave the entries for "username" and "password" empty:

    "enable" : false,
    "username" : "",
    "password" : ""
  • username—the account used to connect to the SMTP server.

  • password—the password used to connect to the SMTP server.

    Identity Cloud encrypts the password.
from (optional)

Specifies a default From: address users see when they receive emails from Identity Cloud.

Although from is optional, the email service requires this property to send email. If you do not specify a from address in the email provider 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).

timeout (integer, optional)

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.

writetimeout (integer, optional)

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.

connectiontimeout (integer, optional)

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.

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 SMTP server does not support STARTTLS, the connection continues without the use of TLS.

ssl

Set "enable" : true to use SSL to connect to the SMTP server.

smtpProperties

Specifies the SSL protocols that will be enabled for SSL connections. Protocols are specified as a whitespace-separated list. The default protocol is TLSv1.2.

threadPoolSize (optional)

Sets the number of concurrent emails that can be handled at a specific time. Emails are sent in separate threads managed by a thread pool. The default thread pool size (if none is specified) is 20.

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 Identity Cloud admin UI, go to Email > Provider.

  2. On the Email Provider page, disable Use my own email provider.

  3. Click Save.

The built-in SMTP server does not support OTP Email Sender nodes in password journeys.

Email templates

Overview

Identity Cloud provides preconfigured email templates for common end-user journeys.

You can customize email templates using Markdown language. 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 Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click + New Template.

  3. Provide the following details:

    • Template Name: Display name for the template.

    • From Address: Enter an email address for the group or individual sending the email.

    • From Name: Enter a name for the group or individual sending the email.

    • Description: A brief description of the template.

  4. Click Save.

Edit an email template

  1. In the Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click a template name.

  3. To change the wording in the email template, edit the markdown text in the left window on the page.

  4. To edit the template styles, click Styles, and edit the CSS style code.

  5. To view available variables that you can use in the template, click Variables, and view the content on the Available Properties page. Click Done.

  6. To edit the template settings, click the More () icon at the top right of the page, and select Settings.

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

  8. Click Update.

  9. Click Save.

Delete an email template

Deleting an email template cannot be undone.

  1. In the Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click the More () icon adjacent to any template.

  3. Select Delete.

  4. In the dialog box, click Delete.

Manage email templates

  1. In the Identity Cloud admin UI, go to Email > Templates.

  2. On the Email Templates page, click the More () icon adjacent to any template, and do any of the following:

    • To disable a template, click Deactivate.

    • To enable a template, click Activate.

    • To duplicate a template, click Duplicate.

      1. In the Duplicate Template window, enter the following details:

        • Template Name: Display name for the template.

        • From Address: Enter an email address for the group or individual sending the email.

        • From Name: Enter a name for the group or individual sending the email.

        • Description: A brief description of the template.

      2. Click Save.

Configure CORS

Overview

Cross-origin resource sharing (CORS) lets user agents make cross-domain server requests. In Identity Cloud, you can configure CORS to allow browsers from trusted domains to access 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 Identity Cloud REST API.

By default, CORS is configured to let the ForgeRock SDKs access Identity Cloud. You can add additional CORS configurations that let other APIs or SDKs access Identity Cloud.

Configure CORS by using the Identity Cloud admin UI, as described in the following sections.

cors config

View CORS configurations

  1. Open the Tenant menu, and choose Tenant settings.

  2. On the Tenant Settings page, click Global Settings > Cross-Origin Resource Sharing (CORS).

Add a new CORS configuration

  1. Open the Tenant menu, 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.

    Configuration types:

    ForgeRock SDK

    Choose this option when you want to work with the ForgeRock SDK.
    Identity Cloud pre-configures accepted origins, methods, and headers for you. You can modify the configuration in the next step.

    Custom

    Choose this option when you want to use your own SDK, APIs, or other software components.

  5. Click Next.

  6. In the New CORS Configuration dialog box, provide CORS details.

    CORS details:

    Name

    Enter a display name. Use only numerals, letters, and hyphens (-).

    Accepted Origins

    Required. Accepted origins that will be allowed to make requests to ForgeRock from your application in a cross-origin context. Wildcards are not supported. Each value should be identical to the origin of the CORS request.
    Example: https://myapp.example.com:443

    Accepted Methods

    Defaults are POST and GET. The set of (non-simple) accepted HTTP methods allowed when making CORS requests to ForgeRock. Use only uppercase characters.

    Accepted Headers (optional)

    Accepted header names when making requests from the above specified trusted domains.
    Header names are case-insensitive. By default, the following simple headers are explicitly accepted: Cache-Control, Content-Language, ExpiresLast-Modified, Pragma.
    If you don’t specify values for this element, then the presence of any header in the CORS request, other than the simple headers listed above, will cause the request to be rejected.

    Advanced settings:

    Exposed Headers (optional)

    Add the response header names that ForgeRock returns.
    The header names are case-insensitive. User agents can make use of any headers that are listed in this property, as well as these simple response headers: Cache-Control, Content-Language, Expires, Last-Modified, Pragma, and Content-Type. User agents must filter out all other response headers.

    Enable Caching

    Max age is the maximum length of time, in seconds, that the browser is allowed to cache the pre-flight response. The value is included in pre-flight responses, in the Access-Control-Max-Age header.

    Allow Credentials

    Enable this property if you send Authorization headers as part of the CORS requests, or need to include information in cookies when making requests.

    When enabled, AM sets the Access-Control-Allow-Credentials: true header.

  7. Click Save CORS Configuration.

Activate or deactivate CORS configurations

  • To activate or deactivate all CORS configurations:

    1. Open the Tenant menu, 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. Open the Tenant menu, 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. Open the Tenant menu, 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.

TLS, secrets, signing, trust, and encryption

Overview

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 Identity Cloud tenant uses a Google-managed SSL certificate for TLS encryption.

If you prefer, Identity Cloud lets you use your own, self-managed SSL certificate instead of using the Google-managed SSL certificate.

For more information about configuring your tenant to use a self-managed certificate, see Configure a self-managed SSL certificate.

Secrets

When you configure Identity Cloud, the secrets you provide in your development environment normally do not change when you promote your environment to staging and production. But, in some situations, you might want the three environments to use different secrets.

For example, you might want Identity Cloud to log in to an external system, such as an OTP provider. But you need 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 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 Identity Cloud admin UI, you could configure ESVs that hold the credentials. Then, the desired credentials to the OTP provider would be used depending on which Identity Cloud environment was running.

For more information, see Define and promote ESVs.

Signing keys and certificates

By default, Identity Cloud generates a set of secret IDs in each Identity Cloud realm. Each secret ID corresponds to functionality in Identity Cloud that requires a signing key or certificate. For a full list of secret IDs, refer to Secret IDs.

Identity Cloud lets you override the generated secret IDs. First, create an ESV secret that holds the key or certificate. Then, map the secret in the secret store of the desired realm.

For more information, see Use ESVs for signing and encryption keys.

Trust relationships with SAML v2.0 providers

If your Identity Cloud tenant has trust relationships with one or more SAML v2.0 providers, the tenant might receive SAML assertions signed by a certificate. The certificate might itself be signed by a certificate authority (CA). For Identity Cloud to trust this type of SAML assertion, the CA’s public certificate must be installed in Identity Cloud.

You can add a CA’s public certificate to your Identity Cloud configuration by submitting a support request.

Encrypted data at rest

In Identity Cloud, your tenant includes a unique data encryption key. All Identity Cloud data that’s stored at rest is encrypted with this key.

You cannot use your own encryption key to encrypt Identity Cloud data.

Realm settings

Overview

Realms are administrative units that group configurations and identities together.

Realms let you manage different sets of identities and applications within the same 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 cannot by default access those in another realm; however, you can grant conditional access across realms.

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. The realms provide the means to keep customers from accessing employee information, while allowing employees conditional access to customer information.

Manage realm settings

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

  2. Go to Realm Settings > Details.

  3. On the Details page:

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

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

    • Name: The realm name is non-configurable.

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

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

  4. To configure a custom domain name, click Custom Domains. For more information, refer to Custom domains.

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

Override realm authentication attributes

Overriding realm authentication attributes is useful when you want to adjust the core authentication properties that apply to a realm. For example, you might want to extend the time limit for responding to an authentication verification email. Use the AM admin UI to make this kind of change.

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

  2. In the AM admin UI, go to Authentication > Settings.

For detailed property information, refer to 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 Identity Cloud admin UI, open the Realm menu (upper left).

  2. Click Switch realm.

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

Alpha and Bravo realms

Overview

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

Identity Cloud currently 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 members use https://<tenant-env-fqdn>/login/?realm=alpha/#/

  • Bravo realm members use https://<tenant-env-fqdn>/login/?realm=bravo/#/

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

Delegated administration

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

The Bravo Realm does not support delegated administration.

Assign internal roles

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

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

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

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

The following table summarizes these differences:

Action Alpha Realm Bravo Realm

Create internal role for the purposes of delegated administration

Add user to internal role

Add internal role to user

⚠️ ️
appears possible but will not work

Custom domains

Overview

Access 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 Identity Cloud admin UI continues to display the default tenant environment URL.

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

    • Wrong: mycompany.com

    • Right: id.mycompany.com

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

Set up a custom domain in Identity Cloud

Configure a custom domain using the UI

The UI lets you set up a custom domain in an individual environment for testing purposes. However, it is not currently compatible with the configuration promotion process. When you are satisfied that the custom domain works as expected within an environment, you need to set it as an ESV. Refer to Configure a custom domain using ESVs.
If your custom domain relies on private DNS or you route your HTTP traffic through a WAF service, you can’t use the UI to set up your custom domain. Instead, you must use an ESV. Refer to Configure a custom domain using ESVs.
  1. In the Identity Cloud admin UI, go to Realm > Realm Settings > Custom Domain.

  2. Click + Add a Custom Domain.

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

    After Identity Cloud validates your domain name, you’re prompted to verify your domain name ownership. In the Verify Domain Name Ownership dialog box, 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.

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

  5. Return to the Verify the Domain Ownership dialog box, and 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, 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 Identity Cloud can generate Google-managed SSL certificates. Refer to 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. Refer to 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. Refer to Check that a custom domain is working in your browser.

Configure a custom domain using ESVs

  1. Choose one of the options below to configure your domain:

  2. In your development environment:

    1. Create an ESV variable with the type as an array:

      • When naming the variable, follow the ESV API naming convention; for example, esv-customdomain or esv-customdomain-alpha.

      • If you have no custom domain for the environment, use an empty array for the ESV value.

      • If you have one custom domain for the environment, use a single-item array for the ESV value; for example, ["id-customers.company.com"].

      • If you have more than one custom domain for the environment, use a multi-item array for the ESV value; for example, ["id-staff.company.com","id-customers.company.com"].

        Create ESV variables in the following ways:

    2. Raise a support ticket to insert a configuration placeholder into your development environment configuration for the custom domain ESV you created in step 2a:

      1. Go to the Backstage website, and click Support > Tickets.

      2. On the support tickets page, click New Ticket.

      3. On the New Ticket page, choose How Do I…​?.

      4. Provide values for the following fields:

        Section Field Value

        Product

        Product

        1. ForgeRock Identity Cloud

        2. Configuration

        Details

        What are you trying to achieve?

        Add a placeholder into development configuration for a custom domain ESV

        Please provide a short description

        Enter the ESV name and the realm the custom domain applies to.

      5. Click Submit.

      6. Wait until the support ticket is resolved before moving to the next step.

    3. If you added a custom domain to the custom domain ESV for this environment:

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

      2. 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, 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 Identity Cloud can generate Google-managed SSL certificates. Refer to 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. Refer to 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>

      3. Confirm that the custom domain is working as expected. Refer to Check that a custom domain is working in your browser.

  3. In your staging environment:

    1. Repeat step 2a for your staging environment. Ensure that 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. Refer to:

    3. Repeat step 2c for your staging environment.

  4. In your production environment:

    1. Repeat step 2a for your production environment. Ensure that 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.

    3. Repeat step 2c for your production environment.

If your custom domain relies on a Google-managed SSL certificate, changing the value of the custom domain ESV variable will trigger Identity Cloud to generate a new Google-managed SSL certificate. As a result, you may not be able to access your tenant using the custom domain for up to 30 minutes.

Add a new custom domain to an ESV

  1. Configure your new custom domain following the instructions in step 1 of Configure a custom domain using ESVs.

  2. In your development, staging, or production environment:

    1. Add the new custom domain to the ESV array value following the instructions in step 2a of Configure a custom domain using ESVs.

    2. Restart Identity Cloud services following the instructions in Update an ESV referenced by a configuration placeholder.

    3. Complete configuration following the instructions in step 2c of Configure a custom domain using ESVs.

If your custom domain relies on a Google-managed SSL certificate, ForgeRock recommends that you only add one new custom domain at a time to minimize the risk to existing custom domains from any new certificate configuration errors.

Switch a custom domain using an ESV

  1. Configure your new custom domain following the instructions in step 1 of Configure a custom domain using ESVs.

  2. In your development, staging, or production environment:

    1. Replace the existing custom domain with the new custom domain as the ESV array value following the instructions in step 2a of Configure a custom domain using ESVs.

    2. Restart Identity Cloud services following the instructions in Update an ESV referenced by a configuration placeholder.

    3. Complete configuration following the instructions in step 2c of Configure a custom domain using ESVs.

Add a CNAME record to your custom domain

If your custom domain relies on public DNS, add a CNAME record to it so 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 Identity Cloud tenant domain:

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

    • In the data field, enter your 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. Refer to Check when CNAME domain name changes propagate.

Check when CNAME domain name changes propagate

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

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

  • Use the nslookup command-line tool:

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

Deactivate CNAME record verification for your custom domain

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

  1. Go to the Backstage website, and click Support > Tickets.

  2. On the support tickets page, click New Ticket.

  3. On the New Ticket page, choose How Do I…​?.

  4. Provide values for the following fields:

    Section Field Value

    Product

    Product

    1. ForgeRock Identity Cloud

    2. DNS

    Details

    What are you trying to achieve?

    Disable CNAME record verification for a custom domain

    Please provide a short description

    Enter custom domain FQDN

  5. 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 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 Identity Cloud domain name settings are correct and match your CNAME record. Refer to 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, refer to 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 ForgeRock domain

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

Custom domain

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

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

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

Deprecated application management

Overview

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

Your applications act as clients to Identity Cloud. ForgeRock uses both OAuth 2.0 and OpenID Connect protocols to protect your applications which act as clients to Identity Cloud. When you register a supported application or service, Identity Cloud sets the OAuth 2.0 grant type based on the type of application you’re registering. 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 Identity Cloud admin UI.

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

Register an application or service

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

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

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

  4. Click Create Application.

Create a client profile

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

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

  3. Review read-only Client Credentials:

    Client Credentials

    Discovery URI

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

    Client ID

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

    Client Secret

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

  4. Edit General Settings:

    General Settings

    Name

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

    App Logo URI

    Specify the location of your custom logo image file.

    Description

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

    Sign-in URLs

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

    Sign-out URLs

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

    Grant Types

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

    Authorization Code

    (default) Instead of requesting authorization directly from the user, your client application or service directs the user to an authorization server (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. Refer to 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.

    SAML2

    Leverages the REST-based services provided by AM’s OAuth 2.0 support. Maintains existing SAML v2.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.

    Client ID Token Public Encryption 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, 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, refer to 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

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

OAuth 2.0

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, refer to 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 may 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:

  • Wrong:
    https://<tenant-env-fqdn>/am/oauth2/client/form_post/…​

  • Right:
    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, 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, refer to OpenID Connect 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, refer to OAuth 2.0 scopes.

Grant types

Grant types, also known as grant flows, describe how your application or service access gets an access token. To choose one, refer to the summary of 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, refer to 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, refer to AM as authorization server.

Keys

Keys protect sensitive information that 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 IDs.

Test SAML2 SSO using JSP flows

Overview

SAML v2.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 SSO. Identity Cloud acts as the authentication service provider (SP) in a circle of trust (CoT). For this test, a self-managed AM instance acts as the identity provider (IDP).

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

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

In Identity Cloud AM instances, you must manually create a module named Federation when you ref:step_2_create_an_sp_circle_of_trust[create an SP circle of trust].

Step 1: Set up an SP and an IDP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    2. Click + Add Entity Provider > Remote.

    3. Import the IDP metadata.

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

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

    2. Click + Add Entity Provider > Remote.

    3. Import the SP metadata.

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

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

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

Step 2: Create an SP circle of trust

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

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

    2. Click + Add Circle of Trust.

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

    4. On the CoT page, provide CoT details.

      CoT details:
      • Description: Enter a unique identifier.

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

    5. Click Save Changes.

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

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

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

      • Name: Must be named Federation.

      • Type: Must be type Federation.

    3. Click Save Changes.

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

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

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

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

    4. Click Save Changes.

Step 3: Create an IDP circle of trust

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

  2. Click + Add Circle of Trust.

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

  4. On the CoT page, provide CoT details.

    CoT details:
    • Description: Enter a unique identifier.

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

  5. Click Save Changes.

Step 4: Test SAML2 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.

Gateways & agents

Overview

Integrate Identity Cloud with ForgeRock Identity Gateway and policy agents to secure access to your web resources.

ForgeRock Identity Gateway

ForgeRock Identity Gateway (IG) integrates your web applications, APIs, and microservices with Identity Cloud. IG enforces security and access control without modifying your applications or the containers where they run—whether on premises, in a public cloud, or in a private cloud.

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

IG can also conduct deep analysis, then throttle and transform requests and responses when necessary.

See the ForgeRock Identity Gateway Identity Cloud Guide for these detailed instructions and examples:

Policy agents

ForgeRock policy agents are Access Management (AM) 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.

See these guides for examples of how to transition from on-premises access management to ForgeRock Identity Cloud without changing the architecture of the agent-based model:

Password policy

Overview

Configure a password policy 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, 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. Refer to NIST Digital Identity Guidelines.

Configure a password policy

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

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

  3. Edit password policy details.

    Password length

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

    Cannot include

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

    • More than two consecutive characters (Example: aaaaaa)

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

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

    Must contain

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

    • Upper case letter

    • Lower case letter

    • Number

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

    Cannot reuse

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

    Force password change

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

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

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

Force end-user password changes

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

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

If you are considering forcing your end users to change their passwords, review the NIST Digital Identity Guidelines. In particular, NIST no longer recommends scheduled password changes; refer to 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.

Journeys

Overview

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

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

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

Authentication template

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

User self-service templates

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

Custom journey

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

Default end-user journey

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

Set a default end-user journey as follows:

  • Set a new journey as the default:

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

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

  • Set an existing journey as the default:

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

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

Device profiling support

Use the ForgeRock SDKs to create authentication journeys based on device context. For more information, refer to Configure device profiling authentication.

Scripting

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

Use the auth scripting editor to do the following:

Authentication templates

Login

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

Show me the default login journey
login
  1. In the Identity Cloud admin UI, go to Journeys > Login.

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

  3. Enter information for each node in the journey:

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

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

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 Identity Cloud with information about how or where a device is used to authenticate.

For detailed instructions, refer to 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.

Show me the default registration journey
register
  1. In the Identity Cloud admin UI, go to Journeys > Registration.

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

  3. Enter information for each node in the journey:

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

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

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.

Show me the default progressive profile journey
progressive login
  1. In the Identity Cloud admin UI, go to Journeys > Progressive Profile.

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

  3. Enter information for each node in the journey:

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

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

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 Identity Cloud admin UI, go to Journeys > Update Password.

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

  3. Enter information for each node in the journey:

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

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

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.

Show me the default reset password journey
reset password
  1. In the Identity Cloud admin UI, go to Journeys > Reset Password.

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

  3. Enter information for each node in the journey:

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

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

Forgotten username

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

Show me the default forgotten username journey
forgot username
  1. In the Identity Cloud admin UI, go to Journeys > Forgotten Username.

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

  3. Enter information for each node in the journey:

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

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

Custom journeys

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

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

  2. Click + New Journey.

  3. Enter journey details.

    Journey Details:
    • Name: Name to display in the Journeys list.

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

    • (Optional) Description: Summarize end user interaction.

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

  4. Click Create journey.

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

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

    For information about all available nodes, refer to Nodes for journeys.

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

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

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 trees, and scripts.

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

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

  2. Check the checkbox beside one more journeys.

  3. Click Export.

  4. View the information on the Export Journeys page.

  5. Click Export.

Import journeys

You can import journeys, including all dependencies such as nodes, inner trees, and scripts.

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

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

  2. Download or skip back up:

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

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

      2. Click Download Backup.

    • Skip the download:

      1. Click Skip Backup.

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

  3. Configure the import:

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

    2. Select the identity object that the journey authenticates.

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

      • Overwrite all conflicts (default)

      • Manually pick conflict resolution

    4. Click Next.

    5. Review the information on the Import Summary page.

    6. Click Start Import.

    7. On the Import Complete page, click Done.

Debug Identity Cloud end-user journeys

Overview

You can debug end-user journeys in your 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.

After you activate or deactivate a journey’s debug mode setting, you must save the journey.
Use debug mode only in your development environment.
Before promoting a journey to your staging environment, ensure that you have deactivated debug mode for the journey. Journeys that are in debug mode are clearly marked with a Debug label in the journey list view.

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

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

Enable debug mode

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

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

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

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

  4. In the Debug panel, enable Debug mode.

  5. Select Enable Debug Popup to display debug logs as you navigate the journey. For more information, refer to View debug information in a pop-up window.

  6. Click Save.

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 Identity Cloud admin UI:

    1. Enable debug mode.

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

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

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

    2. The browser window displays an initial debug step.

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

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

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

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

Shared, transient, and secure state

Shared state

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

Transient state

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

Secure state

Used by nodes to store decrypted transient state.

Roles and assignments

Overview

Roles and assignments let you create an entitlements structure that fits the needs of each realm.

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 Identity Cloud admin UI to:

  • Add new user profiles, device profiles, or roles

  • Add assignments to roles

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

  • Provision identities with role-based permissions

Roles

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

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

A role won’t work until you link it to at least one assignment. During the authorization process, 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. 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, 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, 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, refer to the following documents:

Organizations

Create organizations 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 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 Identity Cloud tenant administrators can create top-level organizations. In this example, Sam Carter is an 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 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. 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. Identity Cloud uses roles and assignments to provision identity profiles with permissions.

For quick takes, refer to About roles and assignments and How provisioning works. To view a list of tenant administrators, refer to View the administrators list. To view realm settings, refer to 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 Identity Cloud user identities, refer to Manage identities.

Create a user profile

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

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

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

Edit a user profile

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

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

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

Reset a user password

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

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

  3. Click Reset Password.

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

Delete a user

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

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

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

Roles

For a quick take, refer to Roles in this guide. For a deeper dive, refer to Roles.

Create an external role

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

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

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

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

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

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

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

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

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

    4. Click Next.

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

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

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

    3. Click Save.

Edit an external role

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

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

  3. Add managed assignments to the role:

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

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

  4. Add members to the role:

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

    2. Select an identity from the members list.

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

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

    1. On the Internal Role page, click Settings.

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

Create an internal role

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

  2. Click Internal Roles.

  3. Click + New Internal Role.

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

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

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

  5. Click Next.

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

  7. To add the identity, click Add.

  8. Set the permission for the identity:

    • View: Grant the identity object view access.

    • Create: Grant the identity object create access.

    • Update: Grant the identity object update access.

    • Delete: Grant the identity object delete access.

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

  10. Click Next.

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

    1. Enable A conditional filter for this role.

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

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

    4. Click Next.

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

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

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

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

      • To view a worldwide list of offset times, click Time zones chart to calculate the offset time.

  13. Click Save.

Edit an internal role

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

  2. On the Manage Identities page, click Internal Roles, and click on a role name.

    • To edit role details:

      1. Click the Details tab.

      2. Edit the Name field and possibly the Description field.

      3. Click Save.

    • To edit a privilege:

      1. Click the Privileges tab.

      2. Click a privilege.

      3. Edit the privilege details.

      4. Click Save.

    • To add a privilege:

      1. Click the Privileges tab.

      2. Click + Add Privileges.

      3. To choose an identity that this role should grant administration privileges to, use the drop-down list field to choose an identity object.

      4. To add the identity, click Add.

      5. Set the permission for the identity:

        • View: Grant the identity object view access.

        • Create: Grant the identity object create access.

        • Update: Grant the identity object update access.

        • Delete: Grant the identity object delete access.

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

      7. Click Save.

    • To edit a member:

      1. Click the Members tab.

      2. Click a member.

      3. Edit the member’s information.

      4. Click Save.

    • To add a member:

      1. Click the Members tab.

      2. Click + Add Members.

      3. Use the drop-down field to choose a member.

      4. Click Save.

    • To set a start and end date for when the role is active:

      1. On the Internal Role page, click Settings.

      2. In the Time Constraint section, click Set Up.

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

      4. Set the time parameter fields.

      5. Click Save.

    • To set a conditional filter for the role:

      1. On the Internal Role page, click Settings.

      2. In the Condition section, click Set Up.

      3. Enable A conditional filter for this role.

      4. Set the condition fields.

      5. Click Save.

    • To use JSON to configure internal role details, privileges, and other information:

      1. On the Internal Role page, click Raw JSON.

      2. Edit the JSON sample.

For a deep dive into roles, refer to Roles.

Assignments

For a quick take, refer to Assignments. For a deep dive into roles and assignments, refer to 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. For more information, refer to Resource mapping.

  1. In the Identity Cloud admin UI, go to Native Consoles > Identity Management. The Identity Management console is displayed.

  2. Click Create Mapping, and add a mapping using information from Configure mappings using the admin UI.

Create an assignment

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

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

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

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

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

    • Mapping: Select a mapping to which the assignment applies.

  4. (Optional) Add an attribute to map to the target system. For more information, refer to 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 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 Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Assignments and click on an assignment name.

  3. In the Details tab and Manage Roles tab, edit the assignment settings.

Organizations

For a quick take, refer to 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. Refer to Accessing the IDM REST APIs.

    For examples of API calls for organizations, refer to Manage Organizations Over REST.

  • By tenant administrators, using the Identity Cloud admin UI as described on this page.

  • By organization owners and organization administrators, using the 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 Identity Cloud admin UI, go to Identities > Import.

  2. On the Bulk Import page, click New Import.

  3. On the Upload CSV page, select Alpha realm - Users, and then click Next.

  4. In the Upload CSV page, Enter the following information and then click Next:

    • CSV File: Browse to your file

    • Match Using: Add a property name to use for a unique record match

  5. When the Import Complete dialog box is displayed, and you can confirm that the import was successful, click Done.

    You can confirm the import in the following ways:

    • Go to Identities > Manage > Alpha realm - Users, and open any user profile. Click Organizations to which I Belong, and make sure that the organization you created is displayed.

    • Go to Identities > Manage > Alpha realm - Organizations, and make sure that the organization you created is displayed.

    • Click the name of the organization you created, click Members, and then make sure that all the imported user identities are displayed.

Create a parent organization

Tenant administrators Organization owners Organization administrators

Only tenant administrators can create a parent organization.

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

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

  3. On the New Alpha realm - Organizations page, enter a name for the organization. Uppercase, lowercase, alphanumeric, special characters, and white spaces are allowed.

  4. Click Save.

  5. In the organization page, change the name, add a description, or assign a parent organization. To designate this organization as the parent, leave the Parent Organization field blank.

  6. Click Save.

Create an organization owner

Tenant administrators Organization owners Organization administrators

Only tenant administrators can create an organization owner.

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

  2. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  3. Click Owner and Add Owner.

  4. In the Add Owner page, select an identity from the drop-down list.

    Make sure that the organization owner is not also an organization member. This can result in giving the organization administrator greater control of the organization than its owner.
  5. Click Save.

Create an organization administrator

Tenant administrators Organization owners Organization administrators

  • Tenant administrators can create an organization administrator in any organization.

  • Organization owners can create organization administrators only within organizations or sub-organization where they are owner.

  • Organization administrators cannot create other organization administrators.

  1. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  2. Click Administrators and Add Administrators.

  3. In the Add Administrators page, select a user from the drop-down list. The user must already belong to the organization.

  4. Click Add Administrators. The username is displayed in the members list.

Create a sub-organization

Tenant administrators Organization owners Organization administrators

  • Tenant administrators can create sub-organizations within any organization.

  • Organization owners can create sub-organizations only within organizations or sub-organizations where they are owner.

  • Organization administrators can create sub-organizations only within organizations or sub-organizations where they are administrator.

Tenant administrators
Tenant administrators can view all organizations.

Follow the steps in to create a parent organization, and then set a parent organization that is:

  • An existing organization

  • One level of hierarchy higher than this child organization

Organization owners and organization administrators
Organization owners and organization administrators can view only the organizations and sub-organizations that they own or administrate.
  1. In the 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 Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  3. In the organization page, change the name, add a description, or assign a parent organization.

    Uppercase, lowercase, alphanumeric, special characters, and white spaces are allowed in the organization name.

    To designate this organization as the parent, leave the Parent Organization field blank.

  4. Click Save.

Organization owners and organization administrators
  1. In the 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 Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  3. On the organization page, click Members and Add Members.

  4. Select an identity from the members list, and then click Save. The username or usernames you added are now displayed in the members list.

Organization owners and organization administrators
  1. In the 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 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 Identity Cloud admin UI, go to Identities > Manage.

  2. On the Manage Identities page, click Alpha realm - Organizations and click on an organization name.

  3. On the organization page, click Delete Alpha realm - Organization.

    This operation cannot be undone.
Organization owners and organization administrators
  1. In the Identity Cloud End User UI, go to Manage.

  2. Follow steps in the tenant administrator instructions.

Sync identities

Register a remote server with your tenant before you want to sync identities, or set up load balancing and failover.

Connectors can read data in your tenant and in an external resource (an app or service that runs on a server outside your tenant).

Use connectors to convert your identity profiles, as well user accounts in a resource server, into a format that both data stores can use.

For more information, refer to About Identity Cloud connectors.

Identity Cloud provides built-in connectors for synchronization with data stores in other cloud services. Refer to the Identity Cloud built-in connectors.

Before you begin

Before you can make a connection, you have to register a remote connector server with your tenant. You also need to have a connector service up and running.

To configure connectors that are not built in to Identity Cloud, here’s an overview of the steps to take:

  1. Register a remote server.

  2. Download a remote server.

  3. Configure the remote server to connect to Identity Cloud.

  4. Install and configure a connector, if needed.

  5. Create a mapping between identities in Identity Cloud and identities in your identity resource server.

  6. (Optional) If you plan to set up load balancing or failover, then register a remote server cluster.

For troubleshooting advice, refer to this knowledge base article: How do I troubleshoot the Java Remote Connector Service (RCS)?.

Register a remote server

  1. In the Identity Cloud admin UI, go to Identities > Connect > Connector Servers.

  2. Click + New Connector Server.

  3. In the New Connector Server dialog box, provide the remote server details:

    • Name: This name is displayed in the Connector Servers list.
      Use only lowercase letters and numerals. No special characters or spaces are allowed.

  4. Click Save.

When the remote server is successfully registered, you’ll see links to the next steps. Be sure to open each link in a different window or tab so have you always have access to the Next Steps dialog box.

Completing the Next Steps

1 Reset the client secret

Identity Cloud creates an OAuth 2.0 client for you, and opens its profile.

client secret

  1. Click Reset to change the client secret.

  2. In the Reset Client Secret dialog box, enter any string to serve as a password.

  3. Read the warning, and then click Save.

2 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 (Java).

    Download the file package to the host that will run the connector server. The filename contains 'OpenICF'.
    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.

3 Install and configure a connector

If the connector you want to use is not bundled with the remote server you downloaded in Next Step 2, you’ll need these instructions. Follow the instructions in the Remote Connector Server (RCS) connectors page to download and install the remote connector you need.

After you complete the Next Steps, click Done in the Next Steps window.

Configure a remote server

  1. Unpack the OpenICF package you downloaded from the IDM Connectors download page.

  2. Edit the ConnectorServer.properties file.

    ConnectorServer.properties details:
    1. Add the OAuth2 Client credentials used to obtain an OAuth2 token. The client uses the Client Credentials grant type.

      • connectorserver.clientId=RCSClient
        Identity Cloud created this OAuth 2 client for you.

      • connectorserver.clientSecret=<client-secret>
        Use the OAuth 2 client secret you entered for RCSClient.

    2. Uncomment these settings and edit them for your tenant:

      • connectorserver.url
        This is the Identity Cloud OpenICF endpoint.
        Use wss over HTTPS so the client can obtain a bearer token through OpenID.

        • In staging and production environments, use three URLs in a space-delimited list. Example:
          connectorserver.url=wss://<tenant-env-fqdn>/openicf/0 wss://<tenant-env-fqdn>/openicf/1 wss://<tenant-env-fqdn>/openicf/2

        • In a development environment, use only one URL. Example:
          connectorserver.url=wss://<tenant-env-fqdn>/openicf/0

      • connectorserver.connectorServerName=<remote-server-name>
        This is the remote server name you set through the Identity Cloud admin UI. Be sure that 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=900
        WebSocket groups check interval, in seconds.

      • connectorserver.webSocketConnections=3
        Specifies the number of sockets the connector server will establish and maintain to each IDM it connects to.

      • connectorserver.connectionTtl=3000
        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.usessl=true
        Enables SSL.

      • connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog

  3. When you’re satisfied with your changes, save the file.

  4. Start the remote server on the OAuth 2.0 client:

    Windows

    bin\ConnectorServer.bat /run

    Linux

    bin/ConnectorServer.sh /run

  5. To verify that the connection is working, view the remote server status in the Remote Servers list.

Create a mapping

Create a mapping between identities in Identity Cloud, and identities in your identity resource server.

  1. In the Identity Cloud admin UI, go to Native Consoles > Identity Management.

  2. In the IDM admin UI, click Create Mapping.
    For detailed information and instructions, refer to Configure a resource mapping.

Once you’ve tested your mapping configuration per the instructions, you can make connections for synchronizing and provisioning user profiles.

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 Identity Cloud admin UI, go to Identities > Connect > Server Clusters.

  2. Click + New Server Cluster.

  3. Provide Server Cluster Details:

    Connector 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 ForgeRock® Directory Services deployment into Identity Cloud.

Password synchronization relies on an LDAP connector configured to synchronize accounts from your DS servers. Identity Cloud password synchronization does not use a password synchronization plugin. Instead, it synchronizes hashed passwords as strings in the same way it synchronizes other LDAP attributes.

This feature depends on having compatible one-way hash password storage schemes in Identity Cloud and in your DS password policies. DS servers in 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 Identity Cloud.

    The following DS password storage schemes are enabled in Identity Cloud:

    • Bcrypt

    • PBKDF2

    • PBKDF2-HMAC-SHA256

    • PBKDF2-HMAC-SHA512

    • Salted SHA-256

    • Salted SHA-512

    • SCRAM-SHA-256

    • SCRAM-SHA-512

  2. Verify that account synchronization works properly from your DS service to Identity Cloud.

    For example, modify a test user’s entry in your DS server, and check that the corresponding account in Identity Cloud is correctly updated after reconciliation runs.

  3. In the native IDM admin UI, configure the LDAP connector to synchronize userPassword attributes as strings:

    1. Delete __PASSWORD__ from the list of LDAP connector properties.

    2. Add userPassword with Native type: string and Run as User enabled.

  4. In the native IDM admin UI, configure the mapping from your remote DS system resource to 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, of type JavaScript:

      // Set the text of {ds_abbr} 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 Identity Cloud after reconciliation runs.

About Identity Cloud connectors

Apps and services that run and store data outside your tenant exist as external resources relative to Identity Cloud.

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, refer to Remote Connector Server (RCS) connectors.

Syncing and provisioning

Here’s how 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 Identity Cloud syncing and provisioning, see a related example in "Assignments".

Data reconciliation

Identity Cloud reconciles data when changes occur in either your identity profiles or in user accounts stored in resource servers.

An Identity Cloud connector first compares an identity profile to its corresponding user account in the resource server. If conflicting information exists, Identity Cloud resolves the conflicts based on your preferences. Then 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, 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 that requests are handled with the greatest efficiency.

When you configure connector servers for failover, if one resource server stops, then your Identity Cloud redirects requests to a standby resource server. This ensures that your end users don’t experience a loss of service. When the stopped resource server restarts, Identity Cloud directs requests to the restarted server.

More information

For a deep dive, refer to the following documents:

Bulk import identities

Overview

You can use a CSV file to bulk import identities. 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.

For information about generating this file, refer to Import bulk data.

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

  2. On the Import Identities page, click + New Import.

  3. On the New Import dialog box, select the realm-target you want to import to.

    Tell me more

    The target can be any managed object such as a user, role, or assignment defined within a realm. For example, you could import ten user profiles to the Bravo realm - Roles target. The imported roles are added to the bravo_role managed object in 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 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, Identity Cloud tries to verify that a user profile with the username bjensen also exists in your tenant. If verified, then Identity Cloud updates the entire bjensen user profile. If no match is found, then 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, 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 Identity Cloud admin UI, go to Identities > Import.

  2. On the Import Identities list, find the filename.
    In the same row, click More ().

  3. Choose View Details or Delete.

Constrain identity queries in the UI

Overview

You can constrain queries in two ways when managing identities with the Identity Cloud admin UI:

Constraining how the Identity Cloud admin UI can be used can improve overall Identity Cloud performance because the constraints forbid queries that might inadvertently use a large amount of computing resources.

Require a minimum length search string

You can require Identity Cloud administrators to enter a minimum length string when querying identities using the Identity Cloud admin UI. This setting also disables sorting search results unless a minimum length string has been specified in the search box.

Applying this setting can speed up the time it takes to retrieve records from large identity data sets.

This setting only affects queries performed in the Identity Cloud admin UI. It does not affect Identity Cloud REST API queries.

To apply the setting:

  1. In the Identity Cloud admin UI, go to Identities > Configure to access the Configure Identities page.

  2. Click on an identity profile. For example, if you want to configure the UI for managing identities in the Alpha realm, click Alpha realm - User.

  3. Enter a number greater than zero in the Minimum Characters field.

  4. Click Save.

To verify that the setting is in effect:

  1. Go to Identities > Manage.

  2. Select the identity profile that corresponds to the one you configured when you applied the setting.

  3. Click one of the column titles at the top of the search results to attempt to sort the results.

    You should not be able to sort the results. Sorting by column should have been disabled.

  4. Specify a string in the Search field that has fewer characters than the minimum number of characters you specified in the profile’s configuration. Then, press Enter.

    The search operation should not be permitted.

  5. Specify a string in the Search field that has the minimum number of characters you specified in the profile’s configuration. Then, press Enter.

    The search operation should be permitted.

  6. Click one of the column titles at the top of the search results to sort the results.

    Sorting the search results should now be permitted.

Forbid sorting or searching resource collections

A resource collection is a set of identities that has a relationship with another identity. For example:

  • All the users with a particular role assignment

  • All the users who are members of an organization

You can forbid Identity Cloud delegated administrators from sorting resource collections and performing searches within resource collections in the Identity Cloud admin UI.

This setting only affects delegated administrators using the Identity Cloud admin UI. It does not affect tenant administrators using the Identity Cloud admin UI.

To apply the setting:

  1. In the Identity Cloud admin UI, go to Identities > Configure to access the Configure Identities page.

  2. Click on an identity profile. For example, if you want to configure the UI for managing identities in the Alpha realm, click Alpha realm - User.

  3. Click the Disable sorting and searching on grids that use this object as a resource collection toggle.

  4. Click Save.

To verify that the setting is in effect:

  1. Log out of Identity Cloud.

  2. Log in to 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

Overview

You may need to use user identity attributes for the following reasons:

  • To customize the identity attribute display names shown in the user profile in the UI

  • To reference the identity attributes in scripts and API calls

The attribute and property names are not consistent between the underlying AM and IDM services. To address this, the reference tables depict the equivalent attribute.

Using the reference tables

  • If you write scripts for AM that access user profiles, then use AM attribute names. User profile script examples: OAuth2 access token modification; OIDC claims; decision node scripts for authentication journeys (trees).

  • If you write scripts for IDM that access managed objects, then use IDM property names. Managed object script examples: onUpdate, onCreate, onDelete, and so forth.

  • If you use APIs to access managed objects or user profiles:

    • Calls to /am APIs must use AM attribute names.

    • Calls to /openidm APIs must use IDM property names.

If you use the IDM admin UI to change the display name of a property, the change is reflected in both the IDM admin UI and the Identity Cloud admin UI; however, on the API side and in scripts, the generic names remain unchanged.

Reference tables

User details

Display Name IDM Property AM Attribute

Username

userName

uid

Common Name

cn

cn

Password

password

userPassword

Status

accountStatus

inetUserStatus

First Name

givenName

givenName

Last Name

sn

sn

Email Address

mail

mail

Description

description

description

Telephone Number

telephoneNumber

telephoneNumber

Address 1

postalAddress

street

City

city

l

Postal Code

postalCode

postalCode

Country

country

co

State/Province

stateProvince

st

Display Name

displayName

displayName

Provisioning Roles

roles

fr-idm-managed-user-roles

Manager

manager

fr-idm-managed-user-manager

Authorization Roles

authzRoles

fr-idm-managed-user-authzroles-internal-role

Effective Roles

effectiveRoles

fr-idm-effectiveRole

Effective Assignments

effectiveAssignments

fr-idm-effectiveAssignment

Last Sync timestamp

lastSync

fr-idm-lastSync

KBA

kbaInfo

fr-idm-kbaInfo

Preferences

preferences

fr-idm-preferences

Consented Mappings

consentedMappings

fr-idm-consentedMapping

Assigned dashboard

assignedDashboard

assignedDashboard

Alias list

aliasList

iplanet-am-user-alias-list

Profile image

profileImage

labeledURI

Description IDM Property AM Attribute

User Metadata

_meta

fr-idm-managed-user

Immutable IDM attribute

_id

fr-idm-uuid

Revision attribute

_rev

etag

General purpose extension attributes

Strings
Display Name IDM Property AM Attribute

Generic Indexed String 1

frIndexedString1

fr-attr-istr1

Generic Indexed String 2

frIndexedString2

fr-attr-istr2

Generic Indexed String 3

frIndexedString3

fr-attr-istr3

Generic Indexed String 4

frIndexedString4

fr-attr-istr4

Generic Indexed String 5

frIndexedString5

fr-attr-istr5

Generic Unindexed String 1

frUnindexedString1

fr-attr-str1

Generic Unindexed String 2

frUnindexedString2

fr-attr-str2

Generic Unindexed String 3

frUnindexedString3

fr-attr-str3

Generic Unindexed String 4

frUnindexedString4

fr-attr-str4

Generic Unindexed String 5

frUnindexedString5

fr-attr-str5

Multivalues
Display Name IDM Property AM Attribute

Generic Indexed Multivalue 1

frIndexedMultivalued1

fr-attr-imulti1

Generic Indexed Multivalue 2

frIndexedMultivalued2

fr-attr-imulti2

Generic Indexed Multivalue 3

frIndexedMultivalued3

fr-attr-imulti3

Generic Indexed Multivalue 4

frIndexedMultivalued4

fr-attr-imulti4

Generic Indexed Multivalue 5

frIndexedMultivalued5

fr-attr-imulti5

Generic Unindexed Multivalue 1

frUnindexedMultivalued1

fr-attr-multi1

Generic Unindexed Multivalue 2

frUnindexedMultivalued2

fr-attr-multi2

Generic Unindexed Multivalue 3

frUnindexedMultivalued3

fr-attr-multi3

Generic Unindexed Multivalue 4

frUnindexedMultivalued4

fr-attr-multi4

Generic Unindexed Multivalue 5

frUnindexedMultivalued5

fr-attr-multi5

Dates
Display Name IDM Property AM Attribute

Generic Indexed Date 1

frIndexedDate1

fr-attr-idate1

Generic Indexed Date 2

frIndexedDate2

fr-attr-idate2

Generic Indexed Date 3

frIndexedDate3

fr-attr-idate3

Generic Indexed Date 4

frIndexedDate4

fr-attr-idate4

Generic Indexed Date 5

frIndexedDate5

fr-attr-idate5

Generic Unindexed Date 1

frUnindexedDate1

fr-attr-date1

Generic Unindexed Date 2

frUnindexedDate2

fr-attr-date2

Generic Unindexed Date 3

frUnindexedDate3

fr-attr-date3

Generic Unindexed Date 4

frUnindexedDate4

fr-attr-date4

Generic Unindexed Date 5

frUnindexedDate5

fr-attr-date5

Integers
Display Name IDM Property AM Attribute

Generic Indexed Integer 1

frIndexedInteger1

fr-attr-iint1

Generic Indexed Integer 2

frIndexedInteger2

fr-attr-iint2

Generic Indexed Integer 3

frIndexedInteger3

fr-attr-iint3

Generic Indexed Integer 4

frIndexedInteger4

fr-attr-iint4

Generic Indexed Integer 5

frIndexedInteger5

fr-attr-iint5

Generic Unindexed Integer 1

frUnindexedInteger1

fr-attr-int1

Generic Unindexed Integer 2

frUnindexedInteger2

fr-attr-int2

Generic Unindexed Integer 3

frUnindexedInteger3

fr-attr-int3

Generic Unindexed Integer 4

frUnindexedInteger4

fr-attr-int4

Generic Unindexed Integer 5

frUnindexedInteger5

fr-attr-int5

UI integration options for Identity Cloud

Overview

When you integrate your applications with your Identity Cloud tenant, you will need to consider how to manage the journey and account pages that your end users will use. There are a number of user interface (UI) options available, and the one you choose will be based on a combination of the following factors:

  • Hosting: Do you want to host your own UI?

  • Application platform: Do you only need to support web applications, or do you also need to support native applications?

  • Theming: How much control do you want over the look and feel of the UI?

  • Journey flow: Do you want to redirect end users to a central UI, or embed a UI into each application?

For a quick take on these factors against each of the UI options, refer to the summary below.

Journey flows

Centralized journey flows

Centralized journey flows are an increasingly familiar sign-in experience to end users and are considered a security best practice. An example of a centralized journey flow is Google G Suite, where a user is redirected to the same authentication page no matter which application they are trying to access.

Centralized journey flows are possible using all UI options.

Embedded journey flows

Embedded journey flows offer a more traditional sign-in experience, as end users are not redirected outside an application. However, embedded journey flows are not considered a security best practice, as individual applications then have access to both the user’s credentials and to the authorization grant.

Embedded journey flows are not recommended, but are possible using the self-hosted Login UI or SDKs.

UI options

Identity Cloud hosted pages

This is the easiest option, as your Identity Cloud tenant already provides hosted pages that allow you to manage:

  • End user journey pages, such as login, registration, and password reset

  • End user account pages, such as user profile and delegated administration

The UI layout is fixed, but can be themed per realm. You can add company logos and change button, link, and background colors. The UI supports web applications but not native applications.

This option is useful if you have limited theming needs or want to quickly try new registration or authentication flows without integrating them into an application.

This option only lets you use centralized journey flows in your applications. Additionally, this is the only option that supports SAML journey flows that use Identity Cloud as the IDP.

ForgeRock does not support the use of Identity Cloud hosted pages in embedded journey flows. Specifically, embedding hosted pages in HTML frames is not supported.

ForgeRock Identity Platform end-user and login UIs (self-hosted)

In this option, you self-host the end-user UIs, the login UIs, or both, and configure them to use your Identity Cloud tenant.

This option offers flexibility if you want to customize the layout of the UIs or customize the theming beyond what the default hosted pages provide. The UIs support web applications but not native applications.

This 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, refer to Platform UIs.

ForgeRock SDKs

For background information about ForgeRock SDKs (SDKs), see https://sdks.forgerock.com/getting-started/using-sdks/.

In this option, you use the SDKs to develop your own custom UI for web, Android, or iOS applications. You then integrate it with your Identity Cloud tenant using the REST API.

Each SDK provides an out-of-the-box UI module that allows you to prototype your custom UI. However, it is only provided as a starting point and is not intended for production use.

This option offers maximum flexibility if you want to customize the behavior, layout, and theming of the UI, or want to support Android and iOS applications. However, it requires a higher level of technical skill than the other options.

It also lets you use both centralized and embedded journey flows in your applications.

Summary

UI App Platform Theming Journey Flows Notes

Identity Cloud hosted pages

Web

Limited

Centralized

  • Default UI for your Identity Cloud tenant

  • Allows rapid journey prototyping

  • Does not support embedded journey flows.

Platform end-user and login UIs

Web

No limitation

Centralized or embedded

  • Choice of self-hosting one or more of the UIs

SDKs

Web, Android, iOS

No limitation

Centralized or embedded

  • Higher level of technical skill required

Identity Cloud hosted pages

Overview

Identity Cloud hosts default web pages (known as hosted pages) that you can use in end-user journeys. Hosted pages support localization, and have customizable themes. The pages are designed to help you quickly create and test common user self-service operations.

For example, the default login journey starts with a sign-in page for capturing username and password. The journey ends with the end-user’s profile page.

600

Types of hosted pages

There are two types of hosted pages:

  • Hosted journey pages. Hosted pages for end user login journeys.

  • Hosted account pages Hosted pages for end user account management, shown after a login journey.

Activate or deactivate hosted pages

Activate or deactivate hosted account pages

To prevent exposing information contained in the default end-user profile, you can deactivate the profile’s hosted page. You can then use the ForgeRock SDKs or your own APIs to create and host your own custom web pages.

When you deactivate the hosted pages option, Identity Cloud displays the following web page to unauthorized users:

450

After you deactivate 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.

Afterwards, all hosted pages associated with your tenant are deactivated.

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

Activate or deactivate journeys

To prevent users from viewing sensitive information that may appear in generated login, registration, password reset pages, you can deactivate the default journey. This prevents a user from navigating to the default administrator login journey.

Afterwards, the journey is no longer visible in the tenant UI.

When you deactivate the default journey, Identity Cloud displays the following web page to a user that attempts to navigate to alpha or bravo realm journey:

450

After you deactivate the default journey, you can still administer the tenant environment while preventing unauthorized access to default journey information.

  1. In the Identity Cloud admin UI, open the Tenant menu, 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 the default journey, beside Hosted Journey Pages, click Activate. The Global Settings toggle displays the status as Active.

    • To deactivate the default journey, beside Hosted Journey Pages, click Deactivate. The Global Settings toggle displays the status as Inactive.

For an explanation about how hosted pages integrate with the default journey, refer to the Journeys page.

Localize Identity Cloud end-user and login UIs

Overview

You can localize the Identity Cloud end-user and login UIs to support the different languages of your end users. You do this with translation configuration, defining a locale-specific set of key/phrase translation pairs that override the default set of key/phrase pairs. You can override some or all of the default keys, in as many locales as you need. The translation configuration has an effect in all realms.

The UIs try to find a translation configuration for the locale requested by an end user’s browser, or gracefully fall back to the default en locale.

To manage translation configuration, use the /openidm/config/uilocale/* endpoint in the REST API.

Translation configuration format

The translation configuration format for each locale is as follows:

{
    "enduser": {(1)
        "pages": {
            "dashboard": {
                "widgets": {
                    "welcome": {
                        "greeting": "Translation for predefined 'greeting' key",(2)
                    }
                }
            }
        }
    },
    "login": {(1)
        "login": {
            "next": "Translation for predefined 'next' key"(2)
        },
        "overrides": {
            "UserName": "Translation for literal phrase 'User Name'",(3)
            "Password": "Translation for literal phrase 'Password'"(3)
        }
    },
    "shared": {(1)
        "sideMenu": {
            "dashboard": "Translation for predefined 'dashboard' key"(2)
        }
    }
}
1 Top-level blocks

The enduser, login, and shared top-level blocks correspond to the names of the UI packages in GitHub:

2 Key/phrase translation pairs with predefined keys

Most of the key/phrase translation pairs are predefined in the en locale translation files for each package:

You can translate some or all of the keys. Additionally, if you want to create different translations in the enduser and login blocks for a key from the shared block, you can copy the JSON structure for the shared key into each of the enduser and login blocks, where they will override the key in the shared block.

3 Key/phrase translation pairs with literal keys

Key/phrase translation pairs defined within an override block are not predefined. Instead, the key is made from a literal phrase with all non-alphanumeric characters (including underscores) stripped out.

These translation pairs with literal keys are designed as a catch-all solution for any UI phrases that have not been defined, or for any unlocalized phrases that come directly from the backend servers. The example shows two literal keys that translate the placeholder text from input fields that are part of an authentication journey. This approach can be taken to translate server output from authentication messages and journey nodes.

Translation pairs with literal keys are currently only available within the login top-level block.

Translation precedence and fall back

The UIs translate each key/phrase pair in a particular order. They initially determine a primary locale using the requested language from an end user’s browser. Then, if no translation is found using the primary locale, they fall back to the default en locale.

The translation precedence for an end user with a browser locale of fr (French) would be as follows:

  1. Attempt to use the primary fr locale:

    1. Look for the translation key in any translation configuration for the fr locale:
      https://<tenant-env-fqdn>/openidm/config/uilocale/fr

      If the translation configuration is not present, a 404 response is returned. See Translation 404 responses.

  1. Fall back to the default en locale:

    1. Look for the translation key in any translation configuration for the en locale:
      https://<tenant-env-fqdn>/openidm/config/uilocale/en

      If the translation configuration is not present, a 404 response is returned. See Translation 404 responses.

    2. Look for the translation key in the translation files for the en locale :

      • platform-enduser/src/locales/en.json

      • platform-login/src/locales/en.json

      • platform-shared/src/locales/en.json

Translation 404 responses

You may see one or more 404 responses in the browser console for the /openidm/config/uilocale/* endpoint. These are expected, and do not indicate a UI error; the 404 responses mean that the UI cannot locate a translation configuration override, which is perfectly valid if you have not added one.

If you would prefer to suppress the 404 responses, create a translation configuration with an empty body for each locale reporting a 404 response.

REST API

Create or replace translation configuration

  1. Create an access token. See Get an access token.

  2. Create or replace the translation configuration for each locale:

    Show request
    $ curl \
    --request PUT 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1)
    --header 'Authorization: Bearer <access-token>' \(2)
    --header 'Content-Type: application/json' \
    --data-raw '{(3)
        "enduser": {
            "pages": {
                "dashboard": {
                    "widgets": {
                        "welcome": {
                            "greeting": "Bonjour"
                        }
                    }
                }
            }
        },
        "login": {
            "login": {
                "next": "Suivant"
            },
            "overrides": {
                "UserName": "Nom d'\''utilisateur",
                "Password": "Mot de passe"
            }
        },
        "shared": {
            "sideMenu": {
                "dashboard": "Tableau de bord"
            }
        }
    }
    '
    1 Replace <locale> with a locale identifier. Some examples are:
    • en (English)

    • es (Spanish)

    • fr (French)

    • en-us (English - United States)

    • es-ar (Spanish - Argentina)

    • fr-ca (French - Canada)

    2 Replace <access-token> with the access token.
    3 Replace the example translation configuration with your own translation configuration.
    Show response
    {
        "_id": "uilocale/fr",
        "enduser": {
            "pages": {
                "dashboard": {
                    "widgets": {
                        "welcome": {
                            "greeting": "Bonjour"
                        }
                    }
                }
            }
        },
        "login": {
            "login": {
                "next": "Suivant"
            },
            "overrides": {
                "UserName": "Nom d'\''utilisateur",
                "Password": "Mot de passe"
            }
        },
        "shared": {
            "sideMenu": {
                "dashboard": "Tableau de bord"
            }
        }
    }

View translation configuration

An access token is not needed to to view the translation configuration as it is publicly accessible.
  1. View the translation configuration using a GET request:

    Show request
    $ curl \
    --request GET 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>'(1)
    1 Replace <locale> with a locale identifier.
    Show response
    {
        "_id": "uilocale/fr",
        "enduser": {
            "pages": {
                "dashboard": {
                    "widgets": {
                        "welcome": {
                            "greeting": "Bonjour"
                        }
                    }
                }
            }
        },
        "login": {
            "login": {
                "next": "Suivant"
            },
            "overrides": {
                "UserName": "Nom d'\''utilisateur",
                "Password": "Mot de passe"
            }
        },
        "shared": {
            "sideMenu": {
                "dashboard": "Tableau de bord"
            }
        }
    }

Delete translation configuration

  1. Create an access token for the realm where the translations are applied. See Get an access token.

  2. Delete the translation configuration:

    Show request
    $ curl \
    --request DELETE 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1)
    --header 'Authorization: Bearer <access-token>' \(2)
    1 Replace <locale> with a locale identifier.
    2 Replace <access-token> with the access token.
    Show response
    {
        "_id": "uilocale/fr",
        "enduser": {
            "pages": {
                "dashboard": {
                    "widgets": {
                        "welcome": {
                            "greeting": "Bonjour"
                        }
                    }
                }
            }
        },
        "login": {
            "login": {
                "next": "Suivant"
            },
            "overrides": {
                "UserName": "Nom d'\''utilisateur",
                "Password": "Mot de passe"
            }
        },
        "shared": {
            "sideMenu": {
                "dashboard": "Tableau de bord"
            }
        }
    }

Customize Identity Cloud end-user and login UI themes

Overview

Identity Cloud realms have a default theme that includes the colors of buttons and links, typefaces, and so on. This default theme applies to the end-user and login UIs. You can add custom themes so that your end users are presented with screens specific to their authentication journey.

Custom themes let you create a different look and feel for each brand that you support, including different profile page layouts, logos, headers, and footers.

A theme is followed throughout an authentication journey. This means that if a user logs in through the Login UI with a specific theme, the remaining pages in the journey will have that same theme.

Add a custom theme

In the Identity Cloud admin UI:

  1. Select Hosted Pages > + New Theme.

    You can also duplicate an existing theme by clicking next to the theme you want, then selecting Duplicate.

  2. Enter a theme name that describes the theme’s purpose; for example, the brand associated with an authentication journey.

  3. Use the tabs and options to customize various aspects of the theme:

    Tab Option What You Can Customize

    Global

    Styles

    Colors of the text, links, menus, buttons, and background pages across all journey and user account pages

    Favicon

    Favicon logo displayed for all journey and account pages. You can localize the favicon. For details, refer to Localize the favicon and theme logo.

    Settings

    Theme name and linked trees

    Journey Pages

    Styles

    Colors of the text, links, menus, buttons, and background pages of authentication and registration journey pages

    Logo

    Logo to display on sign-in and registration pages You can localize the logo. For details, refer to Localize the favicon and theme logo.

    Layout

    Layout of the authentication and registration journey pages, including custom headers and footers

    Account Pages

    Styles

    Colors of the text, links, menus, buttons, and background pages of customer-facing pages, such as account profile and dashboard

    Logo

    Logo to display on customer-facing pages

    Layout

    Layout of customer-facing pages, including custom footers; categories of information that appears on the account profile page

  1. Click the favicon or logo image.

  2. Click + Specify a Locale.

  3. In the Locale field, enter the ISO 639-1 code for the language.

  4. Click Add.

  5. In the Favicon URL field or the Logo URL field, enter the URL for the favicon or logo.

  6. To set alternative text for the logo, in the Alt Text field, enter alternate text.

  7. Click Update.

  8. Click Save.

Apply a custom theme to a journey

In the Identity Cloud admin UI:

  1. Select Journeys, then select the journey to which you want to apply the custom theme, and click Edit.

  2. Click …​ > Edit Details then select Override theme.

  3. 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 Identity Cloud as configuration objects. They are therefore "static" in terms of 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 so on. Scripting is not currently supported in headers and footers.

The account footer is separate from the journey footer. This lets you set up different buttons, links, and so on, that are displayed to a user after they log in.

Enable headers and footers for a theme

  1. In the Identity Cloud admin UI, go to Hosted Pages, then select a theme.

  2. Select either Journey Pages or Account Pages.

  3. In the panel on the right-hand side, click Layout.

    1. Find the Header section (journey pages only), then enable the switch.

    2. Find the Footer section, then enable the switch.

Edit headers and footers

  1. Follow the steps above to find the appropriate Header or Footer section, then click the preview to open the editor.

  2. If you do not need localized content, edit the HTML as appropriate, then go to step 4.

  3. If you need localized content:

    1. See Localize headers and footers to add as many locales as you need.

    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.

Auth scripting

Overview

You can use authentication and authorization (auth) scripting to modify default Identity Cloud behavior in many situations: client-side authentication, policy conditions, handling OpenID Connect claims, and others.

Use JavaScript for auth scripting in 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.

Auth script types

The auth script types available in Identity Cloud include the following:

Script Type Description

OAuth 2.0 Access Token Modification

Modifies the key-value pairs contained within access tokens before they are issued to a client.

Client-side Authentication

Runs on the client during authentication.

Configuration Provider node

Runs in a Configuration Provider node as a step in an authentication journey.

OAuth 2.0 May Act

Adds the may_act claim to tokens when performing token exchanges.

OIDC Claims

Modifies or overrides OpenID Connect claims when issuing an ID token or in the response from the userinfo endpoint.

Journey Decision Node

Runs in a Scripted Decision node as a step in an authentication journey.

OAuth 2.0 Validate Scope

Modifies how Identity Cloud validates requested OAuth 2.0 scopes.

Social Identity Provider Profile Transformation

Adapts the fields received from a social identity provider to align with the fields expected by Identity Cloud.

Policy Condition

Modifies authorization policy decisions.

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 which features syntax highlighting and validation checking. You can maximize the editor to full screen to edit larger scripts:

idcloudui scripts 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. Enter a unique Name and optional Description for the script, then click Save.

    After you save a script, you cannot change its type.

Journey decision node auth scripts

Refer to Journeys for more information on journeys.

You can create, edit, and validate journey decision node auth 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 ⑤:

    idcloudui journeys scripted decision script options

    ① Scripted decision node
    ② Context pane
    ③ Journey decision node script drop-down
    ④ Add new journey decision node script
    ⑤ Edit existing journey decision node script

Custom endpoints

Overview

You can use custom endpoints to run arbitrary scripts through the REST API. These arbitrary scripts are extremely flexible and can extend 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 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, refer to Define and call data queries.

Use JavaScript for scripting custom endpoints in Identity Cloud. Groovy scripts are deprecated.

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 will open the custom endpoint script in a lightweight editor which features syntax highlighting and validation checking. You can 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, see Generate a cURL request for a custom endpoint
⑦ Test tab, see 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".

    • Your new custom endpoint will be accessible over HTTP at:
      https://<tenant-env-fqdn>/openidm/endpoint/<name>

    • Your new custom endpoint will be accessible via 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.

    See Custom endpoints scripting introduction for information on scripting basics.
  5. To test your script, click Save, then either:

  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. To understand how HTTP request methods relate to the script request.method property values, see 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 would map to request.content.param1 and request.content.param2.
  4. Click Generate to output the cURL request, which will appear below your script. The cURL request is complete with an access bearer token, so it’s ready to run.

  5. Click the copy icon () to copy the cURL request from the editor, then paste it into your terminal, then press return to run it in you terminal.

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 will create a request that uses the POST HTTP request method. To understand how HTTP request methods relate to the script request.method variable parameter values, see 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 can access the body using the request.content property. The example above would map to request.content.param1 and request.content.param2.
  4. Click Run to run the cURL request. The result will appear 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 Identity Cloud REST API

Overview

The 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: 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

Not applicable (publicly accessible endpoint)

  • /monitoring

  • /logs

API key and secret.

  • /am/*

  • /openidm/*

  • /.well-known/*

  • /environment/promotion/*

  • /variables

  • /secrets

  • /restart

Access token

Authenticate to Identity Cloud REST API with API key and secret

Overview

You will need an API key and secret to authenticate to the following Identity Cloud REST API endpoints:

  • /monitoring

  • /logs

Summary of use:

  1. Create an API key and secret in the Identity Cloud admin UI.

  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 Identity Cloud admin UI, 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",
        "ctsstore",
        "ctsstore-access",
        "ctsstore-config-audit",
        "ctsstore-upgrade",
        "idm-access",
        "idm-activity",
        "idm-authentication",
        "idm-config",
        "idm-core",
        "idm-everything",
        "idm-sync",
        "userstore",
        "userstore-access",
        "userstore-config-audit",
        "userstore-ldif-importer",
        "userstore-upgrade"
    ],
    "resultCount": 22,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": 1,
    "remainingPagedResults": 0
}

Authenticate to Identity Cloud REST API with access token

Overview

You need an access token to authenticate to the following Identity Cloud REST API endpoints:

  • /am/*

  • /openidm/*

  • /.well-known/*

  • /environment/promotion/* (self-service promotion endpoints)

  • /variables, /secrets, /restart (ESV endpoints)

Summary of use:

  1. Create a service account in the Identity Cloud admin UI and download a private key.

  2. Create a 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 below. To find installation instructions for your particular package manager, refer to https://command-not-found.com/jose.

Step 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. Make a note of the ID for the service account you created. An example of an ID is 449d7e27-7889-47af-a736-83b6bbf97ec5.

Step 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 3-minute expiration time for the JWT, expressed as number of seconds since the Unix epoch. For use in the exp (expiration time) claim.

      $ EXP=$(($(date -u +%s) + 180))
    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

Step 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 statically configured OAuth 2.0 public client for service accounts. This client is created by ForgeRock and is accessible from all customer realms. The client only allows the JWT profile for OAuth 2.0 authorization grant flow.
    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:*. Refer to 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": 180
    }

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 (refer to 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
}

Identity Cloud Postman collection

Overview

Identity Cloud provides REST APIs to help you manage identities, authenticate to the system, monitor Identity Cloud, and more.

You can also use the AM and IDM APIs with Identity Cloud.

To help you quickly use and understand these REST APIs, Identity Cloud provides a Postman collection, containing example requests grouped into features.

Features included:
 
・Intelligent Access
・User Self-Service
・Session Management
・Identity Profiles
・Managed Identities
・Auditing/Monitoring
・OAuth 2.0 Flows

postman collection overview

Getting started

  1. Download and install Postman.

  2. Download the 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.

Preparing your Identity Cloud

To use the Identity Cloud Postman collection, you must create a user identity in Identity Cloud that the collection requests can connect to.

  1. Log in to the Identity Cloud as a tenant administrator.

  2. Ensure you are managing the Alpha realm.

    1. If not, select the current realm in the top-left corner, click Switch realm…​, and switch to the Alpha realm.

  3. Go to Identities > Manage > Users, and then click + New User.

  4. Enter the user name as "postmanAdminUser".

  5. Complete the remaining fields, and then click Save.

  6. On the Manage Identities page, click the user you just created.

  7. Click Reset Password, then enter a new password.

    Make sure that you use a strong password.

  8. Select Authorization Roles, and then click Add Authorization Roles.

  9. Add the openidm-admin and openidm-authorized roles, and then click Save.

The collection requests for managed users will authenticate to Identity Cloud using these credentials.

Proceed to the next section to learn how to enter these credentials, plus other settings necessary to use the collection.

Configuring the collection

The Identity Cloud Postman collection uses a number of variables to populate the requests. These variables are stored at collection level. To view them, click on the top level of the collection menu (labelled "ForgeRock Identity Cloud Collection"), then select the Variables tab.

postman collection variables

The variables are initially set with placeholder values that you will need to modify or replace. For example, the collection needs to know the 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.

See Required variable values to understand which variables you need to edit before you can use the collection. See Optional variable values to understand which variables you may want to edit to customize the collection to suit your environment.

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 those in the table above.

For information on creating a Postman Environment, see Managing environments in the "Postman Learning Center".

Required variable values

Before using the collection, you must provide the following variable values:

Make sure that you use strong passwords for access credentials.

Variable Default Description

platformUrl

https://<tenant-env-fqdn>

Specifies the root URL of your Identity Cloud.

amUrl

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

Specifies the URL of the Access Management (AM) component of your Identity Cloud.

idmUrl

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

Specifies the URL of the Identity Management (IDM) component of your Identity Cloud.

IDCloudAdminUsername

admin@example.com

Specifies the username of an Identity Cloud adminstrator who can authenticate to the top-level realm, and create OAuth 2.0 clients and managed users.

IDCloudAdminPassword

Not Set

Specifies the password of the Identity Cloud adminstrator above.

postmanClientSecret

Not Set

Specifies the password to be used by the OAuth 2.0 administrative, private, and public clients.

These clients are created when you run the Prerequisite requests from the collection.

postmanAdminPassword

Not Set

Specifies the password to be used by the OAuth 2.0 managed admin user.

This is the password you set up in Preparing your Identity Cloud.

postmanDemoPassword

Not Set

Specifies the password to be used by OAuth 2.0 managed realm user.

The realm user is created when you run the Prerequisite requests from the collection.

logApiKey

Not Set

Specifies the API key used to access the monitoring endpoints. It is used in the auditing and monitoring collection requests only.

See Obtaining API Credentials.

logApiSecret

Not Set

Specifies the API secret used to access the monitoring endpoints. It is used in the auditing and monitoring collection requests only.

See Obtaining API Credentials.

Optional variable values

The collection uses the following additional variables, which will work using their default values, although you may want to modify them later:

Variable Default Description

realm

/realms/root/realms/alpha

Specifies the realm that the majority of the requests in the collection target.

You must specify the entire hierarchy of the realm, starting at the top-level realm.

Prefix each realm in the hierarchy with the realms keyword.
Example: "/realms/root/realms/customers/realms/europe".

customDomainUrl

https://id.mycompany.com

Specifies a custom domain that can be used for domain specific requests such as "/.well-known/assetlinks.json".

cookieName

iPlanetDirectoryPro

Specifies the name of the session cookie for AM sessions.

Change the default variable value as a security best practice.

loginJourney

Login

Specifies the authorization journey name to use.

See Login.

redirect_uri

https://httpbin.org/anything

Specifies the URI to which the OAuth 2.0 client will redirect the user upon a successful authentication request.

postmanAdminClientId

postmanAdminClient

Specifies the username to be used for the OAuth 2.0 administrative client.

postmanConfidentialClientId

postmanConfidentialClient

Specifies the username to be used for the OAuth 2.0 private client.

postmanPublicClientId

postmanPublicClient

Specifies the username to be used for the OAuth 2.0 public client.

postmanAdminUsername

postmanAdminUser

Specifies the username to be used for the OAuth 2.0 managed admin user

This is the username you set up in Preparing your Identity Cloud.

postmanDemoUsername

postmanDemoUser

Specifies the username to be used for the OAuth 2.0 managed realm user.

postmanDemoEmail

demo.user@postman.example.com

Specifies the email to be used for the OAuth 2.0 managed realm user.

Using the collection

Before using the Identity Cloud Postman collection, you should run the Prerequisite requests. The requests configure your 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 Configuring the collection before running the prerequisite requests.
  1. In Postman, with the 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 will set a global variable containing a value returned in the response, for use in subsequent requests.

    The details of these can be seen 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, Identity Cloud will contain the following:

  • Three OAuth 2.0 clients:

    1. A client named postmanAdminClient, which provides an access token that can be used to administer the Alpha realm.

    2. A client named postmanConfidentialClient, which is used by the OAuth 2.0 requests to demonstrate a number of grant flows.

    3. A client named postmanPublicClient, which is used by the OAuth 2.0 requests to demonstrate a number of grant flows.

  • Two "alpha_user" identities:

    1. A postmanAdminUser identity, which connects to the postmanAdminClient in order to perform realm administration requests.

    2. A postmanDemoUser identity, which demonstrates a number of user-related endpoints, such as identity profiles, and user self-service.

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.

Note that intelligent access and identity profiles have additional functionality. See 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 ForgeRock 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:

Table 2. 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. See 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. Get Users' ID".

The result is stored in the demoUserId global variable.

Overview

To help you integrate your Android apps with Identity Cloud, you can upload an Android assetlinks.json to your Identity Cloud environment. The assetlinks.json file lets your website declare an association with your Android apps.

To upload the file, use the the /.well-known/assetlinks.json endpoint in the REST API. The endpoint is accessed using a custom domain.

Make sure that you have already set up a custom domain for each environment and realm where you need to upload an Android assetlinks.json file.
  1. Get an access token for the realm that is using the custom domain. See Get an access token.

  2. Upload or replace the assetlinks.json file:

    Show request
    $ curl \
    --request PUT 'https://<custom-domain-fqdn>/.well-known/assetlinks.json' \(1)
    --header 'Authorization: Bearer <access-token>' \(2)
    --header 'Content-Type: application/json' \
    --data-raw '[(3)
      {
        "relation": [
          "delegate_permission/common.handle_all_urls",
          "delegate_permission/common.get_login_creds"
        ],
        "target": {
          "namespace": "web",
          "site": "https://id.mycompany.com"
        }
      }
    ]'
    1 Replace <custom-domain-fqdn> with your custom domain, for example id.mycompany.com.
    2 Replace <access-token> with the access token.
    3 Replace the example assetlinks.json JSON content with your own JSON content.
    Show response
    [
        {
            "relation": [
                "delegate_permission/common.handle_all_urls",
                "delegate_permission/common.get_login_creds"
            ],
            "target": {
                "namespace": "web",
                "site": "https://id.mycompany.com"
            }
        }
    ]
An access token is not needed to to view the assetlinks.json file as it is publicly accessible.
  1. View the assetlinks.json file using a GET request:

    Show request
    $ curl \
    --request GET 'https://<custom-domain-fqdn>/.well-known/assetlinks.json'(1)
    1 Replace <custom-domain-fqdn> with your 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. Get an access token for the realm that is using the custom domain. See Get an access token.

  2. Delete the assetlinks.json file:

    Show request
    $ curl \
    --request DELETE 'https://<custom-domain-fqdn>/.well-known/assetlinks.json' \(1)
    --header 'Authorization: Bearer <access-token>' \(2)
    1 Replace <custom-domain-fqdn> with your custom domain, for example id.mycompany.com.
    2 Replace <access-token> with the access token.
    Show response
    [
        {
            "relation": [
                "delegate_permission/common.handle_all_urls",
                "delegate_permission/common.get_login_creds"
            ],
            "target": {
                "namespace": "web",
                "site": "https://id.mycompany.com"
            }
        }
    ]

ForgeRock REST

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

Add a new resource with HTTP PUT or HTTP POST.

Retrieve a single resource with HTTP GET.

Replace an existing resource with HTTP PUT.

Remove an existing resource with HTTP DELETE.

Modify part of an existing resource with HTTP PATCH.

Perform a predefined action with HTTP POST.

Search a collection of resources with HTTP GET.

Query parameters

ForgeRock 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. For details, refer to 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. For details, refer to 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 ForgeRock 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.

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. For details, refer to 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.

_queryId=identifier

Specify a query by its identifier.

Specific queries can take their own query string parameter arguments depending on the implementation.

_sortKeys=[+-]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.

HTTP status codes

When working with a ForgeRock 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.

Identity Cloud deep dives

Selected pages from across all ForgeRock Product Documentation

icon am Access Management

Provides infrastructure for managing users, roles, and access to protected resources.

Intelligent Authentication
•   Multi-factor authentication
•   Web and Java Policy Agents for SSO
•   ForgeRock authenticator application

Authorization
•   Authorization and policy decisions
•   Web and Java Policy Agents for enforcement
•   Transactional authorization
•   Dynamic OAuth 2.0 authorization

Federation
•   SAML v2.0
•   Introduction to SAML v2.0
•   Configure IdPs, SPs, and CoTs
•   Implement single sign-on and single logout

 
•   OpenID Connect 1.0
•   OAuth 2.0
•   Dynamic OAuth 2.0 authorization

icon idm Identity Management

Reconciles customer identity data to ensure accurate information across disparate resources within an organization.

Identity Synchronization
•   Synchronization types
•   Connector reference

User Self-Service
•   User self-service overview

Identity Lifecycle and Relationships
•   Synchronization
•   Managed objects
•   Relationships between objects
•   Roles
•   Use assignments to provision users

Social Identity
•   Social authentication

20 Edge Security

Integrates web applications, APIs, microservices, Internet of Things devices, and cloud-based services with the ForgeRock Identity Platform.

Identity Gateway
•   Studio
•   Single sign-on and cross-domain single sign-on
•   Get login credentials from data sources
•   Get login credentials from AM
•   Enforce policy decisions from AM
•   Harden authorization with advice from AM
•   Validate certificate-bound access tokens
•   Financial-grade API (FAPI)
•   Throttle requests to protected applications
•   Proxy WebSocket traffic

Federation using Identity Gateway
•   Act as an OpenID Connect relying party
•   Act as an OAuth 2.0 resource server
•   SAML 2.0 single sign-on and federation
•   Transform OIDC ID tokens into SAML assertions

Microservices Security
•   Token validation microservice

Beyond Identity Cloud docs

Identity Cloud how-tos

Your Tenant

•   Monitor uptime status

•   Monitor system performance

•   Monitor users and engagements

•   View tenant settings

•   Audit and debug logs

•   Edit your tenant administrator profile

•   Manage tenant administrator 2-step verification (MFA)

•   Invite tenant administrators

•   Activate/deactivate/delete tenant administrators

•   Configure a realm

•   Override realm authentication attributes

•   Switch realms

•   Create a custom domain name

•   Localize the end-user and login UIs

•   Customize the end-user and login UI themes

•   Promote configuration changes

Applications

•   Determine your application type

•   Register an application or service

•   Configure CORS Support

•   Create a client profile

•   Manage password policy

•   Integrate policy agents

•   Test SAML2 SSO using JSP flows
 

Connections  

•   Connect to an identity resource server

•   Create a connector configuration over REST

•   Bulk import identities

Identities

•   Manage organizations

•   Create a user profile

•   Edit a user profile

•   Reset a user password

•   Create an external role

•   Create an internal role

•   Create an assignment

•   Edit an assignment

•   Bulk import identities

•   Optimize identity search
 

Email Templates  

•   Default email templates

•   Configure your own email service provider

•   Create a new email template

Journeys

•   Create a login journey

•   Deactivate the end-user profile page

•   Configure device profile authentication

•   Create a registration journey

•   Create a progressive password journey

•   Create an update password journey

•   Create a reset password journey

•   Create a forgotten username journey

•   Create a custom journey

•   Set the default end-user journey

•   Monitor journey outcomes
 

Policy  

•   Configure a password policy

FAQs

•    How do I get the organization model in my Identity Cloud environment?

•    How do I create and manage scripts?

•    How do I create and set secrets?

•    How do find IDM & AM user properties?

•    How do I configure CORS Support?

•    Where can I find the allow-list IP addresses Identity Cloud uses?

•    How do I search in only Identity Cloud Docs?

Support

•   Submit a Support ticket

•   Access Support Services

•   Promote configuration changes

Supported browsers

Browser Version

Google Chrome and Chromium

Latest stable version

Firefox

Latest stable version

Safari

Latest stable version

Microsoft Edge

Latest stable version

While ForgeRock Identity Cloud works with all supported browsers, administrative activity works best using Google Chrome.

Click here for legal information about product documentation published by ForgeRock.

About ForgeRock Identity Platform software

ForgeRock Identity Platform serves as the basis for our simple and comprehensive identity and access management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, refer to https://www.forgerock.com.

The platform includes the following components:

  • ForgeRock® Access Management (AM)

  • ForgeRock® Identity Management (IDM)

  • ForgeRock® Directory Services (DS)

  • ForgeRock® Identity Gateway (IG)

Third-party copyrights

FontAwesome

Copyright © 2017 by Dave Gandy, https://fontawesome.com/. This Font Software is licensed under the SIL Open Font License, Version 1.1. Refer to https://opensource.org/license/openfont-html/.

Security and compliance

Overview

The ForgeRock Identity Cloud provides full tenant isolation in a multi-tenant cloud service by using individual trust zones. Every 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 & compliance

  • Find our ISO 27001 certificate in the Schellman Certificate Directory.

    • To view the certificate, go to the Shellman certificate directory, and then search for ForgeRock.

    • To download the ForgeRock certificate, click this link: https://zpr.io/RUTE2.
      The direct link to the certificate is obsolete when a newer version becomes available. If the direct link doesn’t work, then use the main certificate directory search.

  • Refer to our CSA CIAQ certification.

  • Refer to how ForgeRock supports HIPAA compliance.

  • Refer to how ForgeRock can help with GDPR.

Security white paper

Learn more about our security practices in our security white paper.

Identity Cloud product lifecycle and releases

ForgeRock Identity Cloud releases new features, updates functionality and fixes bugs on a continual cadence. ForgeRock 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 ForgeRock 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.

Migration dependent features

Features are not backward compatible and require a tenant migration before they can be used. Refer to Migration dependent features.

General availability

Features are available for production use and are fully functional and supported. They are available to all customers.

Bug fixes and low impact changes

On an ongoing basis, ForgeRock makes bug fixes and low impact changes as necessary to 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

In order to maintain both security and quality in ForgeRock Identity Cloud, we periodically have to modify or remove functionality.

Refer to the list of 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/or migration recommendations where available.

Deprecation notification

Deprecation information is posted to the ForgeRock Identity Cloud documentation. Deprecation notices typically include a date that the feature or behavior will reach end of life. Our policy is to flag a feature for deprecation with at least twelve (12) months advance notice prior to end of life whenever possible, in order to allow a twelve (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?

ForgeRock is making 2-step verification mandatory for all 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 Identity Cloud deprecation and end of life policy.

idcloudui tenant administrator set up 2 step verification skip deprecated

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 (Saturday, February 3, 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 Identity Cloud APIs, it must be updated to use a service account to get an access token.

Once 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 Identity Cloud APIs to use a service account. Refer to How do I prepare my tenants to support 2-step verification?.

  2. Go to the Backstage website, and click Support > Tickets.

  3. On the support tickets page, click New Ticket.

  4. On the New Ticket page, choose Identity Cloud: Config Request.

  5. On the Identity Cloud: Config Request page, provide the following information:

    • Hostname(s)

      • Enter a comma separated list of FQDNs for your development, staging, and production tenant environments, and any sandbox tenant environments.

    • What would you like to do?

      • Select Enforce 2-step verification for tenant administrators

  6. Click Submit to create the support ticket.

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

How is application management changing?

ForgeRock has improved application management by introducing a single UI interface to the Identity Cloud admin UI that manages all aspects of an application relevant to Identity Cloud. This replaces the previous arrangement, which required a combination of actions across the Identity Cloud admin UI, AM admin UI, and IDM admin UI. In addition, ForgeRock 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.

Does this affect any other features?

Yes. If you have not upgraded your tenant, event hooks are not available for application identities.

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?

ForgeRock has introduced a group identity to 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; refer to 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?

Refer to Group management.

Deprecation notices

For information about the Identity Cloud product lifecycle and deprecation, refer to Deprecation and end of life.

Skip option for 2-step verification registration for Identity Cloud tenant administrators

Notification date

February 3, 2023

Skip option for 2-step verification registration for Identity Cloud tenant administrators

ForgeRock has deprecated the option to let Identity Cloud tenant administrators skip 2-step verification. Customers can continue to use the skip option in their tenants, but this functionality will be removed from Identity Cloud on February 3, 2024. Refer to Tenant administrator mandatory 2-step verification FAQ.

End-of-life date

February 3, 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

Marketplace

The ForgeRock Marketplace lets you quickly and easily extend the capabilities of the ForgeRock Identity Platform by integrating third party services into your applications or user journeys. Identity Cloud provides a subset of Marketplace integrations out of the box in your environment.

Your Identity Cloud tenant provides the following Marketplace nodes. You can find them under the Marketplace header in the Identity Cloud admin UI’s drag-and-drop user journey editor.

Integration Use case

Integrate with BioCatch scoring for identity proofing, continuous authentication, and fraud protection. The BioCatch platform develops behavioral biometric profiles of online users to recognize a wide range of human and non-human cybersecurity threats including malware, remote access trojans (RATs), and robotic activity (bots).

Use Duo’s solution for adaptive authentication, bring your own device (BYOD) security, cloud security, endpoint security, mobile security, and two-factor authentication.

Integrate with the Daon IdentityX platform for MFA with mobile authentication or out-of-band authentication using a separate, secure channel.

Integrate an Onfido check for identity verification, matching a user with their official identification documents.

Leverage Twilio for second factor authentication during new account or sign on scenarios.

Check this list periodically as we continue to expand our integrations.

For details on developing and troubleshooting journeys, refer to:

Release notes

Overview

ForgeRock continuously provides GA releases to Identity Cloud to introduce new features, fix known issues, and address security issues.

These GA releases are delivered through release channels:

Code freezes

There will be code freezes on the regular release channel for the following dates:

  • Tuesday, November 21, 2023–Wednesday, November 29, 2023

  • Thursday, December 14, 2023–Monday, January 8, 2024

During a code freeze, ForgeRock only makes critical updates.

Release channels

Rapid channel

If you have a sandbox 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 Identity Cloud implementation. It also lets ForgeRock 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, staging, and production environments.

For early access to documentation about features in the rapid channel, refer to Rapid channel features.

Regular channel (default)

Only established GA releases are deployed to your development, 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[1].

Hotfixes

In general, ForgeRock applies critical hotfixes to both the rapid and regular channels.

On occasion, ForgeRock may apply hotfixes, as necessary, to the rapid channel only. These hotfixes will be released to the regular channel at a later time.

Further information

  • Learn more about release lifecycles.

  • Subscribe to release notifications:

    1. Go to Backstage notification settings.

    2. Scroll down to Documentation Digests.

    3. Check the Identity Cloud Rapid Channel Changelog checkbox.

    4. Check the Identity Cloud Regular Channel Changelog checkbox.

  • Find support or submit an issue:

    1. Go to Backstage support tickets.

    2. Click New Ticket.

    3. Choose How Do I…​?.

 

Regular channel changelog

Subscribe to get automatic updates: Regular channel changelog RSS feed

Refer to the Changelog archive for release notes published before 16 Sep 2022.

15 Mar 2023

Key features

Improved access to reconciliation logs in Identity Cloud

You can now view IDM reconciliation logs in your tenant by updating your audit configurations and specifying the log source idm-recon in a call to the logging API endpoint.

For more information, refer to Update audit configuration.

Resolved issues

Issue ID Summary

FRAAS-14276

Let administrators add idm-recon as a log source for pulling reconciliation audit activity

IAM-3669

Adjust drop-down lists to show the value of the selected option in the form

14 Feb 2023

Key features

Application promotions

You can now use the UI to promote applications between tenant environments. Promoted applications are recreated in the upper environment with any associated static configuration (connectors, mappings, or SAML configuration) and any associated dynamic configuration (OAuth 2.0 clients).

Resolved issues

Issue ID Summary

FRAAS-7542

Control access to hosted account and journey pages

FRAAS-11599

Don’t allow changes to scripts in staging and production environments

FRAAS-13464

Adjust sandbox environment migration to not use development environment migration steps

FRAAS-13809

Autonomous log filters fail in connected environments

IAM-2725

Adjust input field placeholders to clear properly when a user starts typing

IAM-3084

Only allow unique values when adding application owners

IAM-3141

Add 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

IAM-3512

Access Management native console incorrect redirect URL

OPENIDM-16640

Changes to identity objects by onUpdate scripts not triggering relationship property onRetrieve hooks

03 Feb 2023

Key features

Deprecate skip option for tenant administrator MFA

ForgeRock has deprecated the option to let Identity Cloud tenant administrators skip 2-step verification. Customers can continue to use the skip option in their tenants, but this functionality will be removed from Identity Cloud on February 3, 2024.

Resolved issues

Issue ID Summary

FRAAS-9679

Deprecate skip option for tenant administrator MFA

31 Jan 2023

Key features

Service accounts

You can now use service accounts to request access tokens for most 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

Issues marked with an asterisk (*) were inadvertently excluded from the rapid channel changelog.
Issue ID Summary

FRAAS-13478

Remove unrelated AM root realm changes from promotion reports

FRAAS-13519

Remove unexpected file changes from self-service promotion reports

FRAAS-13620

Improve performance of promotion report generation by removing unrelated data

FRAAS-8477

Service accounts

IAM-1939

Fix hCaptcha support in Platform UI

IAM-2025*

Add Uncategorized to the journey category filter

IAM-2224

Replace bullets with checkmarks when validating password policy

IAM-2305*

Add support for localized logos in end-user UI

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-3091*

Fix localized headers rendering as [object Object]

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

Fix font weight of the title text on provisioning tab

IAM-3139*

Fix Revoke button in Users & 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-3145

Fix Active Directory assignment on array attributes to be a merge and not replace

IAM-3146*

Update user-specific attributes to be editable by administrators

IAM-3177

Add paging back to application list view if workforce feature is not enabled

IAM-3257*

Fix escaping of ESV placeholders in the advanced email editor

IAM-3335

Fixed display of localized favicon

19 Jan 2023

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.

Resolved issues

Issues marked with an asterisk were inadvertently excluded from the rapid channel changelog.
Issue ID Summary

AME-22948*

Create endpoint to log out sessions based on user identifier

FRAAS-11964

Avoid potential performance degradation when removing expired token state

FRAAS-12140

Integrate BioCatch authentication journey nodes

FRAAS-13242

Improve invalid page size error message

OPENAM-13766*

No configuration found for log in with session condition advice deny

OPENIDM-17392

Prevent script typos that cause services to fail from being introduced into the system

OPENIDM-17664

LDAP connector has invalid configuration when whitespace added to Base DN

OPENIDM-17953

Support email addresses that contain non-ASCII UTF-8 characters

12 Jan 2023

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

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.

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.

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.

Resolved issues

Issues marked with an asterisk were inadvertently excluded from the rapid channel changelog.
Issue ID Summary

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

FRAAS-11158*

AM cache outdated during restart of Identity Cloud services

FRAAS-11574

Integrate Daon authentication journey nodes

FRAAS-11575

Integrate Onfido authentication journey nodes

FRAAS-11964

Avoid potential performance degradation when removing expired token state

FRAAS-12477

Add list of encrypted secrets to promotion reports

FRAAS-12492*

Add classes to the scripting allow list

FRAAS-12494

Unlock the environment and stop checking progress after successfully promoting an environment

FRAAS-12545

Remove the option to keep orphaned configuration nodes from the promotions API

FRAAS-12552

Add redirect for custom domain login screen

FRAAS-12713

Promotions API failed to generate a report

FRAAS-12917*

Email invites to sandbox tenant administrators sometimes do not work

FRAAS-12939

Add proxy state to output of lock state endpoint for promotions API

FRAAS-12988

Prevent placeholder support being enabled unless a specific migration flag value is set

FRAAS-13057

Add only standard placeholders (not user-defined placeholders) prior to enabling placeholder management

FRAAS-13082*

Provisional report endpoint can return 500 if requested repeatedly before cache is built

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

IAM-2658

Application management improvements

OPENAM-19485

Access multi-tenant social providers without requiring multiple secondary configurations

OPENIDM-17556

Ensure RDVPs are not erased for all types of managed objects for all types of PUT operations

OPENIDM-17616*

Add support for direct assignments

OPENIDM-18024*

Implement weighted assignments

OPENIDM-18037*

Create endpoint for aggregating effective assignments and user identity object type outbound mapping values

OPENIDM-18063*

Include Google Apps connector in bundled connectors

OPENIDM-18388*

Do not schedule clustered-recon-resilience jobs for reconById invocations

14 Dec 2022

The following issues were released on November 29th, but inadvertently excluded from the changelog.

Resolved issues

Issue ID Summary

FRAAS-8589

Promotion hangs when waiting for Identity Cloud services

FRAAS-9155

Promotion reports not showing changes for all connectors

FRAAS-11830

Promotion reports rendering new line characters inside JSON strings

FRAAS-11158

Restart of AM can lead to outdated cache

FRAAS-12049

Promotion reports not showing changes to custom endpoint scripts

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

OPENIDM-16830

Speed up search for organizations

OPENIDM-18388

Do not flag reconById invocations as clustered

OPENIDM-18483

Add name field to resourceCollection query fields for group identity objects

02 Dec 2022

Resolved issues

Issue ID Summary

IAM-3102

Validation fails for ESV list type

29 Nov 2022

Key features

Group management

You can now create and manage groups that are shared across AM and IDM within your 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.

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 Identity Cloud analytics dashboard.

Resolved issues

Issue ID Summary

FRAAS-12379

Add support for groups and assigning users to groups

ANALYTICS-25

Add journey ranking and ability to drill down into journey outcomes to the analytics dashboard

09 Nov 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 Introduction to configuration placeholders.

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.

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

Configuration placeholders visible in all APIs in new customer environments

FRAAS-11570

Add Duo authentication node

FRAAS-11571

Add Twilio authentication node

FRAAS-11825

Add translation configuration key for no search results message

FRAAS-12219

Self-service promotions available in new customer environments

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

FRAAS-12625

Handle ESVs as string type if no type is set

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)

05 Oct 2022

Resolved issues

Issue ID Summary

AME-22684

Include grace period configuration in the OAuth2 provider settings

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

Alter AM XUI to display readonly strings wherever placeholders are in use

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

Provide better error message when an LDAP authentication node encounters a TLS connection issue

OPENAM-18933

Do not override the Success URL node’s value

OPENAM-19196

Do not wait for cache timeout before OAuth2 clients reflect changes to Javascript origins

OPENAM-19868

Correctly handle multi-line text in Email Suspend nodes

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)

OPENIDM-18272

Save managed object properties correctly in Identity Management native console

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

Rapid channel changelog

Subscribe to get automatic updates: Rapid channel changelog RSS feed

March 2023

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
ForgeRock® Identity Governance (add-on)

ForgeRock Identity Governance is a new add-on service to ForgeRock 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, making Identity Cloud the authoritative source of truth for user data in your organization.

  • Define and launch certification campaigns.

  • Allow certifiers to review the access users have in applications and decide if the access should be kept (certified) or removed (revoked).

  • Enable managers to review 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

Identity Governance

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