PingOne Advanced Identity Cloud

About the use case catalog

The use case catalog contains administrator-focused use cases that explain how to configure PingOne Advanced Identity Cloud and select third-party products to meet your organizational needs.

Administration

In PingOne Advanced Identity Cloud, tenant administrators can invite other tenant administrators, promote static configuration changes between environments, monitor their environments, read audit logs, or allow cross-domain service requests (CORS).

The use cases in this section focus on tenant-related administration activities.

Use case Description

Set up administrators

Operate as a super administrator and run tasks to view the tenant settings and invite other administrators on Advanced Identity Cloud.

Read audit logs using REST

Examine audit logs to investigate user behavior, and you use debug logs to investigate system behavior.

Set up administrators

Description

Estimated time to complete: 15 minutes

In this use case, you operate as a super administrator and run tasks to view the tenant settings and invite other administrators on Advanced Identity Cloud.

Goals

After completing this use case, you will know how to do the following:

  • View the tenant settings.

  • Invite other users to be administrators.

Prerequisites

Before you start work on this use case, make sure you have these prerequisites:

  • A basic understanding of:

  • You have received an email from Backstage Support to set up your administrator account for your tenant environments.

  • You have registered your Advanced Identity Cloud account and set up two-step verification in all environments (development, staging, and production).

  • Access to your development environment as an administrator.

  • To test creating a test administrator, an additional email you have access to.

Tasks

Task 1: View tenant settings

  1. In the Advanced Identity Cloud admin UI, open the TENANT menu (upper right), and click Tenant settings. The Tenant Settings page displays.

    Tenant settings detail page

  2. Click Details to display your tenant’s information:

    Field Description

    Tenant name

    Specifies the identifier assigned to the tenant during onboarding and registration. This identifier is not configurable.

    Region

    Specifies the region where your data resides.

    Environment tag

    Describes the type of tenant environment. The possible tags are:

    • Dev: Environment used to build and add new features.

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

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

    • UAT: User acceptance testing (UAT) is a dedicated environment used for testing applications or capabilities with real users before deploying them into production. The UAT and staging environments are used often in parallel to run different usability, stress, and load tests. The UAT environment is an Advanced Identity Cloud add-on capability.

    • Staging: Environment used to test development changes, including stress and scalability tests with realistic deployment settings.

    • Prod: Environment used to deploy applications into operational end-user activity.

    • Other: Environment other than Dev, Staging, or Prod. For example, a demo tenant.

  3. Click Global Settings to view the specific settings:

    Advanced Identity Cloud global settings
    Field Description

    Cookie

    Copy the field value to the clipboard by clicking the icon. The Advanced Identity Cloud tenant cookie is a unique, pseudo-random session cookie for the tenant, generated when your tenant is created. You use the tenant cookie in HTTP headers for Advanced Identity Cloud API requests.

    Cross-Origin Resource Sharing (CORS)

    View the details, add, edit, deactivate, and delete a CORS configuration. CORS provides the ability to integrate web applications in one domain and interact with protected resources in another domain. Learn more in Configure CORS.

    Environment Secrets & Variables

    View the secrets and variables details. Environment Secrets & Variables (ESVs) are configuration variables letting you set values different from your development, staging, and production environments in the Advanced Identity Cloud. Learn more in Introduction to ESVs.

    IP Addresses

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

    Log API Keys

    Use the log API key and secret to authenticate and access the Advanced Identity Cloud REST API endpoints. Learn more in Authenticate to Advanced Identity Cloud REST API with API key and secret.

    Service Accounts

    View, create, edit, activate or deactivate, delete, and regenerate your service account keys. Service accounts let you request access tokens for REST API endpoints. Learn more in Service accounts.

    End User UI

    View and manage your hosted UI pages. Hosted UI pages support customizable themes for your Advanced Identity Cloud end-user UI. Learn more in Advanced Identity Cloud hosted pages.
Check in

At this point, you have:

Viewed your tenant details and global settings.

Task 2: Invite administrators

  1. In the Advanced Identity Cloud admin UI, open the TENANT menu (upper right), and click Invite admins to send invitations to other users to become administrators. You are authorizing them to manage settings in your tenant.

    Invite admins link on the tenant menu
    From the tenant menu, you can add other administrators by clicking Tenant settings > Admins > Invite Admins.

  2. In the Invite Admins dialog box, enter the test user’s email.

  3. Click Tenant Admin to grant privileges to the test user. There are two types of administrator groups on Advanced Identity Cloud:

    • Super Admin: An administrator who has full access to all administrative features and can manage every aspect of this tenant, including adding other administrators.

    • Tenant Admin: An administrator who has full access to all administrative features, except the ability to add other administrators.

  4. Click Send Invitations.
    Advanced Identity Cloud sends an email to the test user’s address containing instructions to register an administrator account.

    Invite others to become an administrator.
Check in

At this point, you have:

Viewed your tenant settings.

Invited a test user to become an administrator.

Validation

You have viewed your tenant settings and invited other users to become administrators. Now, validate adding another administrator by registering and signing on as the additional administrator.

Register test administrator

  1. Access the email of the test administrator.

  2. Click on the email from Advanced Identity Cloud.

  3. Click Complete Registration.

  4. Fill out the fields to register the test administrator.

  5. Click Next.

  6. Select your region of residence, agree to the privacy policy, and click Next.

  7. Click Set up and register for 2-step verification. The Advanced Identity Cloud admin UI displays.

  8. Sign off as the test administrator and sign back on with your original administrator (super admin) account.

Manage other administrators

  1. As the super admin, test deactivating, reactivating, and deleting the test administrator:

  2. Click Tenant Settings.

  3. Click the Admins tab to view the list of administrators.

    When an invited administrator successfully registers, the status column changes from Invited to Active.

  4. Find the test admin. Click the ellipsis icon (), and then click Deactivate.

  5. For the same test admin, click the ellipsis icon (), and then click Activate.

  6. For the same test admin, click the ellipsis icon (), and then click Delete. Then, click Delete on the confirmation dialog. The test admin no longer displays on the list of administrators.

Explore further

Reference material

Reference Description

Administrator settings

Procedures to set your administrator settings.

Tenant environments

Learn about the Advanced Identity Cloud’s tenant environments.

The ForgeRock Authenticator application

Download the ForgeRock Authenticator application to use for MFA.

Read audit logs using REST

Description

Estimated time to complete: 30 minutes

In this use case, you examine audit logs to investigate user behavior, and you use debug logs to investigate system behavior.

Goals

After completing this use case, you will know how to do the following:

  • Retrieve logs

  • Filter log results

  • Tail logs

  • View logs for a specific request

Prerequisites

Before you start work on this use case, ensure that you have these prerequisites:

  • A basic understanding of Advanced Identity Cloud logging sources

  • Access to your Advanced Identity Cloud development environment as a tenant administrator

  • General understanding of how to run commands from the terminal window

  • The curl command installed on your system

Tasks

Task 1: Create an API key and secret, and retrieve log sources

In this task, you create an API key and an API secret in the Advanced Identity Cloud admin UI; you’ll need these values to call the /logs endpoint. Then, you call the /logs/sources endpoint to retrieve log sources.

  1. Get an API key and an API secret:

    1. Log in to the Advanced Identity Cloud admin UI as an administrator.

    2. In the Advanced Identity Cloud admin UI, access the Tenant menu (upper right).

    3. Select Tenant Settings.

    4. Click Global Settings.

    5. On the Global Settings tab, click Log API Keys.

    6. Click + New Log API Key

    7. Provide a name for the key.

    8. Click Create key.

      The UI displays a dialog box containing the new keys:

      Key successfully created message. You have options to copy the api_key_id and api_key_secret.

    9. Copy the api_key_id and api_key_secret values from the dialog box and save them using a text editor. You’ll need to access these two values whenever you make an API call in this use case.

      Store the values in a safe place, and do not share them with anyone else. The API key and API secret values provide access to administrative endpoints in Advanced Identity Cloud.

    10. After you’ve saved the api_key_id and api_key_secret values, click Done.

      You won’t be able to view the api_key_secret value again after you click Done. If you didn’t save this value, you’ll need to repeat the preceding steps to create another API key and secret.

  2. Get your tenant FQDN.

    In the Advanced Identity Cloud admin UI, go to Tenant Settings > Details.

    Your tenant FQDN is labeled Tenant Name.

  3. Advanced Identity Cloud makes browsing the logs easier by storing them in various sources. Learn more about logging sources in the knowledge base article What logging sources are available in Advanced Identity Cloud?

    List the logging sources available in Advanced Identity Cloud:

    1. Open a terminal window.

    2. Run a curl command[3] to list the log sources.

      Specify variables in the curl command as follows:

      • <api-key> — The api_key_id value from step 1

      • <api-secret> — The api_key_secret value from step 1

      • <tenant-env-fqdn> — Your Advanced Identity Cloud tenant FQDN from step 2

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

      The terminal displays output similar to this:

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

  4. Rerun the curl command to list the log sources, but this time, filter the command’s JSON output through the json_pp command[4] to make the output easier to read:

    $ curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
'https://<tenant-env-fqdn>/monitoring/logs/sources' | json_pp
{
   "pagedResultsCookie" : null,
   "remainingPagedResults" : 0,
   "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,
   "totalPagedResults" : 1,
   "totalPagedResultsPolicy" : "NONE"
}

Task 2: Get logs

In this task, you retrieve all available log entries from a log source by calling the logs endpoint. Then you retrieve the tail end of a log source by calling the logs/tail endpoint.

  1. Run a curl command to retrieve the am-authentication log source.

    Specify variables in the curl command as follows:

    • <api-key> — The api_key_id value you got in Task 1

    • <api-secret> — The api_key_secret value you got in Task 1

    • <tenant-env-fqdn> — Your Advanced Identity Cloud tenant FQDN

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

    The curl command displays all available log entries in the am-authentication log source. A query like this one, which usually displays a large amount of log data, is not particularly useful as it is difficult to work with the output without a log analysis tool.

  2. Retrieve the am-authentication log source using the logs/tail endpoint.

    Run a similar curl call, but instead of calling the logs endpoint, call the logs/tail endpoint and filter the output through the json_pp command:

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

    A smaller amount of output displays. Your call may not return any log entries at all if there hasn’t been any recent authentication activity.

    When you call the /logs/tail endpoint without specifying any parameters other than the log source, the call returns log entries from the last 15 seconds of Advanced Identity Cloud activity.

    If the call to the /logs/tail endpoint didn’t return any log entries, log in to the Advanced Identity Cloud admin UI, wait a few seconds for Advanced Identity Cloud to write log entries, and call the /logs/tail endpoint again; several log entries should display.

  3. Call the logs/tail endpoint repeatedly to see changes to a log source since the last time you called the endpoint.

    When you specify the _pagedResultsCookie parameter when calling the logs/tail endpoint, it returns only the changes that have been made to the log source since the last time you called the endpoint.

    In this step, you’ll use the am-everything log source; more entries are written to this log source than to the am-authentication log source:

    1. Retrieve the am-everything log source using the logs/tail endpoint:

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

    2. Review the start of the output from the call to the logs/tail endpoint. You’ll see a value for the pagedResultsCookie key:

         "pagedResultsCookie" : "eyJfc29ydEtleXM...",
   "remainingPagedResults" : -1,
   "result" : [],
   "resultCount" : 0,
   "totalPagedResults" : -1,
   "totalPagedResultsPolicy" : "NONE"
}

    3. Save the pagedResultsCookie key’s value using a text editor. You’ll need this value for subsequent calls to the /logs/tail endpoint.

    4. Retrieve the am-everything log source again using the logs/tail endpoint. This time, specify the _pagedResultsCookie parameter in your curl call so that only the log entries written to the log source since your previous call to the /logs/tail endpoint are displayed:

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

    5. Run the same curl command several times to see the log entries written to the am-everything log source since the call from which you saved the pagedResultsCookie value.

      Additional log entries should be displayed for each call, but the output depends on the level of activity in your Advanced Identity Cloud tenant.

Task 3: Filter log results

In this task, you’ll filter log data using the _queryFilter parameter so that you get a limited amount of log entries from queries. You’ll run a variety of queries to gain experience with filtering.

  1. To formulate query filters, you first need to understand the structure of a log query result so that you can construct a query filter expression:

    1. Run the same query to retrieve the am-authentication log source you ran in Task 2:

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

      If you don’t get any results from your query, log in to the Advanced Identity Cloud admin UI, wait a few seconds for Advanced Identity Cloud to write log entries, and then rerun your curl call. You should get results after doing this.

    2. Examine the value of one of the payload keys the curl command returned. The JSON output should be similar to if not exactly the same as the following; different types of log entries have different JSON objects:

           {
         "payload" : {
            "_id" : "d6741f27-47b2-4047-8c61-09fe846b7d93-70338",
            "component" : "Authentication",
            "entries" : [
               {
                  "info" : {
                     "authLevel" : "0",
                     "displayName" : "MFA Required?",
                     "nodeId" : "6ed9e2ac-bc5a-49b0-ac81-3e33c4ccfa1d",
                     "nodeOutcome" : "Optional",
                     "nodeType" : "ScriptedDecisionNode",
                     "treeName" : "FRSecondFactor"
                  }
               }
            ],
            "eventName" : "AM-NODE-LOGIN-COMPLETED",
            "level" : "INFO",
            "principal" : [
               "pat@example.com"
            ],
            "realm" : "/",
            "source" : "audit",
            "timestamp" : "2023-09-11T18:16:33.923Z",
            "topic" : "authentication",
            "trackingIds" : [
               "d6741f27-47b2-4047-8c61-09fe846b7d93-70286"
            ],
            "transactionId" : "4cbed6e6-6b10-4a06-b978-b95d25b7c254-request-2/0"
         },
         "source" : "am-authentication",
         "timestamp" : "2023-09-11T18:16:33.92361169Z",
         "type" : "application/json"
      }

      You specify JSON keys in log query filter expressions, using a syntax where objects in the JSON hierarchy are separated by forward slashes. In the example JSON output above:

      • The payload object has a nested object named eventName; a query filter to retrieve log entries for a specific log event would compare /payload/eventName to the log event name.

      • The payload object has a nested object named principal; a query filter to retrieve log entries for a specific user (also known as a principal) would compare /payload/principal to the user’s name.

      Learn more about query filter syntax in Filter expressions.

      For examples of query filters, refer to the table in Filter log results.

  2. Run a curl command to retrieve log entries for your authentication activity.

    Specify variables in the curl command as follows:

    • <api-key> — The api_key_id value you got in Task 1

    • <api-secret> — The api_key_secret value you got in Task 1

    • <your-user-id> — The user ID you use to log into Advanced Identity Cloud

    • <tenant-env-fqdn> — Your Advanced Identity Cloud tenant FQDN

    $ curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication' \
--data-urlencode '_queryFilter=/payload/principal eq "<your-user-id>"' \
'https://<tenant-env-fqdn>/monitoring/logs'

    If you don’t get any results from your query, log in to the Advanced Identity Cloud admin UI, wait a few seconds for Advanced Identity Cloud to write log entries, and then rerun your curl call. You should get results after doing this.

  3. Run a curl command to retrieve log entries that indicate you have completed an authentication journey.

    Specify variables in the curl command as follows:

    • <api-key> — The api_key_id value you got in Task 1

    • <api-secret> — The api_key_secret value you got in Task 1

    • <your-user-id> — The user ID you use to log into Advanced Identity Cloud

    • <tenant-env-fqdn> — Your Advanced Identity Cloud tenant FQDN

    $ curl --get \
--header 'x-api-key: <api-key>' \
--header 'x-api-secret: <api-secret>' \
--data 'source=am-authentication' \
--data-urlencode '_queryFilter=/payload/principal eq "<your-user-id>" and /payload/eventName eq "AM-TREE-LOGIN-COMPLETED"' \
'https://<tenant-env-fqdn>/monitoring/logs'

    If you don’t get any results from your query, log in to the Advanced Identity Cloud admin UI, wait a few seconds for Advanced Identity Cloud to write log entries, and then rerun your curl call. You should get results after doing this.

Validation

Now that you’ve had some practice writing API calls to retrieve log entries, you’re ready to validate your skills by retrieving all the log entries for a request to Advanced Identity Cloud.

All log events for an external request to Advanced Identity Cloud, such as authentication, are assigned the same unique transaction ID. Reviewing multiple log entries that a single request generates can be valuable when troubleshooting system behavior.

Steps

In this validation, demonstrate the ability to get a set of log entries for an external request to Advanced Identity Cloud. First, authenticate to the Advanced Identity Cloud admin UI. Then, call the log API to obtain the transaction ID. Finally, run filtered queries to retrieve all the log entries for your authentication.

  1. Log in to the Advanced Identity Cloud admin UI.

  2. Run a curl command to retrieve log entries from the am-authentication log source.

  3. Find one of the log entries for your authentication attempt in the curl command output.

  4. Find the transaction ID in this log record. The key-value pair to locate is similar to this example:

    "transactionId" : "4cbed6e6-6b10-4a06-b978-b95d25b7c254-request-2/0"

  5. Run another curl command to retrieve all the log entries for your transaction from the am-authentication log source.

    You should retrieve multiple log entries.

    Tips:

    • If you use the logs/tail endpoint, you may not get any log entries back. Remember, the logs/tail endpoint retrieves log entries from the only last 15 seconds of Advanced Identity Cloud activity.

    • When constructing your curl command, use /payload/transactionId as the JSON key for your query filter.

  6. Run another curl command to retrieve all the log entries for your transaction from all the log sources.

    Tips:

    • Use the am-everything log source in your curl command.

    • Expect a large number of log entries to be returned in the command output.

Explore further

Reference material

Reference Learning Asset Description

Getting started with the ForgeRock Identity Cloud REST API: Part 8 - Auditing and monitoring

Community

Examples of running Advanced Identity Cloud auditing and monitoring requests using both Postman and curl commands.

What logging sources are available in Advanced Identity Cloud?

Knowledge base

Descriptions of the sources available for audit and debug logging in Advanced Identity Cloud.

How do I set up the PingOne Advanced Identity Cloud app for Splunk?

Knowledge base

Steps for installing, configuring, and using the community-supported PingOne Advanced Identity Cloud app for Splunk, which is available on Splunkbase.

Authentication

Authentication is the act of confirming a user’s identity, for example, by providing a set of credentials.

In PingOne Advanced Identity Cloud, you primarily use journeys to create your authentication flows; However, you can also set up an external application to act as an identity provider.

Since there are many ways to implement authentication based on your needs, use cases vary and can include:

Item Description

Single sign-on (SSO)

SSO lets authenticated users access multiple independent services from a single login session by storing user sessions as HTTP cookies. You can configure Advanced Identity Cloud to let users use SSO with other applications, or let users of other applications use SSO with Advanced Identity Cloud.

This includes creating applications to use popular federation protocols such as SAML and OAuth 2.0/OIDC.

Multi-factor authentication (MFA)

MFA is an authentication technique that requires users to provide multiple forms of identification when authenticating.

MFA provides a more secure method for users to access their accounts with the help of a device.

Pass-through authentication (PTA)

PTA lets you validate passwords with a remote service. This allows you to retain a remote service for authentication or to migrate passwords to Advanced Identity Cloud as part of authentication (just-in-time synchronization).

The use cases in this section focus on authentication:

Use case Description

Login with MFA using push notifications

Authenticate a user with MFA by setting up the ForgeRock Authenticator application for push notification on a smartphone.

Salesforce as SP (SAML)

Configure SSO using SAML federated identities with Advanced Identity Cloud as the Identity provider (IDP) and Salesforce as the Service provider (SP).

Specifically, you configure Advanced Identity Cloud as the IDP for Salesforce using SAML.

Microsoft Entra ID (Azure AD) as OpenID provider

Configure Advanced Identity Cloud to be a relying party (RP), or client, with Microsoft Entra ID (formerly known as Azure AD) as the OpenID provider (IDP).

You also create a journey that lets end users log in to Advanced Identity Cloud optionally using Microsoft Entra ID.

Okta as RP (OIDC)

Configure Okta to be the RP with Advanced Identity Cloud as the IDP.

Pass-through auth (PTA) with Microsoft Entra ID (Azure AD)

Enable pass-through authentication (PTA) to Microsoft Entra ID and let Advanced Identity Cloud capture the Microsoft Entra ID password for future logins.

Login with MFA using push notifications

Description

Estimated time to complete: 30 minutes

In this use case, you authenticate a user with MFA by setting up the ForgeRock Authenticator application for push notification on a smartphone.

Goals

After completing this use case, you will know how to do the following:

  • Set configurations in the AM admin UI, such as configuring a service in Advanced Identity Cloud for push notifications.

  • Capture and validate a username and password.

  • Configure and register an end user’s device with their user profile in Advanced Identity Cloud.

  • Create a journey to enforce MFA at log in.

  • Provide recovery codes to end users if they lose their device.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • A basic understanding of these Advanced Identity Cloud concepts:

    • Realms

    • The AM admin UI

    • Journeys

    • Nodes

    • The Advanced Identity Cloud end-user UI

  • Access to your development environment as an administrator

  • An identity in Advanced Identity Cloud to test the journey (you may need to create this)

  • An Android or iOS smartphone with access to the internet

  • A Backstage account

Tasks

Task 1: Log in and configure the ForgeRock Authenticator Push service

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. In the left menu pane, select Native Consoles > Access Management.

    The realm overview for the Alpha realm displays.

  3. Select Services.

  4. Click + Add a Service.

  5. Create the push service configuration:

    1. Select ForgeRock Authenticator (Push) Service in the service type drop-down list.

    2. Click Create.

    3. Click Save Changes to accept the default settings.

      The default settings don’t encrypt the device metadata stored in user profiles. This use case accepts the default settings for simplicity. Learn more in Configure the ForgeRock Authenticator (Push) service.

Task 2: Create Push service credentials in Backstage

Advanced Identity Cloud uses an external AWS service to send push notifications. Its configuration requires access keys and other metadata. As a Ping Identity customer, you have streamlined access to the required metadata:

  1. In a new tab, log in to Backstage.

  2. In the top right corner, click your profile icon > Profile.

  3. From the left mxenu pane, select Service Credentials.

  4. Under Push Notifications AWS Credentials, click Create.

    The push credentials page in Backstage

  5. In the Description field, enter Push credentials for MFA journey.

  6. Click Create.

  7. Click Download as JSON.

  8. Click Close.

  9. Close the Backstage tab.

Task 3: Configure the Push Notification service in the AM admin UI

  1. Click back to the tab that displays the AM admin UI.

  2. Select Services.

  3. Click + Add a Service.

  4. To configure the Push Notification service, select Push Notification Service in the service type drop-down list.

  5. Open the JSON file you downloaded in step 7.

  6. Enter the fields from the JSON file into the fields that display:

    Don’t enter the quotes that surround the JSON value.
    Field in AM admin UI Field in JSON file Description

    SNS Access Key ID

    accessKeyId

    The generated Key ID; the "accessKeyId" in the JSON.

    SNS Access Key Secret

    accessKeySecret

    The generated Secret; the "accessKeySecret" in the JSON.

    SNS Endpoint for APNS

    APNS

    The generated APNS; the "APNS" in the JSON. Used to send push notifications to the Apple Push Notification Service (APNS).

    SNS Endpoint for GCM

    GCM

    The generated GCM; the "GCM" in the JSON. Used to send push notifications to Android devices using Google Cloud Messaging (GCM).

  7. Click Create.

  8. Click Save Changes.

  9. Close the AM admin UI tab.

  10. Click back to the Advanced Identity Cloud admin UI tab.

Task 4: Create the MFA using push notifications journey

Configure journey options

  1. In the Advanced Identity Cloud admin UI, click Journeys. All existing Advanced Identity Cloud journeys display.

  2. Click + New Journey.

  3. Configure options for the new journey:

    Field Value Description

    Name

    Enter Login with Push MFA

    A name to display in the journeys list.

    Identity Object

    Select Alpha Realm - Users

    The type of object that this journey authenticates.

    Description

    Enter A login journey with MFA using push notifications. This is for the implementation guide.

    Description of the journey.

    Override theme

    Do not enable

    Lets you provide a unique UI for this journey.

    Default journey for end users

    Do not enable

    Lets you designate this journey as the default journey for your Advanced Identity Cloud environment.

    Tags

    Enter Implementation Guide

    Keywords for organizing the journeys list.

  4. Click Save. The journey editor displays.

    To save your progress, periodically click Save in the top right of the journey editor. Failure to do this results in losing your work if the page reloads or if you lose your network connection.
    Journey editor screen
Collect username, password, and validate login on one page

  1. In the top left search bar, enter Page Node.

    A Page node combines multiple nodes that request input into a single page for display to the user. In this case, it allows the username and password boxes to display to the end user on the same page.

  2. Drag the Page Node box from the left side of the journey editor to the right side (the canvas).

  3. Connect the start (person) icon to the Page Node by selecting the icon and dragging it into the left side (input) of the Page Node. An arrow shows the flow of the journey from the person icon into the Page Node.

    When you connect nodes together, the arrows show the flow of the journey from node to node.

  4. Search for the Platform Username node and drag it into the Page Node.

    The Platform Username node prompts the end user to enter their username and stores it in a configurable state attribute.

  5. Search for the Platform Password node and drag it into the Page Node.

    The Platform Password node prompts the end user to enter their password and stores it in a configurable state attribute.

  6. Search for the Data Store Decision node and drag it to the right of the Page Node.

    The Data Store Decision node verifies that the username and password values match those in the data store configured for the realm.

  7. Connect the right side of the Page Node (the outcome) into the left side of the Data Store Decision node (input).

  8. Connect the False outcome of the Data Store Decision node into the Failure node (red X circle).

  9. In the top right of the journey editor, click Save.

When connecting the outcome of a node to another node, make sure there is a hand icon present on the node you’re connecting to.

Click to display an example
Connecting two nodes together
Check in
First stage of the journey completed

At this point, the journey is configured to:

  • a Collect the username and password from the same page

  • b Validate the username and password

The following video demonstrates the steps up to this point in the procedure:

A video displaying the first stage of the journey
Send and verify push notifications

The journey goes down this path when the end user has a device registered with their Advanced Identity Cloud profile.

  1. Search for the Push Sender node and drag it to the right of the Data Store Decision node on the canvas.

  2. Connect the True outcome of the Data Store Decision node to the input of the Push Sender node.

  3. Click the Push Sender node and configure its options:

    Field Value Description

    Message Timeout

    Do not modify.

    Specifies the number of milliseconds the push notification message remains valid.

    User Message

    Do not modify.

    Specifies an optional message to send to the end user on their device.

    Remove ‘skip’ option

    Enable this property.

    Enable this option in the node to make the push authentication mandatory.

    When disabled, the user can skip the push authentication requested by the node and evaluation continues along the Skipped outcome path.

    Share Context Info

    Enable this property.

    Enable this option to include context data, such as remoteIp, userAgent, and location, in the notification payload.

    Custom Payload Attributes

    Do not modify.

    Include shared state objects in the message payload sent to the client. The size of the payload must not exceed 3 Kb or a NodeProcessException is thrown.

    Push Type

    Select Display Challenge Code.

    The type of push authentication the user must perform on their device to continue the journey. Select one of the following types:

    • Tap to accept — Requires the user to tap to accept.

    • Display Challenge Code — Requires the user to select one of three numbers displayed on their device. This selected number must match the code displayed in the browser for the request to be verified.

    • Use Biometrics to Accept — Requires the user’s biometric authentication to process the notification.

    Research shows users might accept a push authentication without fully checking if it’s legitimate. To reduce the chances of a user accepting a malicious push authentication attempt, select Display Challenge Code or Use Biometrics to Accept.
    The push sender node configuration settings

  4. Search for the Push Wait Node and drag it to the right of the Push Sender node in the canvas.

    To let the end user respond to the push notification, the Push Wait node pauses authentication for the specified number of seconds while processing a push authentication request.

  5. Connect the Sent outcome of the Push Sender node to the input of the Push Wait Node.

  6. Search for the Push Result Verifier Node and drag it to the right of the Push Wait Node.

    The Push Result Verifier node works with the Push Sender node to validate the user’s response to a previously sent push notification message.

  7. Connect the Done outcome of the Push Wait Node to the input of the Push Result Verifier Node.

  8. Connect the outcomes of the Push Result Verifier Node to various nodes:

    Outcome path Target node

    Success

    Success node (green check mark)

    Failure

    Failure node (red X)

    Expired

    Push sender node

    Waiting

    Push Wait Node

  9. Click Save.

Check in
The second stage of configuring the journey, completed

At this point, the journey is configured to:

  • a Collect the username and password and present it on the same page.

  • b Validate the username and password.

  • c Send a push notification to the end user’s device.

  • d Validate the push notification.

Register device (smartphone) with Advanced Identity Cloud profile

The journey goes down this path when the Push Sender node goes to the Not Registered outcome, signaling that the end user doesn’t have a device registered with their Advanced Identity Cloud profile.

  1. Search for the Get Authenticator App node and drag it under the Push Sender node.

    The Get Authenticator App node displays information to obtain the ForgeRock Authenticator application from the Apple App Store or the Google Play Store.

  2. Connect the Not Registered outcome of the Push Sender node to the input of the Get Authenticator App node.

  3. Search for the Push Registration node and drag it to the right of the Get Authenticator App node.

  4. Connect the outcome of the Get Authenticator App node to the input of the Push Registration node.

  5. Connect the Failure outcome of the Push Registration node to the Failure node.

  6. Connect the Time Out outcome of the Push Registration node to the Get Authenticator App node.

  7. Click Save.

Check in
The third stage of the journey, completed

At this point, the journey is configured to:

  • a Collect the username and password and present it on the same page.

  • b Validate the username and password.

  • c Send a push notification to the end user’s device.

  • d Validate the push notification sent.

  • e Prompt the user to download the application and register their device if Advanced Identity Cloud doesn’t find a device in the user’s profile.

  • f Validate the push registration.

Add recovery codes and send push notification to the new device

  1. Search for the Recovery Code Display Node and drag it to the right of the Push Registration node.

    If the user’s device is lost, the Recovery Code Display node retrieves generated recovery codes from the transient state and presents them to the user for safekeeping. The codes can be used to authenticate if a registered device is lost or stolen.

  2. Connect the Success outcome of the Push Registration node as input to the Recovery Code Display Node.

  3. Connect the outcome of the Recovery Code Display Node as input to the Push Sender node.

  4. Search for the Recovery Code Collector Decision node and drag it to the right of the Push Wait Node.

    In the event the end user doesn’t have access to or has lost their device, the Recovery Code Collector Decision node lets the end user authenticate with the recovery code provided in the Recovery Code Display node.

  5. Connect the Exit outcome of the Push Wait Node as input to the Recovery Code Collector Decision node.

  6. Connect the True outcome of the Recovery Code Collector Decision node to the Success node.

  7. Search for the Retry Limit Decision node and drag it to the right of the Recovery Code Collector Decision node.

    The Retry Limit Decision node permits the specified number of passes through to the Retry outcome path before continuing evaluation along the Reject outcome path. In this case, it lets the end user reenter their recovery codes up to three times before the journey goes to the Failure node.

  8. Connect the False outcome of the Recovery Code Collector Decision node as input to the Retry Limit Decision node.

  9. Connect the Retry outcome of the Retry Limit Decision node as input to the Recovery Code Collector Decision node.

  10. Connect the Reject outcome of the Retry Limit Decision node to the Failure node.

  11. Click Save. You have now configured the journey successfully.

Check in
The journey completed

The completed journey has the following capabilities:

  • a Collect the username and password and present it on the same page.

  • b Validate the username and password.

  • c Send a push notification to the end user’s device.

  • d Prompt the end user to download the application and register their device if Advanced Identity Cloud doesn’t find a device on the user’s profile. After registering their device, present the end user with recovery codes in the event they don’t have access to or lose their device. Send the user a push notification.

  • e Validate the push notification.

  • f Prompt the end user to enter their recovery codes if a timeout occurs during push notification validation. Allow the end user up to three incorrect entries.

Task 5: Check journey path connections

The MFA using push notifications journey uses many nodes. Use the following table to compare the outcomes of each node and to validate that you wired the journey correctly.

Many nodes can have more than one outcome. "→" denotes that a node only has one outcome path.

Source node Outcome path Target node

Start (person icon)

→

Page Node

Page Node containing:

  • Platform Username

  • Platform Password

→

Data Store Decision

Data Store Decision

True

Push Sender

False

Failure

Push Sender

Sent

Push Wait Node

Not Registered

Get Authenticator App

Push Wait Node

Done

Push Result Verifier Node

Exit

Recovery Code Collector Decision

Push Result Verifier Node

Success

Success

Failure

Failure

Expired

Push Sender

Waiting

Push Wait Node

Recovery Code Collector Decision

True

Success

False

Retry Limit Decision

Retry Limit Decision

Retry

Recovery Code Collector Decision

Reject

Failure

Get Authenticator App

→

Push Registration

Push Registration

Success

Recovery Code Display Node

Failure

Failure

Timeout

Get Authenticator App

Recovery Code Display Node

→

Push Sender

Validation

Now that you have configured the ForgeRock Authenticator push service, the push notifications for Advanced Identity Cloud, and created your journey, you are ready to validate your journey.

Before validating, make sure you have created a test user and have access to an Android or iOS smartphone.

Steps

In the journey you created, there are various paths the end user may go down, depending on their actions and the information in their user profile. For example, if the end user has a device (smartphone) registered with their profile, the journey does not display the page to download the ForgeRock Authenticator application or to register a device. On the other hand, if the end user does not approve the push notification in the specified time (defined in the Push Wait node in the journey), the journey prompts the user to enter a recovery code.

To demonstrate the device registration process and push notification approval, this validation explores the path of an end user who does not have the ForgeRock Authenticator application on their smartphone and does not have a smartphone registered with their user profile in Advanced Identity Cloud.

  1. Get a URL you can use to test the journey:

    1. Log in to the Advanced Identity Cloud admin UI as an administrator.

    2. Select Journeys.

    3. Select the journey you created, Login with Push MFA. A preview screen of the journey displays.

    4. Click the copy icon next to Preview URL, a URL you can use to test a journey as an end user:

      Copying test URL of journey

  2. Log in to Advanced Identity Cloud:

    1. Paste the URL into an incognito window.

      Use incognito mode for testing to avoid caching issues, and so that any current sessions you have don’t interfere with your test.

      The login end-user UI displays.

    2. Enter the test user’s username and password.

    3. Click Next.

      A screen displays prompting you to download the ForgeRock Authenticator application.

  3. Download the ForgeRock Authenticator application:

    1. Click the Apple App Store or Google Play Store link, depending on which smartphone you have.

    2. Download the ForgeRock Authenticator application.

    3. After you have downloaded the ForgeRock Authenticator application, click Continue. A screen displays prompting you to scan a QR code.

  4. Register your user profile with your smartphone and copy recovery codes:

    1. Open the ForgeRock Authenticator application on your smartphone.

    2. Tap the blue + icon in the bottom right corner.

    3. Tap Scan QR Code.

    4. Scan the QR code that displays in your browser window with your smartphone’s. camera.

      A profile displays in the ForgeRock Authenticator application. Verify the test user’s username displays in the account created in the ForgeRock Authenticator application and that recovery codes display in the browser window.

    5. Copy the recovery codes.

      An end user can use recovery codes when they lose their device and need to log in.

    6. Click Done. A push notification is sent to your smartphone.

  5. Approve push notification and finish logging in:

    1. Tap Accept on your smartphone.

    2. Verify the acceptance by using your fingerprint or facial recognition.

      You should now be logged into the Advanced Identity Cloud end-user UI.

  6. Log out of Advanced Identity Cloud end-user UI:

    1. Click the test user’s name in the top right corner of the Advanced Identity Cloud end-user UI.

    2. Select Sign Out.

      You are redirected to a sign-in page. This page differs from the journey you created, Login with MFA Push. The page you are directed to when you sign out is the default journey in the realm. Learn how to set the default journey in "Default end-user journey" in Journeys.

Video of validation

The following video displays the expected validation as an end user registering their device and approving a push notification sent to their phone. The video doesn’t show the end user downloading the ForgeRock Authenticator application.

Explore further

Reference material

Reference Description

Realms

Realms are administrative units that group configurations and identities together.

Realms let you manage different sets of identities and applications within the same Advanced Identity Cloud tenant. Each realm is fully self-contained and operates independently of other realms within a tenant.

Admin interfaces in Advanced Identity Cloud

Get to know the admin interfaces; Advanced Identity Cloud admin UI, AM admin UI, and IDM admin UI.

Journeys

Conceptual information on journeys and their purpose in Advanced Identity Cloud.

Introduction to journeys with ForgeRock University

A guided video of journeys in Advanced Identity Cloud and how to use them.

Nodes for journeys

Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys.

Marketplace nodes for journeys

Integrate third-party services into your applications or journeys with marketplace nodes.

Manage identities

Manage, group, and assign privileges to identities.

Themes

Customize the look and feel of login and end-user UI pages. This is used when you are using the ForgeRock hosted pages as your UI option.

Authenticate using push notification

A more in-depth reference on the configuration properties and the steps to create a journey with push notifications.

Nodes used

The login with MFA using push notifications journey uses many nodes. Learn more about each node using the following list, which orders the nodes as they appear in the journey:

Salesforce as SP (SAML)

Description

Estimated time to complete: 30 minutes.

In this use case, you configure SSO using SAML federated identities with Advanced Identity Cloud as the Identity provider (IDP) and Salesforce as the Service provider (SP).

Specifically, you configure Advanced Identity Cloud as the IDP for Salesforce using SAML. This allows a user from the Advanced Identity Cloud end-user UI, to click the Salesforce application and be logged in to Salesforce with IDP-iniatied SSO.

Goals

After completing this use case, you will know how to do the following:

  • Configure a custom SAML application for SSO using app templates.

  • Configure Salesforce to be a remote SP.

  • Use the Advanced Identity Cloud end-user UI application dashboard to federate to other application.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • A basic understanding of:

    • The Advanced Identity Cloud admin UI

    • SSO (Federation)

    • SAML

    • The Advanced Identity Cloud end-user UI

    • Salesforce

  • Access to your development environment as an administrator.

  • A test Salesforce environment

  • The use case, Provision users to a target application (Salesforce), completed with a test user provisioned from Advanced Identity Cloud to Salesforce. Specifically, make sure the user’s mail attribute in Ping Identity matches the User. Username attribute in Salesforce.

  • A test user in Advanced Identity Cloud to serve as the application owner for the custom SAML (Salesforce) application.

Tasks

This use case requires the use of third-party services. Use your environment specific details where necessary.

Task 1: Create custom SAML application

  1. In the Advanced Identity Cloud end-user UI, go to Applications > add Custom Application.

  2. Select SAML and click Next.

  3. On the Application Details page, enter the following:

    Field Value

    Name

    Enter Salesforce SAML SSO.

    Description

    Enter Ping Identity serving as the IDP for SAML. End users can log into Salesforce from the Advanced Identity Cloud end-user UI, when they are assigned to this application and have an account in Salesforce.

    Owners

    Select a user to be the application owner.

    App Logo URI

  4. From the custom SAML application Salesforce SAML SSO, click the Sign On tab > Set up SSO.

  5. On the Set up Single Sign-On modal window, click download Download Metadata. The metadata to import into Salesforce displays in a new browser tab.

  6. Save this file as identity-cloud-idp-saml-metadata.xml. You will import this file into Salesforce later.

  7. Click Next.

  8. In a new browser tab, go to your Salesforce environment.

Task 2: Configure Salesforce to serve as SP

The next task is to prepare Salesforce to serve as an SP.

  1. Salesforce documents these steps; therefore, in Salesforce’s documentation, Create a SAML Single Sign-On Setting in Salesforce.

    In step 3 of the Salesforce documentation, import the XML file you saved in task 1 by selecting New from Metadata File in Salesforce. The XML file you upload in Salesforce sets the necessary configurations; therefore, you don’t need to complete the steps past step 3.

  2. After configuring SSO in Salesforce, download Salesforce’s SP metadata to import into Advanced Identity Cloud by clicking Download Metadata in Salesforce.

    Salesforce SP SSO settings

    The metadata file name looks similar to SAMLSP-00DDp000001yWwS.xml.

Task 3: Configure custom SAML application

Now that you have configured Salesforce, you must configure the custom SAML Salesforce application in Advanced Identity Cloud to include the information Salesforce requires in the SAML assertion.

  1. Go back to the Advanced Identity Cloud admin UI. You should be on the Set Up Single Sign-On modal window.

    Upload Salesforce SP metadata into Advanced Identity Cloud

  2. Click Browse and upload the SP metadata file you downloaded from Salesforce.

  3. Click Next. The application displays. By default, Advanced Identity Cloud maps the following assertion attributes:

    Name (SAML attribute) Value (attribute in Advanced Identity Cloud) Description

    SSOID

    mail

    Advanced Identity Cloud sends the property of mail (email) as the SAML attribute SSOID.

    User.Email

    mail

    Advanced Identity Cloud sends the property of mail (email) as the SAML attribute User.Email.

    User.ProfileID

    "Standard.User"

    Advanced Identity Cloud sends the static value of Standard.User as the SAML attribute User.ProfileID.

    User.LastName

    sn

    Advanced Identity Cloud sends the property sn (last name) as the SAML attribute User.LastName.

    User.Username

    mail

    Advanced Identity Cloud sends the property of mail (email) as the SAML attribute User.Username.

    By default, the federation identifier is mail to the Salesforce attribute User.Username. Users can change their mail address in Advanced Identity Cloud and doing so breaks their SAML connection to Salesforce. Either make mail immutable in Advanced Identity Cloud, or set a different, immutable attribute as the federation identifier.

    Salesforce supports many SAML assertion formats. For example, you can configure SAML to have a user’s unique identifier in the NameID of the Subject block or in the AttributeStatement block. Refer to Salesforce’s documentation on Example SAML Assertions.
Check in

At this point, you:

Created a custom SAML application in Advanced Identity Cloud for SSO with Salesforce

Configured Salesforce by importing Advanced Identity Cloud’s IDP metadata and exporting Salesforce’s SP metadata file

Configured the custom SAML application in Advanced Identity Cloud by importing Salesforce’s SP metadata

Validation

Now that you created and configured a custom SAML application and configured Salesforce as the SP, validate the configurations by:

  • Adding a user to the application

  • Logging in as the end user to the Advanced Identity Cloud admin UI

  • Federating into Salesforce by clicking the Salesforce application

Steps

  1. From the Advanced Identity Cloud admin UI, go to Applications > Salesforce SAML SSO > Users & Roles tab.

  2. On the people Users tab, click add Add Member.

  3. Add the test user that exists in both Advanced Identity Cloud and Salesforce. The application now displays to the test user in the Advanced Identity Cloud end-user UI.

    Add a user to the custom SAML Salesforce application

  4. In an incognito window, log into the Advanced Identity Cloud end-user UI as the test user.

    The default login URL for end users is the Login journey. In the Advanced Identity Cloud admin UI:

    • Go to Journeys and click the Login journey.

    • In the Preview URL field, click copy (copy).

  5. From the Advanced Identity Cloud end-user UI, click My Applications. The Salesforce SAML application displays.

  6. Click the application. Advanced Identity Cloud redirects you to Salesforce logged in.

    If you receive an error in Salesforce, refer to the Salesforce article Troubleshoot SAML Assertion Errors.

    This article discusses using Salesforce’s SAML validator by providing the SAML assertion Advanced Identity Cloud sends. One way to obtain the SAML assertion is to use the browser plugin SAML tracer.

Video of validation

The following video displays the expected validation as an end user using SSO from the Advanced Identity Cloud end-user UI to log into Salesforce:

Explore further

Reference material

Reference Description

Register a custom SAML app

Instructions on setting up a custom SAML application for SSO.

Implement SSO and SLO

Detailed information on SAML SSO and single logout (SLO).

My applications

Learn about how end users can access applications for SSO in the Advanced Identity Cloud end-user UI.

Configure Salesforce as a SAML SP

Learn how to configure Salesforce as a SAML service provider.

Microsoft Entra ID (Azure AD) as OpenID provider

Description

Estimated time to complete: 45 minutes

In this use case, you configure Advanced Identity Cloud to be a relying party (RP), or client, with Microsoft Entra ID (formerly known as Azure AD) as the OpenID provider (IDP).

You also create a journey that lets end users log in to Advanced Identity Cloud optionally using Microsoft Entra ID.

Goals

After completing this use case, you will know how to do the following:

  • Configure Microsoft Entra ID to be an identity provider (IDP).

  • Configure Advanced Identity Cloud to be a relying party (RP) by delegating authentication to a third party.

  • Create a journey that lets end users log in to Advanced Identity Cloud using either their Microsoft Entra ID credentials or their Advanced Identity Cloud credentials. If no identity exists in Advanced Identity Cloud after a user authenticates with Microsoft Entra ID, complete just in time (JIT) registration based on information returned to Advanced Identity Cloud from Microsoft Entra ID.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • A basic understanding of:

    • Realms

    • The UI under Native Consoles > Access Management

    • Journeys

    • Nodes

    • The Advanced Identity Cloud end-user UI

    • The managed/alpha_user object schema

  • Access to your development environment as an administrator

  • Proficiency in Microsoft Entra ID

  • A Microsoft Entra ID environment with administrator privileges

  • A test identity in Microsoft Entra ID

Tasks

This use case requires the use of third-party services. Use your environment specific details where necessary.

Task 1: Create application in Microsoft Entra ID

Some steps require you to copy information. Paste the information into a text editor to keep track.

  1. Log in to your Microsoft Entra ID environment.

  2. Under Azure services, select App registrations.

    If the resource isn’t present, use the search bar to search for it.

  3. Click + New Registration.

  4. Specify the following values on the Register an application page:

    • Name — Advanced Identity Cloud (OIDC)

    • Supported account types — Select Accounts in any organizational directory (Any Azure AD directory - Multitenant).

    • Redirect URI — Where to redirect an end user after they authenticate with Microsoft Entra ID.

      Select Web and enter the fully qualified domain name (FQDN) of your Advanced Identity Cloud tenant:

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

  5. Click Register.

    Copy the value of Application (client) ID and paste it into a text editor. You’ll need it in a later step.

  6. From the left navigation menu, click Certificates & secrets.

  7. Click + New client secret and enter the following values:

    • Description — Client Secret for Advanced Identity Cloud (OIDC).

    • Expires — Select 180 days (6 months). For the purposes of this use case, six months is sufficient. Ensure you have a change management process in place to update the secrets in Microsoft Entra ID and in Advanced Identity Cloud.

  8. Click Add.

    Copy the secret value from the Value column and paste it into a text editor. You’ll need it in a later step.

Learn more about registering an application in Microsoft’s documentation.

Check in

At this point, you:

Created an application in Microsoft Entra ID for Advanced Identity Cloud to connect to.

Copied the Application client ID.

Created a client secret and copied the secret.

Task 2: Configure Advanced Identity Cloud’s social identity provider service

Because this use case explores the use of Microsoft Entra ID as an additional login option for end users, you must configure the Microsoft social identity provider as follows:

  1. In a new tab, log in to the Advanced Identity Cloud admin UI as an administrator.

  2. In the left navigation pane, select Native Consoles > Access Management.

    The realm overview for the Alpha realm displays.

  3. In the left navigation pane, click Services.

    In the enabled services, check if Social Identity Provider Service is present. If it is, skip to step 7.

  4. Click + Add a Service.

  5. In the Service Types drop-down list, select Social Identity Provider Service.

  6. Click Create.

  7. Ensure the Enabled box is checked.

  8. Click Save Changes to accept the default settings.

  9. Click the Secondary Configurations tab > + Add a Secondary Configuration > Client configuration for Microsoft.

  10. Complete the following fields:

    Fields
    Field Value Description

    Name

    Enter Microsoft Social Login.

    The name of the service.

    Client ID

    Enter the client ID you copied in Task 1.

    For example, 9b6b20d4-36e0-4d13-af17-412f51a6567f.

    Specifies the client_id parameter as described in section 2.2 of The OAuth 2.0 Authorization Framework specification.

    Token Introspection Endpoint URL

    Leave blank.

    The URL to the endpoint handling access token validation, as described in the OAuth 2.0 Token Introspection specification.

    For example, https://oauth2.googleapis.com/tokeninfo.

    Redirect URL

    The redirect URL you entered when creating the application in Microsoft Entra ID. The Redirect URL in Advanced Identity Cloud and the Redirect URI in Microsoft Entra ID must match.

    For example, https://<tenant-env-fqdn>/am.

    The URL to which the identity provider will redirect the user after authenticating, as described in Section 3.1.2 of The OAuth 2.0 Authorization Framework specification.

    Redirect after form post URL

    Leave blank.

    The URL of a custom login page or application. Advanced Identity Cloud sends the processed form post data related to social login authentication to that URL as the value of the form_post_entry query parameter.

    Scope Delimiter

    Enter a blank space in this field by placing your cursor in the field and pressing the Spacebar.

    Specifies the delimiter used to separate scope values. For example, a blank space or a comma character.

    Most providers use a blank space.

    JWKS URI Endpoint

    Leave blank.

    The URI that contains the public keys of the identity provider. Advanced Identity Cloud uses these keys to verify signatures or to encrypt objects.

    JWT Encryption Algorithm

    If not already selected, select NONE.

    The encryption algorithm supported by the provider that PingOne Advanced Identity Cloud should use to encrypt client authentication JWTs when Client Authentication Method is set to PRIVATE_KEY_JWT, and (OpenID Connect providers only) request JWTs when Request Parameter JWT Option is set to VALUE or REFERENCE.

    If set to NONE, PingOne Advanced Identity Cloud doesn’t encrypt the JWTs. Obtain a list of the supported algorithms from the provider’s .well-known endpoint.

    JWT Encryption Method

    If not already selected, select NONE.

    The encryption algorithm supported by the provider that PingOne Advanced Identity Cloud should use to encrypt the following:

    • Client authentication JWTs when Client Authentication Method is set to PRIVATE_KEY_JWT.

    • (OpenID Connect providers only) Request JWTs when Request Parameter JWT Option is set to VALUE or REFERENCE.

      Used in conjunction with JWT Encryption Algorithm. Obtain a list of supported methods from the provider’s .well-known endpoint.

    Certificate Revocation Checking Options

    Leave blank.

    Specify one or more options to be used by the TLS certificate revocation checking mechanism.

    If you select no options, the default behavior is to enable revocation checking with SOFT_FAIL.

  11. Click Create.

  12. In the Client Secret field, enter the client secret you copied in Task 1.

  13. At the bottom of the page, click Save Changes.

    The properties under the UI Config Properties section set the Microsoft logo and branding that displays to the end user when they select to authenticate with Microsoft.

    The default settings use the Microsoft logo and branding. Change them if necessary.

The Transform Script field with the value of Microsoft Profile Normalization is a Groovy script that transforms attributes received from Microsoft into attributes Advanced Identity Cloud can digest.

This use case doesn’t require you to update this script; however, if needed, you can update the script:

  1. Under Native Consoles > Access Management, select Scripts.

  2. In the filter box above the Name column, enter Microsoft Profile Normalization.

  3. Select Microsoft Profile Normalization to view the Groovy script and make changes.
Check in

At this point, you:

Created an application in Microsoft Entra ID for Advanced Identity Cloud to connect to.

Copied the Application client ID.

Created a client secret and copied the secret.

Configured Microsoft Entra ID to be a social identity provider in Advanced Identity Cloud.

Task 3: Create a social authentication journey

In this task you create a journey that allows the end user to log in locally (using their Advanced Identity Cloud credentials) or log in socially using SSO (through Microsoft Entra ID).

After you set up the journey, it includes the following capabilities:

Flowchart of the different paths that can be taken in the social authentication journey
Configure journey options

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

    All existing Advanced Identity Cloud journeys display.

  2. Click + New Journey.

  3. Configure options for the new journey:

    Field Value Description

    Name

    Enter Social authentication with Microsoft.

    A name to display in the journeys list.

    Identity Object

    Select Alpha Realm - Users.

    The type of object that this journey authenticates.

    Description

    Enter A login journey that allows end users to log into the end user UI locally or with Microsoft. This is for the implementation guide..

    Description of the journey.

    Override theme

    Don’t enable.

    Lets you provide a unique UI for this journey.

    Default journey for end users

    Don’t enable.

    Lets you designate this journey as the default journey for your Advanced Identity Cloud environment.

    Tags

    Enter Implementation Guide.

    Keywords for organizing the journeys list.

  4. Click Save. The journey editor displays.

    To save your progress, periodically click Save in the top right of the journey editor. Failure to do this results in losing your work if the page reloads or if you lose your network connection.
    The journey editor screen
Collect and validate user credentials locally

  1. In the top left search bar, enter Page Node.

    A Page node combines multiple nodes that request input into a single page for display to the user. In this case, Advanced Identity Cloud displays the username and password boxes on the same page.

  2. Drag the Page Node box from the left side of the journey editor to the right side (the canvas).

  3. Connect the Start (person) icon to the Page Node by selecting the icon and dragging it into the left side (input) of the Page Node. An arrow shows the flow of the journey from the person icon into the Page Node.

  4. Search for the Platform Username node and drag it into the Page Node.

    The Platform Username node prompts the end user to enter their username and stores it in a configurable state attribute.

  5. Search for the Platform Password node and drag it into the Page Node.

    The Platform Password node prompts the end user to enter their password and stores it in a configurable state attribute.

  6. Search for the Data Store Decision node and drag it to the right of the Page Node.

    The Data Store Decision node verifies that the username and password values match those in the data store configured for the realm.

  7. Connect the right side of the Page Node (the outcome) into the left side of the Data Store Decision node (input).

  8. Connect the True outcome of the Data Store Decision node into the Success node (green circle).

  9. Connect the False outcome of the Data Store Decision node into the Failure node (red X circle).

  10. In the top right of the journey editor, click Save.

When connecting the outcome of a node to another node, make sure there is a hand icon present on the node you’re connecting to.

Click to display an example
Connecting two nodes together
Check in
First stage of the journey completed

At this point, the journey is configured to:

  • a Collect the username and password from the same page.

  • b Validate the username and password.

Add Microsoft as identity provider

The next step in the journey is to:

  • Update the page node description to provide more information to the end user on login.

  • Add Microsoft as an option for the end user to choose when authenticating.

  • Upon successful redirect back to Advanced Identity Cloud, verify if the account (identity) exists in Advanced Identity Cloud.

To add Microsoft as an authentication provider:

  1. Click the Page Node.

  2. In the Page Node configurations under Page Description, click +.

  3. Click + Add and enter the following:

    Field Value Description

    Key

    Enter en.

    The locale of the text to display. You can add multiple locales. The locale set in the end user’s browser determines the locale presented in the journey.

    Description

    Enter Enter your login credentials or log in with Microsoft..

    Custom text that displays to the end user when the journey goes through the Page node.

  4. Click Done and then Save.

  5. Search for the Select Identity Provider node and drag it into the Page Node.

    The Select Identity Providers node presents the user with a list of configured, enabled, social identity providers to use for authentication.

  6. Click the Select Identity Provider node, and in the Filter Enabled Providers field on the right side of the screen, enter Microsoft Social Login.

    By default, the node displays all identity providers marked as Enabled in the Social Identity Provider Service as a selectable option. Specify the name of one of more providers to filter the list.

    View the names of your configured social identity providers in Native Consoles > Access Management > Realms > Realm name > Services > Social Identity Provider Service > Secondary Configurations.

    Don’t change the default properties.

  7. Connect the Local Authentication outcome of the Page Node as input to the Data Store Decision node.

  8. Search for the Social Provider Handler Node and drag it to the right of the Page Node.

    The Social Provider Handler node takes the identity provider the end user selects, in this case Microsoft, from the Select Identity Provider node and attempts to authenticate the user. This node collects relevant profile information from the provider and returns the user to the flow, transforming the profile information into the appropriate attributes.

  9. Configure the properties for the Social Provider Handler node:

    Properties
    Field Value Description

    Name

    Don’t modify.

    Name of the node. The name entered displays in the journey canvas.

    Transformation Script

    Select Normalized Profile to Managed User.

    This script transforms the IdP’s user identity into a normalized user identity that Advanced Identity Cloud can use.

    You can view the script in normalized-profile-to-managed-user.js.

    Username Attribute

    Don’t modify the default value (userName).

    The user identity attribute in Advanced Identity Cloud that contains a user name.

    Client Type

    Don’t modify the default value (BROWSER).

    The client type authenticating to the provider.

  10. Connect the Social Authentication outcome of the Page Node as input to the Social Provider Handler Node.

  11. Connect the Account Exists outcome of the Social Provider Handler Node to the Success node.

  12. Click Save.

Check in
Adding Microsoft as a social login provider and checking if the identity sent back from Microsoft exists in Advanced Identity Cloud

At this point, the journey is configured to:

  • a Display description text on the Page Node screen to inform the end user on the actions they can take, and allow the end user to select between local authentication and social authentication on the Page Node.

    • If the end user selects Microsoft as the social authentication provider, redirect the user to Microsoft to enter their credentials.

    • If the end user decides to authenticate locally, the username and password fields are already displayed.

  • b If the end user selects local authentication, validate the username and password.

  • c If the end user selects social authentication, after they enter their credentials successfully in Microsoft, on redirect back, verify if the identity already exists in Advanced Identity Cloud.

Create identity if not present in Advanced Identity Cloud

If the identity returned from Microsoft Entra ID isn’t present in Advanced Identity Cloud, then Advanced Identity Cloud must create the identity with JIT registration.

This requires that the journey:

  • Check if the attributes in the returned access token from Microsoft Entra ID are enough to create the identity in Advanced Identity Cloud.

    The required attributes to create an identity in Advanced Identity Cloud are set by enabling the required field on properties in a managed object. Learn more about the required property description in Create and modify object types.

    If the required attributes are present, create the identity in Advanced Identity Cloud, create a session for the end user, and log them into the Advanced Identity Cloud admin UI.

  • If the access token from Microsoft Entra ID doesn’t contain enough required information to create the identity, prompt the end user to enter the necessary information. After doing this, create the identity in Advanced Identity Cloud, create a session for the end user, and log them into the Advanced Identity Cloud admin UI.

To create an identity if not present:

  1. Search for the Required Attributes Present node and drag it under thr Social Provider Handler Node.

    The Required Attributes Present node checks the specified identity resource in Advanced Identity Cloud, and determines if all attributes required to create the specified object exist within the shared node state. In this case, these are the attributes that Microsoft sent back to Advanced Identity Cloud.

  2. Connect the No Account Exists outcome of the Social Provider Handler Node as input to the Required Attributes Present node.

  3. In the properties of the Required Attributes Present node, set the value of Identity Resource to managed/alpha_user.

  4. Search for the Create Object node and drag it to the right of the Required Attributes Present node.

    The Create Object node creates a new object in Advanced Identity Cloud based on information collected during authentication, such as user registration.

    Any managed object attributes that are marked as required must be collected during authentication to create the new object. The is why the Required Attributes Present node precedes the Create Object node.

  5. Connect the True outcome of the Required Attributes Present node to the input of the Create Object node.

  6. In the properties of the Create Object node, set the value of Identity Resource to managed/alpha_user.

  7. Connect the Created outcome of the Create Object node to the Success node and the Failed outcome to the Failure node.

  8. Search for the Attribute Collector node and drag it under the Required Attributes Present node.

    The Attribute Collector node collects the values of attributes for use later in the flow; for example, to populate a new account during registration. To reference the attributes, they must exist in the managed object schema.

  9. Connect the False outcome of the Required Attribiutes Present node to the input of the Attribute Collector node.

  10. Configure the properties for the Attribute Collector node:

    Properties
    Field Value Description

    Name

    Don’t modify.

    Name of the node. The name entered displays in the journey canvas.

    Attributes to Collect

    Enter the following attributes:

    • userName

    • mail

    • givenName

    • sn

    You must press Enter after each entry.

    A list of the attributes to collect, based on those in the Advanced Identity Cloud schema for the current identity object.

    For example, to view the properties of alpha_user, from the IDM admin UI, go to Configure > Managed Objects > alpha_user and enter values into this field as they display in the Property Name column.

    All Attributes Required

    Enable.

    When enabled, all attributes collected in this node are required to continue. In this case, all attributes are required because they correspond to the attributes needed by the managed object schema.

    Validate Input

    Don’t enable.

    When enabled, validate the content against any policies specified in the managed object schema for each collected attribute. For example, if you set a policy that the `userName must be in an email format, then the node validates that this policy is met before preceding.

    Identity Attribute

    If not already entered, enter userName.

    The attribute used to identify the object in Advanced Identity Cloud. In this case, the attribute used to reference the identity in the backend.
    Configurations to set in the Attribute Collector Node

  11. Connect the outcome of the Attribute Collector node to the input of the Create Object node.

  12. Click Save. You have now configured the journey successfully.

Check in
The journey completed

The completed journey has the following capabilities:

  • a Display description text on the Page Node screen to inform the end user on the actions they can take, and allow the end user to select between local authentication and social authentication on the Page Node.

  • b If the end user selects Microsoft as the social authentication provider, redirect the user to Microsoft to enter their credentials. After the end user enters their credentials in Microsoft successfully, on redirect back, verify if the identity already exists in Advanced Identity Cloud. If the identity does exist in Advanced Identity Cloud, create a session for the user and log them into the Advanced Identity Cloud end-user UI.

  • c If the user doesn’t exist in Advanced Identity Cloud, check if the required attributes are present to create the identity.

  • d If the required attributes aren’t present, present a screen for the end user to enter the required attributes.

  • e Once the required attributes are present, regardless of if the required attributes were given by Microsoft or entered by the end user, create the identity in Advanced Identity Cloud.

  • f If the end user decides to authenticate locally, the username and password fields are already displayed. If the end user selects local authentication, validate the username and password. Advanced Identity Cloud creates a session for the end user and logs them into the Advanced Identity Cloud end-user UI.

Task 4: Check journey path connections

The Social authentication with Microsoft journey uses many nodes. Use the following table to compare each node’s outcomes and validate that you wired the journey correctly.

Many nodes can have more than one outcome. "→" denotes that a node only has one outcome path.

Source node Outcome path Target node

Start (person icon)

→

Page Node

Page node containing:

  • Platform Username

  • Platform Password

  • Select Identity Provider

Social Authentication

Social Provider Handler Node

Local Authentication

Data Store Decision

Social Provider Handler Node

Account exists

Success

No account exists

Required Attributes Present

Required Attributes Present

True

Create Object

False

Attribute Collector

Attribute Collector

→

Create Object

Create Object

Created

Success

Failed

Failure

Data Store Decision

True

Success

False

Failure

Validation

Now that you have created an application in Microsoft Entra ID, configured Advanced Identity Cloud, and created your journey, you are ready to validate the use case.

Before validating, make sure you have a test user in Microsoft Entra ID that has all the necessary attributes Advanced Identity Cloud requires in its identity:

When you create an identity in Advanced Identity Cloud, you set the required attributes by enabling the required field on properties in a managed object. Learn more about the required property description in Create and modify object types.

  • User Principal Name (UPN)

    Advanced Identity Cloud uses the UPN to create the mail (email) and userName attributes of the identity in Advanced Identity Cloud.

  • Display Name

  • Given Name

  • Surname

The steps in this validation follow a typical flow where Microsoft Entra ID provides the necessary attributes that Advanced Identity Cloud requires to create an identity.

Steps

  1. Get a URL you can use to test the journey:

    1. Log in to the Advanced Identity Cloud admin UI as an administrator.

    2. Select Journeys.

    3. Select the journey you created, Social authentication with Microsoft.

      A preview screen of the journey displays.

    4. Click the copy icon next to Preview URL, a URL you can use to test a journey as an end user.

  2. Authenticate using Microsoft:

    1. Paste the URL into an incognito window.

      Use incognito mode for testing to avoid caching issues so that any current sessions you have don’t interfere with your test.

      The login end-user UI displays.

    2. Click Sign in with Microsoft. The journey redirects you to a Microsoft sign-in page.

    3. Enter the email/UPN of the test user in Microsoft Entra ID.

    4. Click Next.

    5. Enter the password of the test user.

      Microsoft may prompt you to configure MFA or other settings. This depends on the configurations you have set in Microsoft Entra ID.

    6. On the Permissions Requested screen, click Accept. Microsoft is requesting your permission to share the user’s information with Advanced Identity Cloud using the application you created.

      Microsoft redirects you back to Advanced Identity Cloud logged into the Advanced Identity Cloud end-user UI.

      If you receive an error similar to AADSTS500113: no reply address is registered for the application, make sure the Reply URL you configured in Advanced Identity Cloud and in Microsoft Entra ID are the same.

      If you receive the error Session has timed out on redirect to Advanced Identity Cloud, restart the flow. To configure the timeout, go to Native Consoles > Access Management > Authentication > Settings > Trees and set the Max duration (minutes) field.

  3. View created user and logout:

    1. From the left navigation menu, click Profile. View the username of the user in Advanced Identity Cloud. This username correlates to the email/UPN in Microsoft Entra ID.

      Under Social Sign In, view that Microsoft is now a connected application.

    2. Click the test user’s name in the top right corner of the Advanced Identity Cloud end-user UI.

    3. Select Sign Out.

      You are redirected to a sign-in page. This page differs from the journey you created, Social authentication with Microsoft. The page you are directed to when you sign out is the default journey in the realm. Learn how to set the default journey in "Default end-user journey" in Journeys.

    4. Close the incognito window.

For further validation, test the journey with a test user from Microsoft Entra ID that has the Given Name and Surname (sn) blank. The journey prompts you to enter the user information manually, in the event that Microsoft Entra ID doesn’t provide the attributes Advanced Identity Cloud requires to create an identity.

Video of validation

The following video displays the expected validation as an end user authenticating with Microsoft Entra ID:

Explore further

Reference material

Reference Description

Realms

Realms are administrative units that group configurations and identities together.

Realms let you manage different sets of identities and applications within the same Advanced Identity Cloud tenant. Each realm is fully self-contained and operates independently of other realms within a tenant.

Admin interfaces in Advanced Identity Cloud

Get to know the admin interfaces; Advanced Identity Cloud admin UI, AM admin UI, and IDM admin UI.

Journeys

Conceptual information on journeys and their purpose in Advanced Identity Cloud.

Core authentication attributes

Description of fields that relate to authentication settings that apply to the entire realm.

Introduction to journeys with ForgeRock University

A guided video of journeys in Advanced Identity Cloud and how to use them.

Nodes for journeys

Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys.

Themes

Customize the look and feel of login and end-user UI pages. This is used when you are using the ForgeRock hosted pages as your UI option.

Client configuration reference

Reference of the social identity provider service configurations.

Localize login and end-user pages

Learn more about localization (support for languages) with Advanced Identity Cloud hosted (login and end-user UI) pages.

Apply policies to managed objects

Configure policies on properties in a managed object. For example, create a policy on the userName property to be in an email address format.

Nodes used

The Social authentication with Microsoft journey uses many nodes. Learn more about each node using the following list, which orders the nodes as they appear in the journey:

Okta as RP (OIDC)

Description

Estimated time to complete: 20 minutes

In this use case, configure SSO using OIDC with Advanced Identity Cloud as the identity provider (IDP) and Okta as the service provider (SP).

Goals

After completing this use case, you will know how to do the following:

  • Configure Advanced Identity Cloud as an OIDC identity provider

  • Configure Okta as a remote SP

  • Use the Advanced Identity Cloud end-user UI application dashboard to federate to Okta

Prerequisites

Before you start, make sure you have the following:

  • A basic understanding of:

    • The Advanced Identity Cloud admin UI and Advanced Identity Cloud end-user UI

    • SSO (Federation)

    • OIDC

  • Completed the use case Create test users and roles

  • Access to your test Advanced Identity Cloud environment as an administrator

  • Access to an Okta development environment as an administrator

Tasks

This use case requires the use of third-party services. Use your environment-specific details where necessary.

Task 1: Create a custom OIDC application in Advanced Identity Cloud

  1. Log in to the Advanced Identity Cloud admin UI.

  2. In the Advanced Identity Cloud admin UI, go to apps Applications > add Custom Application > OIDC - OpenId Connect > Web.

  3. On the Application Details page, add a web application with the following configuration, and then click Next:

    Field Value

    Name

    okta_client

    Description

    Okta client

    Owners

    App Owner

    App Logo URI

    https://www.okta.com/sites/default/files/Okta_Logo_BrightBlue_Medium-thumbnail.png

  4. On the Web Settings page, add the following configuration, and then click Create Application:

    Field Value

    Client ID

    okta_client

    Client Secret

    Enter a password for the client. Remember the password because you need it to configure Okta.

    The Okta client page is displayed.

  5. On the Okta client page, go to the Sign On tab, add the following configuration, and then click Save:

    Field Value

    Sign-in URLs

    https://<okta-tenant-env-fqdn>/oauth2/v1/authorize/callback

    Grant Types

    Authorization Code

    Scopes

    openid, profile, email

  6. At the end of the General Settings panel, click Show advanced settings, and then Authentication.

  7. Set Token Endpoint Authentication Method to client_secret_post and click Save.

    The configuration should resemble the following examples:

    Add Okta client
    Add Okta client
    Add Okta client
To require Advanced Identity Cloud to ask for consent to share information during authorization flows, deselect Implied Consent.

Task 2: Add Advanced Identity Cloud as an IDP in Okta

Refer to Okta’s documentation on how to Create an app at the Identity Provider.

  1. Log in to the administrator interface for your Okta tenant and go to the Dashboard.

  2. On the Okta Admin Console, click Directory > People > Add person and create a user with the same configuration as a user in Advanced Identity Cloud. This example uses the following user:

    Field Value

    Username

    acruse

    First Name

    alex

    Last Name

    cruse

    Email Address

    alex.cruse@example.com

    I will set password

    Enable

    Password

    Secret12!

    User must change password on first login

    Disable

  3. Select Security > Identity Providers > Add identity providers and add an OpenID Connect IdP provider.

  4. On the Configure OpenID Connect IdP page, add the following configuration, and then click Finish. Leave other fields with the default values:

    Field Value

    Name

    ForgeRock

    IdP Usage

    SSO only

    Scopes

    email, openid, profile

    Client ID

    okta_client

    Authentication type

    Client secret

    Client Secret

    The password created for okta_client in Task 1: Create a custom OIDC application in Advanced Identity Cloud

    Issuer

    https://<tenant-env-fqdn>:443/am/oauth2/alpha

    The port number is required for this property.

    Authorization endpoint

    https://<tenant-env-fqdn>/am/oauth2/alpha/authorize

    Token endpoint

    https://<tenant-env-fqdn>/am/oauth2/alpha/access_token

    JWKS endpoint

    https://<tenant-env-fqdn>/am/oauth2/alpha/connect/jwk_uri

    Userinfo endpoint

    https://<tenant-env-fqdn>/am/oauth2/alpha/userinfo

    If no match is found

    Create new user (JIT)

    Profile Source

    Update attributes for existing users

    The ForgeRock identity provider page is displayed.

  5. (Optional) Select Edit profile and mappings to change the mapping of attributes from Advanced Identity Cloud to Okta.

  6. Enable the ForgeRock identity provider:

    1. On the Okta Admin Console, go to Security > Identity Providers.

    2. On the Routing Rules tab, click Add Routing Rule to redirect requests that meet defined criteria for authentication with Advanced Identity Cloud. The following rule redirects all requests from the example.com domain:

      Field Value

      Rule Name

      PingOne Advanced Identity Cloud

      IF User’s IP is

      Anywhere

      AND User’s device platform is

      Any device

      AND User is accessing

      Any application

      AND User matches

      Domain list on login

      example.com

      THEN Use this identity provider

      ForgeRock

      For other options, learn more in Okta’s documentation.

    3. At the Activate Rule prompt, activate the rule immediately.

      Routing rule
      Check in

      At this point, you:

      Created and configured a custom OIDC application in Advanced Identity Cloud for SSO with Okta

      Configured Okta to redirect requests to Advanced Identity Cloud for authentication. After successful authentication, return the request to Okta.

Validation

Now that you have created and configured a custom OIDC application and configured Okta as the SP, validate the configurations by:

  • Logging in to Okta as an end user

  • Authenticating to Advanced Identity Cloud after redirection

Validate your work with an identity that exists in Advanced Identity Cloud and Okta

  1. In your browser’s privacy or incognito mode, go to your Okta tenant.

  2. Log in as the user you created in Okta. For example, log in as username alex.cruse@example.com.

    Because the username matches the routing rule created in Task 2: Add Advanced Identity Cloud as an IDP in Okta, Okta redirects the request to Advanced Identity Cloud for authentication.

    If something is wrong, the authorization response contains error information to help you resolve the issue.

  3. Log in to Advanced Identity Cloud as the identity you created in Create test users and roles. This example logs in as username acruse password Secret12!.

    If you deselected Implied Consent in Create a custom OIDC application in Advanced Identity Cloud, you are prompted for consent:

    Add new role

  4. Click Allow to give Advanced Identity Cloud consent to access Okta resources.

    After consenting, you are logged in to Okta.

    Success

Validate your work with an identity that exists in Advanced Identity Cloud but not in Okta

  1. In a separate incognito browser, return to your Okta tenant.

  2. In the Okta sign in window, enter the email of a user that exists in Advanced Identity Cloud but not in Okta. For example, enter username bina.raman@example.com created in Create test users and roles.

    Okta redirects the request to Advanced Identity Cloud for authentication.

  3. Log in to Advanced Identity Cloud as a user. For example, log in as username braman password Secret12!.

    After successful authentication, the Okta JIT provisions the user braman based on information in the response and logs them in to Okta.

  4. On the Okta Admin Console, click Directory > People and see that braman@example.com has been provisioned automatically.

Explore further

Reference material

Reference Description

Add users manually

In Okta, manually add users, assign them to apps and groups, and manage their profile.

Create an app at the Identity Provider

In Okta, create a client application to use for authenticating and authorizing users.

link:

Configure identity provider routing rules

In Okta, configure routing rules for each of your Identity Providers or for different combinations of user criteria.

Application management

Set up and manage applications that work with Advanced Identity Cloud.

Pass-through auth (PTA) with Microsoft Entra ID (Azure AD)

Description

Estimated time to complete: 30 minutes

In this use case, you enable pass-through authentication (PTA) to Microsoft Entra ID (formerly Azure AD) and let Advanced Identity Cloud capture the Microsoft Entra ID password for future logins.

Goals

In completing this use case, you will learn how to do the following:

  • Use the Advanced Identity Cloud admin UI

  • Create an authentication journey enabling pass-through authentication for Microsoft Entra ID users provisioned to Advanced Identity Cloud

  • Capture passwords on successful pass-through authentication

Prerequisites

Before you start work on this use case, make sure you have:

  • A basic understanding of:

    • The Advanced Identity Cloud admin UI

    • Journeys

    • Nodes

    • Pass-through authentication

  • Completed the use case to Provision users from Microsoft Entra ID (Azure AD)

  • A test user in Microsoft Entra ID and provisioned in Advanced Identity Cloud with the password to sign in as the test user

  • Access to your Advanced Identity Cloud development environment as an administrator

  • Access to your Microsoft Entra ID tenant environment as an administrator

Tasks

Task 1: Sign on to Microsoft Entra ID as the test user

This confirms you have the test user credentials and the test user is active in Microsoft Entra ID:

  1. Browse to the sign-on page for Microsoft Azure.

  2. Sign on as the test user.

  3. If this is the first time the test user signed on, update the password and record the new password for pass-through authentication.

Do not enable multi-factor authentication for the test user.

For this use case, the test user must be able to authenticate with only a username and password.

Task 2: Confirm the test user account in Advanced Identity Cloud

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Application > Identities > Manage.

  3. Find the Advanced Identity Cloud test user in the list.

    If the test user doesn’t have a Advanced Identity Cloud account yet, provision the account from Microsoft Entra ID.

Check in

At this point, you have:

Signed on as the test user and recorded the credentials.

Confirmed the test user is provisioned in Advanced Identity Cloud.

Task 3: Create a pass-through authentication journey

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Journeys > + New Journey and set at least the following before clicking Save:

    Field Value

    NAME

    PTA with password capture

    Identity Object

    managed/alpha_user

  3. Drag the following nodes onto the journey editor canvas:

    • Page node containing:

      • Platform Username node

      • Platform Password node

    • Data Store Decision node

    • Passthrough Authentication node

    • Identify Existing User node

    • Required Attributes Present node

    • Patch Object node

    • Increment Login Count node

    • Inner Tree Evaluator node

  4. Connect the nodes, clicking Save from time to time to keep your work:

    Pass-through authentication journey layout
    Source node Outcome path Target node

    Start (person icon)

    →

    Page node

    Page node containing:

    • Platform Username node

    • Platform Password node

    →

    Data Store Decision node

    Data Store Decision node

    True

    Increment Login Count node

    False

    Passthrough Authentication node

    Passthrough Authentication node

    Authenticated

    Identify Existing User node

    Missing Input

    Page node

    Failed

    Failure node

    Identify Existing User node

    True

    Required Attributes Present node

    False

    Failure node

    Required Attributes Present node

    True

    Patch Object node

    False

    Increment Login Count node

    Patch Object node

    Patched

    Increment Login Count node

    Failed

    Increment Login Count node

    Increment Login Count node

    →

    Inner Tree Evaluator node

    Inner Tree Evaluator node

    True

    Success node

    False

    Success node

Task 4: Adjust node settings for the journey

Adjust the settings for the specified nodes as follows:

  1. Configure these Page node settings and click Save:

    Field Value

    Page Header

    Key: en, Value: Sign on

    Page Description

    Key: en, Value: This page uses pass-through authentication.

    All other fields

    Accept the default settings, leaving the fields blank.

  2. Configure these Passthrough Authentication node settings and click Save:

    Field Value

    System Endpoint

    The name of the connector for the provisioning application.

    To find the name of the connector:

    1. Log in to the Advanced Identity Cloud admin UI as an administrator.

    2. Select Native Consoles > Identity Management.

    3. On the Identity Management page, select Configure > Connectors.

    4. Find the MSGraphAPI Connector.

      It is named like the application, but the connector name does not include spaces; for example, an application named Microsoft Entra ID has a connector named MicrosoftEntraID.

    Object Type

    Enter User.

    To find the name of the object type:

    1. On the Identity Management page, select Configure > Connector Name > Object Types.

    2. Find the available types in the list.

    Identity Attribute

    Keep userName.

    Password Attribute

    Keep password.

  3. Configure these Identify Existing User node settings and click Save:

    Field Value

    Identifier

    Keep userName.

    Identity Attribute

    Enter userName.

  4. Configure these Required Attributes Present node settings and click Save:

    Field Value

    Identity Resource

    managed/alpha_user

  5. Configure these Patch Object node settings and click Save:

    Field Value

    Patch As Object

    Enable.

    Identity Resource

    managed/alpha_user

    Identity Attribute

    Keep userName.

  6. Configure these Inner Tree Evaluator node settings and click Save:

    Field Value

    Tree Name

    Select ProgressiveProfile.
Check in

At this point, you have:

Signed on as the test user and recorded the credentials.

Confirmed the test user is provisioned in Advanced Identity Cloud.

Prepared a journey and connected the nodes.

Configured passthrough authentication nodes.

Task 5: Adjust password policy settings

When Advanced Identity Cloud updates a password, it checks the password policy to prevent weak passwords. Pass-through authentication has no way of ensuring a remote password is valid according to the Advanced Identity Cloud policy.

Default Microsoft Entra ID password policies don’t necessarily match the default Advanced Identity Cloud password policy. Adjust the Advanced Identity Cloud password policy appropriately to avoid rejecting valid Microsoft Entra ID passwords:

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Security > Password Policy.

  3. Adjust the settings to avoid rejecting valid Microsoft Entra ID passwords.

  4. Click Save.

This changes the password policy for all identities in the realm.

Task 6: Allow public client flows in Microsoft Entra ID

Update the Microsoft Entra ID application Advanced Identity Cloud uses for provisioning. This change allows the Advanced Identity Cloud connector to authenticate to Microsoft Entra ID with the username and password:

  1. Sign in to the Microsoft Entra ID tenant as administrator.

  2. Select Home > App registrations > Microsoft Entra ID application.

  3. In the App registrations page, change Authentication > Advanced settings > Allow public client flows to Yes.

  4. Click Save.

Check in

At this point, you have:

Signed on as the test user and recorded the credentials.

Confirmed the test user is provisioned in Advanced Identity Cloud.

Prepared a journey and connected the nodes.

Configured passthrough authentication nodes.

Aligned password policy settings.

Allowed public client flows in Microsoft Entra ID.

Validation

You are ready to validate the pass-through authentication journey.

Steps

Validate authentication in each of the following ways.

Default login before

Check the user cannot log in to Advanced Identity Cloud. Advanced Identity Cloud doesn’t have the user’s password:

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Journeys > Login and copy the Preview URL.

  3. Paste the URL into an incognito window.

    Use incognito mode for testing to avoid caching issues. No current sessions interfere with your test.

    The login page for the tenant displays.

  4. Log in as the test user.

    Log in fails.

Pass-through authentication

Log in with the user’s Microsoft Entra ID credentials, providing the username and password. After Advanced Identity Cloud verifies the credentials in Microsoft Entra ID, it stores the captured password in the user’s profile:

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Journeys > Pass-through authentication with password capture and copy the Preview URL.

  3. Paste the URL into an incognito window.

    The login page for the pass-through authentication journey displays.

  4. Log in as the test user.

    Behind the scenes, the journey proceeds as follows:

    1. The Data Store Decision node fails to authenticate the user.

    2. The Passthrough Authentication node tests the username and password through the connector to Microsoft Entra ID.

      You provided the correct credentials, so the test succeeds. The node has confirmed the password is valid.

    3. The Identify Existing User node finds the provisioned test user in Advanced Identity Cloud.

    4. The Required Attributes Present node checks the shared node state has the managed/alpha_user attributes needed for a minimally complete user profile.

    5. The Patch Object node updates the test user profile with the required attributes, capturing the valid password.

    6. The Increment Login Count node updates the login count.

    7. The Inner Tree Evaluator node invokes the ProgressiveProfile journey.

    8. The journey succeeds and the test user profile displays.

Default login after

Advanced Identity Cloud captured the user password during the pass-through authentication journey. The user can now log in to Advanced Identity Cloud directly:

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Journeys > Login and copy the Preview URL.

  3. Paste the URL into an incognito window.

    The login page for the tenant displays.

  4. Log in as the test user.

    Log in succeeds.

Video of validation

Explore further

Reference material

Reference Description

Admin UIs

Get to know the Advanced Identity Cloud admin UI.

Azure AD provisioning

Learn about connecting Advanced Identity Cloud to Microsoft Entra ID.

Pass-through authentication

Read about alternative pass-through authentication methods.

Tutorial: Register an app with Microsoft Entra ID

Refer to this Microsoft Entra ID documentation for details.

Nodes used

The following nodes are listed in the order they appear in the journey.

Ping Identity as external authentication method for Microsoft Entra ID (Azure AD)

Description

Estimated time to complete: 30 minutes.

In this use case, you configure Advanced Identity Cloud as an external authentication method for Microsoft Entra ID (Azure AD).

Specifically, you configure Advanced Identity Cloud as the identity provider (IdP) for Microsoft Entra ID using OIDC. This allows a user from Microsoft Entra ID to use Advanced Identity Cloud as a second factor authentication solution.

Goals

After completing this use case, you will know how to do the following:

  • Configure a custom OIDC application for SSO.

  • Configure Microsoft Entra ID to use an external authentication method.

  • Configure a custom journey for MFA purposes.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • A basic understanding of:

    • The Advanced Identity Cloud admin UI

    • SSO (Federation)

    • OIDC

    • The Advanced Identity Cloud end-user UI

    • Microsoft Entra ID

  • Access to your development environment as an administrator.

  • A test Microsoft Entra ID environment with at least a P1 license.

  • An admin with the Privileged Role Administrator or Global Administrator role in Microsoft Entra ID.

  • A test user in Advanced Identity Cloud to serve as the application owner for the custom OIDC (Microsoft Entra ID) application.

  • The use case matches a user from Microsoft Entra ID to a test user in Advanced Identity Cloud. Specifically, make sure the test user’s frIndexedString1 attribute in Advanced Identity Cloud matches the Object ID attribute for the user in Microsoft Entra ID.

Tasks

This use case requires the use of third-party services. Use your environment specific details where necessary.

Task 1: Create a new OIDC web app in Advanced Identity Cloud

  1. Create a new OIDC Web App (Applications > Custom Applications > OIDC - OpenId Connect > Web) with the following config:

    Field Value

    Sign-in URLs

    https://login.microsoftonline.com/common/federation/externalauthprovider

    Grant Type

    Implicit

    Scopes

    openid

    Response Types

    id_token

    Claims

    profile

    Advanced > Authentication > Token Endpoint Authentication Method

    none

Task 2: Set up Microsoft Entra ID as the service provider

Please reference Configure a new external authentication provider with Microsoft Entra ID.

The next task is to prepare Microsoft Entra ID to serve as a service provider (SP) and use Advanced Identity Cloud as an external authentication method.

Register a new app (required)

  1. Navigate to https://entra.microsoft.com/#home.

    Microsoft Entra ID admin center

  2. In the left panel, click Applications > App registrations.

  3. Click New registration.

    Start new registration for app

  4. Complete the following fields, and click Register:

    Field Value

    Name

    <AIC-EAM-DOC>

    Supported account types

    Accounts in this organizational directory only (... - Single tenant)

    Redirect URI

    <Your AIC authorization_endpoint> https:// <your instance>.forgeblocks.com/am/oauth2/alpha/authorize

    Select a platform

    Web
    App registration filled in

  5. In the new app’s Overview page, note the UUID under Application (client) ID. You will need it to create an external authentication method.

    Overview page for app

  6. On the left, under Manage, click API permissions.

    API permissions

  7. Click Add a permission.

  8. Click APIs my organization uses.

    Request API permissions list

  9. In the search box, search for Microsoft Graph.

    Request API permissions selection

  10. In the result list, select Microsoft Graph.

  11. Select Delegated permissions.

    Delegated Permissions

  12. Under the Openid permissions section, select the openid and profile checkboxes, and click Add permissions.

    Delegated Permissions

  13. Click Grant admin consent for <your company>.

    Delegated Permissions after grant

  14. Complete the necessary steps for this task, including granting admin consent, and refresh the screen to display the updated permission status. Learn more in Grant tenant-wide admin consent to an application in the Microsoft Entra ID documentation.

    Delegated Permissions after grant successful with checks
Create a new group (if needed)

We highly recommend that you initially don’t include all users in case you encounter issues. Instead, we recommend that you use a group.

  1. In the left panel, click Identity > Groups > All groups.

    All groups

  2. Click New group, and complete the following fields:

    New Group
    Field Value

    Group type

    Security

    Group Name

    Anything you want

    Membership type

    Assigned

  3. Add a few test users, as needed.

Add a new authentication method (required)

  1. Navigate to https://entra.microsoft.com/#home.

  2. In the left panel, click Protection > Authentication methods.

    New Authentication methods - Policies

  3. Click Add external method (Preview), complete the following fields, and click Save:

    Field Value

    Name

    <Anything you want>

    Client ID

    Use the generated Application (client) ID you recorded when setting up the application in Advanced Identity Cloud

    Discovery Endpoint

    .var##<tenant-env-fqdn>##.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration

    App ID

    Use the generated Application (client) ID you recorded when setting up the application in Advanced Identity Cloud
    Add external method (Preview)

  4. Set Include or Exclude of users/groups, as needed.

  5. Ensure that you granted admin consent from Task 2 - Register a new app, step 20. You need the Privileged Role Administrator or Global Administrator role to grant admin consent for the provider’s application.

Create new conditional access (required)

  1. Navigate to https://entra.microsoft.com/#home.

  2. In the left-hand panel, click Protection > Conditional Access.

    Conditional Access Overview

  3. Click Create new policy, and complete the following fields:

    Field Value

    Name

    <anything you want>

    Users

    You can add anyone you want, but we highly recommend that you don’t include all users at first in case you encounter issues. Instead, we recommend that you use a group. For example, the optional one created above.

    Target resources

    Apps you want to protect (My Apps for testing purposes)

    Network

    Set as needed

    Condition

    Set as needed

    Grant

    Grant access selected: Check Require multifactor authentication

    Grant

    For multiple controls: Set according to your security model

Task 3: Complete set up of Microsoft Entra ID in Advanced Identity Cloud

Please reference: How do I override claims in the OIDC ID token in Advanced Identity Cloud or AM?

  1. Make a copy of the Alpha OIDC Claims Script, and add the following lines in the getComputedClaims function, right before the return: 

    //MS Entra EAM
var recievedSub = session.getProperty("eamsub");
computedClaims.put("sub", recievedSub);
var amrMFAUsed = session.getProperty("eam-mfa-type");
var amrClaim = [amrMFAUsed];
computedClaims.put("amr", amrClaim);

  2. Update your OIDC Client. From the Platform UI, navigate to Native Consoles > Access Management > Applications > OAuth 2.0 - Clients > clients > <The Client you create in the AIC Initial Setup above>.

    1. On the Core tab, complete the following fields:

      Field Value

      Redirection URIs

      https:// login.microsoftonline.com/common/federation/externalauthprovider

      Default Scope(s)

      openid profile

    2. On the Advance tab, complete the following fields:

      Field Value

      JavaScript Origins

      https://login.microsoftonline.com
      https://login.microsoftonline.com:443

      Response Types

      id_token

      Grant Types

      Implicit

      Token Endpoint Authentication Method

      None

    3. On the OAuth2 Provider Overrides tab, complete the following fields:

      Field Value

      Enable OAuth2 Provider Overrides

      Enabled

      Access Token Modification Plugin Type

      Scripted

      Access Token Modification Script

      Alpha OAuth2 Access Token Modification Script

      OIDC Claims Plugin Type

      SCRIPTED

      OIDC Claims Script

      Name of the script you created in step 1

      OIDC Claims Plugin Implementation Class

      org.forgerock.openam.oauth2.OpenAMScopeValidator

      Use Client-Side Access & Refresh Tokens

      Enabled

      Allow Clients to Skip Consent

      Enabled

      Scope Evaluation Plugin Implementation Class

      org.forgerock.openam.oauth2.OpenAMScopeValidator

      Scope Validation Plugin Type

      JAVA

      Scope Validation Plugin Implementation Class

      org.forgerock.openam.oauth2.OpenAMScopeValidator

      Authorize Endpoint Data Provider Plugin Type

      SCRIPTED

      Authorize Endpoint Data Provider Script

      OAuth2 Authorize Endpoint Data Provider Script

      Authorize Endpoint Data Provider Plugin Implementation Class

      org.forgerock.openam.oauth2.OpenAMScopeValidator

      Overrideable Id_Token Claims

      sub acr amr

  3. In the left panel, click Services.

  4. Click Add a Service.

  5. In the drop-down list, select Session Property Whitelist Service, and click Create.

  6. In the Allowlisted Session Property Names and Session Properties to return for session queries fields, enter eamsub and eam-mfa-type, and click Save Changes.

    Session Property Whitelist Service

  7. Import this journey, and update the config variable in the EAMGetLoginHint script with your EAM-specific data.

    The EAMGetLoginHint script takes the redirect from Entra with a signed JWT containing the username to auth-n in the journey.

    Learn more in Importing journeys.

This journey is only provided as an example. It isn’t configured to perform MFA.
Journey example

  1. Update the EAMGetLoginHint script within the journey with the following details:

    Field Value

    issuer

    The issuer URL in the format - https://login.microsoftonline.com/<tid>/v2.0

    For <tid>, on the left panel, navigate to Identity > Overview to find your tenant ID (TID).

    jwksJson

    The full JWKS that can be found at https://login.microsoftonline.com/<tid>/discovery/v2.0/keys

    audience

    The MS EAM App ID

    tid

    The MS EAM Tenant ID

    nodeName

    The name used for logging purposes

  2. Make sure your test user has the User principal name from MS set on the frIndexedString1 field for your test user in Advanced Identity Cloud.

  3. Navigate to the Access Management native console (Native Consoles > Access Management) and in the Advanced OpenID Connect tab, update your OAuth2 Provider by completing the following fields:

    Field Value

    Enable "claims_parameter_supported"

    True (on)

    OpenID Connect acr_values to Auth Chain Mapping

    possessionorinherence: EAM SAMPLE (my journey name)

Validation

Now that you have created and configured the EAM setup, validate the configurations:

Steps

  1. Navigate to https://myapps.microsoft.com.

  2. Enter the test user’s username and password.

  3. Select the external authentication method you set up.

  4. Select your MFA Choice (Assumption - Your Journey Administrator set up the MFA challenge).

At this point, the user should be logged into Entra.

Video of validation

The following video displays the expected flow from Microsoft Entra ID to Advanced Identity Cloud:

Customization

PingOne Advanced Identity Cloud is highly customizable. For example, you can tailor the end-user experience or script a custom action within an authentication journey. Therefore, the use cases in this section focus on customization, from branding to code:

Use case Description

Customize a theme for hosted pages

Customize the look and feel of the Advanced Identity Cloud end-user UI hosted pages to match your organization’s branding.

Customize emails

Customize an email template to match your organization’s branding.

Create a script in a journey to record last login time

Duplicate an existing journey and modify it to record the time the user logs in to the Advanced Identity Cloud end-user UI. You use a script in a journey to record the login time.

Get an access token in a journey

Create a script to get a service account access token within your journeys. Then, create a simple journey with this script to prove you can successfully request an access token.

Customize a theme for hosted pages

Description

Estimated time to complete: 20 minutes.

In this use case, you customize the look and feel of the Advanced Identity Cloud end-user UI hosted pages to match your organization’s branding.

Goals

After completing this use case, you will know how to do the following:

  • Create a new theme in Advanced Identity Cloud.

  • Define the branding for end-user journey pages and account pages.

  • Enable account controls so that end users can download and delete their data from their profile page.

  • Set the new theme as the default theme for the Advanced Identity Cloud end-user UI hosted pages.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • Access to your Advanced Identity Cloud development environment as an administrator.

  • A URL that specifies the location of a logo image. The URL must be publicly accessible.

  • A proficient understanding of HTML. Ping Identity allows you to customize pages with your own custom HTML.

  • You have completed the use case create test users and roles. Specifically, you have created the test user acruse.

Tasks

Task 1: Create a new theme and define the branding

In this task, you create a new theme for end-user hosted pages and define the branding.

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Go to wysiwyg Hosted Pages and add New Theme.

  3. Enter My Organization Theme, and then click Save.

    The Hosted Pages editor displays.

  4. In Global Settings make the following branding changes:

    Tab Option Customize

    Styles

    Brand Colors

    Click the Brand Color field and enter the hex value #009C80.

    Click the Brand Hover Color field and enter the hex value #007661.

  5. Click Journey Pages and make the following branding changes:

    Tab Option Customize

    Styles

    Page Background

    Click the Page Background Color field and enter the hex value #007661.

    Logo

    Logo

    Click the pencil icon (), enter your logo URL in the Logo URL field, and then click Update.

    Layout

    Footer

    Enable the Footer switch.

    Click the pencil icon (), edit the HTML, and then click Update. For example, enter the following:

    <div class="d-flex justify-content-center py-4 w-100">
<span class="pr-1">© 2023</span>
<a href="https://www.my-example-org.com" class="text-body">My Organization</a>
<a href="https://www.my-example-org.com/privacy-policy" style="color:#0000ee" class="pl-3 text-body">Privacy Policy</a>
<a href="https://www.my-example-org.com/terms-conditions" style="color:#0000ee" class="pl-3 text-body">Terms &amp; Conditions</a>
</div>

  6. Click Account Pages and make the following branding changes:

    Tab Option Customize

    Logo

    Expanded Version

    Click the pencil icon (), enter your logo URL in the Logo URL field, and then click Update.

    Collapsed Version

    Click the pencil icon (), enter your logo URL in the Logo URL field, and then click Update.

    Layout

    Profile Page

    Enable Account Controls.

    Account controls allow end users to download the data Identity Cloud has about them in a JSON format and allow end users to delete their account information.

    End users can only view the information and take actions for the items you enable in the Profile Page. Learn more in Configure visible information and end-user actions.

  7. Click Global to review your changes.

    Customized theme

  8. Click Save.

Task 2: Set the new theme as the default theme

  1. In the Advanced Identity Cloud admin UI, go to wysiwyg Hosted Pages.

  2. Click the ellipsis icon () for the My Organization Theme and select Set as Realm Default.

    My Organization Theme is now the realm default theme.

Default realm theme
The default theme applies to the end-user login pages and the Advanced Identity Cloud end-user UI. You can add custom themes so that your end users are presented with screens specific to their authentication journey. Learn more in Add a custom theme.
Check in

At this point, you:

Created a new theme.

Defined the branding for the theme.

Enabled account controls in the end-user account pages.

Set the new theme as the default for end-user journey pages .and the Advanced Identity Cloud end-user UI.

Validation

Now that you have created your new theme and set it as the default, you are ready to validate the configuration.

The steps in this validation check that the login pages and Advanced Identity Cloud end-user UI display the new theme, including letting end users download and delete their account data.

In this validation task you log in as acruse, who is one of the users created in Create users and roles.

Steps

  1. In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click on the Login journey provided as default in Advanced Identity Cloud.

  2. Copy and paste the Preview URL into an Incognito window.

    The Sign In page for the tenant displays with the My Organization Theme branding.

    Login page with customized theme

  3. Enter the username and password for acruse, and then click Next.

    You are logged in to the Advanced Identity Cloud end-user UI.

  4. Click Edit Your Profile.

    The Profile page displays, including Account Controls.

    Profile page with customized theme

  5. In the Advanced Identity Cloud admin UI, go to wysiwyg Hosted Pages.

  6. Click the ellipsis icon () for a different theme and select Set as Realm Default.

  7. Go back to the Advanced Identity Cloud end-user UI (in the Incognito window) and refresh the browser.

    The look and feel of the Advanced Identity Cloud end-user UI changes to the theme you selected as the default.

Video of validation

The following video displays the expected validation of logging in with the new theme and changing to a different default theme:

Explore further

Reference material

Reference Description

Identity Cloud hosted pages

Learn about hosted pages you can use in journeys and the Advanced Identity Cloud end-user UI.

Demo: Configure themes for the Alpha and Bravo realms - ForgeRock University

A guided walkthrough video demonstrating how to configure themes for the Advanced Identity Cloud end-user UI account pages.

Use case: Create dynamically branded journeys in Advanced Identity Cloud

A guided walkthrough demonstrating how to apply themes dynamically during a journey, based on the end user’s organization.

Customize emails

Description

Estimated time to complete: 20 minutes

In this use case, you:

  • Duplicate the default registration email

  • Customize the duplicated email to match your organization’s branding

  • Add the new email template to the User Registration journey (you must complete the User registration use case)

  • Register as a new end user to test the newly branded email

Goals

After completing this use case, you will know how to do the following:

  • Create new email templates

  • Update journeys to use different email templates

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • You have completed the User registration use case

  • Access to your Advanced Identity Cloud development environment as an administrator

  • A basic understanding of journeys and nodes

  • A basic understanding of CSS

Tasks

Task 1: Create a new user registration email template

In your staging and production tenant environments, you must update the email provider configuration with values to connect to something other than the built-in SMTP server.
Duplicate the default user registration email

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

  2. On the Email Templates page, click the ellipsis icon () for the Registration template and select Duplicate.

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

    Field Value

    Template Name

    Branded Registration

    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

    Branded version of the default Registration email.

  4. Click Save.

    The email templates editor displays.

Customize the new email template
You can add images to your email template if they are hosted online. Learn more in How do I update email templates in Advanced Identity Cloud to include images and HTML formatting?.

  1. In the email templates editor, make the following changes to the Branded Registration email template:

    Change Detail

    Update the heading text

    Replace the heading text in line 1 with Thank you for registering.

    Leave the # characters. This indicates a heading, in this case, an H3 heading.

    Update the email verification link text

    Update the email verification link text in line 3 to:

    To confirm your email address, click [verify email](<{{object.resumeURI}}>).

  2. Click Save.

  3. Click Styles to change the look and feel of the email template. Make the following changes:

    Change Detail

    Update the font

    Add font-family:arial; under .content to change the font used in the email.

    Change the link color

    Change the color value under a to #0C85CF.

    Format the heading text

    Add the following CSS to format the heading text:

    h3{
   color:#324054
}
    Registration email preview

  4. Click Save.

    The email preview shows the updated email template:

    Registration email preview

  5. In the URL, copy the email template name shown after /edit (brandedRegistration). You will need this in the next task.

    Email template name
You can send yourself a test email to check everything looks correct before proceeding. Click Send Test Email, enter your email address, and click Send.

Task 2: Update the user registration journey

In this task, you update the User Registration journey to use your new email template.

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

  2. Click the ellipsis icon () for the Registration journey and select Edit.

  3. Click the Email Suspend Node and enter brandedRegistration in the Email Template Name field.

    The name you enter must exactly match the name shown in the URL when you customized the email template.

  4. Click Save.

Check in

At this point, you:

Created a new email template for user registration.

Customized the email to use your organization’s font and colors.

Updated the User Registration journey to use your new email template.

Validation

Now that you have created a new email template for user registration and added it to the User Registration journey, you are ready to validate the email.

The steps in this validation register a new end user in Advanced Identity Cloud so you can check they receive the branded email during the registration process.

When you register the new end user, ensure you use an email address that you can access.

Steps

  1. In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click on the User Registration journey you just updated.

  2. In the Preview URL field, click copy and paste the URL into an Incognito window.

    The Sign Up page for the tenant displays.

  3. In the Sign Up page, enter the following details:

    Field Value

    Username

    cbarnes

    First Name

    Charlie

    Last Name

    Barnes

    Email Address

    Enter an email address for this new user. You must have access to this email account.

  4. Click Next. A message displays informing you an email has been sent.

  5. Check the inbox for the email address you entered and view the registration email. Confirm it has been branded as expected.

  6. Click the link in the email to confirm your email address and continue registration.

  7. Enter Ch4ng3it! in the Password field.

  8. Click Next.

    You are logged into the Advanced Identity Cloud end-user UI as Charlie Barnes.

Video

The following video displays the expected validation of registering a new end user using the updated email template:

Explore further

Reference material

Reference Description

Email templates

Learn about creating, editing and managing email templates.

How do I update email templates in Advanced Identity Cloud to include images and HTML formatting?

Steps for enhancing email templates in Advanced Identity Cloud with images and HTML formatting.

How do I use ESVs in an email template in Advanced Identity Cloud?

Steps for including Environment secrets and variables (ESVs) in email templates.

How do I send locale-based emails from a journey inAdvanced Identity Cloud?

Steps to send localized emails from a journey.

Journeys

Conceptual information on journeys and their purpose in Advanced Identity Cloud.

Create a script in a journey to record last login time

Description

Estimated time to complete: 20 minutes

In this use case, you duplicate an existing journey and modify it to record the time the user logs in to the Advanced Identity Cloud end-user UI. You use a script in your journey to record the login time.

Goals

After completing this use case, you will know how to do the following:

  • Create a script to use in a journey, referred to as a journey decision script.

  • Change a field name in the end user profile.

  • Adapt a journey to record shared state data in the end user profile.

Prerequisites

Before you start work on this use case, make sure you have:

  • A basic understanding of:

    • JavaScript.

    • Journeys and nodes.

    • Realms.

    • The Advanced Identity Cloud admin UI.

    • The Advanced Identity Cloud end-user UI.

    • The managed/alpha_user object schema.

  • Access to your Advanced Identity Cloud development environment as an administrator.

  • A test identity in Advanced Identity Cloud.

Tasks

Task 1: Create a journey decision script

A journey decision script runs in Advanced Identity Cloud during an authentication journey. It’s called a decision script because it’s programmed to decide how the journey continues.

When the script runs, it can also read and change the shared state of the journey. In this example, the script adds a timestamp to record when it runs in the shared state.

Later, nodes can use the shared state data to take action. You can configure nodes to use shared state data and script the actions Advanced Identity Cloud takes. In this example, a later node writes the timestamp in the authenticating user’s profile.

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

    Select the alpha realm if it is not selected by default.

  2. In the left menu pane, select Scripts > Auth scripts and click + New script.

  3. Select Journey Decision Node and click Next to open the script editor.

  4. Set the fields as follows and click Save and Close:

    Field Value

    Name

    last-login-time

    Description

    Set last login time. Use this after successful authentication.

    JavaScript

    		 
    function tag(message) {
    return '*** last-login-time: '.concat(message)
}

var lastLoginAttribute = 'frUnindexedDate1'
var lastLoginTime = new Date().toISOString()
sharedState.get('objectAttributes').put(lastLoginAttribute, lastLoginTime)
logger.message(tag('Setting ' + lastLoginAttribute + ' to ' + lastLoginTime))
outcome = 'Success'

    The script sets the shared state objectAttributes.frUnindexedDate1 to the current time as an ISO date string. Managed users have many optional fields. The frUnindexedDate1 field is one of them. The script sets this field in objectAttributes, the attributes of the managed user object, so a later node can write the updated frUnindexedDate1 value from shared state to the user’s profile.

    The frUnindexedDate1 field is an unindexed field, meaning Advanced Identity Cloud does not maintain a search index for the field. If applications look up profiles based on the last login time, use one of the frIndexedDate* fields instead.

    Notice the following objects from Advanced Identity Cloud bound to the journey decision script execution context; the script uses them directly without having to define them first:

    • sharedState: Use this to access the shared journey state.

    • logger: Use this to log debug messages.

    • outcome: Set the outcome to a string as the last processing step.

    There is no authentication decision to make, so the script’s only outcome is Success. You include each outcome in the Scripted Decision node Outcomes setting when using the script in a journey.

Check in

At this point, you:

Created a script to add last login time to the journey’s shared state data.

Task 2: Update the target managed user field

By default, the label in the Advanced Identity Cloud end-user UI for the frUnindexedDate1 field is Generic Unindexed Date 1. The journey uses this field for last login times; therefore, you change the label to Last Login Time for readability.

  1. In the left menu pane of Advanced Identity Cloud admin UI, select Native Consoles > Identity Management.

    The IDM admin UI dashboard displays.

  2. In the top menu of the IDM admin UI, select Configure > Managed Objects and click the card for Alpha_user to edit the managed object properties.

  3. Scroll to the frUnindexedDate1 row and click it to edit the property.

  4. Set the fields as follows and click Save:

    Field Value

    Readable Title

    Last Login Time

    This changes the label in the Advanced Identity Cloud end-user UI.

    Show advanced options > Searchable

    Enable this.

    Show advanced options > User Editable

    Disable this.
Check in

At this point, you:

Created a script to add last login time to the journey’s shared state data.

Configured the Last Login Time label in the Advanced Identity Cloud end-user UI.

Task 3: Create a last login journey

You base the last login journey on the default Login journey. To reference the script, you add a Scripted Decision node. To write the last login time to the user’s profile, you add a Patch Object node.

Duplicate the default login journey

  1. In the left menu pane of Advanced Identity Cloud admin UI, select Journeys

  2. Select the More () menu for the default Login journey and select Duplicate to display the Duplicate Journey modal.

  3. Set the fields as follows and click Save:

    Field Value

    Name

    Log in and set last login time

    Identity Object

    Alpha realm - Users managed/alpha_user

    Description

    Duplicate of default Login journey that also sets last login time

    The Advanced Identity Cloud admin UI displays the journey editor.

Configure your last login time journey

  1. In the journey editor, find these nodes to drag and drop them onto the journey canvas:

    • Scripted Decision node

    • Patch Object node

  2. Select the Scripted Decision node and set the fields as follows:

    Field Value

    Name

    Last login time

    Script

    last-login-time

    Outcomes

    Success

    Leave the default settings for other fields.

    When the journey reaches this node, your journey decision script runs.

  3. Select the Patch Object node and set the fields as follows:

    Field Value

    Identity Resource

    managed/alpha_user

    Leave the default settings for other fields.

    When the journey reaches this node, it updates the managed/alpha_user object properties with the shared state objectAttributes fields including the frUnindexedDate1 field set by your script. This update stores the last login time in the end user’s profile.

  4. Reconnect the Scripted Decision node True outcome to the Last login time node input.

  5. Connect the Last login time node outcome to the Patch Object node input.

  6. Connect the Patch Object node Patched outcome to the Increment Login Count node input.

  7. Connect the Patch Object node Failed outcome to the Failure node.

At this point, the authentication journey is complete. The following shows a rectangle around the nodes you added after duplicating the default journey:

Last login time journey

  • a Collects the username and password.

  • b Validates the username and password.

  • c Records the time in the shared state object attributes on frUnindexedDate1.

  • d Writes the time to the user’s profile.

  • e Increments the number of authentications.

  • f Triggers an inner journey; in this case, a journey for progressive profiling.

Check in

At this point, you:

Created a script to add last login time to the journey’s shared state data.

Configured the Last Login Time label in the Advanced Identity Cloud end-user UI.

Duplicate and configured a journey to record the last Login time.

Task 4: Check journey path connections

Use the following table to check the connections for each node in the Log in and set last login time journey.

Some nodes have more than one outcome. The → symbol means the node only has one outcome path.

Source node Outcome path Target node

Start (person icon)

→

Page node

Page node containing:

  • Platform Username node

  • Platform Password node

→

Data Store Decision node

Data Store Decision node

True

Scripted Decision node

(Last login time)

False

Failure node

Scripted Decision node

(Last login time)

→

Patch Object node

Patch Object node

Patched

Increment Login Count node

Failed

Failure node

Increment Login Count node

→

Inner Tree Evaluator node

Inner Tree Evaluator node

True

Success node

False

Failure node

Validation

Now that you have created your script, updated a label in the Advanced Identity Cloud end-user UI, duplicated the default Login journey, and updated the copy to record the last login time in the user’s profile, you are ready to validate the journey.

Before validating, make sure you have a test user in the alpha realm.

Steps

  1. Get a URL you can use to test the journey:

    1. Log in to the Advanced Identity Cloud admin UI as an administrator.

    2. Select Journeys.

    3. Select the journey you created, Log in and set last login time.

      A preview screen of the journey displays.

    4. Click the copy icon next to Preview URL, a URL you can use to test the journey as an end user:

      Copy the test URL for the journey

  2. Log in to the Advanced Identity Cloud end-user UI:

    1. Paste the URL into an incognito window.

      Use incognito mode for testing to avoid caching issues and interference with any current sessions.

      The Advanced Identity Cloud end-user UI displays the login screen.

    2. Enter the test user’s username and password.

    3. Click Next.

      The Advanced Identity Cloud end-user UI displays the test user’s profile.

  3. Click Edit Your Profile to display the profile screen then Edit Personal Info to display the profile fields.

  4. Scroll to the Last Login Time field.

    The field contains the timestamp written when the test user logged in:

    Last login timestamp

    The Advanced Identity Cloud end-user UI appends (optional) to the field name for managed object properties without Required enabled.

Video of validation

From the end user’s perspective, the journey works as follows. The video starts with the test user logged in before trying the last login time journey:

Explore further

Reference material

Reference Description

Admin interfaces in Advanced Identity Cloud

Get to know the admin interfaces; Advanced Identity Cloud admin UI, AM admin UI, and IDM admin UI.

Journeys

Conceptual information on journeys and their purpose in Advanced Identity Cloud.

Introduction to journeys with ForgeRock University

A guided video of journeys in Advanced Identity Cloud and how to use them.

Nodes for journeys

Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys.

User identity attributes and properties reference

Reference information for end user profile properties.

Scripted decision node API

Reference information for journey decision node scripts.

Nodes used

The last login time journey uses the following nodes:

Get an access token in a journey

Description

Estimated time to complete: 25 minutes

In this use case, create a script to get an access token using a service account. A service account lets you request access tokens for most Advanced Identity Cloud REST API endpoints. Then, create a simple journey with this script to prove you can successfully request an access token.

The script in this use case uses the fr:idm:* scope for access to /openidm/* API endpoints. If you want to get an access token for other Advanced Identity Cloud API endpoints, set up your service account for the required scopes and update the scopes referenced in the script to match.

Service accounts can only be used with Advanced Identity Cloud API endpoints; if you want to communicate with a third-party API, you’ll need to use the standard OAuth 2.0 client credential flow.

Goals

After completing this use case, you will know how to do the following:

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • A basic understanding of:

    • Journeys and nodes

    • JavaScript

    • Service accounts

    • ESVs

  • Access to your Advanced Identity Cloud development environment as a tenant administrator.

  • A service account that can grant the fr:idm:* scope to an access token.

    You’ll need the service account ID and private key later when you create ESVs.

Tasks

Task 1: Create ESVs

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

  2. Create the following ESVs:

    ESV name ESV type Description

    esv-tenant-env-fqdn

    Variable (string)

    Tenant FQDN (in the appropriate FQDN format); for example: openam-mycompany-ew2.id.forgerock.io

    esv-service-account-id

    Secret

    Service account ID; for example: 449d7e27-7889-47af-a736-83b6bbf97ec5

    esv-service-account-privatekey

    Secret

    Service account private key; for example: 

    {
  d: "RhpIZ32rNfkoVkQh3pt1me...rDkFL9nBWDOZvXQ2LsFEBc",
  dp: "RfrvtBH_NmzxS......IpJ1vYZS_J0cw",
  dq: "OVO8_yXFRHT...2VREB2b8f8xvIhv5jrQWQ",
  e: "AQAB",
  kty: "RSA",
  n: "5LoH3Fc8IdRg1...K4eUvMEJsjVvfRgzpWCDM0",
  p: "_wjzIYyYcQiNOZdV1Cp7...kjDw",
  q: "5ZeYq0C......6WOaiYw",
  qi: "Z9ECeon...q56tpl2Mu65yqlw",
}

  3. Apply the updates.

    Learn more about creating ESVs and applying updates in Manage ESVs using the UI .

Task 2: Create a script to get an access token

  1. Download the sample script: getAccessToken.js.

    View script 
    /*
 * Copyright © 2024 Ping Identity Corporation
 *
 * This code is to be used exclusively in connection with Ping Identity Corporation
 * software or services.
 * Ping Identity Corporation only offers such software or services to legal entities
 * who have entered into a binding license agreement with Ping Identity Corporation.
*/

var nodeConfig = {
  nodeName: "Get Access Token Demo",
  tenantFqdnEsv: "esv.tenant.env.fqdn",
  accountIdEsv: "esv.service.account.id",
  privateKeyEsv: "esv.service.account.privatekey",
  accessTokenStateField: "idmAccessToken",
  maxAttempts: 3,
  scope: "fr:idm:*",
  serviceAccountClientId: "service-account",
  jwtValiditySeconds: 10,
};

var nodeLogger = {
  debug: function (message) {
    logger.message("***" + nodeConfig.nodeName + " " + message);
  },
  warning: function (message) {
    logger.warning("***" + nodeConfig.nodeName + " " + message);
  },
  error: function (message) {
    logger.error("***" + nodeConfig.nodeName + " " + message);
  },
};

var nodeOutcomes = {
  SUCCESS: "Success",
  ERROR: "Error",
};

var javaImports = JavaImporter(
  org.forgerock.openam.auth.node.api.Action,
  org.forgerock.json.jose.builders.JwtBuilderFactory,
  org.forgerock.json.jose.jwt.JwtClaimsSet,
  org.forgerock.json.jose.jws.JwsAlgorithm,
  org.forgerock.json.jose.jws.SignedJwt,
  org.forgerock.json.jose.jws.handlers.SecretRSASigningHandler,
  org.forgerock.json.jose.jwk.RsaJWK,
  javax.crypto.spec.SecretKeySpec,
  org.forgerock.secrets.SecretBuilder,
  org.forgerock.secrets.keys.SigningKey,
  java.time.temporal.ChronoUnit,
  java.time.Clock,
  java.util.UUID
);

function getKeyFromJwk(issuer, jwk) {
  var privateKey = javaImports.RsaJWK.parse(jwk).toRSAPrivateKey();

  var secretBuilder = new javaImports.SecretBuilder();

  secretBuilder
    .secretKey(privateKey)
    .stableId(issuer)
    .expiresIn(
      5,
      javaImports.ChronoUnit.MINUTES,
      javaImports.Clock.systemUTC()
    );
  return new javaImports.SigningKey(secretBuilder);
}

function getAssertionJwt(accountId, privateKey, audience, validity) {
  var signingHandler = new javaImports.SecretRSASigningHandler(
    getKeyFromJwk(accountId, privateKey)
  );

  var iat = new Date().getTime();
  var exp = new Date(iat + validity * 1000);

  var jwtClaims = new javaImports.JwtClaimsSet();

  jwtClaims.setIssuer(accountId);
  jwtClaims.setSubject(accountId);
  jwtClaims.addAudience(audience);
  jwtClaims.setExpirationTime(exp);
  jwtClaims.setJwtId(javaImports.UUID.randomUUID());

  var jwt = new javaImports.JwtBuilderFactory()
    .jws(signingHandler)
    .headers()
    .alg(javaImports.JwsAlgorithm.RS256)
    .done()
    .claims(jwtClaims)
    .build();

  return jwt;
}

function getAccessToken(accountId, privateKey, tenantFqdn, maxAttempts) {
  var response = null;
  var accessToken = null;
  var tokenEndpoint = "https://"
    .concat(tenantFqdn)
    .concat("/am/oauth2/access_token");

  nodeLogger.debug("Getting Access Token from endpoint " + tokenEndpoint);

  var assertionJwt = getAssertionJwt(
    accountId,
    privateKey,
    tokenEndpoint,
    nodeConfig.jwtValiditySeconds
  );

  if (!assertionJwt) {
    nodeLogger.error("Error getting assertion JWT");
    return null;
  }

  nodeLogger.debug("Got assertion JWT " + assertionJwt);

  for (var attempt = 0; attempt < maxAttempts; attempt++) {
    nodeLogger.debug("Attempt " + (attempt + 1) + " of " + maxAttempts);
    try {
      var request = new org.forgerock.http.protocol.Request();
      request.setUri(tokenEndpoint);
      request.setMethod("POST");
      request
        .getHeaders()
        .add("Content-Type", "application/x-www-form-urlencoded");

      var params = "grant_type="
        .concat(
          encodeURIComponent("urn:ietf:params:oauth:grant-type:jwt-bearer")
        )
        .concat("&client_id=")
        .concat(encodeURIComponent(nodeConfig.serviceAccountClientId))
        .concat("&assertion=")
        .concat(encodeURIComponent(assertionJwt))
        .concat("&scope=")
        .concat(encodeURIComponent(nodeConfig.scope));

      request.setEntity(params);
      response = httpClient.send(request).get();
      if (response) {
        break;
      }
    } catch (e) {
      nodeLogger.error(
        "Failure calling access token endpoint: " +
          tokenEndpoint +
          " exception:" +
          e
      );
    }
  }

  if (!response) {
    nodeLogger.error("Bad response");
    return null;
  }

  if (response.getStatus().getCode() !== 200) {
    nodeLogger.error(
      "Unable to acquire Access Token. HTTP Result: " + response.getStatus()
    );
    return null;
  }

  try {
    var responseJson = response.getEntity().getString();
    nodeLogger.debug("Response content " + responseJson);
    var oauth2response = JSON.parse(responseJson);
    accessToken = oauth2response.access_token;
    nodeLogger.debug("Access Token acquired: " + accessToken);
    return accessToken;
  } catch (e) {
    nodeLogger.error("Error getting access token from response: " + e);
  }

  return null;
}

(function () {
  try {
    nodeLogger.debug("Node starting");

    var accessToken = nodeState.get(nodeConfig.accessTokenStateField);

    if (accessToken) {
      nodeLogger.debug("Access token already present: continuing");
      action = javaImports.Action.goTo(nodeOutcomes.SUCCESS).build();
      return;
    }

    var tenantFqdn = systemEnv.getProperty(nodeConfig.tenantFqdnEsv);
    if (!tenantFqdn) {
      nodeLogger.error("Couldn't get FQDN from esv " + config.tenantFqdnEsv);
      action = javaImports.Action.goTo(nodeOutcomes.ERROR).build();
      return;
    }

    var accountId = systemEnv.getProperty(nodeConfig.accountIdEsv);
    if (!accountId) {
      nodeLogger.error(
        "Couldn't get service account id from esv " + nodeConfig.accountIdEsv
      );
      action = javaImports.Action.goTo(nodeOutcomes.ERROR).build();
      return;
    }

    var privateKey = systemEnv.getProperty(nodeConfig.privateKeyEsv);
    if (!privateKey) {
      nodeLogger.error(
        "Couldn't get private key from esv " + nodeConfig.privateKey
      );
      action = javaImports.Action.goTo(nodeOutcomes.ERROR).build();
      return;
    }

    accessToken = getAccessToken(
      accountId,
      privateKey,
      tenantFqdn,
      nodeConfig.maxAttempts
    );

    if (!accessToken) {
      nodeLogger.error("Failed to get access token");
      action = javaImports.Action.goTo(nodeOutcomes.ERROR).build();
      return;
    }

    nodeLogger.debug("Success - adding token to transient state");
    nodeState.putTransient(nodeConfig.accessTokenStateField, accessToken);
    action = javaImports.Action.goTo(nodeOutcomes.SUCCESS).build();
  } catch (e) {
    nodeLogger.error("Exception encountered " + e);
    action = javaImports.Action.goTo(nodeOutcomes.ERROR).build();
    return;
  }
})();

  2. In the Advanced Identity Cloud admin UI, go to code Scripts > Auth Scripts and click + New Script.

  3. Select Journey Decision Node and click Next.

  4. Select Legacy and click Next.

  5. In the New Journey Decision Node Script window, enter the following details:

    Field Value

    Name

    Get access token

    Description

    Get an access token using a service account

    JavaScript

    Replace the sample JavaScript with the contents of the downloaded getAccessToken.js script.

  6. Check the variables defined in the script and update as needed:

    var nodeConfig = {
  nodeName: "Get Access Token Demo", (1)
  tenantFqdnEsv: "esv.tenant.env.fqdn", (2)
  accountIdEsv: "esv.service.account.id", (3)
  privateKeyEsv: "esv.service.account.privatekey", (4)
  accessTokenStateField: "idmAccessToken",
  maxAttempts: 3,
  scope: "fr:idm:*", (5)
  serviceAccountClientId: "service-account", (6)
  jwtValiditySeconds: 10,
};
    1 The nodeName indicates the name of your journey for debugging purposes.
    2 The tenantFqdnEsv contains the script reference to the esv-tenant-env-fqdn ESV.
    3 The accountIdEsv contains the script reference to the esv-service-account-id ESV.
    4 The privateKeyEsv contains the script reference to the esv-service-account-privatekey ESV.
    5 The scope you chose when you set up your service account; this determines which API endpoints you can get an access token for.
    6 The serviceAccountClientId must be set to service-account to use the built-in OAuth 2.0 public client for service accounts; otherwise, the JWT profile for OAuth 2.0 authorization grant flow will fail.

  7. Click Save and Close.

Task 3: Create a journey to get an access token

  1. In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click + New Journey.

  2. In the New Journey window, enter the following details:

    Field Value

    Name

    Get Access Token Demo

    Identity Object

    Alpha realm - Users managed/alpha_user

    Description

    Journey to get an access token using a service account

  3. Click Save. The journey editor displays.

  4. In the journey editor, search for the Scripted Decision node and drag it onto the canvas.

  5. Configure this node as follows:

    Field Value

    Name

    Get Access Token

    Script

    Get access token

    Outcomes

    Create two outcomes: Success and Error

  6. In the journey editor, search for the Message Node and drag two copies of it onto the canvas.

  7. Select the first Message Node and configure it as follows:

    Field Value

    Name

    Success Message

    Message

    Key

    en

    Value

    Access token successfully acquired

  8. Select the second Message Node and configure it as follows:

    Field Value

    Name

    Error Message

    Message

    Key

    en

    Value

    Failed to get access token

  9. Connect the nodes:

    Get access token journey
    Source node Outcome path Target node

    Start (person icon)

    →

    Scripted Decision node

    (Get Access Token)

    Scripted Decision node

    (Get Access Token)

    Success

    Message node

    (Success Message)

    Error

    Message node

    (Error Message)

    Message node

    (Success Message)

    True

    Success node

    False

    Success node

    Message node

    (Error Message)

    True

    Failure node

    False

    Failure node

  10. Click Save.

Check in

At this point, you:

Created ESVs for the tenant FQDN and service account details.

Created a script to get an access token using a service account.

Created a simple journey to get an access token.

Validation

Now that you have created a journey to get an access token, you are ready to validate it.

The journey runs the script to acquire an access token using the service account and ESVs you set up. If an access token is successfully acquired, the Success Message is shown.

If you want to view the access token created during testing, you can enable debug mode in your development environment.

Steps

  1. In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click on the Get Access Token Demo journey you just created.

  2. In the Preview URL field, click copy and paste the URL into an Incognito window.

    The script runs to get an access token, and if successful, the Success Message displays:

    Success message

    The Yes and No buttons shown are the default outcomes for a Message node; they are not relevant to this example and don’t do anything further.

    If an access token is not acquired, the Error Message is shown instead (Failed to get access token).

Explore further

Reference material

Reference Description

Service accounts

Information about service accounts in Advanced Identity Cloud.

Authenticate to Advanced Identity Cloud REST API with access token

Learn how to authenticate to Advanced Identity Cloud REST API endpoints using an access token.

ESVs

Information about environment secrets and variables (ESVs).

Journeys

Conceptual information on journeys and their purpose in Advanced Identity Cloud.

Nodes for journeys

Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys.

Scripted decision node API

Reference information for journey decision node scripts.

Nodes used

The following nodes are listed in the order they appear in the journey.

Data (identity) management

In PingOne Advanced Identity Cloud, data management covers a wide-range of activities including:

Item Description

Identity object schema

The model for your data including users, roles, and applications. Create new objects or modify existing ones so that each object represents the properties your organizations requires.

Organizations

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

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

Roles

Roles define privileges for user and device identities. Roles let you automatically assign and update privileges in numerous identity profiles. For further information about roles and assignments, refer to Roles and assignments.

The role object is a managed object type that uses the relationships mechanism to link the role to the managed object to which it applies.

Applications

While you can use applications for authentication, applications are also used for provisioning and synchronization.

The use cases in this section focus on data management in a holistic way:

Use case Description

Create test users and roles

Create test users and roles, assign users to roles, and log in to the Advanced Identity Cloud end-user UI as one of the users.

Assign roles to users dynamically

Dynamically assign a user to a role based off a criteria being met.

Provision data between Advanced Identity Cloud and PingDirectory

Provision accounts to and from Advanced Identity Cloud and PingDirectory.

Create organizations to delegate administration

Configure Advanced Identity Cloud to group users into organizations. Use organizations to delegate user administration to different groups of users.

Enable managers to manage their direct reports

Configure Advanced Identity Cloud to enable managers to update their direct reports' information and assign provisioning roles to them through Advanced Identity Cloud end-user UI.

Provision users from Microsoft Entra ID (Azure AD)

Provision accounts from Microsoft Entra ID (formerly Azure AD) into Advanced Identity Cloud.

Provision data from Active Directory (AD) using RCS

Provision accounts from an on-premise Active Directory (AD) server into Advanced Identity Cloud.

Create test users and roles

Description

Estimated time to complete: 10 minutes

In this use case, you create test users and roles, assign users to roles, and log in to the Advanced Identity Cloud end-user UI as one of the users.

Goals

After completing this use case, you will know how to do the following:

  • Create new users

  • Create a role

  • Assign the role to the users

Prerequisites

Before you start, make sure you have a basic understanding of these Advanced Identity Cloud concepts:

  • Advanced Identity Cloud admin UI

  • Advanced Identity Cloud end-user UI

Tasks

Task 1: Create new users

In this task, you create two new users.

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

    Add new user

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

  3. On the New Alpha realm - User page, enter the following information for the user, and then click Save:

    Field Value

    Username

    acruse

    First Name

    alex

    Last Name

    cruse

    Email Address

    alex.cruse@example.com

    Password

    Secret12!

  4. Go back to the New Alpha realm - User page and repeat the last step to add another user with the following values:

    Field Value

    Username

    braman

    First name

    bina

    Last name

    raman

    Email Address

    bina.raman@example.com

    Password

    Secret12!

Task 2: Create a role

In this task, you create a role called employee. Roles define privileges for user and device identities. Although the role isn’t required for this use case, you can bulk assign users to an application when they are assigned a role.

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

    Add new role

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

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

    Field Value

    Name

    employee

    Description

    Role granted to workers on the company payroll

  4. Skip the option to assign the role conditionally, and click Next.

  5. Skip the option to assign the role temporarily, and click Save.

    The employee role page is displayed.

  6. Click Role Members > add Add Role Members.

  7. Select your users from the drop-down list and then click Save.

    The role is assigned to the users.

Check in

At this point, you:

Created two new users

Created a role

Assigned the role to the users

Validation

To validate your work:

  1. In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click on the Login journey provided as default in Advanced Identity Cloud.

  2. Copy and paste the Preview URL into an incognito window.

    The login page for the tenant is displayed.

  3. Log in to the tenant as one of the new users and view the profile page for the user.

Explore further

Reference material

Reference Description

Roles

Information about roles

Login

Information about the default login journey

Assign roles to users dynamically

Description

Estimated time to complete: 10 minutes

In the use case Create test users and roles, you created two users and a role and then assigned the role users to the users. In this use case, you are going to:

  • Assign an inactive status to one of the users

  • Add a condition to the role so that it applies only to active users

Goals

After completing this use case, you will know how to:

  • Change the properties of a user

  • Add a condition to a role

Prerequisites

Before you start, make sure you have:

  • A basic understanding of these Ping Identity concepts:

    • Advanced Identity Cloud admin UI

    • Advanced Identity Cloud end-user UI

  • Completed the use case in Create test users and roles

Tasks

Task 1: Assign an inactive status to a user

In this task, you select one of the users you created in Create test users and roles and change their status to inactive.

  1. In the Advanced Identity Cloud admin UI, go to people Identities > Manage > people Alpha realm - Users.

  2. Click on the user acruse.

  3. On the user details page, change the Status from the default value active to inactive and save the change.

Task 2: Add a condition to a role

In this task, you create a condition so that the role applies only to active users.

  1. In the Advanced Identity Cloud admin UI, go to people Identities > Manage > assignment_ind Alpha Realm - Roles.

  2. Click on the employee role and then click on Settings.

    Add new role

  3. In the Condition panel, click on Set up to create the following condition for the role and save the condition:

    Field Value

    A conditional filter for this role

    Enable

    Assign to alpha_user if Any keyboard_arrow_down conditions are met

    Any

    Alpha_user properties keyboard_arrow_down

    Status

    contains keyboard_arrow_down

    is

    Blank

    active
    Add new role

  4. (Optional) Click on add Add Rule to add another condition and take a moment to browse the other conditions that can apply to roles.

Check in

At this point, you:

Made a user inactive

Added a condition to a role

Validation

In Create test users and roles, you created the employee role and manually assigned it to braman and acruse. To validate this use case, make sure the role is no longer assigned to acruse.

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

  2. Make sure braman is in the list but acruse is not.

  3. Change the status of braman to inactive and acruse to active, then make sure acruse is in the list but braman is not.

Explore further

Reference material

Reference Description

Roles

Information about roles

Grant roles dynamically

Information about how to assign roles over REST

Create organizations to delegate administration

Description

Estimated time to complete: 20 minutes

In this use case, you configure Advanced Identity Cloud to group users into organizations. Use organizations to delegate user administration to different groups of users.

Goals

After completing this use case, you will know how to do the following:

  • Create users.

  • Create organizations.

  • Assign administrators to organizations for delegated administration.

  • Add users (members) to organizations.

  • Use the Advanced Identity Cloud end-user UI to manage users in an organization as an organization administrator.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • Access to your Advanced Identity Cloud development environment as an administrator.

  • A basic understanding of realms.

Tasks

Task 1: Create organization administrators and users

In this task, you create six test users. Two users will be administrators for OrgA and OrgB, respectively. The other four are members of OrgA and OrgB.

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Go to people Identities > Manage.

  3. Click people Alpha realm - Users and add New Alpha realm - User.

  4. On the New Alpha realm - User page, enter the following information for the user, and then click Save:

    Field Value

    Username

    orga_admin

    First Name

    OrgA

    Last Name

    Admin

    Email Address

    orgaadmin@example.com

    Password

    Secret12!

  5. Go back to the New Alpha realm - User page and repeat steps 3 and 4 to add another administrator user with the following values:

    Field Value

    Username

    orgb_admin

    First Name

    OrgB

    Last Name

    Admin

    Email Address

    orgbadmin@example.com

    Password

    Secret12!

  6. Go back to the New Alpha realm - User page and repeat steps 3 and 4 to add four more users with the following values:

    • User1 in OrgA:

      Field Value

      Username

      orga_emorris

      First Name

      Elysia

      Last Name

      Morris

      Email Address

      emorris@example.com

      Password

      Secret12!

    • User2 in OrgA:

      Field Value

      Username

      orga_flandry

      First Name

      Fatma

      Last Name

      Landry

      Email Address

      flandry@example.com

      Password

      Secret12!

    • User1 in OrgB

      Field Value

      Username

      orgb_ajarvis

      First Name

      Amin

      Last Name

      Jarvis

      Email Address

      ajarvis@example.com

      Password

      Secret12!

    • User2 in OrgB

      Field Value

      Username

      orgb_mpattison

      Fist Name

      Morgan

      Last Name

      Pattison

      Email Address

      mpattison@example.com

      Password

      Secret12!

Six new users now display in the alpha realm.

New users in the alpha realm

Task 2: Create two organizations and assign administrators

In this task, you create two parent organizations, OrgA and OrgB, and assign administrators to them.

Parent organizations can only be created by super or tenant administrators. Sub-organizations are allowed within an organization, and organization administrators can create them within their respective organizations.

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

  2. On the Manage Identities page, click settings_system_daydream Alpha realm - Organizations.

  3. Create OrgA and assign an administrator:

    1. Click add New Alpha realm - Organization.

    2. In the Name field, enter OrgA, and then click Save.

    3. In the Description field, enter Organization A - employees, and then click Save.

      Create OrgA

    4. Click Administrators and add Add Administrators.

    5. Search for and select the user orga_admin, and then click Save.

      Add OrgA admin

  4. Go back to the Alpha realm - Organization page.

  5. Create OrgB and assign an administrator:

    1. Click add New Alpha realm - Organization.

    2. In the Name field, enter OrgB, and then click Save.

    3. In the Description field, enter Organization B - contractors, and then click Save.

    4. Click Administrators and add Add Administrators.

    5. Search for and select the user orgb_admin, and then click Save.

  6. Go back to the Alpha realm - Organization page.

You now have two alpha realm organizations, OrgA and OrgB, each with an assigned administrator.

New organizations in the alpha realm

Task 3: Add members to the organizations

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

  2. On the Manage Identities page, click settings_system_daydream Alpha realm - Organizations.

  3. Add members to OrgA:

    1. Click OrgA.

    2. Click Members and add Add Members.

    3. Search for and select orga_emorris and orga_flandry, and then click Save.

      The selected users are added to OrgA.

      OrgA members

  4. Go back to the Alpha realm - Organization page.

  5. Add members to OrgB:

    1. Click OrgB.

    2. Click Members and add Add Members.

    3. Search for and select orgb_ajarvis and orgb_mpattison, and then click Save.

      The selected users are added to OrgB.

      OrgB members

  6. Go back to the Alpha realm - Organization page.

Check in

At this point, you:

Created new users in the alpha realm.

Created two organizations in the alpha realm.

Assigned an administrator to each organization.

Added two members to each organization.

Validation

Now that you have set up your organizations and assigned administrators to them, you are ready to validate the configuration.

The steps in this validation check that organization administrators only have access to users who are members of their organizations. An additional step checks that the organization administrator can update the details of an individual user within their organization.

To restrict the access organization (delegated) administrators have in Advanced Identity Cloud, organization administrators access user management functions through the Advanced Identity Cloud end-user UI and not the Advanced Identity Cloud admin UI.

Steps

  1. In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click on the Login journey provided as default in Advanced Identity Cloud.

  2. Copy and paste the Preview URL into an Incognito window.

    The login page for the tenant displays.

  3. In the Sign In page, enter the username and password for orga_admin, and then click Next.

    You are logged in to the Advanced Identity Cloud end-user UI as the OrgA admin. The left panel includes two administration menu items: settings_system_daydream Alpha realm - organization and people Alpha realm - user. These menu items display to an end user when they are a delegated administrator.

    Org administrator end user dashboard

  4. Click people Alpha realm - user.

    Only the users you added as OrgA members are listed (orga_emorris and orga_flandry).

    OrgA members

  5. Log out of the Advanced Identity Cloud end-user UI .

  6. In the Sign In screen, enter the username and password for orgb_admin, and then click Next.

  7. Click people Alpha realm - user.

    Only the users you added as OrgB members are listed (orgb_ajarvis and orgb_mpattison).

    OrgB members

  8. Click on orgb_mpattison.

  9. Enter a phone number in the Telephone Number field, and then click Save.

  10. Verify the updated user details:

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

    2. Search for orgb_mpattison.

      The phone number you added as the OrgA administrator is shown in the Telephone Number field.

      User with a telephone number added by the organization admistrator

To explore the role of organization administrators further, check out the other options in the Advanced Identity Cloud end-user UI. Organization administrators can do the following within their organization:

  • Add and update organization members.

  • Add and update sub-organizations.

  • Delegate user identity administration through roles and assignments.

Learn more in Administration.

Explore further

Reference material

Reference Description

Structure identities using organizations

An overview of organizations in Advanced Identity Cloud. Includes an example to help explain organization concepts.

Organizations

A deeper dive into organizations.

Realms

Realms are administrative units that group configurations and identities together.

Realms let you manage different sets of identities and applications within the same Advanced Identity Cloud tenant. Each realm is fully self-contained and operates independently of other realms within a tenant.

Admin interfaces in Advanced Identity Cloud

Get to know the admin interfaces; Advanced Identity Cloud admin UI, AM admin UI, and IDM admin UI.

Use case: Configure organizations in PingOne Advanced Identity Cloud

A guided walkthrough on configuring organizations, including setting up owners, administrators, and members.

Also explores how to delegate a subset of administration tasks to certain users based on an internal role.

Organization roles and privileges - ForgeRock University

A guided walkthrough video describing the Organization managed object.

Demo: Implement the organization - ForgeRock University

A guided walkthrough video demonstrating how to build an example organization.

Enable managers to manage their direct reports

Description

Estimated time to complete: 20 minutes

In this use case, you configure delegated administration to let managers update their direct reports' information and assign provisioning roles to them through the Advanced Identity Cloud end-user UI.

You’ll need to use Relationship-derived virtual properties (RDVPs) to filter users based on their manager relationships in the Advanced Identity Cloud end-user UI. This approach stores references to the target objects of a relationship as a property of the source object, enabling their use in privilege filters.

Goals

After completing this use case, you will know how to do the following:

  • Define a virtual property to use as a privilege filter.

  • Set up relationship notifications.

  • Configure delegated administration by creating an internal role with privileges.

  • Test delegated administration in the Advanced Identity Cloud end-user UI.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

Learn more about creating test users in Create test users and roles.

Tasks

Task 1: Define a virtual property to use as a privilege filter

In this task, you define a virtual property to store the manager ID. To achieve this, you can modify an indexed general purpose extension attribute. The example uses frindexedstring1.

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. In the left menu pane, select Native Consoles > Identity Management.

  3. Click Configure > Managed Objects and select Alpha_user.

  4. Click the pencil icon () next to frIndexedString1.

  5. On the Details tab, enter the following information:

    Field Value

    Readable title

    custom_managerID

    Description

    Manager’s ID

    1. Click Show advanced options.

    2. Select Virtual and Return By Default.

      Virtual property - Details tab

    3. Click Save.

  6. Click the Query Configuration tab and enter the following information:

    Field Value

    Referenced Relationship Fields

    ["manager"]

    Referenced Object Fields

    _id

    Flatten Properties

    Select the checkbox.
    Virtual property - Query Configuration tab

  7. Click Save.

With this configuration, whenever an alpha_user object is updated, Advanced Identity Cloud will resolve its manager relationship and store the relationship data in the frindexedstring1 property along with the updated object.

Task 2: Set up relationship notifications

In this task, you configure relationship notifications so that a user object is notified whenever its manager relationship changes. Relationship notifications are triggered by any activities related to an object update, including the onUpdate and postUpdate, script hooks, and implicit synchronization.

Relationship notifications are necessary because an object can be impacted by a relationship change even if it is not the direct target of the change. Without these notifications, the user object won’t receive updates. Since manager/reports is a reverse relationship, you must ensure the user object is notified when a report is added to a manager.

Enable “Notify Self” on the manager relationship property

  1. In the Identity Management native console, click Configure > Managed Objects, and then select Alpha_user.

  2. Click the manager relationship property.

  3. On the Details tab, click Show advanced options.

  4. Select Notify Self.

  5. Click Save.

    Manager property with Notify Self selected
Enable notifications on the reports relationship property

  1. In the Identity Management native console, return to Configure > Managed Objects > Alpha_user.

  2. Click the reports relationship property.

  3. On the Details tab > Relationship Configuration, click the pencil icon () next to alpha_user.

  4. Select Notify, and then click Save.

    Reports property with Notify selected

Task 3: Assign a manager user (testmanager1) to a report user (testuser1)

In this task, you assign a manager to the report user.

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

  2. On the Manage Identities page, click settings_system_daydream Alpha realm - Users.

  3. Search for and select testuser1.

  4. Scroll down to the Manager field and enter the manager. In our example, this is testmanager1.

    Test user record with manager populated

  5. Click Save.

  6. Click [.label]Raw JSON# and notice that the frIndexedString1 field is populated, similar to this:

     "frIndexedString1": "4d130ce4-1cc9-40c8-899d-468ec1ef0161"
Check in

At this point, you:

Defined a virtual property in the Alpha realm to use as a privilege filter.

Set up relationship notifications.

Added the test manager to the test user.

Task 4: Configure delegated administration privileges

In this task, you create an internal role with privileges and assign it to managers, enabling them to view and manage their direct reports through the Advanced Identity Cloud end-user UI.

Create an internal managers role with privileges

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

  2. On the Manage Identities page, click peopleInternal Roles.

  3. Click + New Internal Role.

  4. Enter the following information, and then click Next:

    Field Value

    Name

    managers

    Description

    Role for managers

  5. Select Alpha Realm Users - managed/alpha_user from the drop-down list, and then click Add.

  6. Select the View and Update checkboxes, and then click Show advanced.

  7. Under Attribute Permissions, click set all attributes, and select None.

  8. Scroll through the list of attributes and enable the ones to be exposed to the manager:

    • Set userName, givenName, cn and sn to Read.

    • Set description and roles to Read/Write.

      Internal managers role permissions

  9. Select Administer only a subset of Alpha realm - Users by applying a filter.

  10. Click Advanced Editor and enter the following query expression:

    frIndexedString1 eq "{{_id}}""

    This filter condition means that only objects that have a property named frIndexedString1 whose value matches the value of the authenticated user’s _id are returned.

    Internal role permissions query expression

  11. Click Next.

  12. Click Next (without setting a dynamic internal role assignment).

  13. Click Save (without setting a time constraint).

Assign the internal role to the manager user (testmanager1)

  1. Click the Members tab for the newly created manager internal role.

  2. Click Add Members.

  3. Select testmanager1.

  4. Click Save.

Internal managers role assigned to test manager
Check in

At this point, you:

Defined a virtual property in the Alpha realm to use as a privilege filter.

Set up a relationship notifications.

Added the test manager to the test user.

Created an internal managers role with privileges and assigned the internal role to the test manager user.

Validation

You are now ready to validate the configuration.

Steps

  1. In an Incognito browser window, go to the Advanced Identity Cloud end-user UI login URL.

  2. In the Sign In page, enter the username and password for testmanager1, and then click Next.

    Alpha realm - User appears as a menu option on the left menu pane, enabling managers to view and manage their direct reports.

    Manage reports through though the Advanced Identity Cloud end-user UI

  3. Click Alpha realm - User.

    The manager’s direct reports are listed (just testuser1 in this example).

    Manager’s reports listed in the Advanced Identity Cloud end-user UI

  4. Click testuser1.

    Testuser1 details in Advanced Identity Cloud end-user UI

The manager can make updates to their report users' details based on the attribute permissions defined in the internal role.

Explore further

Reference material

Reference Description

Advanced Identity Cloud identity schema

An overview of the identity schema used to organize users, roles, assignments, groups, organizations, and applications.

Relationships

An overview of relationships in the identity model.

Relationship-derived virtual properties (RDVPs)

An overview of virtual properties that can be calculated based on relationships and relationship notifications.

Roles and assignments

An overview of building an entitlement structure in Advanced Identity Cloud.

Modeling Identities - ForgeRock University

On-demand training videos and demos on identity modeling in Advanced Identity Cloud.

Provision data between Advanced Identity Cloud and PingDirectory

Description

Estimated time to complete: 1 hour.

In this use case, you configure two apps in Advanced Identity Cloud to provision data to and from PingDirectory using the LDAP app template via a remote connector server (RCS).

Goals

After completing this use case, you will know how to do the following:

  • Create an authoritative app to provision data to Advanced Identity Cloud.

  • Create a target app to provision data from Advanced Identity Cloud.

  • Let Advanced Identity Cloud communicate with an on-premise external data store, a PingDirectory server, by installing a remote connector server (RCS), also referred to as a remote server, and using an LDAP connector.

  • Map attributes between Advanced Identity Cloud and an external data source.

  • Determine the actions Advanced Identity Cloud takes with synchronization situations.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

Tasks

The following tasks assume you have access to a server with PingDirectory installed. Substitute your own environment and PingDirectory details as necessary.

Task 1: Download remote server

Advanced Identity Cloud uses a remote server to connect to on-premise external data stores. The remote server contains bundled connectors.

Register a remote server

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. In the left menu pane, go to Identities > Connect and click + New Connector Server.

  3. In the New Connector Server dialog box, provide the following:

    Name — This name displays in the Connector Servers list.
    Use only lowercase letters and numerals. Underscores and hyphens are the only special characters allowed. In this case, enter ping-directory.

  4. Click Save. This creates an OAuth2 client.

When the remote server is successfully registered, links display the next steps. Be sure to open each link in a different window or tab, so you always have access to the Next Steps dialog box. These steps are listed in the following sections.

The next steps page after registering a remote server in Advanced Identity Cloud
Reset the client secret and download remote server

  1. Under the Client Credentials box, next to the Client Secret field, click Reset.

  2. In the Reset Client Secret dialog box, enter any string to serve as a password.

  3. Read the warning, and then click Save.

  4. Go to Identities > Connect, and click ping-directory.

  5. Under the Quick Start box, click the Download a connector server link. You’re redirected to the IDM Cloud Connectors download page.

    • Log in to Backstage.

    • Download the remote server to the host that runs the connector server.

      We recommend you use the Java version of RCS. Only download the .NET version if you need to use a PowerShell connector. For more information about the differences between the RCS types, learn more in Install a Remote Connector Server (RCS).

      You can run the connector server on the same host as the external data source or you can run it on a different host. For example, you could download the remote server to a different server that has connectivity to the external data source

Task 2: Configure the remote server

  1. On the server you downloaded RCS, unpack the remote server you downloaded in task 1.

  2. On the remote server, open ConnectorServer.properties. This file includes the configurations to connect to your Advanced Identity Cloud tenant.

    The path to this file may differ depending on the version and type of remote server you download.

  3. The remote server (OAuth2 client) uses the Client Credentials grant type. To add the OAuth2 client credentials, operational, and security settings, specify the following values in ConnectorServer.properties:

    The default values in ConnectorServer.properties serve as starting configurations for your remote server. Adjust the properties to the needs of your organization.
    ConnectorServer.properties
    Field Value Description

    connectorserver.url

    Uncomment and update to connectorserver.url=wss://<tenant-env-fqdn>/openicf/0.

    This is the Advanced Identity Cloud OpenICF endpoint.

    • In sandbox or development environments, use only one URL. Example:
      connectorserver.url=wss://<tenant-env-fqdn>/openicf/0

    • In staging and production environments, use three URLs in a space-delimited list. For example: connectorserver.url=wss://<tenant-env-fqdn>/openicf/0 wss://<tenant-env-fqdn>/openicf/1 wss://<tenant-env-fqdn>/openicf/2

    connectorserver.connectorServerName

    The name of the remote server in Advanced Identity Cloud to connect to. Uncomment and enter the name of the remote server (OAuth2 client) you created in task 1.

    For example, connectorserver.connectorServerName=ping-directory.

    The name of the remote server (OAuth2 client) in Advanced Identity Cloud to connect to.

    connectorserver.pingPongInterval

    Uncomment and don’t modify.

    The WebSocket Ping/Pong interval, in seconds. The default is 60 seconds.

    connectorserver.housekeepingInterval

    Uncomment and don’t modify.

    The WebSocket connections housekeeping interval, in seconds. The default is 20 seconds.

    connectorserver.groupCheckInterval

    Uncomment and don’t modify

    The WebSocket groups check interval, in seconds. The default is 60 seconds.

    connectorserver.webSocketConnections

    Uncomment and don’t modify.

    Specifies the number of sockets the connector server establishes and maintains to each Advanced Identity Cloud (IDM) backend instance. The default is 3.

    connectorserver.connectionTtl

    Uncomment and don’t modify.

    The WebSocket connection’s time to live (ttl), in seconds. The default is 300 seconds.

    connectorserver.newConnectionsInterval

    Uncomment and don’t modify.

    The time between new connections, in seconds. The default is 10 seconds.

    connectorserver.tokenEndpoint

    Uncomment and update to connectorserver.tokenEndpoint=https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token.

    The token endpoint to retrieve the access token.

    connectorserver.clientId

    Update to connectorserver.clientId=RCSClient.

    When you create a remote server in Advanced Identity Cloud, Advanced Identity Cloud sets the clientId to RCSClient.

    connectorserver.clientSecret

    Update to connectorserver.clientSecret=client-secret.

    Enter the client secret you reset.

    The client secret for the OAuth2 client.

    connectorserver.scope

    Uncomment and update to connectorserver.scope=fr:idm:*.

    The OAuth2 token scope. The scope fr:idm:* gives access to /openidm/* (identity-related) API endpoints.

    connectorserver.loggerClass

    Don’t modify. Ensure the key/value pair is connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog.

    The logging class the remote server uses.

    You don’t need to set the connectorserver.usessl property; the remote server determines connection security from the value of the connectorserver.url property.

  4. Save the file.

  5. Start the remote server from the openicf-zip-<version>\openicf directory by running one of the following commands:

    • Windows

    • Linux

    bin\ConnectorServer.bat /run

    If the server starts successfully, the following (or similar) displays: RCS <version> started.

    bin/ConnectorServer.sh /run

    If the server starts successfully, the following (or similar) displays: RCS 1.5.20.15 started.

    This starts the remote server for the terminal session only. Consider creating a job to start or stop your remote server(s).

  6. To verify that the connection between Advanced Identity Cloud and the remote server is successful, in the Advanced Identity Cloud admin UI, navigate to Identites > Connect.

    The Status column of the remote server, in this case, ping-directory, displays Connected.

    If the status is Waiting to connect…​, make sure the server where the remote server resides is connected to Advanced Identity Cloud. Verify the properties you set in ConnectorServer.properties are correct.
    To view the bundled connectors with RCS, select the connected remote serve in Advanced Identity Cloud and click the Connectors tab. Learn more about each connector in the Connector reference.
Check in

At this point, you:

Registered the remote server and reset the client secret in Advanced Identity Cloud.

Downloaded and installed the remote server on the same server (or a server with connectivity) to the PingDirectory server.

Configured the remote server ConnectorServer.properties file to specify settings, namely, the connection details between the remote server and Advanced Identity Cloud.

Task 3: Create authoritative LDAP app to provision users from PingDirectory server

In Advanced Identity Cloud, you create one app to provision data from an external data source and another app to provision data from Advanced Identity Cloud. In both situations, you use RCS to facilitate the connection between the two.

This task configures an authoritative app to provision data from PingDirectory to Advanced Identity Cloud.

  1. From the Advanced Identity Cloud admin UI, go to Applications and click grid_view Browse App Catalog.

  2. In the Filter apps search box, enter and select LDAP.

    Select the latest application version.

  3. Click Next.

  4. Click Next again.

  5. Enter the following details:

    Field Value Description

    Name

    Enter PingDirectory - Authoritative.

    N/A

    Description

    Enter This app is to provision data from the PingDirectory server to Advanced Identity Cloud.

    Optional. The purpose of the app.

    Owners

    Select the test user you created in Advanced Identity Cloud to be the app owner.

    Every app has an owner. The owner is responsible for the app, including the details and the users and roles who have access to the app.

    App Logo URI

    Don’t modify.

    The location of the app logo.

    Authoritative

    Enable.

    If you want the app to be authoritative, enable this field. When enabled, synchronization can only happen from the app to Advanced Identity Cloud, and Advanced Identity Cloud can’t push changes to the app. If you don’t enable this field, Advanced Identity Cloud can provision data to the app.

  6. Click Create App. Advanced Identity Cloud redirects you to the newly created app.

  7. Enter the connection details for the app by going to the Provisioning tab and clicking Set up Provisioning.

  8. Enter the following details:

    Field Value Description

    Host Name or IP

    Enter the host name or IP of the server where you installed the remote server. If entering the IP address leads to a connection failure, try the host name.

    N/A

    Port

    Enter the port to connect to the PingDirectory server. For example, 389. In a production scenario, use a common secure port, such as 1636.

    The server must be actively waiting for inbound requests on this port, and firewall policies must be in place to allow Advanced Identity Cloud to connect to the server via this port.

    Learn more about the port the server is listening on in PingDirectory LDAP connection handler.

    Use SSL

    Disable

    Enabled by default. In a production scenario, enable.

    Login Account DN

    Enter the name of the administrator service account to connect to the server. For example, cn=Directory Manager.

    N/A

    Password

    Enter the password of the administrator service account to connect to the server.

    N/A

    Base DNs

    Enter base DNs that include your users and groups.

    For example, DC=example,DC=com.
    Connection settings for the authoritative PingDirectory app

  9. Click Connect. Advanced Identity Cloud uses the remote server that has connectivity to the PingDirectory server. On the Provisioning tab, the status Connected displays.

    If you receive an error connecting to the PingDirectory server, ensure your connection details are correct. If the error persists, check the PingDirectory server error log.

  10. On the Provisioning tab, click Data to confirm that you’re reading data from PingDirectory.

    Advanced Identity Cloud connected to a PingDirectory server using the LDAP app template

Task 4: Map attributes from the PingDirectory server to Advanced Identity Cloud

Now that you’ve connected the PingDirectory server to Advanced Identity Cloud, you must map and correlate the attributes between the two:

Because of hashing compatibility and because organizations typically have a phased approach to migrating passwords, this use case doesn’t map or migrate passwords.

  1. In the PingDirectory - Authoritative app, click Mappings > add Add a property.

  2. In the Ping Identity Property field, select userName.

  3. Click Next.

  4. In the PingDirectory - Authoritative Property field, select source.uid.

  5. Click Save.

  6. Repeat steps 2 - 5 for the following fields:

    Ping Identity property PingDirectory property

    mail

    source.mail

    givenName

    source.givenName

    sn

    source.sn

    When you create a mapping, you must specify the attributes required by the Advanced Identity Cloud managed object, which is the alpha_user managed object in this use case. Otherwise, you will experience an error during object creation.

    In a default Advanced Identity Cloud tenant, the required properties are userName, givenName, sn, and mail.

    Learn more in property definition fields.
Correlate user attributes

Now that you’ve mapped attributes between PingDirectory to Advanced Identity Cloud, ensure that you also correlate user attributes between the PingDirectory Authoritative app and Advanced Identity Cloud. Correlation ensures user account updates match between Advanced Identity Cloud and the application. In this use case, correlation would apply to the userName attribute.

The Account Correlation section of the Reconciliation > Settings tab lets you choose the attributes to use to match users in the PingDirectory Authoritative app to users in the Advanced Identity Cloud admin UI:

  1. On the Reconciliation > Settings tab, navigate to the Account Correlation section.

  2. Click Match using.

  3. In the Attribute(s) to Match dropdown list, choose the attributes to use to match users in the PingDirectory Authoritative app to users in Advanced Identity Cloud admin UI.

  4. To use a query to set or edit match attributes, click Use advanced query.

    • For an authoritative application:

      1. Choose to correlate a user if any or all attributes are matched.

      2. Use the User property field to set the user property to match.

    • For a target application:

      • Edit the correlation query script.

  5. Click Save.

Learn more about correlating user attributes in Configure basic and advanced correlation between accounts.

Check in

At this point, you:

Registered the remote server and reset the client secret in Advanced Identity Cloud.

Downloaded and installed the remote server on the same server or on a server with connectivity to the PingDirectory server.

Configured the remote server ConnectorServer.properties file to specify settings, specifically the connection details between the remote server and Advanced Identity Cloud.

Created an authoritative LDAP app to provision data from PingDirectory to Advanced Identity Cloud.

Mapped attributes from the PingDirectory server to Advanced Identity Cloud.

Correlated user accounts between the PingDirectory - Authoritative app and Advanced Identity Cloud.

Task 5: Create target LDAP app to provision users to PingDirectory server from Advanced Identity Cloud

In the previous task, you created an authoritative app and connected the PingDirectory server to Advanced Identity Cloud to prepare to provision data into Advanced Identity Cloud.

In this task, you create an app to provision data from Advanced Identity Cloud to the PingDirectory server.

  1. From the Advanced Identity Cloud admin UI, go to Applications and click grid_view Browse App Catalog.

  2. In the Filter apps search box, enter and select LDAP.

    Select the latest application version.

  3. Click Next.

  4. Click Next again.

  5. Enter the following details:

    Field Value Description

    Name

    Enter PingDirectory - Target.

    N/A

    Description

    Enter This app is to provision data from Advanced Identity Cloud TO the PingDirectory server.

    Optional. The purpose of the app.

    Owners

    Select the test user you created in Advanced Identity Cloud to be the app owner.

    Every app has an owner. The owner is responsible for the app, including the details and the users and roles who have access to the app.

    App Logo URI

    Don’t modify.

    The location of the app logo.

    Authoritative

    Don’t enable.

    When enabled, synchronization can only happen from the app to Advanced Identity Cloud and Advanced Identity Cloud can’t push changes to the app. If you don’t enable this field, Advanced Identity Cloud can provision data to the app.

  6. Click Create App. Advanced Identity Cloud redirects you to the newly created app.

  7. Enter the connection details for the app by going to the Provisioning tab and clicking Set up Provisioning.

  8. Enter the following details:

    Field Value Description

    Host Name or IP

    Enter the host name or IP of the server where you installed the remote server. If entering the IP address leads to a connection failure, try the host name.

    N/A

    Port

    Enter the port to connect to the PingDirectory server.

    For example, 389. In a production scenario, use a common secure port, such as 1636.

    The server must be actively waiting for inbound requests on this port and firewall policies must be in place to allow Advanced Identity Cloud to connect to the server via this port.

    Learn more in PingDirectory LDAP connection handler.

    Use SSL

    Disable

    Enabled by default. In a production scenario, enable.

    Login Account DN

    Enter the name of the administrator service account to connect to the server. For example, cn=Directory Manager.

    N/A

    Password

    Enter the password of the administrator service account to connect to the server.

    N/A

    Base DNs

    Enter base DNs that include your users and groups.

    For example, DC=example,DC=com.
    Connection settings for the target PingDirectory server

  9. Click Connect. Advanced Identity Cloud uses the remote server that has connectivity to the PingDirectory server. On the Provisioning tab, the status Connected displays.

    If you receive an error connecting to the PingDirectory server, ensure your connections details are correct. If the error persists, check the PingDirectory server error log.

  10. On the Provisioning tab, click Data to confirm that you’re reading data from PingDirectory.

    Advanced Identity Cloud connected to a PingDirectory server using the LDAP app template

Task 6: Map attributes from Advanced Identity Cloud to the PingDirectory server

By default, Advanced Identity Cloud maps attributes in the target app; however, you must add attributes to suit your specific needs. In this instance, you must add additional PingDirectory attributes.

  1. From the PingDirectory - Target app, click Mappings > Outbound > add Add a property.

  2. In the PingDirectory - Target Property field, select uid.

  3. Click Next.

  4. In the ForgeRock field, select source.userName.

  5. Click Save.

  6. Again, click add Add a property.

  7. In the PingDirectory - Target Property field, select dn.

  8. In the ForgeRock field, select source.userName.

  9. Enable Apply transformation script.

  10. Transform the dn attribute to match your directory structure. For example, enter the following in the Transformation Script box:

    "uid=" + source + ",ou=People,dc=example,dc=com"
    Adding a transformation script to create the distinguished name (dn) in the PingDirectory server

  11. Click Save.

Task 7: Configure situations and actions for both apps

  1. Select the PingDirectory - Authoritative app.

  2. From the Provisioning tab, click Reconciliation > Settings.

  3. Under the Situation Rules section, set the following actions for each situation:

    Situation Action

    Ambiguous

    Select Exception.

    Source Missing

    Authoritative apps only.

    Select Exception.

    Missing

    Select Create.

    Found Already Linked

    Select Exception.

    Unqualified

    Select Delete.

    Unassigned

    Select Exception.

    Link Only

    Select Unlink.

    Confirmed

    Select Update.

    Found

    Select Update.

    Absent

    Select Create.

    For descriptions of the situations and actions, learn more in Manage reconciliation rules.

  4. Repeat steps 2 and 3 for the PingDirectory - Target app.

Check in

At this point, you:

Registered the remote server and reset the client secret in Advanced Identity Cloud.

Downloaded and installed the remote server on the same server (or a server with connectivity) to the PingDirectory server.

Configured the remote server ConnectorServer.properties file to specify settings, namely, the connection details between the remote server and Advanced Identity Cloud.

Created an authoritative LDAP app to provision data from PingDirectory to Advanced Identity Cloud.

Mapped attributes from the PingDirectory server to Advanced Identity Cloud.

Created an LDAP app to provision data from Advanced Identity Cloud to the PingDirectory server.

Mapped attributes from Advanced Identity Cloud to the PingDirectory server.

Configured the situations and actions for both apps.

Validation

Validate provisioning data to and from Advanced Identity Cloud and the PingDirectory server by:

  • Provisioning one user from PingDirectory into Advanced Identity Cloud.

  • Adding a user to the PingDirectory - Target app.

Provision user from the PingDirectory server

  1. From the Advanced Identity Cloud admin UI, click Applications > PingDirectory - Authoritative.

  2. Click the Provisioning tab. To show provisioning a user into Advanced Identity Cloud, restrict the reconciliation to one user matching a defined criteria.

  3. Under Reconciliation > Settings, click Show advanced settings.

  4. Enable the Filter Source checkbox (PingDirectory is the source) and fill out the following details:

    Field Value

    Assign to PingDirectoryAuthoritative if Any keyboard_arrow_down conditions are met

    Select Any.

    PingDirectoryAuthoritative properties keyboard_arrow_down

    Select uid.

    contains keyboard_arrow_down

    Select is.

    Blank

    Enter the uid of the user you want to pull in from the PingDirectory server.
    Filter reconciliation to be a single user

  5. Scroll down and click Save.

  6. In the left tabs, click Reconciliation > Reconcile.

  7. Click Reconcile Now. Monitor the progress of the reconciliation in the metrics that display. Since you are filtering to reconcile only one user, failures on the reconciled data are expected.

  8. In the left menu pane, Identities > Manage > Alpha realm - Users and search for the user. The user successfully displays in Advanced Identity Cloud.

    If the user doesn’t display, check the following:

    • The fields Advanced Identity Cloud required to create an identity are present in the inbound mapping.

    • The source filtering to reconcile only one record is correct.

Provision a user to the PingDirectory server

  1. From the Advanced Identity Cloud admin UI, click Applications > PingDirectory - Target.

  2. Click the Users & Roles tab.

  3. Click add Add Member.

  4. Select a test user.

  5. Click Next.

  6. Review the account information.

  7. Click Assign. The user successfully creates in the PingDirectory server.

  8. From the Provisioning tab, click Data.

  9. The user successfully displays from the read-only view of the PingDirectory server data.

Video of validation

The following video displays the expected validation for provisioning a user from a PingDirectory server to Advanced Identity Cloud and provisioning a user from Advanced Identity Cloud to a PingDirectory server.

Explore further

Reference material

Reference Description

Sync identities

Register and connect a remote server with Advanced Identity Cloud.

Introduction to the PingDirectory server

Learn about PingDirectory including system requirements, installation requirements, and loading sample data.

Register an application using app templates

Gain an in-depth understanding of registering an application using app templates.

LDAP provisoning

Learn how to connect an LDAP server to Advanced Identity Cloud.

Add or edit a mapping

Learn how to add or edit mappings with application templates.

Reconciliation rules

Learn the various actions you can take on reconciliation situations. For example, if the situation is ABSENT (account not present or found) Advanced Identity Cloud can perform the CREATE action (create the object).

Identity object fields

Understand identity object fields you can modify, such as setting a property as required or whether an end user can update the property in the Advanced Identity Cloud end-user UI.

Synchronization types

Understand the various synchronization types Advanced Identity Cloud uses to keep data consistent: reconciliation, liveSync, and implicit synchronization.

PingOne Open Connector Framework (ICF)

Learn more about connectors. This includes connectors bundled with RCS and connectors you can download and add to the remote server.

Provision users from Microsoft Entra ID (Azure AD)

Description

Estimated time to complete: 30 minutes

In this use case, you provision accounts from Microsoft Entra ID (formerly Azure AD) into Advanced Identity Cloud.

Goals

In completing this use case, you will learn how to do the following:

  • Use the Advanced Identity Cloud admin UI

  • Set up a Microsoft Entra ID application as an authoritative identity data source

  • Provision identity data from the application to Advanced Identity Cloud

  • Enable incremental reconciliation

Prerequisites

Before you start work on this use case, make sure you have:

  • A basic understanding of:

    • The Advanced Identity Cloud admin UI

    • The managed/alpha_user object schema

    • Application templates

    • Reconciliation

  • Access to your Microsoft Entra ID tenant environment as an administrator

  • Access to your Advanced Identity Cloud development environment as an administrator

  • A test user in Advanced Identity Cloud to serve as the application owner for the Microsoft Entra ID application

Tasks

Task 1: Create a Microsoft Entra ID application

Some steps require you to copy information. Paste the information into a text editor to keep track.

Advanced Identity Cloud uses a Microsoft Entra ID application account to connect to Microsoft Entra ID through the Microsoft Graph API. To register the application in Advanced Identity Cloud, make sure you record:

  • The tenant ID

  • The client ID

  • The client secret—​the value of the secret, not the secret ID

You register the application and set the Graph API permissions Advanced Identity Cloud requires.

  1. Sign in to the Microsoft Entra ID tenant as administrator.

  2. Select Home > + Add > App registration.

  3. Set a Name and click Register.

  4. On the profile page for the application you registered, record the values for:

    • Application (client) ID

    • Directory (tenant) ID

  5. On the profile page for the application you registered, select Client credentials > Client secrets > + New client secret and add a client secret.

    Record the client secret for use when configuring the connection from Advanced Identity Cloud. You cannot retrieve the secret after leaving the page where you created it.

  6. On the profile page for the application you registered, select API permissions > + Add a permission and add the following Microsoft Graph API permissions:

    • User.Export.All

    • User.ManageIdentities.All

    • User.Read.All

    • User.ReadWrite.All

    • Group.Create

    • Group.Read.All

    • Group.ReadWrite.All

    • Directory.Read.All

    • Directory.ReadWrite.All

  7. On the API permissions page, select Grant admin consent for tenant.

    Each permission must have Granted for tenant status before you connect Advanced Identity Cloud to the Microsoft Entra ID tenant:

    Graph API permissions in the UI

    If you cannot grant the permissions yourself, ask the primary tenant administrator to grant the permissions.

Task 2: Create a Microsoft Entra ID test user account

To validate reconciliation, Advanced Identity Cloud requires at least one user with the required Advanced Identity Cloud properties:

  • An email address

  • A display name

  • A first name

  • A last name

Create the test account in Microsoft Entra ID:

  1. Sign in to the Microsoft Entra ID tenant as administrator.

  2. Select Home > + Add > User > Create new user.

  3. Prepare to create the user with the following settings:

    Field Value

    User principal name

    scarter@domain, where domain is the Microsoft Entra ID tenant domain

    Mail nickname

    Select Derive from user principal name.

    Display name

    Sam Carter

    Password

    Select Auto-generate password.

    This use case doesn’t use the password, but record the password so you can sign on to Microsoft Entra ID later.

    Account enabled

    Leave this selected.

    First name

    Sam

    Last name

    Carter

    Email

    scarter@example.com

  4. Review and create the test user account.

Check in

At this point, you:

Registered an Microsoft Entra ID application and recorded its tenant ID, client ID, and client secret.

Created a test user account with at least the required Advanced Identity Cloud account properties.

Task 3: Configure Microsoft Entra ID as an authoritative identity data source

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Application > grid_view Browse App Catalog > Azure AD Provisioning and click Next.

    Select the latest application version.

  3. Click Next again and create an application with the following settings:

    Field Value

    Name

    Microsoft Entra ID

    Owners

    The Advanced Identity Cloud test user to act as the owner of this application.

    Authoritative

    Enable.

  4. In the application profile screen, select Provisioning > Set up Provisioning, enter the information you collected when registering the Microsoft Entra ID application, and click Connect:

    Field Value

    Tenant

    The Directory (tenant) ID from Microsoft Entra ID; for example, f7ff6108-c26f-48dd-ae9e-9743eefbd11f.

    Client ID

    The Application (client) ID from Microsoft Entra ID; for example, b5ee41de-4a06-40ec-b170-1edbeb7c7764.

    Client Secret (optional)

    The value of the client secret from Microsoft Entra ID.

    The client secret is not optional for this use case.

  5. Make sure the Advanced Identity Cloud admin UI displays the application as Connected:

    Successful connection

  6. Select Data to display a table of details from accounts in Microsoft Entra ID.

    This confirms Advanced Identity Cloud can access the account properties.

Task 4: Configure reconciliation

Advanced Identity Cloud uses reconciliation to keep its accounts in sync with accounts in other systems. You configure:

  • How account properties in the other systems map to Advanced Identity Cloud account properties.

  • What Advanced Identity Cloud does in each reconciliation situation.

Inbound mapping

For this use case, configure at least a minimal inbound mapping:

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Application > Microsoft Entra ID > Provisioning > Mapping > Inbound.

  3. Review how an Microsoft Entra ID user account maps to the corresponding Advanced Identity Cloud alpha_user account:

    Use the default inbound mapping

  4. Adjust the inbound mapping to the following settings:

    Microsoft Entra ID user property Advanced Identity Cloud alpha_user property

    source.givenName

    givenName

    source.mail

    mail

    source.surname

    sn

    source.userPrincipalName

    userName

    Reconciliation only synchronizes mapped properties. If required, add additional mappings.

Reconciliation situations

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Application > Microsoft Entra ID > Reconciliation > Settings.

  3. Edit the default Situation Rules to set Link Only to UNLINK:

    Completed situation rules table

    Advanced Identity Cloud is now ready to provision user accounts from the Microsoft Entra ID tenant.

Check in

At this point, you:

Registered an Microsoft Entra ID application and recorded its tenant ID, client ID, and client secret.

Created a test user account with at least the required Advanced Identity Cloud account properties.

Used an application template to connect Advanced Identity Cloud to the Microsoft Entra ID tenant.

Configured Advanced Identity Cloud reconciliation to provision user accounts.

Task 5: Prepare reconciliation for validation

Although you can run reconciliation manually for initial synchronization and testing, you can also enable incremental reconciliation as a recurring task. Incremental reconciliation runs periodically, synchronizing new changes automatically.

For testing, you can restrict which accounts reconciliation synchronizes with a filter. After validating your work, you can disable the filter and reconcile all accounts.

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Application > Microsoft Entra ID > Reconciliation > Settings.

  3. Select Schedules > Incremental Reconciliation > Set Up and configure the task.

    For example, to run reconciliation every 15 minutes, select Use cron and set the Frequency to */15 * * * * ?:

    Configure a reconciliation task

  4. Select Show advanced settings and filter reconciliation to target only the Microsoft Entra ID test account.

    For example, select Filter Source and set the filter to match when the user mail is the test account email address:

    Filter on mail

  5. Click Save.

Validation

With Advanced Identity Cloud connected to Microsoft Entra ID as an authoritative identity data source, validate the configuration by provisioning an account from Microsoft Entra ID to Advanced Identity Cloud and receiving updates to the newly created Advanced Identity Cloud user.

Steps

Initial reconciliation

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. Select Application > Microsoft Entra ID > Provisioning > Reconciliation > Reconcile > Reconcile Now.

    Reconciliation creates the test user account from Microsoft Entra ID in Advanced Identity Cloud.

    On the reconciliation status page, Unresolved Microsoft Entra ID users is greater than zero. Advanced Identity Cloud found an Microsoft Entra ID user account and created an identity in Advanced Identity Cloud.

  3. Select Identities > Manage and search for the test user account.

    The Advanced Identity Cloud admin UI displays the new account reconciliation created based on the Microsoft Entra ID test user account.

Incremental reconciliation

  1. Sign in to the Microsoft Entra ID tenant as administrator.

  2. Select Home > Users > Select test user > Edit properties, change one of the mapped properties such as First name, and Save your change.

  3. Log in to the Advanced Identity Cloud admin UI as an administrator.

  4. Wait for reconciliation to run as scheduled or select Reconcile Now again in Advanced Identity Cloud admin UI.

    Reconciliation applies the changes you made in Microsoft Entra ID to the account in Advanced Identity Cloud.

    On the reconciliation status page, 1-to-1 match is greater than 0. Advanced Identity Cloud found an Microsoft Entra ID account with a matching Advanced Identity Cloud account and reconciled the two.

  5. Select Identities > Manage, search for the account, and select it to display the details.

    The Advanced Identity Cloud admin UI displays the change from the Microsoft Entra ID test user account.

Video of validation

From the administrator’s perspective, the validation process works as follows:

Explore further

Reference material

Reference Description

Admin UIs

Get to know the Advanced Identity Cloud admin UI.

Azure AD provisioning

Learn about connecting Advanced Identity Cloud to Microsoft Entra ID.

Reconcile and synchronize end-user accounts

Learn about reconciliation of user accounts.

Register an application

Find out more about application templates.

Synchronization types

Learn how Advanced Identity Cloud keeps data consistent across multiple systems.

Tutorial: Register an app with Microsoft Entra ID

Refer to this Microsoft Entra ID documentation for details.

Provision data from Active Directory (AD) using RCS

Description

Estimated time to complete: 1 hour

In this use case, you provision accounts from an on-premise AD server into Advanced Identity Cloud.

Goals

After completing this use case, you will know how to do the following:

  • Let Advanced Identity Cloud communicate with an on-premise external data store, Active Directory (AD), by installing a remote connector server (RCS), also referred to as a remote server, and using an AD LDAP connector.

  • Map attributes from AD to Advanced Identity Cloud.

  • Determine the actions Advanced Identity Cloud takes with synchronization situations.

  • Provision users from an on-prem external data source into Advanced Identity Cloud.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • A basic understanding of:

    • The managed/alpha_user object schema

    • Application templates

    • Advanced Identity Cloud remote connector servers (RCS)

    • PingOne Open Connector Framework (ICF)

    • Mappings

    • Reconciliation

    • Synchronization

    • Synchronization situations and actions

  • Access to your development environment as an administrator.

  • Access to an on-premise AD server (it can be a test server) that contains user test data with the following minimum properties on the user(s):

    • userPrincipalName (UPN) — Unique identifier for the user in AD. Typically, it’s in an email format.

    • mail — Email address

    • givenName — First name

    • sn — Last name

  • A test user in Advanced Identity Cloud that serves as the application owner for the Active Directory application.

  • A server to install the remote server on. The server must be able to connect to the on-premise AD server.

  • A Backstage account.

Tasks

The following tasks assume you have access to an AD server. Substitute your own environment and AD details as necessary.

Task 1: Download remote server

Advanced Identity Cloud uses a remote server to connect to on-premise external data stores. The remote server contains bundled connectors.

Register a remote server

  1. Log in to the Advanced Identity Cloud admin UI as an administrator.

  2. In the left menu pane, go to Identities > Connect and click + New Connector Server.

  3. In the New Connector Server dialog box, provide the following:

    Name — This name displays in the Connector Servers list.
    Use only lowercase letters and numerals. Underscores and hyphens are the only special characters allowed. In this case, enter ad-imp-guide.

  4. Click Save. This creates an OAuth2 client.

When the remote server is successfully registered, links display the next steps. Be sure to open each link in a different window or tab, so you always have access to the Next Steps dialog box. These steps are listed in the following sections.

The next steps page after registering a remote server in Advanced Identity Cloud
Reset the client secret and download remote server

  1. Under the Client Credentials box, next to the Client Secret field, click Reset.

  2. In the Reset Client Secret dialog box, enter any string to serve as a password.

  3. Read the warning, and then click Save.

  4. Go to Identities > Connect, and click ad-imp-guide.

  5. Under the Quick Start box, click the Download a connector server link. You’re redirected to the IDM Cloud Connectors download page.

    • Log in to Backstage.

    • Download the remote server to the host that runs the connector server.

      We recommend you use the Java version of RCS. Only download the .NET version if you need to use a PowerShell connector. For more information about the differences between the RCS types, learn more in Install a Remote Connector Server (RCS).

      You can run the connector server on the same host as the external data source or you can run it on a different host. For example, you could download the remote server to a different server that has connectivity to the external data source

Task 2: Configure the remote server

  1. On the server you downloaded RCS, unpack the remote server you downloaded in task 1.

  2. On the remote server, open ConnectorServer.properties. This file includes the configurations to connect to your Advanced Identity Cloud tenant.

    The path to this file may differ depending on the version and type of remote server you download.

  3. The remote server (OAuth2 client) uses the Client Credentials grant type. To add the OAuth2 client credentials, operational, and security settings, specify the following values in ConnectorServer.properties:

    The default values in ConnectorServer.properties serve as starting configurations for your remote server. Adjust the properties to the needs of your organization.
    ConnectorServer.properties
    Field Value Description

    connectorserver.url

    Uncomment and update to connectorserver.url=wss://<tenant-env-fqdn>/openicf/0.

    This is the Advanced Identity Cloud OpenICF endpoint.

    • In sandbox or development environments, use only one URL. Example:
      connectorserver.url=wss://<tenant-env-fqdn>/openicf/0

    • In staging and production environments, use three URLs in a space-delimited list. For example: connectorserver.url=wss://<tenant-env-fqdn>/openicf/0 wss://<tenant-env-fqdn>/openicf/1 wss://<tenant-env-fqdn>/openicf/2

    connectorserver.connectorServerName

    The name of the remote server in Advanced Identity Cloud to connect to. Uncomment and enter the name of the remote server (OAuth2 client) you created in task 1.

    For example, connectorserver.connectorServerName=ad-imp-guide.

    The name of the remote server (OAuth2 client) in Advanced Identity Cloud to connect to.

    connectorserver.pingPongInterval

    Uncomment and don’t modify.

    The WebSocket Ping/Pong interval, in seconds. The default is 60 seconds.

    connectorserver.housekeepingInterval

    Uncomment and don’t modify.

    The WebSocket connections housekeeping interval, in seconds. The default is 20 seconds.

    connectorserver.groupCheckInterval

    Uncomment and don’t modify

    The WebSocket groups check interval, in seconds. The default is 60 seconds.

    connectorserver.webSocketConnections

    Uncomment and don’t modify.

    Specifies the number of sockets the connector server establishes and maintains to each Advanced Identity Cloud (IDM) backend instance. The default is 3.

    connectorserver.connectionTtl

    Uncomment and don’t modify.

    The WebSocket connection’s time to live (ttl), in seconds. The default is 300 seconds.

    connectorserver.newConnectionsInterval

    Uncomment and don’t modify.

    The time between new connections, in seconds. The default is 10 seconds.

    connectorserver.tokenEndpoint

    Uncomment and update to connectorserver.tokenEndpoint=https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token.

    The token endpoint to retrieve the access token.

    connectorserver.clientId

    Update to connectorserver.clientId=RCSClient.

    When you create a remote server in Advanced Identity Cloud, Advanced Identity Cloud sets the clientId to RCSClient.

    connectorserver.clientSecret

    Update to connectorserver.clientSecret=client-secret.

    Enter the client secret you reset.

    The client secret for the OAuth2 client.

    connectorserver.scope

    Uncomment and update to connectorserver.scope=fr:idm:*.

    The OAuth2 token scope. The scope fr:idm:* gives access to /openidm/* (identity-related) API endpoints.

    connectorserver.loggerClass

    Don’t modify. Ensure the key/value pair is connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog.

    The logging class the remote server uses.

    You don’t need to set the connectorserver.usessl property; the remote server determines connection security from the value of the connectorserver.url property.

  4. Save the file.

  5. Start the remote server from the openicf-zip-<version>\openicf directory by running one of the following commands:

    • Windows

    • Linux

    bin\ConnectorServer.bat /run

    If the server starts successfully, the following (or similar) displays: RCS <version> started.

    bin/ConnectorServer.sh /run

    If the server starts successfully, the following (or similar) displays: RCS 1.5.20.15 started.

    This starts the remote server for the terminal session only. Consider creating a job to start or stop your remote server(s).

  6. To verify that the connection between Advanced Identity Cloud and the remote server is successful, in the Advanced Identity Cloud admin UI, navigate to Identites > Connect.

    The Status column of the remote server, in this case, ad-imp-guide, displays Connected.

    If the status is Waiting to connect…​, make sure the server where the remote server resides is connected to Advanced Identity Cloud. Verify the properties you set in ConnectorServer.properties are correct.
    To view the bundled connectors with RCS, select the connected remote serve in Advanced Identity Cloud and click the Connectors tab. Learn more about each connector in the Connector reference.
    The remote server connected to Advanced Identity Cloud
Check in

At this point, you:

Registered the remote server and reset the client secret in Advanced Identity Cloud.

Downloaded and installed the remote server on the same server where AD resides.

Configured the remote server ConnectorServer.properties file to specify settings, namely, the connection details between the remote server and Advanced Identity Cloud.

Task 3: Connect AD to Advanced Identity Cloud using AD LDAP connector app template

Now that Advanced Identity Cloud is connected to the intranet where AD resides via an installed remote server, Advanced Identity Cloud can now connect to AD.

  1. From the Advanced Identity Cloud admin UI, go to Applications and click grid_view Browse App Catalog.

  2. In the Filter apps search box, enter and select Active Directory.

    Select the latest application version.

  3. Click Next.

  4. Click Next again.

  5. Enter the following details:

    Field Value Description

    Name

    Enter AD Implementation Guide.

    N/A

    Description

    Enter Application used to connect to an on-premise AD server using a remote server.

    Optional. The purpose of the application.

    Owners

    Select the test user you created in Advanced Identity Cloud to be the test owner.

    Every application has an owner. The owner is responsible for the application, including the details and the users and roles who have access to the application.

    App Logo URI

    Don’t modify.

    The location of the application logo.

    Authoritative

    Enable.

    If you want the application to be authoritative, enable this field. When enabled, synchronization can only happen from the application to Advanced Identity Cloud and Advanced Identity Cloud can’t push changes to the application. If you don’t enable this field, Advanced Identity Cloud can provision data to the application.

  6. Click Create Application. Advanced Identity Cloud redirects you to the newly created application.

  7. Enter the connection details for the application by going to the Provisioning tab and clicking Set up Provisioning.

  8. Enter the following details:

    Field Value Description

    Host Name or IP

    Enter the host name or IP of the server where you installed the remote server. If entering the IP address leads to a connection failure, try the host name.

    N/A

    Port

    Enter the port to connect to your AD server. For example, 389. In a production scenario, use a common secure port, such as 1636.

    The AD server must be actively waiting for inbound requests on this port and firewall policies must be in place to allow Advanced Identity Cloud to connect to the AD server via this port.

    Use SSL

    Disable

    Enabled by default. In a production scenario, enable.

    Login Account DN

    Enter the name of the administrator service account to connect to the AD server.

    N/A

    Password

    Enter the password of the administrator service account to connect to the AD server.

    N/A

    Base DNs

    Enter base DNs that include your users and groups.

    For example, DC=example,DC=com.

  9. Click Connect. Advanced Identity Cloud uses the remote server that has connectivity to AD to connect to AD. On the Provisioning tab, the status Connected displays.

Task 4: Map attributes from AD to Advanced Identity Cloud

Now that you have registered the application and connected Advanced Identity Cloud to the AD server, you are ready to map the attributes from AD to Advanced Identity Cloud.

Review inbound mapping attributes

Inbound attributes are the attributes going from the external data store (AD) to Advanced Identity Cloud for provisioning operations.

All application templates are configured to auto-map attributes.

When you create a mapping, you must specify the attributes required by the Advanced Identity Cloud managed object, which is the alpha_user managed object in this use case. Otherwise, you will experience an error during object creation.

In a default Advanced Identity Cloud tenant, the required properties are userName, givenName, sn, and mail.

Learn more in property definition fields.

  1. From the left menu pane, go to Applications and select an application. In this case, click AD Implementation Guide.

  2. Click the Provisioning tab and make sure you select User.

  3. Click Mapping > Inbound. Observe the default mapping. The following image displays a sample of the auto-mapped attributes:

    Inbound mapping for AD
Configure sync situations and actions

Advanced Identity Cloud evaluates each record during the reconciliation process. When reconciling, Advanced Identity Cloud determines the state of the record, referred to as the situation. Based off the situation, Advanced Identity Cloud takes an action that you configure.

You define what action Advanced Identity Cloud takes in each situation.

For example, if reconciliation detects a record exists in the source but not in the target (the situation), in this case Advanced Identity Cloud, create the record in Advanced Identity Cloud (the action).

  1. From the Provisioning tab, click Reconciliation > Settings.

  2. Under the Situation Rules section, set the following actions for each situation:

    Situation Action

    Ambiguous

    Select Exception.

    Source Missing

    Select Exception.

    Missing

    Select Create.

    Found Already Linked

    Select Exception.

    Unqualified

    Select Delete.

    Unassigned

    Select Exception.

    Link Only

    Select Unlink.

    Confirmed

    Select Update.

    Found

    Select Update.

    Absent

    Select Create.

    For descriptions of the situations and actions, learn more in Manage reconciliation rules.

Situation rules for AD application
Check in

At this point, you:

Registered the remote server and reset the client secret in Advanced Identity Cloud.

Downloaded and installed the remote server where AD resides.

Configured the remote server ConnectorServer.properties file to specify settings, namely, the connection details between the remote server and Advanced Identity Cloud.

Registered the Active Directory application template.

Configured provisioning, which included:

  • Reviewing the auto-mapped inbound attributes from AD to Advanced Identity Cloud.

  • Configuring situation rules for synchronization.

Advanced Identity Cloud is now ready for provisioning. Normally, you would complete more tasks to reconcile users and set up schedules, however; for the purposes of this use case, those tasks are left for the following Validation section.

Validation

To test provisioning between AD and Advanced Identity Cloud, reconcile one user account and update the same user account in AD to observe the change in Advanced Identity Cloud.

These validations use the test user, Sam Carter. Substitute your test user as necessary.

Reconcile data from AD to Advanced Identity Cloud

Usually, you would want to reconcile an entire set of users from an external data source into Advanced Identity Cloud, however; for the purposes of this use case, only one account is reconciled. To reconcile one account, you must add a filter so that Advanced Identity Cloud only reconciles based on the filter.

  1. From the Provisioning tab, click Reconciliation > Settings.

  2. Scroll down and click Show advanced settings.

  3. Enable the Filter Source checkbox (AD is the source) and fill out the following details:

    Field Value

    Assign to ADImplementationGuide if Any keyboard_arrow_down conditions are met

    Select Any.

    ADimplementationguide properties keyboard_arrow_down

    Select mail.

    contains keyboard_arrow_down

    Select is.

    Blank

    Enter the email of the user you want to pull in from AD. The mail attribute must be populated in AD, and the email you enter must be an exact match. For example, enter samcarter@example.com.
    Filter reconciliation to be a single user

  4. Scroll down and click Save.

  5. In the left tabs, click Reconciliation > Reconcile.

  6. Click Reconcile Now. Monitor the progress of the reconciliation in the metrics that display. Since you are filtering to reconcile only one user, failures on the reconciled data is expected.

  7. In the left menu pane, Identities > Manage > Alpha realm - Users and search for the user. The user successfully displays in Advanced Identity Cloud.

    If the user doesn’t display, check the following:

    • The fields Advanced Identity Cloud requires to create an identity are present in the inbound mapping.

    • The source filtering to reconcile only one record is correct.

  8. Go into your AD server, and update the sn (last name) of your test user. In this example, update the sn to Changed.

  9. From the left menu pane, go to Applications and select AD Implementation Guide. In the Reconcile tab, click Reconcile Now again.

  10. Similar to step 7, locate the test user in Advanced Identity Cloud. The last name is updated.

You can set a schedule to perform a full or incremental reconciliation by going to Reconciliation > Settings. Learn more in reconciliation schedules.

Video of validation

The following video shows the expected validation provisioning a user from AD and updating that same user in AD to see additional reflected changes in Advanced Identity Cloud:

Explore further

Reference material

In this use case, you configured only one remote server, however; in a production scenario, register a server cluster and install remote servers on multiple servers for high-availability.
Reference Description

Sync identities

Register and connect a remote server with Advanced Identity Cloud.

Register an application using app templates

Gain an in-depth understanding of registering an application using app templates.

AD provisioning

Learn how to connect AD to Advanced Identity Cloud.

Add or edit a mapping

Learn how to add or edit mappings with application templates.

Reconciliation rules

Learn the various actions you can take on reconciliation situations. For example, if the situation is ABSENT (account not present or found) Advanced Identity Cloud can perform the CREATE action (create the object).

Managed object fields

Understand managed object fields you can modify, such as setting a property as required or whether an end user can update the property in the Advanced Identity Cloud end-user UI.

Synchronization types

Understand the various synchronization types Advanced Identity Cloud uses to keep data consistent: reconciliation, liveSync, and implicit synchronization.

PingOne Open Connector Framework (ICF)

Learn more about connectors. This includes connectors bundled with RCS and connectors you can download and add to the remote server.

Self-service

In PingOne Advanced Identity Cloud, many self-service activities take place during authentication in journeys and also relate to creating or updating identities. However, the use cases in this section specifically focus on end-user self-service:

Use case Description

User registration

Test the default registration journey to observe how it works. Then, duplicate it and make changes to meet your organization’s needs. Finally, register as a new end user using the updated registration journey.

Learn about additional self-service use cases in End user self-service.

User registration

Description

Estimated time to complete: 20 minutes

In this use case, you test the default registration journey to observe how it works. Then, you duplicate it and make changes to meet your organization’s needs. Finally, you register as a new end user using the updated registration journey.

To quickly test this user registration journey without building it from scratch, you can download it from the Ping Identity Integration Directory. Learn more in User Registration Journey.

Goals

After completing this use case, you will know how to create a new user registration journey.

Prerequisites

Before you start work on this use case, ensure you have these prerequisites:

  • Access to your Advanced Identity Cloud development environment as an administrator.

  • A basic understanding of journeys and nodes.

Tasks

Task 1: Test the default registration journey

  1. In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click on the Registration journey.

  2. In the Preview URL field, click copy and paste the URL into an Incognito window.

    The Sign Up page for the tenant displays.

  3. In the Sign Up page, enter the following details:

    Field Value

    Username

    asmith

    First Name

    Amy

    Last Name

    Smith

    Email Address

    asmith@example.com

    Password

    Ch4ng3it!

    Select a security question

    Select What’s your favorite color?

    Answer

    Red

  4. Click Next.

    You are logged into the Advanced Identity Cloud end-user UI as Amy Smith.

  5. Close the Incognito window and go back to the Advanced Identity Cloud admin UI.

  6. Go to people Identities > Manage.

  7. Enter asmith in the Search field and press Enter.

    The user asmith displays with the details you entered above:

    Confirm the new user

Task 2: Modify the default registration journey

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

  2. On the Journeys page, click the ellipsis icon () for the Registration journey and select Duplicate.

  3. In the Duplicate Journey window, enter the following details:

    Field Value

    Name

    User Registration

    Identity Object

    Alpha realm - Users managed/alpha_user

    Description

    Updated user registration journey.

  4. Click Save.

    The journey editor displays.

  5. In the journey editor, select the KBA Definition node in the Page Node and click delete to delete this node.

    This removes the security questions from the registration process.

  6. Search for the Email Suspend Node and drag it on to the journey canvas.

    The Email Suspend Node sends an email to the end user and only resumes the journey once they click a link in the email. In this case, they confirm their email address.

  7. Select the Platform Password node in the Page Node and drag it out of the node on to the journey canvas.

  8. Connect the Page Node outcome to the Email Suspend Node input.

  9. Connect the Email Suspend Node outcome to the Platform Password node input.

  10. Click the Email Suspend Node and review the default settings. You do not need to modify them.

    Email Suspend Node settings

    The Email Template Name field shows which email template is used in the journey.

  11. Connect the Platform Password node outcome to the Create Object node input.

  12. Click Save.

Check in
Updated user registration journey

At this point, the journey is configured to:

  • a Collect the username, user details, terms and conditions, and present it on the same page.

  • b Email the end user so they can confirm their email address.

  • c Once confirmed, collect the end user’s password.

  • d Create the new identity in Advanced Identity Cloud.

  • e Increment the successful login count property for the end user.

Task 3: Check journey path connections

Use the following table to check the outcomes for each node in the User Registration journey.

Many nodes can have more than one outcome. "→" denotes that a node only has one outcome path.

Source node Outcome path Target node

Start (person icon)

→

Page Node

Page Node containing:

  • Platform Username

  • Attribute Collector

  • Accept Terms and Conditions

→

Email Suspend Node

Email Suspend Node

→

Platform Password

Platform Password

→

Create Object

Create Object

Created

Increment Login Count

Failed

Failure

Increment Login Count

→

Success

Validation

Now that you have created a new user registration journey, you are ready to validate your journey.

The steps in this validation register a new end user in Advanced Identity Cloud so you can verify the new User Registration journey.

When you register the new end user, ensure you use an email address that you can access.

Steps

  1. In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click on the User Registration journey you just updated.

  2. In the Preview URL field, click copy and paste the URL into an Incognito window.

    The Sign Up page for the tenant displays.

  3. In the Sign Up page, enter the following details:

    Field Value

    Username

    agarcia

    First Name

    Alex

    Last Name

    Garcia

    Email Address

    Enter an email address for this new end user. You must have access to this email account.

  4. Click Next. A message displays informing you an email has been sent.

  5. Click the link in the Registration email to confirm your email address and continue registration.

  6. Enter Ch4ng3it! in the Password field.

  7. Click Next.

    You are logged into the Advanced Identity Cloud end-user UI as Alex Garcia.

  8. Close the Incognito window and go back to the Advanced Identity Cloud admin UI.

  9. Go to people Identities > Manage.

  10. Enter agarcia in the Search field and press Enter.

    The user agarcia displays with the details you entered above.

Video of validation

The following video displays the expected validation of registering a new end user using the updated registration journey:

Explore further

Reference material

Reference Description

Registration

Information about the default registration journey.

Journeys

Conceptual information on journeys and their purpose in Advanced Identity Cloud.

Nodes for journeys

Learn about the configurable nodes Advanced Identity Cloud offers for use in journeys.

Manage identities

Manage, group, and assign privileges to identities.

Nodes used

The User Registration journey uses the following nodes:

Third-party integrations

Third-party integrations are nested throughout the relevant use case sections. The following table displays links to the third-party use cases:

Use case Description

Provision data between Advanced Identity Cloud and PingDirectory

Provision data to and from Advanced Identity Cloud and PingDirectory.

Okta as RP (OIDC)

Advanced Identity Cloud serves as the IDP for Okta using OIDC.

Validate by navigating to Okta, being redirected to Advanced Identity Cloud and logging in, and then being redirected back to Okta logged in.

Salesforce as SP (SAML)

Advanced Identity Cloud serves as the IDP for Salesforce using SAML.

Validate by logging into the Advanced Identity Cloud end-user UI to SSO into Salesforce.

Microsoft Entra ID (Azure AD) as OpenID provider

Configure social authentication by letting Microsoft Entra ID serve as the IDP to Advanced Identity Cloud using OIDC.

Validate by authenticating with Microsoft Entra ID and automatically be signed in to the Advanced Identity Cloud end-user UI.

Ping Identity as external authentication method for Microsoft Entra ID (Azure AD)

Configure Advanced Identity Cloud as an external authentication method for Microsoft Entra ID (Azure AD).

Validate by authenticating using Advanced Identity Cloud and automatically be signed in to Microsoft Entra ID.

Pass-through auth (PTA) with Microsoft Entra ID (Azure AD)

Connect to Microsoft Entra ID in a journey to capture an end user’s password, after successful authentication, to store in Advanced Identity Cloud.

Validate by authenticating with Microsoft Entra ID in a PTA journey for Advanced Identity Cloud to capture the password. Then, log into the Advanced Identity Cloud end-user UI with the default login journey to show that Advanced Identity Cloud successfully stored the password.

Ping Identity as external authentication method for Microsoft Entra ID (Azure AD)

Configure Advanced Identity Cloud as the IDP for Microsoft Entra ID using OIDC.

Validate by using Advanced Identity Cloud as a second authentication factor for Microsoft Entra ID.

Provision data from Active Directory (AD) using RCS

Provision users from an on-prem data source, AD, using a remote connector server (RCS).

Validate from AD by using Advanced Identity Cloud.
1. A sandbox environment is an add-on capability.
2. A UAT (user acceptance testing) environment is an add-on capability.
3. All the example commands in this use case are written using Z shell syntax. You may need to adjust your command syntax slightly if you are using a different shell.
4. If you’re running on Microsoft Windows, you’ll need to use an alternative command such as the jq command for JSON formatting.