Web Agents 2024.9

Post-installation

Review directories for configuration 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 Agent 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 .var]/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 a group in an Apache agent installation, add an AmAgentId directive to the Apache configuration file, httpd.conf.

To create multiple agent groups in an installation, set AmAgentId to a different value in each Apache configuration file. Set only one AmAgentId directive in each httpd.conf. If more than one value is set, the agent uses the last set value.

When AmAgentId isn’t specified in httpd.conf, it takes the default value of 0.

The following example httpd.conf file configures a group with AmAgentId 1. The group includes two virtual hosts, each protected by a different instance of the agent. 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>

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

Agent instances Directive configuration Description

Agent_1 and Agent_2

Not set (default 0)

Agent_1 and Agent_2 instances share runtime resources and the policy cache with each other.

Agent_3, Agent_4, and Agent_5

1

Agent_3, Agent_4, and Agent_5 instances share runtime resources and the policy cache with each other.

Agent_6

2

Agent_6 instance doesn’t share runtime resources or the 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 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

Be mindful of security breaches and vulnerabilities. Ensure your environment isn’t using outdated, insecure protocols, such as SSL 3.0, TLS 1.0, and others.

To secure communications, configure the agent to validate server certificates installed in the server where AM runs and/or to present a client certificate to AM. Learn more in AM’s Secure HTTP and LDAP connections.

To facilitate integration and test, Web Agent is configured by default to trust any server certificate. Test client certificates aren’t 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 Agent 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 Agent 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 Ping Identity Platform. For more information about the audit log format, refer to Audit log format in AM’s Security guide.

Web Agent supports propagation of the transaction ID across the Ping 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, the Web Agent does not write audit log records. To configure audit logging, perform the following procedure:

Configure audit logging for the agent

This procedure assumes the Web Agent 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.

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. Learn more from 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 labels 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 label. The label 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 label. The label 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 admin UI, go to Configure > Secret Stores > Keystore Secret Store Name > Mappings.

    3. Configure the following secret labels:

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

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

        Note that you may already have a secret configured for this secret label, because it is also used for signing certain OpenID Connect ID tokens and remote consent requests. Learn more from Secret label default mappings in AM’s Security guide.

      3. Save your changes.

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

    No further configuration is required in the agents.

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, refer to OpenSSL requirements.

Before installing, make sure 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.