Java Policy Agents 5.9.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, and configure as many agent instances as necessary.

  • 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

Preinstallation Tasks

  1. Download Java Agent from BackStage. For more information, see Downloading and Unzipping Java Agents.

  2. Create at least one policy in AM to protect resources with the agent. For more information, see Configuring Policies in AM’s Authorization Guide.

  3. Create an agent profile in AM, required by the agent to connect and communicate with AM. For more information, see Creating Agent Profiles.

  4. Make sure that the key pair configured for signing the OpenID Connect JWTs exchanged between AM and the agent is not the default test key pair. For more information, see Configure Communication With AM Servers.

  5. Configure AM to protect the CDSSO session cookie from hijacking. For more information, see Enabling Restricted Tokens for CDSSO Session Cookies in AM’s Security Guide.

  6. For environments with load balancers or reverse proxies, consider the communication between the agent and the AM servers, and between the agent and client. For more information, see Configuration for Load Balancers and Reverse Proxies.

  7. Create a text file for the agent password, and protect it. For example, use commands similar to these, changing the password value and path:

    • Unix

    • Windows

    $ cat > /tmp/pwd.txt
password
CTRL+D

$ chmod 400 /tmp/pwd.txt
    C:> type > pwd.txt
password
CTRL+Z

    In Windows Explorer, right-click the password file, for example pwd.txt, select Read-Only, and then click OK.

Download and Unzip Java Agent

Go to the ForgeRock BackStage website 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, see 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

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, see 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 one of the following procedures to create new key aliases and configure them in AM.

Configure AM Secret IDs for the Agents' OAuth 2.0 Provider (AM 6.0 and earlier versions)

By default, AM 6.0 and earlier versions sign JWTs with the test key alias provided in AM’s JCEKS keystore, and sign claims with an autogenerated secret.

Perform the following steps to create and set up a new key and a new secret:

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

    1. Create an RSA key pair. For more information about creating a key alias in the AM keystore, see Creating Key Aliases in AM’s Security Guide.

    2. Create an HMAC secret.

  2. In the AM console, select Configure > Global Services > OAuth2 Provider, and perform the following steps:

    1. In the ID Token Signing Key Alias for Agent Clients, replace the test key alias with the new RSA key alias.

    2. In Authenticity Secret, replace the value with the new HMAC secret.

      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.

    3. Save your changes.

No further configuration is required in the agents.

Configure AM Secret IDs for the Agents' OAuth 2.0 Provider (AM 6.5 and later versions)

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.

Perform the following steps to create and set up new keys on a keystore secret store:

  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 console, 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, see Secret ID Default Mappings in AM’s Security Guide.

  3. Save your changes.

For more information about secret stores, see Configuring Secret Stores in AM’s Security Guide.

No further configuration is required in the agents.

Create Java 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, see API Explorer in your AM instance.

Create an Agent Profile in the AM Console

  1. In the AM console, 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 is used during the agent installation. For example, MyAgent.

    Agent URL

    The URL where the agent resides, for example, http://www.example.com:8080/agentapp. 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 AM instance. If AM 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 use with as login, logout, naming, and cross-domain SSO.

    Password

    The password the agent uses to authenticate to AM. Use this password when installing an agent.

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

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 console, 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 user name and the path to a read-only file containing the agent administrator password. For silent installs, you can add the --acceptLicense option to auto-accept the software license agreement.

Prepare for Load Balancers and Reverse Proxies Between AM and Java Agent

When your environment includes reverse proxies or load balancers between the agents and AM, you must configure both AM and your environment before you install the agents. Failure to do so can cause the agent installation to fail, or can compromise the agent’s functionality. For more information, see Configuration for Load Balancers and Reverse Proxies.

Copyright © 2010-2023 ForgeRock, all rights reserved.