--- title: Secure connections description: To secure communications, configure the agent to validate server certificates installed in the server where AM runs and to present a client certificate to AM. Learn more in AM's Secure HTTP and LDAP connections. component: web-agents version: 2025.11 page_id: web-agents:installation-guide:secure-connections canonical_url: https://docs.pingidentity.com/web-agents/2025.11/installation-guide/secure-connections.html section_ids: securing-agent-am-communication: Secure communication between the agent and AM openssl-config: Secure communication with OpenSSL configure-server-validation-openssl: Configure server certificate validation using OpenSSL configure-client-cert-auth-openssl: Configure client certificate authentication using OpenSSL native-win-ssl-config: Secure communication with Schannel configure-server-validation-schannel: Configure server certificate validation using Schannel configure-client-cert-auth-schannel: Configure client certificate authentication using Schannel fips: FIPS 140 compliance fips-unix: Unix-based agents fips-windows: Windows-based agents --- # Secure connections ## Secure communication between the agent and AM | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Be aware of security breaches and vulnerabilities. Make sure 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 to present a client certificate to AM. Learn more in AM's [Secure HTTP and LDAP connections](https://docs.pingidentity.com/pingam/8/security/secure-connections.html). 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](../properties-reference/com.sun.identity.agents.config.cookie.secure.html) to `true`. ## Secure communication with OpenSSL Unix-based agents support OpenSSL libraries. Windows-based agents can use OpenSSL or the [Windows Secure Channel API (Schannel)](post-installation.html#native-win-ssl-config). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you want to use OpenSSL for the IIS, ISAPI, or Windows Apache agent, configure the agent to use OpenSSL before continuing:- Make sure the [OpenSSL libraries](pre-installation.html#pre-SSL-configuration) are in the correct location. - Disable Schannel by setting the [Enable OpenSSL to Secure Internal Communications](../properties-reference/org.forgerock.agents.config.secure.channel.disable.html) property to `true`. | ### Configure server certificate validation using OpenSSL Perform the following steps to configure the agent to validate AM's or Advanced Identity Cloud's server certificate: 1. Set the [Server Certificate Trust](../properties-reference/com.sun.identity.agents.config.trust.server.certs.html) property to `false`. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The [Server Certificate Trust](../properties-reference/com.sun.identity.agents.config.trust.server.certs.html) property should always be `false` in production. | 2. Set the [CA Certificate File Name](../properties-reference/com.forgerock.agents.config.cert.ca.file.html) property to the filename of the CA bundle for your system. The exact location and name of the CRT file varies by operating system. For example, for Ubuntu, it's `/etc/ssl/certs/ca-certificates.crt`. 3. Set the [OpenSSL Certificate Verification Depth](../properties-reference/org.forgerock.agents.config.cert.verify.depth.html) property to the level of certificate validation required in your environment. 4. Restart the agent. ### Configure client certificate authentication using OpenSSL When AM or Advanced Identity Cloud are configured to perform client authentication, you must configure the agent to present its client certificates as follows: 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 [Public Client Certificate File Name](../properties-reference/com.forgerock.agents.config.cert.file.html) property 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 [Private Client Certificate File Name](../properties-reference/com.forgerock.agents.config.cert.key.html) property 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: 1. Obfuscate the password using the `agentadmin --p` command. For example: * Unix * Windows ``` $ /path/to/web_agents/agent_type/bin/> agentadmin --p encryption-Key "cat certificate_password.file" Encrypted password value: zck+6RKqjtc= ``` ``` C:\path\to\web_agents\agent_type\bin> agentadmin.exe --p encryption-Key "Certificate_File_Password" Encrypted password value: zck+6RKqjtc= ``` Where encryption-Key is the value of the [Agent Profile Password Encryption Key](../properties-reference/com.sun.identity.agents.config.key.html) property. 2. Set the [Private Key Password](../properties-reference/com.forgerock.agents.config.cert.key.password.html) property to the encrypted password value. For example: ```none com.forgerock.agents.config.cert.key.password = zck+6RKqjtc= ``` 6. Restart the agent. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | | Use the [`agentadmin --Vi` command](agentadmin.html#vi) to validate the TLS connection settings between the agent and AM or Advanced Identity Cloud. | ## Secure communication with Schannel By default, IIS, ISAPI, and Apache for Windows agents use the Windows built-in Secure Channel API (Schannel). Alternatively, you can use OpenSSL as described in [Secure internal communication with OpenSSL](post-installation.html#openssl-config). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Before continuing, make sure the agent is configured to use Schannel:- If this is a new installation, Windows-based agents use Schannel by default. - If you've previously configured the IIS, ISAPI, or Apache agent to use OpenSSL libraries, set the [Enable OpenSSL to Secure Internal Communications](../properties-reference/org.forgerock.agents.config.secure.channel.disable.html) property to `false`. | ### Configure server certificate validation using Schannel Perform the following steps to configure the agent to validate AM's or Advanced Identity Cloud's server certificate: 1. Set the [Server Certificate Trust](../properties-reference/com.sun.identity.agents.config.trust.server.certs.html) property to `false`. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The [Server Certificate Trust](../properties-reference/com.sun.identity.agents.config.trust.server.certs.html) property should always be `false` in production. | 2. If you're using self-signed certificates or the server certificate is issued from a new CA, add the certificates required to validate AM's or Advanced Identity Cloud's server certificate to the Windows certificate store. For example, to use PowerShell, add certificates to the following locations: * **Root CA certificates**: add them to the `Cert:\LocalMachine\Root` location. * **Intermediate CA certificates**: add them to the `Cert:\LocalMachine\Ca` location. 3. Restart the agent. ### Configure client certificate authentication using Schannel When AM or Advanced Identity Cloud are configured to perform client authentication, you must configure the agent to present its client certificates using one of the following methods. The method you use depends on whether you are loading the client certificate through the Windows certificate store or through a PFX certificate: * Agent authenticates using a client certificate stored in the Windows Certificate store Configure the agent to present its client certificate as follows: 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 [Public Client Certificate Friendly Name](../properties-reference/com.forgerock.agents.config.win.clientcert.friendly.name.html) property to the friendly name of the client certificate chain. For example: ```none com.forgerock.agents.config.win.clientcert.friendly.name = agent.example.com ``` ![Friendly name of the client certificate imported into the Windows certificate store.](_images/windows-cert-friendly-name.png) 3. Restart the agent. * Agent authenticates using a PFX file that contains the certificate chain Configure the agent to present its client certificate as follows: 1. Create a Personal Information Exchange (PFX) file that contains the certificate chain for the agent and its private key. For example, `client.pfx` . 2. Set the [Public Client Certificate File Name](../properties-reference/com.forgerock.agents.config.cert.file.html) property to the PFX file you just created. For example: ```none com.forgerock.agents.config.cert.file = C:\Certificates\client.pfx ``` 3. Obfuscate the certificate password 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= ``` Where encryption-Key is the value of the [Agent Profile Password Encryption Key](../properties-reference/com.sun.identity.agents.config.key.html) property. 4. Set the [Private Key Password](../properties-reference/com.forgerock.agents.config.cert.key.password.html) property to the encrypted password value. For example: ```none com.forgerock.agents.config.cert.key.password = zck+6RKqjtc= ``` 5. Restart the agent. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | | Use the [`agentadmin --Vi` command](agentadmin.html#vi) to validate the TLS connection settings between the agent and AM or Advanced Identity Cloud. | ## FIPS 140 compliance Managing FIPS is a complicated process that requires specialist knowledge. Unless you have to be FIPS compliant, it's best not to use FIPS mode. ### Unix-based agents | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The OpenSSL version is important. Web Agents operating in FIPS mode only work with OpenSSL 3.x. Currently, OpenSSL 3.1.2 is the only FIPS module that's FIPS 140-3 validated. All other OpenSSL FIPS modules are FIPS 140-2 validated. | To achieve [FIPS 140–3](https://csrc.nist.gov/publications/detail/fips/140/3/final) compliance, configure the FIPS module using OpenSSL 3.1.2, which is a FIPS 140-3 compliant security provider. The FIPS 140-3 security provider can then be used with any OpenSSL 3.x version. Learn more in [OpenSSL Downloads](https://openssl-library.org/source/) and [OpenSSL 3.1.2 security policy](https://openssl-library.org/source/fips-doc/openssl-3.1.2-security-policy-2023-12-29.pdf). The agent automatically enables FIPS mode when it detects that the OpenSSL FIPS security provider is configured. You can configure the FIPS module in OpenSSL or in your operating system if your vendor provides OpenSSL 3.x and supports FIPS mode. Find more information in these links: * [fips\_module](https://docs.openssl.org/master/man7/fips_module) in the OpenSSL documentation * [FIPS README](https://github.com/openssl/openssl/blob/master/README-FIPS.md) in the OpenSSL repository * [Switching RHEL to FIPS mode](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/security_hardening/switching-rhel-to-fips-mode_security-hardening#switching-rhel-to-fips-mode_security-hardening) in the RHEL documentation * [FIPS 140-3 Compliance in Oracle Linux 9](https://docs.oracle.com/en/operating-systems/oracle-linux/9/security/fips_compliance.html) in the Oracle documentation * [FIPS for Ubuntu 22.04](https://ubuntu.com/security/certifications/docs/2204/fips) in the Ubuntu documentation * [Enabling compliance with FIPS 140-3](https://documentation.suse.com/sles/15-SP6/html/SLES-all/cha-security-fips.html) in the SUSE Linux documentation ### Windows-based agents | | | | - | -------------------------------------------------------- | | | Windows Servers are currently only FIPS 140-2 compliant. | To achieve [FIPS 140–2](https://csrc.nist.gov/pubs/fips/140-2/upd2/final) compliance, enable FIPS compliant algorithms. The agent automatically enables FIPS mode when it detects the use of FIPS compliant algorithms. You can configure Windows to use FIPS compliant algorithms by setting the Local Security Policy: 1. Go to Local Security Policy > Local Policies > Security Options > System cryptography > Use FIPS compliant algorithms for encryption, hashing, and signing and select the `Enabled` option. 2. Click Apply. This enables FIPS mode using Schannel. | | | | - | --------------------------------------------------------------------------------------------------------- | | | Use the [`agentadmin --Vi` command](agentadmin.html#vi) to verify that the agent is running in FIPS mode. |