Web Agents 2024.3

Post-installation tasks

Note the location of configuration files and logs

Each agent instance has a numbered configuration and logs directory, starting with agent_1. The first agent configuration and logs are located at web_agents/agent_type/instances/agent_1/.

The following configuration files and logs are created:

  • web_agents/agent_type/instances/agent_1/config/: Bootstrap properties to connect to AM and download the configuration. This directory contains properties that are used only in local configuration mode.

  • web_agents/agent_type/instances/agent_1/logs/audit/: Audit log directory. Used only if Audit Log Location is LOCAL or ALL.

  • web_agents/agent_type/instances/agent_1/logs/debug/: The directory where the agent writes debug log files after startup.

During agent startup, the location of the logs can be based on the agent web server, or defined in the site configuration file for the server. For example, bootstrap logs for NGINX Plus Web Agents Documentation can be written to /var/log/nginx/error.log.

Validate the agent instance

Validate the agent instance by using the agentadmin --V[i] command. For information about the options and requirements for this command, refer to agentadmin.

  • Linux

  • Windows

$ sudo -u web-server-user
$ cd /web_agents/agent_type/bin/
$ ./agentadmin --Vi agent_name am_identity_name /path/to/am_identity_password
C:\web_agents\agent-type\bin> agentadmin --Vi ^
agent_name am_identity_name C:/path/to/am_identity_password /

A result similar to this is displayed:

Running configuration validation for agent_1:

  Agent instance is configured with 1 naming.url value(s):
  1. https://am.example.com:8443/am is valid
  selected https://am.example.com:8443/am as naming.url value
  validate_bootstrap_configuration: ok
  validate_ssl_libraries: ok
  validate_agent_login: ok
  get_allocator_blockspace_sz(): trying for configured cache size 16777216 bytes
  validate_system_resources: ok
  validate_session_profile: ok
  validate_websocket_connection: ok
  validate_worker_init_shutdown: ok

Result: 7 out of 7 tests passed, 0 skipped.

If validate_websocket_connection is not ok, make sure the web server and the network infrastructure between the web server and the AM servers support WebSockets.

Configure shared runtime resources and memory

Consider using agent resource groups in atypical deployments, where multiple independent web servers are deployed on the same machine. Agent resource groups apply only to Apache HTTP server or NGNIX, because IIS and ISAPI runs only as a single instance.

Agent resource groups allow server processes to share resources and memory, such as background tasks, log files, runtime resources including pipes, caches, and notification channels to AM.

An agent resource group is determined by the AmAgentID directive in a web server configuration. The value is numeric and defaults to 0 for a typical, single-server deployment. By default, up to 32 agent instances can be in a single installation. For information about changing this limit, refer to AM_MAX_AGENTS in Environment variables.

Choose whether to share resources

Consider the information in the following table before configuring your agent resource groups:

Impact Advantage Caution

Shared agent policy and session cache

Potentially reduces overhead of requests to AM for authentication and authorization.

Cache may fill with irrelevant entries.

Reduced memory consumption.

Sharing the cache among different locations or virtual hosts may not be desirable.

-

Agent instances that are members of the same agent group must be configured in the same Apache or NGINX Plus installation.

Reduced number of background threads. (Single WebSocket connection to AM for notifications)

Reduced system resource usage.

Ensure that the AM_MAX_AGENTS environment variable is set to, at least, the total number of agent instances in the installation.

Agent instances share runtime files and semaphores

Reduced system resource usage.

Ensure that files and resources can be accessed by all agent instances.

For example, add the users running the instances to the same group and configure the resources to have 660 permissions. Learn more from AM_RESOURCE_PERMISSIONS in Environment variables.

Configure Apache agent groups

To create an Apache agent group, edit the Apache configuration file, /etc/httpd/conf/httpd.conf, to add an AmAgentId directive.

To isolate agents in different web servers hosted on the same machine, set AmAgentId to a different value in each server configuration.

The following example httpd.conf file configures one group with AmAgentId 1, including two virtual hosts. Each virtual host is protected by a different instance of the agent, but both agent instances belong to the agent group 1.

The AmAgentId configuration must be outside the VirtualHost section. 
AmAgentId 1
<VirtualHost *:80>
ServerName www.site1.com
DocumentRoot /home/www/site1.com
AssignUserID site1 www-data
AmAgent On
AmAgentConf /web_agents/apache24_agent/bin/../instances/agent_1/config/agent.conf
…​
</VirtualHost>

<VirtualHost *:8080>
ServerName www.site2.com
DocumentRoot /home/www/site3.com
AssignUserID site2 www-data
AmAgent On
AmAgentConf /web_agents/apache24_agent/bin/../instances/agent_2/config/agent.conf
…​
</VirtualHost>

When AmAgentId is not specified for an agent instance, it uses the default value of 0.

To create multiple agent groups in an Apache agent installation, use different values for AmAgentId. In the previous example, you could specify two groups by using AmAgentId 1 and AmAgentId 2.

The following table shows an example of six Apache agent instances split into three different agent groups:

Agent instances Directive configuration Description

Agent_1 and Agent_2

Not set (defaults to 0)

The instances share runtime resources and policy cache.

Agent_3, Agent_4, and Agent_5

1

The instances share runtime resources and policy cache.

Agent_6

2

The instance does not share runtime resources and policy cache with any other instance.

Configure NGINX Plus agent groups

To add NGINX Plus agent instances to a group, add the openam_agent_instance directive to each instance in the NGINX Plus server configuration file /etc/nginx/nginx.conf.

The following example nginx.conf file configures one agent group, openam_agent_instance 2, containing agent_3 and agent_4:

server {
  listen       80 default_server;
  server_name  localhost;
  openam_agent on;
  openam_agent_configuration /web_agents/nginx31_agent/bin/../instances/agent_3/config/agent.conf; openam_agent_instance 2
  …​
  location /customers {
    openam_agent on;
    openam_agent_configuration /web_agents/nginx31_agent/bin/../instances/agent_4/config/agent.conf; openam_agent_instance 2
    root   /www/customers
    index  index.html
  }
…​

When openam_agent_instance is not specified for an agent instance, the instance uses the default value of 1.

To create multiple agent groups in an NGINX Plus agent installation, use different values for openam_agent_instance. In the previous example, you could specify two groups by using openam_agent_instance 2 and openam_agent_instance 3.

Secure communication between the agent and AM

Your environment may require that the WebSocket communication between AM and the agents happens over TLS. You can configure the agent to validate server certificates (installed in the server where AM runs), or to present a client certificate to AM, or both.

To facilitate integration and testing, Web Agents Documentation is configured by default to trust any server certificate. Test client certificates are not provided or configured.

To send cookies only when the communication channel is secure, set Enable Cookie Security to true.

Secure internal communication with OpenSSL

Unix-based agents support only OpenSSL libraries. Windows-based agents can use OpenSSL or Secure communication with the Windows Secure Channel API.

You can find details about supported versions of OpenSSL, and where to locate related libraries in Secure communication between Web Agents Documentation and AM.

Configure server-side and client-side validation using OpenSSL

Perform the following steps to configure the agent to validate AM’s server certificate chain and to present client certificates if requested:

  1. Open the /web_agents/agent_type/instances/agent_nnn/config/agent.conf configuration file.

  2. (For IIS, ISAPI, and Apache agent) Configure the agent to use OpenSSL.

    1. Set the property Enable OpenSSL to Secure Internal Communications to true.

    2. Ensure that the OpenSSL libraries are in the appropriate place, as specified in OpenSSL library location by operating system.

  3. (Optional) Configure the agent to validate AM’s server certificate:

    1. Create a Privacy-Enhanced Mail (PEM) file that contains the certificates required to validate AM’s server certificate. For example, ca.pem .

    2. Set the property Server Certificate Trust to false.

    3. Set the property CA Certificate File Name to the PEM file previously created. For example:

      • Unix

      • Windows

      com.forgerock.agents.config.cert.ca.file = /opt/certificates/ca.pem
      com.forgerock.agents.config.cert.ca.file = C:\Certificates\ca.pem

    4. Set the property OpenSSL Certificate Verification Depth to the level of certificate validation required in your environment.

  4. (Optional) To configure the agent to present its client certificate when AM is configured to perform client authentication, perform the following steps:

    1. Create a PEM file that contains the certificate chain for the agent. For example, client-cert.pem .

    2. Create a PEM file that contains the private key corresponding to the certificate. For example, client-private-key.pem .

    3. Set the property Public Client Certificate File Name to the file containing the certificate chain. For example:

      • Unix

      • Windows

      com.forgerock.agents.config.cert.file = /opt/certificates/client-cert.pem
      com.forgerock.agents.config.cert.file = C:\Certificates\client-cert.pem

    4. Set the property Private Client Certificate File Name to the file containing the client certificate private key. For example:

      • Unix

      • Windows

      com.forgerock.agents.config.cert.key = /opt/certificates/client-private-key.pem
      com.forgerock.agents.config.cert.key = C:\Certificates\client-private-key.pem

    5. If the private key is password-protected, obfuscate the password by using the agentadmin --p command and configure it in the property Private Key Password. For example:

      • Unix

      • Windows

      $ /path/to/web_agents/agent_type/bin/> agentadmin --p "Encryption Key" “cat certificate_password.file”
Encrypted password value: zck...jtc=com.forgerock.agents.config.cert.key.password = zck...tc=
      C:\path\to\web_agents\agent_type\bin> agentadmin.exe --p "Encryption_Key" "Certificate_File_Password"
Encrypted password value: zck...jtc=com.forgerock.agents.config.cert.key.password = zck...tc=

      Encryption Key is the value of the property Agent Profile Password Encryption Key.

  5. Review your configuration. It should look similar to the following:

    • Unix

    • Windows

    //Server-side
com.sun.identity.agents.config.trust.server.certs = false
com.forgerock.agents.config.cert.ca.file = /opt/certificates/ca.pem
//Client-side
com.forgerock.agents.config.cert.file = /opt/certificates/client-cert.pem
com.forgerock.agents.config.cert.key = /opt/certificates/client-private-key.pem
com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=
    //General
org.forgerock.agents.config.secure.channel.disable=true
//Server-side
com.sun.identity.agents.config.trust.server.certs = false
com.forgerock.agents.config.cert.ca.file = C:\Certificates\ca.pem
//Client-side
com.forgerock.agents.config.cert.file = C:\Certificates\client-cert.pem
com.forgerock.agents.config.cert.key = C:\Certificates\client-private-key.pem
com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=

  6. Restart the agent.

Secure communication with the Windows Secure Channel API

By default, IIS, ISAPI, and Apache for Windows agents use the Windows built-in Secure Channel API. You can find details about using OpenSSL in Securing internal communication with OpenSSL.

Configure server-side and client-side validation using the Windows built-in Secure Channel API

Perform the following steps to configure the agent to validate AM’s certificate chain and to present client certificates if requested:

  1. Open the /web_agents/agent_type/instances/agent_nnn/config/agent.conf configuration file.

  2. Configure the agent to use the Windows built-in Secure Channel API:

    1. If this is a new installation, continue to the next step. Windows-based agents use the Windows built-in Secure Channel API by default.

    2. If you configured the IIS, ISAPI, or Apache agent to use OpenSSL libraries, set the property Enable OpenSSL to Secure Internal Communications to false.

  3. (Optional) To configure the agent to validate AM certificate chain, perform the following steps:

    1. Add the certificates required to validate AM’s server certificate to the Windows certificate store. For example, to use PowerShell, add root certificates to the Cert:\LocalMachine\Root location, and CA certificates to the Cert:\LocalMachine\Ca location.

    2. Set the property Server Certificate Trust to false.

  4. (Optional) When AM is configured to perform client authentication, configure the agent to present client certificates:

    1. Import the client certificate chain and private key into the Windows certificate store. For example, for PowerShell, import them to Cert:\LocalMachine\My.

    2. Set the property Public Client Certificate File Name to the friendly name of the client certificate chain. For example:

      com.forgerock.agents.config.cert.file = agent.example.com
      Friendly name of the client certificate imported into the Windows certificate store.

      For compatibility, the agent supports an alternative configuration that does not use the Windows certificate store.

      1. Create a Personal Information Exchange (PFX) file containing the certificate chain for the agent and its private key. For example, client.pfx .

      2. Set the property Public Client Certificate File Name to the previously created PFX file. For example:

        com.forgerock.agents.config.cert.file = C:\Certificates\client.pfx

      3. Obfuscate the certificate password by using the agentadmin --p command. For example:

        C:\path\to\web_agents\agent_type\bin> agentadmin.exe --p "Encryption_Key" "Certificate_File_Password"
Encrypted password value: zck+6RKqjtc=

        Encryption_Key is the value of the Agent Profile Password Encryption Key property.

      4. Set the property Private Key Password to the value of the encrypted password. For example:

        com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=

      5. Restart the agent.

  5. Review your configuration. It should look similar to the following:

    • Windows Cert Store

    • Windows PFX / PCKS12 File

    //Server-side
com.sun.identity.agents.config.trust.server.certs = false
//Client-side
com.forgerock.agents.config.cert.file = agent.example.com
    //Server-side
com.sun.identity.agents.config.trust.server.certs = false
//Client-side
com.forgerock.agents.config.cert.file = C:\Certificates\client.pfx
com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=

  6. Restart the agent.

Support load balancers and reverse proxies between clients and agents

When your environment has reverse proxies or load balancers configured between agents and clients, you must perform additional configuration in the agents to account for the anonymization of both the clients and the agents.

Failure to do so may cause policy evaluation and other agent features to fail.

Learn more from Configure load balancers and reverse proxies.

Configure audit logging

Web Agents Documentation supports the logging of audit events for security, troubleshooting, and regulatory compliance. Store agent audit event logs in the following ways:

Remotely

Log audit events to the audit event handler configured in the AM realm. In a site comprised of several AM servers, agents write audit logs to the AM server that satisfies the agent request for client authentication or resource authorization.

Agents cannot log audit events remotely if:

  • AM’s audit logging service is disabled.

  • No audit event handler is configured in the agent profile realm.

  • All audit event handlers configured in the agent profile realm are disabled.

    For more information about audit logging in AM, refer to Audit logging in AM’s Security guide.

Locally

Log audit events in JSON format to a file in the agent installation directory, /web_agents/agent_type/logs/audit/.

Locally and remotely

Log audit events:

  • To a file in the agent installation directory.

  • To the audit event handler configured in the agent profile realm.

The example is an agent log record:

{
   "timestamp":"2017-10-30T11:56:57Z",
   "eventName":"AM-ACCESS-OUTCOME",
   "transactionId":"608831c4-7351-4277-8a5f-b1a83fe2277e",
   "userId":"id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
   "trackingIds":[
      "fd5c8ccf-7d97-49ba-a775-76c3c06eb933-82095",
      "fd5c8ccf-7d97-49ba-a775-76c3c06eb933-82177"
   ],
   "component":"Web Policy Agent",
   "realm":"/",
   "server":{
      "ip":"127.0.0.1",
      "port":8020
   },
   "request":{
      "protocol":"HTTP/1.1",
      "operation":"GET"
   },
   "http":{
      "request":{
         "secure":false,
         "method":"GET",
         "path":"http://my.example.com:8020/examples/",
         "cookies":{
            "am-auth-jwt":"eyJ0eXAiOiJKV1QiLCJhbGciOi[...]"
            "i18next":"en",
            "amlbcookie":"01",
            "iPlanetDirectoryPro":"Ts2zDkGUqgtkoxR[...]"
         }
      }
   },
   "response":{
      "status":"DENIED"
   },
   "_id":"fd5c8ccf-7d97-49ba-a775-76c3c06eb933-81703"
}
Local audit logs do not have an _id attribute, which is an internal AM id.

The audit log format adheres to the log structure shared across the ForgeRock Identity Platform. For more information about the audit log format, refer to Audit log format in AM’s Security guide.

Web Agents Documentation supports propagation of the transaction ID across the ForgeRock Identity Platform using the HTTP header X-ForgeRock-TransactionId. For more information about configuring the header, refer to Trust transaction headers in AM’s Security guide.

By default, Web Agents Documentation does not write audit log records. To configure audit logging, perform the following procedure:

To configure audit logging

This procedure assumes that Web Agents Documentation is in centralized configuration mode. Property names are provided for local configuration mode.

  1. In the AM admin UI, go to Realms > Realm Name > Applications > Agents > Web > Agent Name > Global > Audit.

  2. In Audit Access Types, select the type of messages to log. For example, select LOG_ALL to log access allowed and access denied events.

  3. In Audit Log Location, select whether to write the audit logs locally to the agent installation (LOCAL), remotely to AM (REMOTE), or to both places (ALL). For example, keep REMOTE to log audit events to the AM instances.

  4. In Local Audit Log Rotation Size, specify the maximum size, in bytes, of the audit log files.

    This is a bootstrap property. After changing this property, restart the web server where the agent runs.

Copyright © 2010-2024 ForgeRock, all rights reserved.