Identity Gateway 2024.3

Identity Cloud

This guide provides examples of how to integrate your business application and APIs with Identity Cloud for Single Sign-On and API Security, with ForgeRock Identity Gateway. It is for ForgeRock Identity Cloud evaluators, administrators, and architects.

Example installation for this guide

Unless otherwise stated, the examples in this guide assume the following installation:

When using the ForgeRock Identity Cloud, you need to know the value of the following properties:

  • The root URL of your ForgeRock Identity Cloud. For example, https://myTenant.forgeblocks.com.

    The URL of the Access Management component of the ForgeRock Identity Cloud is the root URL of your Identity Cloud followed by /am. For example, https://myTenant.forgeblocks.com/am.

  • The realm where you work. The examples in this document use alpha.

    Prefix each realm in the hierarchy with the realms keyword. For example, /realms/root/realms/alpha.

If you use a different configuration, substitute in the procedures accordingly.

Authenticate an IG agent to Identity Cloud

IG agents are automatically authenticated to Identity Cloud by a non-configurable authentication module. Authentication chains and modules are deprecated in Identity Cloud and replaced by journeys.

You can now authenticate IG agents to Identity Cloud with a journey. The procedure is currently optional, but will be required when authentication chains and modules are removed in a future release of Identity Cloud.

For more information, refer to Identity Cloud’s Journeys.

This section describes how to create a journey to authenticate an IG agent to Identity Cloud. The journey has the following requirements:

  • It must be called Agent

  • Its nodes must pass the agent credentials to the Agent Data Store Decision node.

When you define a journey in Identity Cloud, that same journey is used for all instances of IG, Java agent, and Web agent. Consider this point if you change the journey configuration.

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

  2. Click Journeys > New Journey.

  3. Add a journey with the following information and click Create journey:

    • Name: Agent

    • Identity Object: The user or device to authenticate.

    • (Optional) Description: Authenticate an IG agent to Identity Cloud

    The journey designer is displayed, with the Start entry point connected to the Failure exit point, and a Success node.

  4. Using the Filter nodes bar, find and then drag the following nodes from the Components panel into the designer area:

    • Zero Page Login Collector node to check whether the agent credentials are provided in the incoming authentication request, and use their values in the following nodes.

      This node is required for compatibility with Java agent and Web agent.

    • Page node to collect the agent credentials if they are not provided in the incoming authentication request, and use their values in the following nodes.

    • Agent Data Store Decision node to verify the agent credentials match the registered IG agent profile.

    Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, do not configure the nodes, and use only the default values.

  5. Drag the following nodes from the Components panel into the Page node:

    • Platform Username node to prompt the user to enter their username.

    • /auth-node-ref/latest/auth-node-platform-password.html[Platform Password] node to prompt the user to enter their password.

  6. Connect the nodes as follows and save the journey:

    A journey that can be used to authenticate an agent to Identity Cloud.

Register an IG agent in Identity Cloud

This procedure registers an agent that acts on behalf of IG.

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

  2. Click verified_user Gateways & Agents > New Gateway/Agent > Identity Gateway > Next, and add an agent profile:

    • ID: agent-name

    • Password: agent-password

    • Redirect URLs: URL for CDSSO

    Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.

  3. Click Save Profile > Done. The agent profile page is displayed.

  4. Click open_in_new Native Consoles > Access Management and make the following optional changes in the AM admin UI.

    Change Action

    Store the agent password in AM’s secret service.

    Set a Secret Label Identifier, and configure a mapping to the corresponding secret. If AM finds a matching secret in a secret store, it uses that secret instead of the agent password configured in Step 2.

    The secret label has the format am.application.agents.identifier.secret, where identifier is the Secret Label Identifier.

    The Secret Label Identifier can contain only characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

    Note the following points:

    • Set a Secret Label Identifier that clearly identifies the agent.

    • If you update or delete the Secret Label Identifier, AM updates or deletes the corresponding mapping for the previous identifier provided no other agent shares the mapping.

    • When you rotate a secret, update the corresponding mapping.

    Direct login to a custom URL instead of the default AM login page.

    Configure Login URL Template for CDSSO.

    Apply a different introspection scope.

    Click Token Introspection and select a scope from the drop-down list.

Set up a demo user in Identity Cloud

This procedure sets up a demo user in the alpha realm.

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

  2. Go to group Identities > Manage > settings_system_daydream Alpha realm - Users, and add a user with the following values:

    • Username: demo

    • First name: demo

    • Last name: user

    • Email Address: demo@example.com

    • Password: Ch4ng3!t