Web Agents 5.10.3

Prepare for installation

Before you install

Consider the following points before you install:

  • Install AM and Web Agent in different servers.

  • Make sure AM is running, so that you can contact AM from the agent web server.

  • Install the web server before you install the agent.

  • Install only one Web Agent for each web server, and configure as many agent instances as necessary.

  • 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, see Configure load balancers and reverse proxies.

Download and unzip Web 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 installation and configuration program agentadmin.

config/

Configuration templates used by the agentadmin command during installation.

instances/

Configuration files, and audit and debug logs for individual instances of the agents. The directory is empty when first extracted.

Agent configuration files are created in /path/to/web_agents/agent_type/instances/agent_n/config/agent.conf. Make sure that the path, including the parent path, does not exceed 260 characters.

legal/

Licensing information including third-party licenses.

lib/

Shared libraries used by the agent.

log/

Log files written during installation. The directory is empty when first extracted.

When the agent is running, the directory can contain the following files:

  • POST data preservation files. The agent stores POST data preservation files temporarily. To store POST data in a dedicated directory, configure POST Data Storage Directory.

  • The system_n.log file, where the agent logs information related to agent tasks running in the background. Web Agent timestamps events in coordinated universal time (UTC).

  • (IIS Web Agent only) The backup of the site and application configuration files created after running the agentadmin -g command.

  • (IIS Web Agent only) Files related to the agent caches.

Pre-installation tasks

  1. In AM, add an agent profile, as described in Create an agent profile in AM using the console:

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

    • Agent ID: web-agent

    • Agent URL: http://www.example.com:80

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

    • Password: password

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

    The example in this guide uses 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.

  3. Configure AM to protect the CDSSO cookie from hijacking. For more information, see Enabling restricted tokens for CDSSO session cookies in AM’s Security guide.

  4. 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
    'password' | Out-File -Encoding ascii pwd.txt

    In Windows Explorer, right-click the password file, for example pwd.txt, 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, by using a password manager.

  5. If either of the following are true, set up the required environment variables :

    • AM is configured to perform client authentication

    • The agent web server is to configured to validate AM’s server certificate

    For more information, see Environment variables.

Configure AM to sign authentication information

AM communicates all authentication and authorization information to Web Agent, using OpenID Connect ID tokens. For security, configure AM and the agent to use signed tokens. For more information, see RFC 7518: JSON Web Algorithms (JWA).

AM also 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 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

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

  • Sign the session ID tokens 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 the 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.

    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.

      2. Create an HMAC secret.

    2. In the AM console, go to Configure > Secret Stores > Keystore Secret Store Name > Mappings.

    3. Configure the following secret IDs:

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

      2. Configure the new HMAC secret in the am.services.oauth2.jwt.authenticity.signing secret ID.

        Note that you may already have a secret configured for this secret ID, since 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 agent profiles

Use Web Agent profiles to connect to and communicate with AM.

Create an agent profile for a single agent instance

This section describes how to create an agent profile in the AM UI. Alternatively, create agent profiles by using the /realm-config/agents/WebAgent/{id} endpoint in the REST API. For more information, see REST API explorer in AM’s Getting started with REST.

  1. In the AM console, select Realms > Realm Name > Applications > Agents > Web, and add an agent.

  2. Complete the web form using the following hints:

    Agent ID

    The ID of the agent profile, used during the agent installation.

    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 the Web Agent protects, such as http://www.example.com:80

    In centralized configuration mode, the Agent URL populates 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.

    In centralized configuration mode, the Server URL populates 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.

    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, by using a password manager.

Create an agent profile for multiple agent instances when post data preservation is enabled

By default, the POST data preservation load balancer cookie name and value is set by the agent profile. Therefore, each agent instance behind a load balancer requires its own agent profile.

In scalable environments, such as deployments with load balancing, or environments that run Kubernetes, resources are dynamically created and destroyed.

To facilitate the rapid creation and destruction of agent instances when post data preservation is enabled, set the POST data preservation configuration in agent.conf to map one agent profile to multiple agent instances.

The configuration in agent.conf overrides the configuration in AM for the following properties:

For an example, see Map one agent profile to multiple agent instances when POST data preservation is enabled.

Create an agent profile group

Use agent profile groups when you set up multiple agents, and want to inherit settings from the group.

  1. In the AM console, go to Realms > Realm Name > Applications > Agents > Web.

  2. Select the Groups tab, and add a group with the following settings:

    • Group ID: A name for the profile group.

    • Server URL: The URL of the AM server in which to store the profile.

Inherit properties from an agent profile group

  1. Set up an agent profile and agent profile group, as described in Create an agent profile for a single agent instance and Create an agent profile group.

  2. In the AM console, select your agent profile.

  3. On the Global tab, select Group, and select a group from the drop-down menu. The agent profile is added to the group.

  4. For each setting in the Global tab, select or deselect the icon:

    • : Inherit this setting from the group

    • : Do not inherit this setting from the group

Secure communication between Web Agent and AM

Web Agent requires OpenSSL or the Windows built-in Secure Channel API to be available at install time. Unix agents support only OpenSSL. Windows agents support OpenSSL and the Windows Secure Channel API.

Find information about supported OpenSSL versions in the Release notes.

Before installing, make sure that the OpenSSL libraries are located or referenced as shown in the following table:

Operating System OpenSSL Library Location or Variable

Windows 32-bit

  • libeay32.dll

  • ssleay32.dll

  • libcrypto-1_1.dll(1)

  • libssl-1_1.dll(1)

\windows\syswow64

Windows 64-bit

  • libeay64.dll

  • ssleay64.dll

  • libcrypto-1_1-x64.dll(1)

  • libssl-1_1.dll(1)

\windows\system32

Linux

  • libcrypto.so

  • libssl.so

$LD_LIBRARY_PATH $LD_LIBRARY_PATH_64

AIX

  • libcrypto.so

  • libssl.so

$LIBPATH

(1)OpenSSL 1.1.0+ only

Windows 64-bit servers require both 32-bit and 64-bit OpenSSL libraries.