Java Agents 2023.11.1

Prepare for installation

Before you install

Consider the following points before you install:

  • Install AM and Java Agent in different containers.

  • Install the container before you install the agent.

  • Install only one Java Agent for each container.

  • Install a supported version of the Java runtime environment, as described in Java Requirements. Set the JAVA_HOME environment variable accordingly. The agent installer requires Java.

    $ echo $JAVA_HOME
/path/to/java

  • For environments with load balancers or reverse proxies, consider the communication between the agent and the AM servers, and between the agent and the client. Configure both AM and the environment before you install the agent. For more information, refer to Configure load balancers and reverse proxies.

Download and unzip Java Agent

Go to the ForgeRock BackStage download site and download an agent based on your architecture, and operating system requirements. Verify the checksum of the downloaded file against the checksum posted on the download page.

Unzip the file in the directory where you plan to store the agent configuration and log files. The following directories are extracted:

Directory Description

bin

The agentadmin installation and configuration program. For more information, refer to agentadmin command.

config

Configuration templates used by the agentadmin command during installation

data

Not used

etc

Configuration templates used during installation

installer-logs

Location of log files written during installation

legal-notices

Licensing information including third-party licenses

lib

Shared libraries used by the agent

locale

Property files used by the installation program

README

README file containing platform and install information for the agent

Preinstallation tasks

  1. Create a text file for the agent password, and protect it. For example, use commands similar to these, but use a strong password and store it in a secure place:

    • Unix

    • Windows

    $ cat > /secure-directory/pwd.txt
password
CTRL+D

$ chmod 400 /secure-directory/pwd.txt
    C:> type > pwd.txt
password
CTRL+Z

    In Windows Explorer, right-click the file, select Read-Only, and then click OK.

    Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example using a password manager or by using the command line tool agentadmin --key.

  2. (Optional) Create a signing key for pre-authentication cookies and POST data preservation cookies. The key must be at least 64 characters long, but preferably 80.

    1. Create the key with the agentadmin --key command:

      • Unix

      • Windows

      $ agentadmin --key 80
ZRY...xXO
      C:> agentadmin --key 80
ZRY...xXO

    2. Write the key to a file:

      • Unix

      • Windows

      $ cat > /secure-directory/signing-key.txt
ZRY...xXO
CTRL+D

$ chmod 400 /secure-directory/signing-key.txt
      C:> type > /secure-directory/signing-key.txt
ZRY...xXO
CTRL+Z

      In Windows Explorer, right-click the file, select Read-Only, and then click OK.

  3. In AM, add an agent profile, as described in Create agent profiles:

    The examples in this guide use an agent profile in the top-level realm, with the following values:

    • Agent ID: java-agent

    • Agent URL: http://agent.example.com:80/app

    • Server URL: http://openam.example.com:8080/openam

    • Password: password

  4. In AM, add a policy set and policy, to protect resources with the agent, as described in Policies in AM’s Authorization guide.

    The examples in this guide use a policy set and policy in the top-level realm, with the following values:

    • Policy set:

      • Name: PEP

      • Resource Types: URL

    • Policy:

      • Name: PEP-policy

      • Resource Type: URL

      • Resource pattern: *://*:*/*

      • Resource value: *://*:*/*

      • Actions tab: Allow HTTP GET and POST

      • Subjects tab: All Authenticated Users.

    When you create your own policy set instead of using the default policy set, iPlanetAMWebAgentService, update the following properties in the agent profile:

  5. When you exchange signed OpenID Connect JWTs between AM and the agent, set up a new key and secret as described in Configure Communication With AM Servers. Do not use the default test key pair in a real environment.

Configure communication with AM servers

AM communicates authentication and authorization information to Java Agent by using OpenID Connect (OIDC) JSON web tokens (JWT). To secure the JSON payload, AM and the agent support JWT signing with the RS256 algorithm. For more information, refer to RFC 7518.

AM uses an HMAC signing key to protect requested ACR claims values between sending the user to the authentication endpoint, and returning from successful authentication.

By default, AM uses a demo key and an autogenerated secret for these purposes. For production environments, perform the steps in the following procedure to create new key aliases and configure them in AM.

Configure AM secret IDs for the agents' OAuth 2.0 provider

By default, AM 6.5 and later versions are configured to:

  • Sign JWTs with the secret mapped to the am.global.services.oauth2.oidc.agent.idtoken.signing secret ID. This secret ID defaults to the rsajwtsigningkey key alias provided in AM’s JCEKS keystore.

  • Sign claims with the secret mapped to the am.services.oauth2.jwt.authenticity.signing secret ID. This secret ID defaults to the hmacsigningtest key alias available in AM’s JCEKS keystore.

For more information about secret stores, refer to Secret stores in AM’s Security guide.

  1. Create the following aliases in one of the secret stores configured in AM, for example, the default JCEKS keystore:

    • RSA key pair

    • HMAC secret

  2. In the AM admin UI, select Configure > Secret Stores > Keystore Secret Store Name > Mappings, and configure the following secret IDs:

    • The new RSA key alias in the am.global.services.oauth2.oidc.agent.idtoken.signing secret ID.

    • The new HMAC secret in the am.services.oauth2.jwt.authenticity.signing secret ID.

    You might already have a secret configured for this secret ID, because it is also used for signing certain OpenID Connect ID tokens and remote consent requests. For more information, refer to Secret ID default mappings in AM’s Security guide.

  3. Save your changes.

Create agent profiles

Java Agent requires a profile to connect to and communicate with AM, regardless of whether the agent is in remote configuration mode or local configuration mode.

This section describes how to create an agent profile and inherit properties from a group. Alternatively, create agent profiles by using the /realm-config/agents/WebAgent/{id} endpoint in the REST API.

For more information, refer to API Explorer in your AM instance.

Create an agent profile in the AM admin UI

  1. In the AM admin UI, select Realms > realm name > Applications > Agents > Java, and add an agent using the following hints:

    Agent ID

    The ID of the agent profile. This ID resembles a username in AM and is used during the agent installation. For example, MyAgent.

    When AM is not available, the related error message contains the agent profile name. Consider this in your choice of agent profile name.
    Agent URL

    The URL where the agent resides. For more information, refer to Example installation for this guide.

    When the agent is in remote configuration mode, the Agent URL is used to populate the agent profile for services, such as notifications.

    Server URL

    The full URL to an authorization server, such as Identity Cloud or AM. For more information, refer to Example installation for this guide.

    If the authorization server is deployed in a site configuration (behind a load balancer), enter the site URL. When the agent is in remote configuration mode, the Server URL is used to populate the agent profile for login, logout, naming, and cross-domain SSO.

    Password

    The password the agent uses to authenticate to an authorization server, such as Identity Cloud or AM. Use this password when installing an agent.

    Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example using a password manager or by using the command line tool agentadmin --key.

Create an agent profile with the ssoadm command line tool

For information about how to use ssoadm and properties with multiple aliases, see Property aliases.

For more information about ssoadm, refer to ssoadm in AM’s Reference.

  1. Set up ssoadm, as described in AM’s Setting up administration tools in AM’s Installation.

  2. Create a text file for the agent password, and protect it. For example, use commands similar to these, but use a strong password and store it in a secure place:

    • Unix

    • Windows

    $ cat > /secure-directory/pwd.txt
password
CTRL+D

$ chmod 400 /secure-directory/pwd.txt
    C:> type > pwd.txt
password
CTRL+Z

    In Windows Explorer, right-click the file, select Read-Only, and then click OK.

    Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example using a password manager or by using the command line tool agentadmin --key.

  3. Run the an ssoadm command similar to this to create the agent:

    ./ssoadm create-agent \
--agentname java-agent \
--agenttype J2EEAgent \
--password-file /secure-directory/pwd.txt \
--realm / \
--agenturl http://agent.example.com:80/app \
--serverurl http://am.example.com:8080/am \
--adminid uid=amadmin,ou=People,dc=am,dc=myorg,dc=org \
--attributevalues userpassword=password

Agent configuration was created.

  4. (Optional) Configure additional properties for the agent, by adding them to the --attributevalues option.

    Add the following line to the above example to configure a value for Max Entries in Not-Enforced IP Cache:

    --attributevalues com.sun.identity.agents.config.notenforced.ip.cache.size=2000

Create an agent profile group and inherit settings

Use agent profile groups to set up multiple agents that inherit settings from the group.

  1. In the AM admin UI, select Realms > realm name > Applications > Agents > Java.

  2. In the Group tab, add a group. Use the URL to the AM server in which to store the profile.

  3. Edit the group configuration as necessary, and save the configuration.

  4. Select Realms > realm name > Applications > Agents > Java, and select an agent you created previously.

  5. In the Global tab, select Group, and add the agent to the group you created previously. The icon appears next to some properties.

  6. For each property where appears, toggle the icon to set inheritance:

    • Do not inherit the value from the group.

    • Inherit the value from the group.

Authenticate agents to the identity provider

Authenticate agents to Identity Cloud

Java Agent is 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 Java Agent 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 Java 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 Identity Gateway, 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 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 that the agent credentials match the registered Java Agent 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.

Authenticate agents to AM

From AM 7.3

When AM 7.3 is installed with a default configuration, as described in Evaluation, Java Agent is automatically authenticated to AM by an authentication tree. Otherwise, Java Agent is authenticated to AM by an AM authentication module.

Authentication chains and modules were deprecated in AM 7. When they are removed in a future release of AM, it will be necessary to configure an appropriate authentication tree when you are not using the default configuration.

For more information, refer to AM’s Authentication Nodes and Trees.

This section describes how to create an authentication tree to authenticate Java Agent to AM. The tree 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 tree in AM, that same tree is used for all instances of Identity Gateway, Java Agent, and Web Agent. Consider this point if you change the tree configuration.

  1. On the Realms page of the AM admin UI, choose the realm in which to create the authentication tree.

  2. On the Realm Overview page, click Authentication > Trees > Create tree.

  3. Create a tree named Agent.

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

    The authentication tree designer provides the following features on the toolbar:

    Button Usage
    Trees auto layout

    Lay out and align nodes according to the order they are connected.
    Trees full screen

    Toggle the designer window between normal and full-screen layout.
    Trees delete node

    Remove the selected node. Note that the Start entry point cannot be deleted.

  4. Using the Filter 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 that the agent credentials match the registered Java 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:

    • Username Collector node, to prompt the user to enter their username

    • Password Collector node,to prompt the user to enter their password

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

    A tree that can be used to authenticate an agent to AM.

Create agent administrators for a realm

To create agent profiles when installing Java Agent, you need the credentials of an AM user who can read and write agent profiles.

This section describes how to create an agent administrator for a specific realm. Use this procedure to reduce the scope given to users who create agent profiles.

  1. In the AM admin UI, select Realms > realm name > Identities.

  2. In the Groups tab, add a group for agent administrators.

  3. In the Privileges tab, enable Log Read and Log Write.

  4. Return to Realms > realm name > Identities, add agent administrator identities.

  5. For each identity, select the Groups tab, add the user to agent profile administrator group.

  6. Provide each system administrator who installs agents with their agent administrator credentials.

    When installing the agent with the --custom-install option, the system administrator can choose the option to create the profile during installation, and then provide the agent administrator username and the path to a read-only file containing the agent administrator password.

  • For installation with Identity Cloud, install