ForgeRock Identity Cloud documentation

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.

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

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

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

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

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

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.

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.

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:

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:

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:

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:

The categories are:

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.

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:

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

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.

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.

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.

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

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

You can set up additional tenant administrators in the same way as you did for your development, staging, and production environments. Refer to Invite tenant administrators.

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

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

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.

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

On your tenant administrator profile page:

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

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

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

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:

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

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:

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

To authenticate to the API, refer to 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:

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:

To apply any pending updates:

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

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.

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:

The following illustration demonstrates the process:

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

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

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

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

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.

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:

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

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

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.

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

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

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.

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

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.

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.

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

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

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

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.

To revert a promotion, submit a support ticket:

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

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.

In the lower environment, the promotions UI lets you:

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.

In the upper environment, the promotions UI lets you:

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.

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.

The process of promoting applications is a UI-only feature. When you run a promotion, the lower environment sends the upper environment a snapshot of the application configuration in the lower environment. Then, when you log into or refresh the Identity Cloud admin UI of the upper environment, the applications are promoted according to the following rules:

For background on viewing changes in the Promotion tab, refer to View changes awaiting promotion to the upper environment.

The Promotion tab also shows a list of all the applications in the environment. This is shown after any static configuration changes and is simply a list of applications (rather than a list of applications that have configuration changes).

For example, in the screenshot below, the UI shows one item of static configuration (a connector associated with the ServiceNow application) and then lists the three applications in the environment:

If you promoted any applications that have associated OAuth 2.0 clients, you can load the dynamic configuration for those OAuth 2.0 clients into the upper environment.

A tenant administrator can manage service accounts in these ways:

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

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

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.

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

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?

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

Example request:

Example response:

Identity Cloud returns the available sources in the result array.

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

Example request:

Example response:

Identity Cloud returns the available log entries in the result array.

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

To tail, or get the latest entries in the stored logs for a source, use the /monitoring/logs/tail endpoint with the source as a parameter.

The first call to the tail endpoint returns log entries from the last 15 seconds. Subsequent calls return log entries in a range that starts from the last returned log entry in the previous result (inclusive) and ends with the latest log entry but one. If calls to the tail endpoint are not frequent enough to match the rate at which the log entries are produced, the result may not include all available log entries.

The format of the log results depends on the source or sources specified in your request. Some sources return only JSON formatted log entries and some sources return only plaintext log entries. Some sources, such as am-everything, can return log entries in both formats.

Example request:

Example response:

You can specify multiple sources in a single call. Example 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:

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

Example response:

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

The benefits of the _queryFilter parameter are:

The _queryFilter parameter takes a URL-encoded filter expression:

To understand how to construct a filter expression, refer to the filter expression rules for _queryFilter. Here are some basic examples:

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?

Identity Cloud supports two email service configuration types:

Use of the MS Graph API email client requires a properly configured Microsoft Azure tenant. The steps for configuring an Azure tenant should be used as an outline, as the specific options, menus, and features may have changed.

In your staging and production tenant environments, configure the email provider to use your own external service: