Web Policy Agents 5.9.1

Prepare for Installation

Before You Install

Consider the following points before you install:

  • Install AM and Web Agent in different containers.

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

  • Install the container before you install the agent.

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

Pre-Installation Tasks

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

  2. Create at least one policy in AM to protect resources with the agent, as described in Configuring Policies in AM’s Authorization Guide.

  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
    C:> '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.

  5. Set up the required environment variables if either of the following are true:

    • AM is configured to perform client authentication

    • The container where the agent is to be installed is configured to validate AM’s server certificate

    For more information, see Environment Variables.

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 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 (configured in 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).

  • 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 (IIS Web Agent only).

Configure AM to Sign Authentication Information

AM communicates all authentication and authorization information to Web Agent, using OpenID Connect ID tokens. To secure the integrity of the JSON payload (outlined in RFC 7518), AM and the agent support signing the tokens for communication with the RS256 algorithm.

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 (From AM 6.5)

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.

Configure AM Secret IDs for the Agent OAuth 2.0 Provider in AM 6.0

By default, AM 6.0 signs session ID tokens with the test key alias provided in AM’s JCEKS keystore and sign the claims with a secret autogenerated at time.

  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, go to Configure > Global Services > OAuth2 Provider.

  3. Perform the following actions:

    1. Replace the test key alias in the ID Token Signing Key Alias for Agent Clients field with the new RSA key alias.

    2. Replace the value in the Authenticity Secret field with the new HMAC secret.

      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.

    3. Save your changes.

    No further configuration is required in the agents.

Create Agent Profiles

Use a Web Agent profile to connect to and communicate with AM, regardless of whether it is stored centrally in AM or on the agent server.

Create an Agent Profile for a Single Agent Instance

This section describes how to create an agent profile in the AM UI.

  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.

    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.

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 and Inherit Settings

Agent profile groups are used to set up multiple agents to inherit settings from the group.

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

  2. In the Groups tab, provide the following information to add a group:

    • Group ID

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

  3. In 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

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.

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.

For information about supported OpenSSL versions, see OpenSSL Requirements.

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.

Prepare for Load Balancers and Reverse Proxies

When your environment has reverse proxies or load balancers configured between the agents and AM, you must perform additional configuration in both AM and your environment before installing the agents.

Failure to do so may cause the agent installation to fail, or it may compromise the agent functionality.

For more information, see Configuration for Load Balancers and Reverse Proxies.

Copyright © 2010-2023 ForgeRock, all rights reserved.