SSL in AM/OpenAM and Policy Agents

This book provides information on SSL in AM/OpenAM and policy agents, including connections and certificates.


Installation and Configuration


How do I enable SSL in AM/OpenAM (All versions) post-install?

The purpose of this article is to provide information on enabling SSL in AM/OpenAM post-install for a new installation.

Enabling SSL post-install

Note

If this is a NEW install, it is preferable to reinstall AM/OpenAM rather than making lots of configuration changes. This article steps you through an easy process that allows you to start fresh and reconfigure AM/OpenAM for SSL. For existing installations that cannot be reconfigured from scratch, you can enable SSL as described in How do I enable SSL in AM/OpenAM (All versions) for an existing installation?

To enable SSL:

  1. Stop the web application container in which AM/OpenAM runs.
  2. Enable SSL on your web application container per your vendors instructions. Ensure the truststore used by the JVM running AM/OpenAM has the necessary certificates installed. See example: Installation Guide › Securing Installations › Using Self-Signed Certificates
  3. Take a backup of your configuration data to ensure you have it for reference or in case you want to restore your current configuration. See How do I make a backup of configuration data in AM/OpenAM (All versions)? for further information.
  4. Delete the AM/OpenAM configuration files, which are typically under the $HOME directory of the user running the web application container. You can use the following command if you only have one AM/OpenAM instance and your configuration files are under $HOME:
    $ rm -rf $HOME/openam $HOME/.openamcfg
    This command also deletes the embedded directory server and all of its contents if you are using the internal AM/OpenAM configuration store.
  5. Delete the entries under the configured AM/OpenAM suffix (by default dc=openam,dc=forgerock,dc=org) if you use an external configuration store.
  6. Restart the web application container in which AM/OpenAM runs.
  7. Navigate to the initial AM/OpenAM configuration page in your browser, for example, http://host1.example.com:8080/openam.
  8. Reconfigure AM/OpenAM from scratch, ensuring you select the SSL/TLS Enabled option and specify the corresponding port.
Note

Once you have enabled SSL in AM/OpenAM, you should include details of the truststore that contains the required certificates in the setup or setup.bat script prior to installing ssoadm and in the ssoadm or ssoadm.bat script once it is installed. This is described in FAQ: Installing and using ssoadm in AM/OpenAM (Q. How do I install the ssoadm administration tool if I am using SSL?).

See Also

How do I enable SSL in AM/OpenAM (All versions) for an existing installation?

How do I make a backup of configuration data in AM/OpenAM (All versions)?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

Installation Guide › Securing Installations › Using Self-Signed Certificates

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I enable SSL in AM/OpenAM (All versions) for an existing installation?

The purpose of this article is to provide information on enabling SSL in AM/OpenAM for an existing installation. It assumes you have already enabled SSL on your web application container and the truststore used by the JVM running AM/OpenAM has the necessary certificates installed.

Enabling SSL for an existing installation

Note

If this is an existing install, you can enable SSL as described in this article. If it is a new install, it is preferable to reinstall AM/OpenAM rather than making lots of configuration changes as described in How do I enable SSL in AM/OpenAM (All versions) post-install?

To enable SSL:

  1. Enable SSL on your web application container per your vendors instructions. Ensure the truststore used by the JVM running AM/OpenAM has the necessary certificates installed. See example: Installation Guide › Securing Installations › Using Self-Signed Certificates
  2. Take a backup of your configuration data to ensure you have it for reference or in case you want to restore your current configuration. See How do I make a backup of configuration data in AM/OpenAM (All versions)? for further information.
  3. Log into the console as the admin user (typically amadmin).
  4. Clone the server configuration:
    • AM / OpenAM 13.5 console: navigate to: Deployment > Servers and select the vertical ellipsis > Clone on the AM/OpenAM instance you want to change to an SSL enabled installation.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites and select the check box next to the server you want to change to an SSL enabled installation. Click Clone to clone this server configuration.
  5. Enter the new server URL in the Server URL field using the https protocol instead of http and changing the port as appropriate. For example, if your existing server URL was: http://host1.example.com:8080/openam, you would change it to something similar to: https://host1.example.com:8443/openam
  6. Update the Realm DNS alias in the top level realm if the hostname has changed: 
    • AM / OpenAM 13.x console: navigate to: Realms > Top Level Realm / > Properties > Realm/DNS Aliases.
    • Pre-OpenAM 13 console: navigate to: Access Control > (Top Level Realm) > General > Realm/DNS Aliases.
  7. Update the cookie domain if the hostname domain has changed: 
    • AM 5 and later console: navigate to: Configure > Global Services > Platform > Cookie Domains.
    • OpenAM 13.5 console: navigate to: Configure > Global Services > System > Platform > Cookie Domains.
    • Pre-OpenAM 13.5 console: navigate to: Configuration > System > Platform > Cookie Domains.
  8. Logout of the console.
  9. Edit the bootstrap file (located in $HOME) to point to the new server.
    • AM 5 and later: $HOME/openam/boot.json
    • OpenAM 13.x: $HOME/openam/bootstrap
  10. Restart the web application container in which AM/OpenAM runs.
  11. Navigate to the new server URL that you specified in step 5 to ensure it works as expected.
  12. If the new server is operational, remove the old server and Realm DNS alias associated with the old hostname (if different).
Note

Once you have enabled SSL in AM/OpenAM, you should include details of the truststore that contains the required certificates in the setup or setup.bat script prior to installing ssoadm and in the ssoadm or ssoadm.bat script once it is installed. This is described in FAQ: Installing and using ssoadm in AM/OpenAM (Q. How do I install the ssoadm administration tool if I am using SSL?).

See Also

How do I enable SSL in AM/OpenAM (All versions) post-install?

How do I make a backup of configuration data in AM/OpenAM (All versions)?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

Installation Guide › Securing Installations › Using Self-Signed Certificates

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

The purpose of this article is to provide information on making AM/OpenAM communicate with a secured LDAP (LDAPS) server such as DS/OpenDJ (SSL/TLS enabled). This information applies whether you are using the DS/OpenDJ generated self-signed certificate or a CA-signed certificate for a CA that may or may not already be present in the security store.

Making AM/OpenAM communicate with a secured LDAP server

When your LDAP server uses LDAP secured access (LDAPS), you must import the LDAP server certificate into the JVM truststore used by AM/OpenAM. This allows the JVM to trust the LDAP server certificate and enables AM/OpenAM to connect to the secured LDAP server. Additionally,  there are some version specific issues you should be aware of to ensure your setup is successful. See the Known issues section for further information.

Once you have resolved any version specific issues, you can proceed to import the LDAP server certificate into the JVM truststore used by AM/OpenAM; the following instructions differ depending on whether you are using the default JVM truststore or a non-default one:

See How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL? for further information.

Known issues

The following known issues affect specific AM / Java® versions:

AM/OpenAM version Java version Issue

AM 5.x and 6.0.0.x

ssoadm in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x

JDK 1.8.0_192 or later;

JDK 11

These versions of AM and ssoadm ​​​​do not correctly support the TLSv1.2 protocol.

AM 5.1.x; AM 6 or later

JDK 1.7.0_191;

JDK 1.8.0_181

These versions of AM introduce stricter hostname validation.

Lack of TLS 1.2 protocol support

AM 5.x and 6.0.0.x, and certain ssoadm versions (in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x) ​​​​do not correctly support the TLSv1.2 protocol, whereas using more secure ciphers or installing DS in production mode forces the protocol version to TLSv1.2. In Java versions prior to JDK 1.8.0_192, unsupported cipher suites were simply ignored, which is why these connections continued to work despite the mismatch in protocol versions.

Changes were introduced in JDK 1.8.0_192 (JDK-8162362 : Introduce system property to control enabled ciphersuites), which changed how the JDK determined which cipher suites (and resulting protocol) to use. As a consequence of these Java changes, AM and ssoadm cannot communicate with DS using a SSL/TLS secured connection because it uses different cipher suites and protocol to the DS server; both the client and server must support the same cipher suites and protocol agreed upon when attempting to establish a secure connection.

You can resolve this issue as follows:

  • If the issue is on the AM side, you can upgrade to AM 6.5 or later; you can download this from BackStage.
  • If the issue is on the ssoadm side, you can upgrade to AM 6.5.0.2 or AM 6.5.1, and then upgrade ssoadm to version 5.1.2.3; you can download this from BackStage.

See AM 5.x and 6.0.0.x, IDM 6.x and Rest2LDAP cannot connect to DS 5.x or 6 after restricting DS cipher suites or Java upgrade and Cannot install or use ssoadm in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x after restricting configuration store (DS/OpenDJ) cipher suites or Java upgrade for further information and workarounds.

Stricter hostname validation

Changes introduced in AM 5.1.x; AM 6 or later, and DS 5.5.1 or later have made LDAP SSL hostname validation stricter. AM checks the hostname in the LDAP server certificate correctly matches the hostname used to connect to the secured directory server (for example, DS or Active Directory®) and DS checks that the server it is trying to connect to has a certificate that matches the hostname.

Java 1.7.0_191 and 1.8.0_181 introduced changes to improve LDAP support by enabling endpoint identification algorithms by default for LDAPS connections; this also results in stricter hostname validation.

As a result of these changes, you must ensure the hostname you are connecting to the LDAP server with matches the hostnames specified in the server certificate via the SAN (Subject Alternative Name). See LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 6.x and DS 5.5.1, 5.5.2, 6.x for further information.

Using the default JVM truststore

You can do this as follows:

  1. If you are using the DS/OpenDJ generated self-signed certificate, you must first export this with its alias of 'server-cert' using the following keytool command:
    $ keytool -export -alias server-cert -file server-cert.crt -keystore /path/to/ds/config/keystore -storetype [storetype] -storepass:file /path/to/ds/config/keystore.pin
    
    If you want to export the certificate in PEM format, you should use the following command instead:
    keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storetype [storetype] -storepass [storepassword] -rfc -file [keyStore.pem]
  2. Import the generated self-signed certificate or the issuer certificate of the CA who signed the LDAP server certificate (if it is not already present in the store) into the JVM truststore used by AM/OpenAM using the following keytool command:
    $ keytool -importcert -alias [alias_of_certificate_entry] -file [path_to_certificate_file] -trustcacerts -keystore /path/to/truststore -storetype [storetype]
    For example, your command would look similar to this if you were importing the DS/OpenDJ generated self-signed certificate into the JVM truststore, where AM/OpenAM is deployed and running on Apache Tomcat™ web container:
    $ keytool -importcert -alias server-cert -file /path/to/server-cert.crt -trustcacerts -keystore $JAVA_HOME/jre/lib/security/cacerts -storetype JKS

Finally, AM/OpenAM should be configured to connect to the LDAP server on the secured port as required.

Using a non-default truststore

You can do this as follows:

  1. If you are using the DS/OpenDJ generated self-signed certificate, you must first export this with its alias of 'server-cert' using the following keytool command:
    $ keytool -export -alias server-cert -file server-cert.crt -keystore /path/to/ds/config/keystore -storetype [storetype] -storepass:file /path/to/ds/config/keystore.pin
    
    If you want to export the certificate in PEM format, you should use the following command instead:
    keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storetype [storetype] -storepass [storepassword] -rfc -file [keyStore.pem]
  2. Add the following JVM option to the web container or application server on which you have deployed AM/OpenAM to identify your truststore:
    -Djavax.net.ssl.trustStore=/path/to/truststore
  3. Import the generated self-signed certificate or the issuer certificate of the CA who signed the LDAP server certificate (if it is not already present in the store) into your truststore using the following keytool command:
    $ keytool -importcert -alias [alias_of_certificate_entry] -file [path_to_certificate_file] -trustcacerts -keystore /path/to/truststore -storetype [storetype]

Finally, AM/OpenAM should be configured to connect to the LDAP server on the secured port as required.

See Also

AM/OpenAM (All versions) fails to connect to DS/OpenDJ using a secured connection with an ERROR: Connection factory became offline

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

FAQ: SSL certificate management in AM/OpenAM and Policy Agents

FAQ: SSL certificate management in DS/OpenDJ

Setup and Maintenance Guide › Setting Up Keys and Keystores

Installation Guide › Securing Installations › Using Self-Signed Certificates

Installation Guide › Preparing for Installation › Preparing an External Configuration Data Store

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL?

The purpose of this article is to provide information on importing a certificate into the JVM truststore used by AM/OpenAM to make SSL connections work. This information applies to SSL connections for any browser (HTTPS) or Java® based client applications that need to use the truststore, for example, ssoadm, connecting AM/OpenAM to an external configuration store, communicating with an LDAPS server etc.

Overview

Like most web applications, AM/OpenAM relies on the underlying JVM of the web container to utilize certificates for SSL connections and does not do any encrypting or decrypting itself.  

For SSL connections to work, you must import the server’s SSL certificate or the CA certificate that signed the server’s certificate into the JVM truststore used by AM/OpenAM. This allows the JVM to trust the server's SSL certificate and enables AM/OpenAM to make the SSL connection to the specific client:

Getting the server certificate

Before importing the certificate into the JVM truststore, you must ensure you have it in a file ready for import. If you do not have a certificate file, you can retrieve the certificate from the server using the openssl command. For example, to retrieve the SSL certificate from the server:

$ echo "" | openssl s_client -connect [hostname:port] -showcerts 2>/dev/null | openssl x509 -out certfile.txt

This command outputs the resulting certificate into the certfile.txt file, for example:

-----BEGIN CERTIFICATE----- 
MIIDaTCCAlGgAwIBAgIEahsEmDANBgkqhkiG9w0BAQsFADBlMQswCQYDVQQGEwJD 
QTELMAkGA1UECBMCQkMxETAPBgNVBAcTCFJpY2htb25kMQwwCgYDVQQLEwNvcmcx 
KDAmBgNVBAMTH29wZW5hbXRzdGMxLmNpdHkucmljaG1vbmQuYmMuY2EwHhcNMTcw 
H29wZW5hbXRzdGMxLmNpdHkucmljaG1vbmQuYmMuY2EwggEiMA0GCSqGSIb3DQEB 
AQUAA4IBDwAwggEKAoIBAQCn49VN9btFdguqLE6os7l9h/G0R4b+zXKIgmYs711e 
L/7HegeqjBhVR+NWAqRZRKRwJmt/TIfNjEnm4GIfyzsTK7yiklO5n5KG1tS0ufon 
YNFWw4gPVOr93NDLpDSiNV1Al2B5hoNzeDL222R0wqH9Kr5mpt6Kjq+mT9tgFZNw  
H7V0bipi02I30uKpjLLTLZjqOkDJcPvQITgTwsCzmV3xAgMBAAGjITAfMB0GA1Ud 
DgQWBBTFVHkrqrAyA43/mCyXkIy2/y964DANBgkqhkiG9w0BAQsFAAOCAQEAikKH 
qCsyc9twkOsvjJWqWUJoiIHk5K4sfFAH5hXrbw6gfej3XuZGn4Vh3DG/aV2PydhU  
alVVP6DCExMSk2maKKSfx2G6LxYXDaTmGoighzgHlyIjnoPb7SqH4G1LS8hxmrr7
qXpFxUS9fb0DTV+w7fBnwBfzrLV5eDqJJYs5qj8cARIiqKt3/VEO3jxlnPJoh/cr 
SqIxLBzMQPA8hDw4/LL1MHwqshjvES2m59cg7vJNSH0ZyDKDn/EpNU2WbZH3XPn3 
h1rps4YwIloW8vpDx38FLJhurXl9AiOjDAl9rP2kaKfZe0QCYDR2Xx+YPV6sTbc0 
NC3FmBMTIUjDqEYvKxeSNf5hdViG3Qg5TiI1KsYVlCQ8gNU7myW5a6Sb/wMUpyNe 
NjAyMDAxMjE1WhcNMjcwNTMxMDAxMjE1WjBlMQswCQYDVQQGEwJDQTELMAkGA1UE  
CBMCQkMxETAPBgNVBAcTCFJpY2htb25kMQwwCgYDVQQLEwNvcmcxKDAmBgNVBAMT 
diFo/GwcoJn8GOAXz6xvFqI1yVud6iK95E+bnT6BiTCSfCUFI43m23EGG/I43CED 
l59u5SeLVZVCIs91qA== 
-----END CERTIFICATE----- 

You can also view the SSL certificate in the browser as detailed in this blog: How to View SSL Certificate Details in Each Browser and What You Can Learn; Firefox® allows you export this certificate to a file as well.

Importing the certificate into the truststore

You can import the certificate into the JVM truststore used by AM/OpenAM as follows, where step 1 is not needed if you use the default JVM truststore:

  1. If you are using a non-default truststore: Add the following JVM option to the web container or application server on which you have deployed AM/OpenAM to identify your truststore:
    -Djavax.net.ssl.trustStore=/path/to/truststore
  2. Import the certificate file into the JVM truststore using the following keytool command:
    $ keytool -importcert -alias [alias_of_certificate_entry] -file [path_to_certificate_file] -trustcacerts -keystore /path/to/truststore -storetype [storetype]

For example, your command would look similar to this if you are importing the certificate output above into the default JVM truststore, where AM/OpenAM is deployed and running on Apache Tomcat™ web container:

$ keytool -importcert -alias server-cert -file /path/to/certfile.txt -trustcacerts -keystore $JAVA_HOME/jre/lib/security/cacerts -storetype JKS

Troubleshooting

The following is an overview of troubleshooting steps you can take to collect useful data if you believe certificates are responsible for the issues you are seeing:

  1. Run the openssl command to display certificate details for the server:
    $ openssl s_client -connect [hostname:port] -showcerts
  2. Output details for the truststore to see what certificates it contains:
    $ keytool -list -v -keystore [truststore] -storetype [storetype] -storepass [password]
  3. Enable SSL debug logging as detailed in FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents (Q. How do I debug SSL connection issues?). See Debugging SSL/TLS Connections for further information on SSL debugging. 
  4. For ssoadm only: 

Common errors

You will see errors such as the following if the certificate is missing from the truststore and needs to be imported:

  • The following error means the HTTP container that AM/OpenAM runs on is unable to trust the certificate presented by other servers and/or client applications that are trying to connect to AM/OpenAM over SSL or the certificate is missing.
    javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
    
  • The following error means the certificate with a subject that matches this hostname is not found:
    javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching host1.example.com found
    

openssl output

You will also see errors in response to the openssl command if the server certificate cannot be retrieved, which again means you need to import it into the JVM truststore. For example:

$ openssl s_client -connect host1.example.com:443 -showcerts

CONNECTED(00000003) 
depth=0 C = UK, ST = Bristol, L = Bristol, OU = Admin, CN = host1.example.com
verify error:num=20:unable to get local issuer certificate 
verify return:1 
depth=0 C = UK, ST = Bristol, L = Bristol, OU = Admin, CN = host1.example.com 
verify error:num=27:certificate not trusted 
...

See Also

Installation Guide › Securing Installations › Securing Communications

Setup and Maintenance Guide › Setting Up Keys and Keystores

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

FAQ: SSL certificate management in AM/OpenAM and Policy Agents

How to View SSL Certificate Details in Each Browser and What You Can Learn

Debugging SSL/TLS Connections

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I configure AM/OpenAM (All versions) to check the HTTP header for the user certificate?

The purpose of this article is to provide information on configuring AM/OpenAM to check the HTTP header for the user (X.509) certificate. This setup can be used if you are SSL offloading at a load balancer or reverse proxy in front of AM/OpenAM, the user certificate is passed to AM/OpenAM in the HTTP header (in PEM format) and the Certificate Authentication module is used to authenticate users.

Configuring AM/OpenAM

Note

If you use IG/OpenIG as your reverse proxy, IG/OpenIG will just pass the HTTP header containing the user certificate (providing you have not configured IG/OpenIG to explicitly remove headers as part of a Filter configuration). If however you want IG/OpenIG to retrieve the user certificate and pass it to AM/OpenAM, you will need to configure IG/OpenIG as detailed in How do I configure IG/OpenIG (All versions) to retrieve the user certificate and pass it to AM/OpenAM in the HTTP header?

You can configure the Certificate Authentication module to check the HTTP header for user certificates using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Modules > [Certificate Module] and update the following fields:
    • Trusted Remote Hosts - Add the IP of the host supplying the HTTP header that contains the user certificate. You can add "any" instead of a specific IP to allow any host; however, this option is not as secure. Remove the "none" value.
    • HTTP Header Name for Client Certificate - Enter the HTTP header name for the client certificate that is inserted by the load balancer or reverse proxy. This should be the full PEM encoded certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- boundary lines. In between these boundary lines, there should be the Base64 encoding output of the DER encoded certificate.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > Module Instances > [Certificate Module] and update the Trusted Remote Hosts and HTTP Header Name for Client Certificate fields as detailed above.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthCertService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-cert-gw-cert-auth-enabled=[hostIP] sunAMHttpParamName=[header]
    
    replacing [realmname], [adminID], [passwordfile], [hostIP] and [header] with appropriate values.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

How do I configure IG/OpenIG (All versions) to retrieve the user certificate and pass it to AM/OpenAM in the HTTP header?

Authentication and Single Sign-On Guide › Implementing Authentication › Certificate Authentication Module

Gateway Guide › Understanding OpenIG › Handlers, Filters, and Chains

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5938 (Cert Auth module should not read cert from HTTP request when 'iplanet-am-auth-cert-gw-cert-auth-enabled' is set)


SSL Offloading


How do I configure a Web Policy Agent (All versions) for SSL offloading?

The purpose of this article is to provide information on configuring a Web Policy Agent for SSL offloading to ensure the policy agent can redirect to the goto parameter URL successfully, even if this parameter uses protocol http instead of https.

Configuring a policy agent for SSL offloading

You can configure a Web policy agent for SSL offloading using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent ID] > Advanced and enable Override Request URL Protocol.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Advanced > Load Balancer > Override Request URL Protocol and select the Enabled option.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Load Balancer > Override Request URL Protocol and select the Enabled option.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Advanced > Load Balancer > Override Request URL Protocol and select the Enabled option.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.override.protocol=true
    replacing [realmname], [agentname], [adminID] and [passwordfile] with appropriate values.

When this enabled, the protocol part of the incoming request is overridden with the one specified in the com.sun.identity.agents.config.agenturi.prefix property, so you also need to ensure this is set appropriately.

Note

You should enable this property if the policy agent sits behind a SSL/TLS offloader, a load balancer or a proxy, and the protocol used by users is different to the protocol used by the policy agent.

You can set this property using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent ID] > Global > Agent Deployment URI Prefix and specify the correct URI.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web > [Agent Name] > Global > Profile > Agent Deployment URI Prefix and specify the correct URI.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web > [Agent Name] > Global > Profile > Agent Deployment URI Prefix and specify the correct URI.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web > [Agent Name] > Global > Profile > Agent Deployment URI Prefix and specify the correct URI.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.agenturi.prefix=[URI]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [URI] with appropriate values.

Example

For example, with the following settings:

Load balancer URL=http://host1.example.com:8080
com.sun.identity.agents.config.override.protocol=true
com.sun.identity.agents.config.agenturi.prefix=https://agent.example.com:443/amagent 

When a request is received, the policy agent overrides the protocol part of the incoming URL (http) with the protocol specified in com.sun.identity.agents.config.agenturi.prefix (https) and uses this for the goto parameter.

See Also

How do I configure a Java Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

Agents and policies in AM/OpenAM

User Guide › Configuring Advanced Properties

User Guide › Configuring Global Properties

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3375 (IIS6 notification mode does not work if SSL offloading is done at a loadbalancer)


How do I configure a Java Policy Agent (All versions) for SSL offloading?

The purpose of this article is to provide guidance on configuring a Java Policy Agent for SSL offloading to ensure the policy agent can redirect to the URL in the goto parameter successfully, even if this parameter uses protocol http instead of https.

Configuring a policy agent for SSL offloading

You can configure a Java policy agent for SSL offloading using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Java > [Agent ID] > Advanced > Alternate Agent URL > Alternative Agent Protocol and enter the required protocol (http or https).
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > J2EE > [Agent Name] > Advanced > Alternate Agent URL > Alternative Agent Protocol and enter the required protocol (http or https).
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > J2EE > [Agent Name] > Advanced > Alternate Agent URL > Alternative Agent Protocol and enter the required protocol (http or https).
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > J2EE > [Agent Name] > Advanced > Alternate Agent URL > Alternative Agent Protocol and enter the required protocol (http or https).
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.agent.protocol=[protocol]
    replacing [realmname], [agentname], [adminID], [passwordfile] and [protocol] with appropriate values.

When this is specified, the protocol part of the incoming request is overridden with the one specified here.

Note

You should specify this property if the policy agent sits behind an SSL/TLS offloader, a load balancer or a proxy, and the protocol used by users is different to the protocol used by the policy agent.

Example

For example, with the following settings:

Load balancer URL=http://host1.example.com:8080
com.sun.identity.agents.config.agent.protocol=https

When a request is received, the policy agent overrides the protocol part of the incoming URL (http) with the protocol specified in com.sun.identity.agents.config.agent.protocol (https) and uses this for the goto parameter.

See Also

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

Agents and policies in AM/OpenAM

User Guide › Configuring Advanced Properties

User Guide › Configuring Java Agents Behind Load Balancers

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

The purpose of this article is to provide information on configuring SSL offloading at the Policy Agent (Web and Java) for virtual hosts. It is assumed that you have correctly configured your virtual hosts for SSL; you must specify the SSL parameters in all the ssl vhost sections rather than just the default ssl vhost.

Configuring SSL offloading at policy agent

You can configure SSL offloading at the policy agent using either the console or ssoadm:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or Java > [Agent ID] > Global > FQDN Virtual Host Map and enter the virtual host domain name you want to map in the 'Map Key' field and the actual FQDN in the 'Corresponding Map Value' field.
  • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > Agents > Web or J2EE > [Agent Name] > Global > Fully Qualified Domain Name Checking > FQDN Virtual Host Map and enter the virtual host domain name you want to map in the 'Map Key' field and the actual FQDN in the 'Corresponding Map Value' field.
  • OpenAM 13.x console: navigate to: Realms > [Realm Name] > Agents > Web or J2EE > [Agent Name] > Global > Fully Qualified Domain Name Checking > FQDN Virtual Host Map and enter the virtual host domain name you want to map in the 'Map Key' field and the actual FQDN in the 'Corresponding Map Value' field.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Agents > Web or J2EE > [Agent Name] > Global > Fully Qualified Domain Name Checking > FQDN Virtual Host Map and enter the virtual host domain name you want to map in the 'Map Key' field and the actual FQDN in the 'Corresponding Map Value' field.
  • ssoadm: enter the following command:
    $ ./ssoadm update-agent -e [realmname] -b [agentname] -u [adminID] -f [passwordfile] -a com.sun.identity.agents.config.fqdn.mapping=[[domainname]]=[FQDN]
    replacing [realmname], [agentname], [adminID], [passwordfile], [domainname] and [FQDN] with appropriate values. For example, if you have a virtual host domain name of example.net and your FQDN is host1.example.com, you would specify this property as follows in the ssoadm command:
    com.sun.identity.agents.config.fqdn.mapping=[example.net]=host1.example.com
Note

You should set up FQDN mapping for all virtual hosts; if a domain can be reached with and without www, you should specify mapping for both variants. For example, [example.net]=host1.example.com and [www.example.net]=www.host1.example.com

This FQDN mapping will allow you to access the policy agent on different FQDNs but won't affect how policies are evaluated; the policy rule must still match the requested URL for it to be evaluated. 

See Also

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

Agents and policies in AM/OpenAM

Web Agents 5 User Guide › Configuring Global Properties

Java Agents 5 User Guide › Configuring Global Properties

Related Training

N/A

Related Issue Tracker IDs

N/A


Frequently Asked Questions


FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

The purpose of this FAQ is to provide answers to commonly asked questions regarding SSL/TLS secured connections in AM/OpenAM and Policy Agents.

Frequently asked questions

This article covers questions related to SSL/TLS secured connections; see FAQ: SSL certificate management in AM/OpenAM and Policy Agents for questions related to SSL certificate management in AM/OpenAM and Policy Agents.

Q. Should I enable SSL before installing AM/OpenAM?

A. Yes, you should enable SSL before installing AM/OpenAM as this makes configuration a lot simpler. See Installation Guide › Using Self-Signed Certificates for further information on setting up AM/OpenAM with SSL if you are using Apache Tomcat™ as the deployment container.

If you have already installed AM/OpenAM, refer to the following articles for further information on enabling SSL:

Q. Do I need to do anything differently when installing ssoadm?

A. If you access the configuration store and/or AM/OpenAM instance using a SSL/TLS secured connection, you should include details of the truststore that contains the required certificates in the setup or setup.bat script prior to installing ssoadm and in the ssoadm or ssoadm.bat script once it is installed.

This is described in FAQ: Installing and using ssoadm in AM/OpenAM (Q. How do I install the ssoadm administration tool if I am using SSL?).

Q. How do I make AM/OpenAM communicate with a secured LDAP server, such as DS/OpenDJ?

A. When DS/OpenDJ uses LDAP secured access (LDAPS), you must import the DS/OpenDJ server certificate into your AM/OpenAM truststore. This allows the JVM to trust the DS/OpenDJ server certificate and enables AM/OpenAM to connect to the secured DS/OpenDJ.

See How do I make AM/OpenAM (All versions) communicate with a secured LDAP server? for further information.

Q. How do I configure a policy agent for SSL offloading?

A. You can configure a policy agent for SSL offloading as described in the following articles (depending on policy agent type):

If you use virtual hosts, the following article may also be useful: How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts? 

Q. How do I test my SSL connection to an external resource?

A. You can use the openssl third-party tool to provide information about the SSL connection as well as attempting a SSL handshake. You can run a command such as the following to provide this information:

$ openssl s_client -connect [hostname:port] -showcerts

Q. How do I debug SSL connection issues?

A. You can enable SSL debug logging to provide detailed SSL debugging information, including details of which truststore is being used and which certificates are included in that truststore. You can enable SSL debugging by adding the following JVM option to the web container or application server on which you have deployed AM/OpenAM:

-Djavax.net.debug=SSL,handshake,trustmanager

The location of the SSL debug logs are specific to your web container or application server. For example, for AM/OpenAM deployed on Apache Tomcat, the SSL debug logs are written to catalina.out, which is located in the /path/to/tomcat/logs directory by default.

See Debugging SSL/TLS Connections for further information on SSL debugging. 

Q. What versions of TLS are supported by AM/OpenAM and the policy agents?

A. Supported versions of TLS are determined by the web application container as well as the underlying version of Java® and OpenSSL. You should ensure you are using appropriate versions of these technologies in accordance with what is supported by your AM/OpenAM and/or agent versions.

See Installation Guide › Security Settings for details on setting the protocols used by AM/OpenAM.

Web agents: TLS v1.3

Web agents 5.6 and later, and web policy agents 4.2 support TLSv1.3 if OpenSSL 1.1.1 or later is used. See Web Policy Agent Release Notes › Supported OpenSSL Versions for further information.

Web agents: TLS v1.2

Both Java 8 and OpenJDK 8 support TLS v1.2 by default; you can configure Java 7 to use TLS v1.2 if required.

You should ensure you are running Web policy agents 4.x or later, and have installed OpenSSL 1.0.2 or greater. Additionally, you should ensure TLS v1.2 is not specified in the org.forgerock.agents.config.tls advanced encryption property that can be set in the agent.conf file.

The org.forgerock.agents.config.tls property is used to disable SSL/TLS versions. By default, only TLSv1.2 is enabled in Web Agents 5.5 and later, and web policy agents 4.2. In earlier versions, you should disable weaker ciphers by specifying them with - in front. For example, the following setting only enables TLSv1.2:

org.forgerock.agents.config.tls=-SSLv3 -TLSv1 -TLSv1.1

There is a known issue with the Web Agent 4 product documentation: OPENAM-9640 (WPA property org.forgerock.agents.config.tls usage should be corrected), which is fixed in 4.1.

See FAQ: SSL certificate management in AM/OpenAM and Policy Agents (Q. How do I configure the Web policy agent for two-way SSL?) for further information on setting this property.

Q. Can I change which SSL/TLS ciphers are used by the policy agents to connect to AM/OpenAM over SSL/TLS?

A. Yes, you can configure the list of ciphers that are supported as described in: User Guide › Configuring Bootstrap Properties.

Q. Does the Java policy agent offer a separate configuration for SSL/TLS client authentication?

A. No, it does not; by default it uses the HttpsURLConnection class provided by the JVM. 

See Also

Policy Agents and AM/OpenAM (All versions) fail to install on IBM WebSphere when SSL is enabled

FAQ: SSL certificate management in AM/OpenAM and Policy Agents

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

FAQ: SAML certificate management in AM/OpenAM

FAQ: Installing and using ssoadm in AM/OpenAM

SSL in AM/OpenAM and Policy Agents

Installation Guide › Securing Installations

Debugging SSL/TLS Connections


FAQ: SSL certificate management in AM/OpenAM and Policy Agents

The purpose of this FAQ is to provide answers to commonly asked questions about SSL certificate management in AM/OpenAM and Policy Agents.

Frequently asked questions

This article covers questions related to SSL certificate management; see FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents for questions related to SSL/TLS secured connections in AM/OpenAM and Policy Agents.

Q. Does AM/OpenAM handle certificate checking for SSL connections?

A. No. The SSL handshake is handled by the HTTP container and the JRE. The container where you install AM/OpenAM requires a certificate in order to set up secure connections. See Installation Guide › Using Self-Signed Certificates for steps that demonstrate how to set up Apache Tomcat™ with an HTTPS connector, using the Java® keytool command to manage the certificate and keystores. 

Q. Why am I getting Exception: unable to find valid certification path?

A. If you encounter certificate errors such as the following:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This means the HTTP container that AM/OpenAM runs on is unable to trust the certificate presented by other servers and/or client applications that are trying to connect to AM/OpenAM over SSL or the certificate is missing. To rectify:

  • Ensure you import the new certificate into each server's default cacerts truststore and restart the containers.
  • Ensure the CN of the certificate matches the hostname of the remote server; to verify this, you can use the following command:
    $ openssl s_client -connect hostname:port 

Q. Where are the Root CA certificates stored?

A. The JDK uses the default cacerts store from the Java home directory. If your certificates have been signed by a public Certificate Authority (CA), those certificates are automatically installed in the Java CA certificates truststore ($JAVA_HOME/jre/lib/security/cacerts) and browsers, and should therefore be recognized by AM/OpenAM without further configuration.  

If you're using a self-signed test certificate, you must also add it to the relevant truststores.  

For example: AM1 needs the certificate of AM2 in its truststore (and vice-versa) as described in the section Installation Guide › Using Self-Signed Certificates. By default this is $JAVA_HOME/jre/lib/security/cacerts.

Q. What is the difference between the keystore and truststore?

A. Truststores are used for public, signed certificates and keystores are used for private keys; the truststore is used to find the certificates of other servers to be trusted, whereas the keystore is what the HTTP container uses to find its own server certificate. Typically, both truststores and keystores have the same default password.

Q. Can I use my own truststore rather than the default truststore?

A. Yes, you can but you must update the server.xml file for your web application container to point to your non-default truststore. In addition, you should ensure you have imported the necessary certificates into the truststore. See How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL? for further information.

To connect to DS/OpenDJ over LDAPS in this scenario, you should follow the instructions given in How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

Q. Does AM/OpenAM require a specific keystore type?

A. AM/OpenAM does not read the server certificate for HTTP(s) connections; the SSL handshake is handled by the container and the JRE. If you are experiencing problems with the keystore format, it is unlikely that it can be fixed from within AM/OpenAM.

In other cases where the certificates are processed by AM/OpenAM itself (for example, SAML2 federation or x509 certificate authentication) the keystore type does matter. The default directory for keystore files (.keypass, .storepass, keystore.jceks / keystore.jks) is %BASE_DIR%/%SERVER_URI%/.

Q. How do I list the keys in my keystore?

A. You can list all the keys in your keystore using one of the following commands depending on your keystore format:

  • JCEKS format:
    $ keytool -list -v -keystore [keystore] -storetype JCEKS -storepass [password]
  • JKS format:
    $ keytool -list -v -keystore [keystore] -storepass [password]

replacing [keystore] with the full path and name of the keystore file, and [password] with the keystore password.

Q. How long do the generated self-signed certificates last?

A. The generated self-signed certificates expire after one year, although you can replace them with ones that have a longer expiration time.

The AM/OpenAM keystore.jceks /keystore.jks has one certificate included by default, which can be used for testing purposes. This has an alias of test and is valid for a 10 year period.

Caution

You must not use this test certificate in production environments; instead, you should use a certificate obtained from a trusted CA or generate your own self-signed certificate. 

Q. Why does the Persistent Cookie module still issue persistent cookies after the certificate has expired?

A. The Persistent Cookie module does not validate the certificate when it issues the persistent cookies (called session-jwt by default).

Q. What happens to persistent cookies that were issued before the certificate was updated?

A. Persistent cookies that were issued by the old certificate are invalidated when you update the certificate in the keystore.

Q. Will the Web policy agent trust the server certificate?

A. Yes, the Web policy agent trusts all server certificates by default. You can disable this behavior by setting the com.sun.identity.agents.config.trust.server.certs property to false. When this is set to false, the policy agent only trusts the AM/OpenAM SSL certificate if the certificate is found to be correct and valid, which is more secure.

You can set this property to false in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory). If you set this property to false, you must also set the com.forgerock.agents.config.cert.ca.file property in the agent.conf file.

See the User Guide › Reference for further information on these properties.

Q. How do I configure the Web policy agent for two-way SSL?

A. Two-way SSL (also referred to as mutual SSL or Certificate Authentication) is where the policy agent provides its certificate for AM/OpenAM to check during the SSL handshake (with certificate authentication).

You need to configure the following encryption properties in the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory):

com.forgerock.agents.config.cert.ca.file = AM_SSL_CA
com.forgerock.agents.config.cert.file = AM_SSL_CERT
com.forgerock.agents.config.cert.key = AM_SSL_KEY
com.forgerock.agents.config.cert.key.password = AM_SSL_PASSWORD
com.forgerock.agents.config.ciphers = AM_SSL_CIPHERS
org.forgerock.agents.config.tls = AM_SSL_OPTIONS

See User Guide › Encryption Properties for further information on these properties. Alternatively, these properties can be set as environment variables prior to installing your web agent as detailed in the Installation > SSL section in Tips and feature insights for Web Policy Agents 4.x (applies to later agents as well).

Q. How do I use an existing CA signed certificate (in PEM format) in AM/OpenAM?

A. You need to add the CA signed certificate to the AM/OpenAM keystore in order to use it. You can do this as follows:

  1. Convert the PEM certificate file to PKCS#12 (.p12) using the openssl third-party tool:
    $ openssl pkcs12 -export -in [certificate.crt] -inkey [privateKey.key] -out [certificate.p12] -name [alias]
    replacing [certificate.crt], [privateKeyml.key], [certificate.p12] and [alias] with appropriate values.
  2. Import the p12 file generated in step 1 into the AM/OpenAM keystore using the keytool command:
    $ keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore [AMkeystore] -srckeystore [certificate.p12] -srcstoretype PKCS12 -srcstorepass [password] -alias [alias]
    replacing [changeit], [AMkeystore], [certificate.p12], password] and [alias] with appropriate values.

Q. How do I get the certificate out of the keystore in PEM format?

A. You can use the following keytool command to retrieve the certificate from the keystore in PEM format:

$ keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storepass [storepassword] -rfc -file [keyStore.pem]

replacing [alias], [keypassword], [keystore], [storepassword] and [keyStore.pem] with appropriate values, where:

  • [keypassword] is the password used to protect the private key of the generated key pair. 
  • [keystore] is the full path and name of the keystore file.
  • [storepassword] is the keystore password.

Q. How do I convert a PEM certificate file and private key to PKCS#12 (.pfx .p12)?

A. You can use the openssl third-party tool to perform this conversion using the following command:

$ openssl pkcs12 -export -out [certificate.pfx] -inkey [privateKey.key] -in [certificate.crt] -certfile [CACert.crt]

replacing [certificate.pfx], [privateKey.key], [certificate.crt] and [CACert.crt] with appropriate values.

Q. How do I convert a PKCS#12 file (.pfx .p12) that contains a private key and certificates to PEM format?

A. You can use the openssl third-party tool to perform this conversion using the following command:

$ openssl pkcs12 -in [keyStore.pfx] -out [keyStore.pem] -nodes

replacing [keyStore.pfx] and [keyStore.pem] with appropriate values

Note

You can add -nocerts to only output the private key or add -nokeys to only output the certificates.

Q. How can I create an OAuth2 provider HMAC signing key in AM 6.5 and later using keytool ?

A. The OAuth2 provider HMAC signing key (secret id: am.services.oauth2.jwt.authenticity.signing) can be created using the following keytool command:

$ keytool -genseckey -alias hmacsigningtest -keyalg HMacSHA512 -keysize 512 -keystore [keystore] -storetype [storetype] -storepass [storepassword] -keypass [keypassword]

replacing [keystore], [storetype], [storepassword] and [keypassword] with appropriate values.

See Setup and Maintenance Guide › Secret ID Mappings for JWT Authenticity Signing for further information about this signing key.

See Also

FAQ: SAML certificate management in AM/OpenAM

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL?

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

RSA server certificate CommonName (CN) does NOT match server name warning in Proxy log for AM/OpenAM (All versions)

Setup and Maintenance Guide › Setting Up Keys and Keystores

The Most Common OpenSSL Commands

keytool command


Known Issues


AM 5.x and 6.0.0.x, IDM 6.x and Rest2LDAP cannot connect to DS 5.x or 6 after restricting DS cipher suites or Java upgrade

The purpose of this article is to provide assistance if connections to DS fail with a java.io.EOFException after restricting cipher suites in DS, installing DS using Production mode or upgrading to Java® JDK 11 or JDK 1.8.0_192 (or later). This issue affects various use cases including AM connecting to a DS configuration store, identity store, CTS store and so on; IDM connecting to an external DS repository or connections to DS using the Rest2LDAP gateway servlet.

Symptoms

A java.io.EOFException occurs before an SSL connection is established. You will see this error occurring in different logs depending on what is trying to connect to DS.

AM

If you are using DS as an identity store, you will notice that you cannot see any identities in the repository.

You will also see the following Connect Errors in the CoreSystem, IdRepo or Session debug logs depending on what type of stores you are using DS for (configuration, identity or CTS):

Connect Error: No operational connection factories available
   at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:206)
   at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:144)
   at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:113)
   at org.forgerock.opendj.ldap.LoadBalancer.getMonitoredLdapClient(LoadBalancer.java:411)
   at org.forgerock.opendj.ldap.LoadBalancer.access$3300(LoadBalancer.java:68)
   at org.forgerock.opendj.ldap.LoadBalancer$LdapClientSocketImpl.getLoadBalancedContext(LoadBalancer.java:787)
   at org.forgerock.opendj.ldap.LoadBalancer$LdapClientSocketImpl.lambda$getLoadBalancedContext$4(LoadBalancer.java:797)
...
Caused by: Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake: java.io.EOFException
   at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:206)
   at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:144)
   at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:113)
   at org.forgerock.opendj.grizzly.GrizzlyLdapSocketConnector$CompletionHandlerAdapter$1.failed(GrizzlyLdapSocketConnector.java:274)
   ... 28 more
Caused by: java.io.EOFException
   ... 27 more

IDM

You will see the following errors in openidm0.log after starting IDM:

May 28, 2019 2:27:01 PM org.glassfish.grizzly.filterchain.DefaultFilterChain execute
FEIN: GRIZZLY0013: Exception during FilterChain execution
java.io.EOFException
   at org.glassfish.grizzly.nio.transport.TCPNIOTransport.read(TCPNIOTransport.java:630)
   at org.glassfish.grizzly.nio.transport.TCPNIOTransportFilter.handleRead(TCPNIOTransportFilter.java:75)
   at org.glassfish.grizzly.filterchain.TransportFilter.handleRead(TransportFilter.java:173)
   at org.glassfish.grizzly.ssl.SSLBaseFilter$SSLTransportFilterWrapper.handleRead(SSLBaseFilter.java:1145)
   at org.glassfish.grizzly.filterchain.ExecutorResolver$9.execute(ExecutorResolver.java:119)
   at org.glassfish.grizzly.filterchain.DefaultFilterChain.executeFilter(DefaultFilterChain.java:284)
   at org.glassfish.grizzly.filterchain.DefaultFilterChain.executeChainPart(DefaultFilterChain.java:201)
   at org.glassfish.grizzly.filterchain.DefaultFilterChain.execute(DefaultFilterChain.java:133)
   at org.glassfish.grizzly.filterchain.DefaultFilterChain.process(DefaultFilterChain.java:112)
...

May 28, 2019 2:27:01 PM org.forgerock.openidm.repo.opendj.impl.OpenDJRepoService waitForConnection
WARNUNG: Unable to get DS connection. Next attempt at Tues May 28 14:28:01 CEST 2019

Rest2LDAP

You will see connect errors similar to the following on the Rest2LDAP side if logging has been enabled:

29-May-2019 15:07:42.780 WARNING [OpenDJ LDAP SDK Client Selector(1) SelectorRunner] org.forgerock.i18n.slf4j.LocalizedLogger.warn Connection factory 'CachedConnectionPool(size=0[in:0 + out:0 + pending:0], maxSize=24, blocked=0, ldapClient=org.forgerock.opendj.ldap.LdapClientImpl@2517fc05)' is no longer operational: Connect Error

You can enable logging in the Rest2LDAP gateway servlet (if it runs in the Apache Tomcat™ web container) by specifying logging properties in the logging.properties file (located in the WEB-INF/classes directory where the gateway servlet is deployed).

SSL debugging - AM

If you enable SSL debug logging for AM, you will just see that the secure ciphers are being ignored, for example:

Ignoring unsupported cipher suite: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
Ignoring unsupported cipher suite: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
Ignoring unsupported cipher suite: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

You can enable SSL debug logging as described in FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents (Q. How do I debug SSL connection issues?).

SSL debugging - DS

If you enable SSL debug logging for DS, you may see errors similar to the following in the DS server.out log:

%% Initialized:  [Session-7, SSL_NULL_WITH_NULL_NULL]
LDAPS 0.0.0.0 port 40636(2) SelectorRunner, fatal error: 40: no cipher suites in common
javax.net.ssl.SSLHandshakeException: no cipher suites in common
%% Invalidated:  [Session-7, SSL_NULL_WITH_NULL_NULL]
LDAPS 0.0.0.0 port 40636(2) SelectorRunner, SEND TLSv1.2 ALERT:  fatal, description = handshake_failure
LDAPS 0.0.0.0 port 40636(2) SelectorRunner, WRITE: TLSv1.2 Alert, length = 2
LDAPS 0.0.0.0 port 40636(2) SelectorRunner, fatal: engine already closed.  Rethrowing javax.net.ssl.SSLHandshakeException: no cipher suites in common
Using SSLEngineImpl.

You can enable SSL debug logging as described in FAQ: SSL certificate management in DS/OpenDJ (Q. How do I debug a SSL handshake error?).

Additionally, the server.out log does not show the more secure cipher suites that have been enabled.

Recent Changes

Upgraded to JDK 1.8.0_192 or later, or JDK 11.

Restricted cipher suites in DS to more secure ones such as TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, which use protocol version TLSv1.2.

Installed DS using the --productionMode setup option (which restricts the available ciphers and forces the protocol version to TLSv1.2).

Causes

AM connects to DS using the embedded LDAP SDK and IDM connects to DS using the Grizzly LDAP connector (which in turn uses the Rest2LDAP servlet).

These mechanisms for connecting to DS securely do not correctly support the TLSv1.2 protocol, whereas using the more secure ciphers and installing DS in production mode forces the protocol version to TLSv1.2. In Java versions prior to JDK 1.8.0_192, unsupported cipher suites were simply ignored, which is why these connections continued to work despite the mismatch in protocol versions.

Changes were introduced in JDK 1.8.0_192 (JDK-8162362 : Introduce system property to control enabled ciphersuites), which changed how the JDK determined which cipher suites (and resulting protocol) to use. As a consequence of these Java changes, AM, IDM and the Rest2LDAP cannot communicate with DS using a SSL/TLS secured connection because it uses different cipher suites and protocol to the DS server; both the client and server must support the same cipher suites and protocol agreed upon when attempting to establish a secure connection.

Solution

This issue can be resolved by as follows:

  • If you are experiencing this specific issue with AM connecting to DS, this can be resolved by upgrading to AM 6.5 or later; you can download this from BackStage.
  • If you are experiencing this specific issue with IDM or Rest2LDAP connecting to DS, this can be resolved by upgrading to DS 6.5 or later; you can download this from BackStage.

Workaround

You can workaround this issue using one of the following options:

  • Downgrade to JDK 1.8.0_191 or earlier.
  • Add one or more cipher suites that use the TLSv1.1 or TLSv1.0 protocol version, for example: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, and so on. See Security Guide › TLS Protocols and Cipher Suites for further information. You should review any security risks of using alternative cipher suites before proceeding.
Note

Java 8 does not support keys with 256-bit AES encryption by default, so you may need to install the Oracle® Java JCE unlimited strength jars if you want to use keys with 256-bit AES encryption. See Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files Download for further information and links to download the jars.

See Also

Cannot install or use ssoadm in AM 5.x, 6.0.0.x, 6.5.0, 6.5.0.1 and OpenAM 13.x after restricting configuration store (DS/OpenDJ) cipher suites or Java upgrade

LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 6.x and DS 5.5.1, 5.5.2, 6.x

Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x

SSL handshake failed with no cipher suites in common in DS 5 after restricting cipher suites or upgrading Java

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

SSL in DS/OpenDJ

Administration Guide › TLS Protocols and Cipher Suites

Security Guide › Set Up Servers in Production Mode

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14986 (AM 6 Cannot connect to TLSv1.2 DJ server (production mode) after JDK 8 update 192)

OPENIDM-11152 (Unable to connect to External DS datastore via TLS/SSL)

OPENDJ-5553 (Rest2Ldap cannot connect to TLSv1.2 servers)


LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 6.x and DS 5.5.1, 5.5.2, 6.x

The purpose of this article is to provide assistance if your LDAP/LDAPS connection fails with a "java.security.cert.CertificateException: No subject alternative DNS name matching" error. This issue can affect AM and DS.

Symptoms

The "No subject alternative DNS name matching" error can be seen in various AM debug logs with different contexts, for example:

  • Configuration debug log:
    ERROR: SMSEntry: Unable to initalize(exception):
    SMSException Exception Code:5
    Message:Unexpected LDAP exception occurred.
    --------------------------------------------------
    The lower level exception message
    Connect Error: No operational connection factories available
    The lower level exception:
    Connect Error: No operational connection factories available
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:206)
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:144)
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:113)
    ...
    Caused by: Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.
    ...
    Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
       at sun.security.ssl.Handshaker.checkThrown(Handshaker.java:1478)
       at sun.security.ssl.SSLEngineImpl.checkTaskThrown(SSLEngineImpl.java:535)
       at sun.security.ssl.SSLEngineImpl.writeAppRecord(SSLEngineImpl.java:1214)
       at sun.security.ssl.SSLEngineImpl.wrap(SSLEngineImpl.java:1186)
       at javax.net.ssl.SSLEngine.wrap(SSLEngine.java:469)
    ...
    Caused by: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.
    
  • IdRepo debug log:
    ERROR: An error occurred while trying to initiate persistent search connection
    Connect Error: No operational connection factories available
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:206)
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:144)
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:113)
    ...
    Caused by: Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found
    ...
    Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
       at sun.security.ssl.Handshaker.checkThrown(Handshaker.java:1529)
       at sun.security.ssl.SSLEngineImpl.checkTaskThrown(SSLEngineImpl.java:535)
       at sun.security.ssl.SSLEngineImpl.writeAppRecord(SSLEngineImpl.java:1214)
       at sun.security.ssl.SSLEngineImpl.wrap(SSLEngineImpl.java:1186)
       at javax.net.ssl.SSLEngine.wrap(SSLEngine.java:469)
    ...
    Caused by: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.
    
    
  • OpenDJ-SDK debug log:
    WARNING: Connection factory 'CachedConnectionPool(size=0[in:0 + out:0 + pending:0], maxSize=10, blocked=0, ldapClient=org.forgerock.opendj.ldap.LdapClientImpl@57c4d233)' is no longer operational: Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.
    

Amster

You may also see a similar error when trying to install AM using Amster:

"stderr": "SLF4J: Failed to load class \"org.slf4j.impl.StaticLoggerBinder\".\nSLF4J: Defaulting to no-operation (NOP) logger implementation\nSLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.\nFailed to execute the 'install-openam' command: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.",

Upgrade

You may encounter this error during an AM upgrade as well; in which case, you will also see an error similar to the following in the web application container log (for example, catalina.out for Apache Tomcat™):

org.forgerock.openam.upgrade.UpgradeException: Unable to parse product versions for comparison. Current: null war: ForgeRock Access Management 6.0.0 Build 3676519ec1 (2018-May-08 10:07)
Note

If you see the "Unable to parse product versions for comparison" error without the "No subject alternative DNS name matching" error, you should refer to AM/OpenAM (All versions) upgrade fails when com.iplanet.am.version is empty or corrupted for further information on resolving this known upgrade issue.

Recent Changes

There are various changes that could cause this issue, including (but not limited to):

  • Upgraded to, or installed AM 5.1.x; or AM 6 or later.
  • Upgraded to, or installed DS 5.5.1 or later.
  • Upgraded Java® to 1.7.0_191 or later; or 1.8.0_181 or later (including Oracle® JDK and OpenJDK).
  • Created a new data store (configuration, identity or CTS) or changed the DNS name of an existing one.
  • Changed server certificates.
  • Enabled SSL (changed the connection from LDAP to LDAPS).

Causes

Changes introduced in recent AM and DS versions (AM 5.1.x; AM 6 or later; DS 5.5.1 or later) have made LDAP SSL hostname validation stricter. AM checks the hostname in the LDAP server certificate correctly matches the hostname used to connect to the secured directory server (for example, DS or Active Directory®) and DS checks that the server it is trying to connect to has a certificate that matches the hostname.

These changes affect any secured LDAP/LDAPS connections:

  • AM connecting to a configuration store, identity store, CTS store etc.
  • Connections from LDAP command line tools such as ldapsearch.
  • Connections from admin tools such as dsconfig and dsreplication.
  • Connections to DS using the external REST2LDAP interface or DSML gateway; this includes IDM connecting to an external DS repository as that uses the REST2LDAP interface.
  • DS connecting to other LDAP servers when configured for pass-through authentication.

Java

Java 1.7.0_191 and 1.8.0_181 introduced changes to improve LDAP support by enabling endpoint identification algorithms by default for LDAPS connections; this also results in stricter hostname validation. For further information see:

Solution

This issue can be resolved by ensuring the hostname you are connecting to the LDAP server with matches the hostnames specified in the server certificate via the SAN (Subject Alternative Name). The SAN allows you to specify multiple hostnames and takes precedence over the Subject/CN entry in the certificate; you should list all the DNS hostnames that you expect to connect to the LDAP server in the SAN. See Administration Guide › Setting Up Server Certificates for further information.

Put simply, this means the hostname in the error (for example, host1.example.com) should be added to the SAN in the LDAP server certificate. The server certificate is located in the JVM truststore used by AM, which is $JAVA_HOME/jre/lib/security/cacerts by default. In the AM configuration, you should also check that the hostname specified for the LDAP connection is correct (and matches what is in the certificate's SAN).

Alternatives

The following options can be used to switch off stricter hostname validation; however this would make your deployment less secure and as such is not recommended: 

  • You can switch off hostname checks in DS by setting the org.forgerock.opendj.hostNameVerificationDisabled environment variable to true. See Javadoc › SSL_HOST_NAME_VALIDATION_DISABLED_PROPERTY for further information. 
  • You can switch off hostname validation in Java by setting the com.sun.jndi.ldap.object.disableEndpointIdentification JVM option to true. 

See Also

How do I configure LDAPS clients in DS/OpenDJ (All versions)?

How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL?

FAQ: SSL certificate management in AM/OpenAM and Policy Agents

FAQ: SSL certificate management in DS/OpenDJ

Best practice for upgrading to AM 6.x

SSL in DS/OpenDJ

SSL in AM/OpenAM and Policy Agents

Upgrade Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13984 (Upgrade/Install Document need for stricter Hostname Matching for LDAP certificates)


SSLHandshakeException or ClassCastException when using an HSM and Java 11 with ForgeRock products

The purpose of this article is to provide assistance if you encounter an SSLHandshakeException or ClassCastException when using a Hardware Security Module (HSM) via the PKCS11 module with Java® 11. This issue affects all ForgeRock products that are compatible with Java 11 (AM, DS, IDM and IG 6.5 and later).

Symptoms

In DS/OpenDJ, you will see the following in the logs:

Unable to connect to the server: 91 (Connect Error) Additional Information: The LDAP connection has failed because an error occurred during the SSL handshake: java.io.EOFException

If you enable SSL debug logging, you will see one of the following errors depending on whether you are using TLS 1.3 or storing EC keys:

  • Using TLS 1.3 with Java 11:
    javax.net.ssl.SSLHandshakeException: Cannot produce CertificateVerify signature 
       at java.base/sun.security.ssl.Alert.createSSLException(Alert.java:128) 
       at java.base/sun.security.ssl.TransportContext.fatal(TransportContext.java:321) 
       at java.base/sun.security.ssl.TransportContext.fatal(TransportContext.java:264) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyMessage.<init>(CertificateVerify.java:905) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyProducer.onProduceCertificateVerify(CertificateVerify.java:1077)
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyProducer.produce(CertificateVerify.java:1070) 
       at java.base/sun.security.ssl.SSLHandshake.produce(SSLHandshake.java:436) 
       at java.base/sun.security.ssl.ClientHello$T13ClientHelloConsumer.goServerHello(ClientHello.java:1224) 
       at java.base/sun.security.ssl.ClientHello$T13ClientHelloConsumer.consume(ClientHello.java:1160) 
       at java.base/sun.security.ssl.ClientHello$ClientHelloConsumer.onClientHello(ClientHello.java:849) 
       at java.base/sun.security.ssl.ClientHello$ClientHelloConsumer.consume(ClientHello.java:810) 
       at java.base/sun.security.ssl.SSLHandshake.consume(SSLHandshake.java:392) 
       at java.base/sun.security.ssl.HandshakeContext.dispatch(HandshakeContext.java:444) 
       at java.base/sun.security.ssl.HandshakeContext.dispatch(HandshakeContext.java:421) 
       at java.base/sun.security.ssl.TransportContext.dispatch(TransportContext.java:178) 
       at java.base/sun.security.ssl.SSLTransport.decode(SSLTransport.java:164) 
       at java.base/sun.security.ssl.SSLSocketImpl.decode(SSLSocketImpl.java:1152) 
       at java.base/sun.security.ssl.SSLSocketImpl.readHandshakeRecord(SSLSocketImpl.java:1063) 
       at java.base/sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:402) 
       at TLSServer$ServerThread.run(TLSServer.java:92) 
    Caused by: java.security.InvalidKeyException: No installed provider supports this key: sun.security.pkcs11.P11Key$P11PrivateKey 
       at java.base/java.security.Signature$Delegate.chooseProvider(Signature.java:1163) 
       at java.base/java.security.Signature$Delegate.engineInitSign(Signature.java:1204) 
       at java.base/java.security.Signature.initSign(Signature.java:546) 
       at java.base/sun.security.ssl.SignatureScheme.getSignature(SignatureScheme.java:473) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyMessage.<init>(CertificateVerify.java:895) 
    
  • Storing EC keys in the PKCS11 module and using Java 11:
    java.lang.ClassCastException: class sun.security.pkcs11.P11Key$P11PrivateKey cannot be cast to class java.security.interfaces.ECPrivateKey (sun.security.pkcs11.P11Key$P11PrivateKey is in module jdk.crypto.cryptoki of loader 'platform'; java.security.interfaces.ECPrivateKey is in module java.base of loader 'bootstrap') 
       at java.base/sun.security.ssl.SignatureScheme.getPreferableAlgorithm(SignatureScheme.java:436) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyMessage.<init>(CertificateVerify.java:867) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyProducer.onProduceCertificateVerify(CertificateVerify.java:1077)
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyProducer.produce(CertificateVerify.java:1070) 
       at java.base/sun.security.ssl.SSLHandshake.produce(SSLHandshake.java:436) 
       at java.base/sun.security.ssl.ClientHello$T13ClientHelloConsumer.goServerHello(ClientHello.java:1224) 
       at java.base/sun.security.ssl.ClientHello$T13ClientHelloConsumer.consume(ClientHello.java:1160) 
       at java.base/sun.security.ssl.ClientHello$ClientHelloConsumer.onClientHello(ClientHello.java:849) 
       at java.base/sun.security.ssl.ClientHello$ClientHelloConsumer.consume(ClientHello.java:810) 
    

You can enable SSL debugging as indicated in the following articles depending on your product:

Recent Changes

Upgraded to Java 11.

Implemented an HSM via the PKCS11 module and kept the default protocol (TLS 1.3 is the default protocol used for a PKCS11 HSM).

Used EC keys stored in PKCS11.

Causes

There are two JDK bugs that are causing these issues:

These errors are a result of bugs in the JDK rather than being issues with ForgeRock products.

Solution

Until the JDK bugs are fixed, you can workaround these issues as follows:

  • SSLHandshakeException error - you can either use TLS 1.2 or you can downgrade Java to JDK 1.8.
  • ClassCastException error - the only workaround for this issue is to downgrade Java to JDK 1.8.

See Also

Security Guide › Using a Hardware Security Module

Integrator's Guide › Configuring IDM For a Hardware Security Module (HSM) Device

How do I configure AM/OpenAM (All versions) to use a Hardware Security Module (HSM) for signing SAML assertions?

Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-5761 (java.security.InvalidKeyException during SSL Handshake with keys in SoftHSM)


AM/OpenAM (All versions) redirects to HTTP when deployed on Apache Tomcat with a load balancer doing SSL/TLS offloading

The purpose of this article is to provide assistance if AM/OpenAM redirects to a URL using the http protocol instead of the expected https protocol. This issue occurs when AM/OpenAM is deployed on Apache Tomcat™ with a load balancer or proxy (such as HAProxy) doing SSL/TLS offloading. In particular, this affects deployments where the load balancer or proxy sets the X-Forwarded-Proto header.

Symptoms

After logging into AM/OpenAM (using a URL with the https protocol), you are redirected to a URL that uses the http protocol.

You may also see this behavior when moving between newer XUI JavaScript®-based administration pages and old JATO console pages. Upon switching back to XUI pages from an old console page, the protocol changes to http.

You will see a 302 redirect response with the wrong protocol, for example:

HTTP/1.1 302 Found
Location: http://host1.example.com:8080/openam

Recent Changes

Configured a load balancer or proxy in front of AM/OpenAM to offload SSL/TLS.

Causes

Tomcat is not honoring the X-Forwarded-Proto header set by the load balancer or proxy, or has not been configured for SSL offloading:

  • Tomcat needs to honor the X-Forwarded-Proto header set by the load balancer or proxy to ensure that all the client redirect calls are made using the https protocol; otherwise it will switch the protocol to the one associated with the port AM/OpenAM listens on (http).
  • Tomcat needs to be configured for SSL offloading else it will receive a Location-Header from AM/OpenAM with protocol http instead of https since the load balancer or proxy is doing SSL offloading.

Solution

You can resolve this issue by making the following changes:

  1. Configure Tomcat using one of the following options (fixes redirection for SAML2 federation and/or WS-Federation):
    • Configure Tomcat to honor the X-Forwarded-Proto header.
    • Configure Tomcat for SSL offloading.
  2. Configure the Base URL Source Service (OpenAM 12.0.1 and later) (fixes redirection for OAuth2 and other redirection issues).

Configure Tomcat to honor the X-Forwarded-Proto header

You can configure Tomcat to honor the X-Forwarded-Proto header by adding the following to the server.xml file:

<Valve className="org.apache.catalina.valves.RemoteIpValve"
    remoteIpHeader="x-forwarded-for"
    remoteIpProxiesHeader="x-forwarded-by"
    protocolHeader="x-forwarded-proto"
    protocolHeaderHttpsValue="https"
/>

Configure Tomcat for SSL offloading

You can configure Tomcat for SSL offloading by specifying the proxyPort and proxyName attributes in the <Connector> element in the server.xml file, for example:

<Connector port="8080" protocol="HTTP/1.1"
    maxThreads="150" clientAuth="false"
    SSLEnabled="false"
    scheme="https" secure="true"
    proxyPort="443" proxyName="proxy.example.com"
/>

Configure the Base URL Source Service

Note

You may need to add the Base URL Source service if it is not listed under Services by clicking Add a Service or Add and then selecting Base URL Source. If you are using ssoadm, you can replace set-realm-svc-attrs in the ssoadm command with add-svc-realm to add this service and set the attributes with the same command.

The Base URL Source Service applies to all XUI pages and the OpenID Base URL. You can set the Base URL Source Service using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Services > Base URL Source and select Host/protocol from incoming request.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Services > Base URL Source and select Host/protocol from incoming request.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s amRealmBaseURL -e [realmname] -u [adminID] -f [passwordfile] -a base-url-source=REQUEST_VALUES
    replacing [realmname], [adminID] and [passwordfile] with appropriate values.

You may want to use a different option for the Base URL Source if it's more appropriate to your setup, for example, Fixed value. See OpenID Connect 1.0 Guide › Configuring the Base URL Source Service for further information.

The following table provides the corresponding values to use for the base-url-source attribute if you want to configure this via ssoadm along with the attribute name for other required fields:

Option ssoadm value Other attributes
Extension class EXTENSION_CLASS Extension class name field: base-url-extension-class attribute.
Fixed value FIXED_VALUE Fixed value base URL field: base-url-fixed-value attribute.
Forwarded header FORWARDED_HEADER  
Host/protocol from incoming request REQUEST_VALUES  
X-Forwarded-* headers X_FORWARDED_HEADERS  

See Also

How do I set up Realm DNS Aliases in AM/OpenAM (All versions)?

How do I configure SSL offloading at the Policy Agent (All versions) for virtual hosts?

How do I configure a Web Policy Agent (All versions) for SSL offloading?

How do I configure a Java Policy Agent (All versions) for SSL offloading?

OpenID Connect 1.0 Guide › Configuring the Base URL Source Service

Related Training

N/A

Related Issue Tracker IDs

OPENAM-5534 (OAuth2/OIDC SSL connection is based on incoming request not on the site configuration)


AM/OpenAM (All versions) fails to connect to DS/OpenDJ using a secured connection with an ERROR: Connection factory became offline

The purpose of this article is to provide assistance if AM/OpenAM fails to connect to DS/OpenDJ using a secured connection (SSL/TLS enabled). You will see errors such as "ERROR: Connection factory became offline", "Connect Error: General SSLEngine problem" and "unable to find valid certification path to requested target" when this happens.

Symptoms

An error similar to the following is shown in the IdRepo log when AM/OpenAM fails to connect to DS/OpenDJ:

LDAPUtils:03/16/2018 11:32:19:797 AM EST: Thread[localhost-startStop-1,5,main]
ERROR: Connection factory became offline: AuthenticatedConnectionFactory(HeartBeatConnectionFactory(LDAPConnectionFactory(test.example.com:443)), SimpleBindRequest(name=cn=Directory Manager, authentication=simple, controls=[]))
org.forgerock.opendj.ldap.ConnectionException: Connect Error: General SSLEngine problem
   at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:210)
   at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:172)
   at org.forgerock.opendj.ldap.ErrorResultException.newErrorResult(ErrorResultException.java:142)
   at com.forgerock.opendj.ldap.LDAPConnectionFactoryImpl$CompletionHandlerAdapter.adaptConnectionException(LDAPConnectionFactoryImpl.java:187)
   at com.forgerock.opendj.ldap.LDAPConnectionFactoryImpl$CompletionHandlerAdapter.onFailure(LDAPConnectionFactoryImpl.java:194)
   at com.forgerock.opendj.ldap.LDAPConnectionFactoryImpl$CompletionHandlerAdapter.access$200(LDAPConnectionFactoryImpl.java:76)
   at com.forgerock.opendj.ldap.LDAPConnectionFactoryImpl$CompletionHandlerAdapter$2.failed(LDAPConnectionFactoryImpl.java:147)
...
Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
   at sun.security.ssl.Handshaker.checkThrown(Handshaker.java:1300)
   at sun.security.ssl.SSLEngineImpl.checkTaskThrown(SSLEngineImpl.java:513)
   at sun.security.ssl.SSLEngineImpl.writeAppRecord(SSLEngineImpl.java:1177)
   at sun.security.ssl.SSLEngineImpl.wrap(SSLEngineImpl.java:1149)
   at javax.net.ssl.SSLEngine.wrap(SSLEngine.java:469)
   at org.glassfish.grizzly.ssl.SSLConnectionContext.wrap(SSLConnectionContext.java:339)
   at org.glassfish.grizzly.ssl.SSLUtils.handshakeWrap(SSLUtils.java:303)
   at org.glassfish.grizzly.ssl.SSLBaseFilter.doHandshakeStep(SSLBaseFilter.java:621)
   ... 17 more
Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
   at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)
   at sun.security.ssl.SSLEngineImpl.fatal(SSLEngineImpl.java:1683)
   at sun.security.ssl.Handshaker.fatalSE(Handshaker.java:278)
   at sun.security.ssl.Handshaker.fatalSE(Handshaker.java:270)
   at sun.security.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1439)
   at sun.security.ssl.ClientHandshaker.processMessage(ClientHandshaker.java:209)
   at sun.security.ssl.Handshaker.processLoop(Handshaker.java:878)
   at sun.security.ssl.Handshaker$1.run(Handshaker.java:818)
   at sun.security.ssl.Handshaker$1.run(Handshaker.java:816)
   at java.security.AccessController.doPrivileged(Native Method)
   at sun.security.ssl.Handshaker$DelegatedTask.run(Handshaker.java:1237)
   at org.glassfish.grizzly.ssl.SSLUtils.executeDelegatedTask(SSLUtils.java:252)
   at org.glassfish.grizzly.ssl.SSLBaseFilter.doHandshakeStep(SSLBaseFilter.java:632)
   ... 17 more
Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:385)
   at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:292)
   at sun.security.validator.Validator.validate(Validator.java:260)
   at sun.security.ssl.X509TrustManagerImpl.validate(X509TrustManagerImpl.java:326)
   at sun.security.ssl.X509TrustManagerImpl.checkTrusted(X509TrustManagerImpl.java:283)
   at sun.security.ssl.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:138)
   at sun.security.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1426)
   ... 25 more
Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   at sun.security.provider.certpath.SunCertPathBuilder.engineBuild(SunCertPathBuilder.java:196)
   at java.security.cert.CertPathBuilder.build(CertPathBuilder.java:268)
   at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:380)
   ... 31 more

You may see a similar error in the OpenDJ-SDK log when configuring AM/OpenAM servers:

org.forgerock.opendj.ldap.LoadBalancer:06/08/2018 11:07:59:746 AM BST: Thread[OpenDJ LDAP SDK Client Selector(1) SelectorRunner,5,main]: TransactionId[de8dd168-1af6-4213-a6dc-56740aee391f-108]
WARNING: Connection factory 'org.forgerock.opendj.ldap.LdapClientImpl@563521a3' is no longer operational: Connect Error: General SSLEngine problem

A corresponding java.net.ConnectException may also be seen in the Configuration log when this happens; this reveals the connection was refused when the client attempted to establish a network session over HTTP,  not HTTPS when configuring the servers:

WARNING: AMSetupUtils.getRemoteServerInfo()
java.net.ConnectException: Connection refused (Connection refused)
   at java.net.PlainSocketImpl.socketConnect(Native Method)
   at java.net.AbstractPlainSocketImpl.doConnect(AbstractPlainSocketImpl.java:350)
   at java.net.AbstractPlainSocketImpl.connectToAddress(AbstractPlainSocketImpl.java:206)
   at java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:188)
   at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:392)
   at java.net.Socket.connect(Socket.java:589)
   at sun.net.NetworkClient.doConnect(NetworkClient.java:178)
   at sun.net.www.http.HttpClient.openServer(HttpClient.java:463)
   at sun.net.www.http.HttpClient.openServer(HttpClient.java:558)
   at sun.net.www.http.HttpClient.(HttpClient.java:242)
   at sun.net.www.http.HttpClient.New(HttpClient.java:339)
   at sun.net.www.http.HttpClient.New(HttpClient.java:357)
   at sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient(HttpURLConnection.java:1220)
...

Recent Changes

Configured DS/OpenDJ to use LDAP secure access (LDAPS).

Changed the DS/OpenDJ server certificate.

Causes

AM/OpenAM cannot connect to the secured DS/OpenDJ because the JVM does not trust the DS/OpenDJ server certificate.

Solution

You must import the DS/OpenDJ server certificate into your AM/OpenAM truststore to allow the JVM to trust the DS/OpenDJ server certificate.

See How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL? and How do I make AM/OpenAM (All versions) communicate with a secured LDAP server? for further information.

See Also

AM/OpenAM (All versions) fails to connect to the user data store when anonymous access is disabled in DS/OpenDJ

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

How do I use externally created SSL keys with DS/OpenDJ (All versions)?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

SSL in AM/OpenAM and Policy Agents

Related Training

N/A

Related Issue Tracker IDs

N/A


Apache Web Agent (All versions) repeatedly reports failed to load OPENSSL_init_ssl errors

The purpose of this article is to provide assistance if the Apache™ Web Agent repeatedly reports SSL errors such as "failed to load OPENSSL_init_ssl".

Symptoms

The Web Agent appears to be functioning normally, however, one of the following error snippets is shown repeatedly in your logs depending on which version of the Web Agent you are using:

  • Web Agents 5.5.1.0 and later:
    [Mon Aug 12 14:03:29.156134 2019] [amagent:notice] [pid 1234:tid 140277498116015] OpenSSL library status: trying libssl... libssl.so.1.1 dlopen error: libssl.so.1.1: cannot open shared object file: No such file or directory, found libssl.so.10, failed to load OPENSSL_init_ssl, failed to load TLS_client_method, failed to load SSL_get_state, trying libcrypto... libcrypto.so.1.1 dlopen error: libcrypto.so.1.1: cannot open shared object file: No such file or directory, found libcrypto.so.10, OpenSSL v1.0.x/0.9.8 library support is available
    
  • Pre-Web Agents 5.5.1.0:
    Aug 12 14:03:29.950273 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): trying libssl...
    [Mon Aug 12 14:03:29.950664  2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl():  libssl.so.1.1 dlopen error: libssl.so.1.1: cannot open shared object  file: No such file or directory
    [Mon Aug 12 14:03:29.950902 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): found libssl.so.10
    [Mon Aug 12 14:03:29.951107 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): failed to load OPENSSL_init_ssl
    [Mon Aug 12 14:03:29.951124 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): failed to load TLS_client_method
    [Mon Aug 12 14:03:29.951128 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): failed to load SSL_get_state
    [Mon Aug 12 14:03:29.951309 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): trying libcrypto...
    [Mon Aug 12 14:03:29.951534  2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl():  libcrypto.so.1.1 dlopen error: libcrypto.so.1.1: cannot open shared  object file: No such file or directory
    [Mon Aug 12 14:03:29.951707 2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl(): found libcrypto.so.10
    [Mon Aug 12 14:03:29.951999  2019] [amagent:error] [pid 1234:tid 140277498116015] init_ssl():  OpenSSL v1.0.x/0.9.8 library support is available
    

You may see these error snippets in either, or both the Agent logs and Apache logs (located in /path/to/agent/log and /path/to/apache/logs/error_log respectively). The change in log output is due to AMAGENTS-1933 (init_ssl errors fill error_log), which made the messages less verbose.

Recent Changes

N/A

Causes

The Web Agent tries to load various OpenSSL libraries before finding the appropriate one, as evidenced by the following message:

OpenSSL v1.0.x/0.9.8 library support is available

The reason you see all the messages leading up to this point is because of how the Apache logger works when using MPM preforking. While the Agent is trying to load libraries, there are only two logging options available: Error and Notice. These messages are Notice level and are therefore shown.

Solution

Firstly, these messages can be safely ignored because the OpenSSL library is found in the end. Additionally, you can make them less verbose by upgrading to Agents 5.5.1.0 or later; you can download this from BackStage.

The only way to completely prevent these messages is to change your Apache MPM configuration to use a threaded MPM like worker or event. This is documented on the Apache pages: Multi-Processing Modules (MPMs) but in essence:

  • A threaded MPM like worker or event is suitable for sites that need a lot of scalability.
  • The prefork MPM is suitable for sites that require stability or compatibility with older software.
Note

Managing your Apache configuration is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

See Also

Installing a Web Agent (All versions) fails with a no ssl/library support error

SSL in AM/OpenAM and Policy Agents

Related Training

N/A

Related Issue Tracker IDs

AMAGENTS-2716 (Remove init_ssl(): failed to load OPENSSL_init_ssl message in apache error_log)

AMAGENTS-1933 (init_ssl errors fill error_log)


Policy Agents and AM/OpenAM (All versions) fail to install on IBM WebSphere when SSL is enabled

The purpose of this article is to provide assistance if Policy Agents and AM/OpenAM fail with "java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory", when installing on IBM® WebSphere® with SSL is enabled. Additionally, this issue only occurs when using an IBM JVM.

Symptoms

The following error is shown in the policy agent or AM/OpenAM install log after the failed install attempt:

09/23/2016 19:10:05:930 EDT] ValidateURL.isServerUrlValid threw exception :
java.net.SocketException: java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory
   at javax.net.ssl.DefaultSSLSocketFactory.a(SSLSocketFactory.java:7)
   at javax.net.ssl.DefaultSSLSocketFactory.createSocket(SSLSocketFactory.java:1)
   at com.ibm.net.ssl.www2.protocol.https.c.afterConnect(c.java:62)
   at com.ibm.net.ssl.www2.protocol.https.d.connect(d.java:19)
   at com.ibm.net.ssl.www2.protocol.https.b.connect(b.java:57)
   at com.sun.identity.install.tools.configurator.ValidateURL.isServerURLValidInternal(ValidateURL.java:103)
   at com.sun.identity.install.tools.configurator.ValidateURL.access$000(ValidateURL.java:44)
   at com.sun.identity.install.tools.configurator.ValidateURL$URLValidatorProxy.run(ValidateURL.java:350)
   at java.lang.Thread.run(Thread.java:736)
Caused by: java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory

Recent Changes

N/A

Causes

The IBM JVM does not contain any SSL implementation classes, which means com.ibm.websphere.ssl.protocol.SSLSocketFactory is not found during the install process. 

This is a known issue with WebSphere when SSL is enabled: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory

Solution

This issue can be resolved by either using the Oracle® JVM instead of the IBM JVM or by making changes to the java.security file (located in the /path/to/websphere/java*/jre/lib/security directory).

To change the java.security file, you need to uncomment the two default JSSE socket factories and comment out the two WebSphere specific ones, so that it looks like this:

# Default JSSE socket factories 
ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl 
ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl 
# WebSphere socket factories (in cryptosf.jar) 
#ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory 
#ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory

See Also

Installation Guide › Preparing for Installation › Preparing IBM WebSphere

User Guide › Installing the WebSphere Java Agent

Related Training

N/A

Related Issue Tracker IDs

OPENAM-2341 (Improve WebSphere Portal agent integration)


Installing a Web Agent (All versions) fails with a no ssl/library support error

The purpose of this article is to provide assistance if you receive a "no ssl/library support" error when trying to install a Web agent.

Symptoms

An error similar to one of the following is shown when installing the Web agent depending on your operating system:

  • On Unix®, Linux® and Solaris® systems:
    init_ssl(): libssl.so is not available 
    init_ssl(): libcrypto.so is not available
    
  • On Microsoft® Windows® systems:
    init_ssl(): ssleay64.dll is not available (error: 126) 
    init_ssl(): libeay64.dll is not available (error: 126)
    
    init_ssl(): ssleay32.dll is not available (error: 126) 
    init_ssl(): libeay32.dll is not available (error: 126)
    

The corresponding install log shows the following error:

2017-08-31 11:27:09 am_agent_login(): error -26 (no ssl/library support) connecting to https://host1.example.com:8443/openam (https://host1.example.com:8443/openam)

Recent Changes

N/A

Causes

The Web agent cannot load the SSL libraries. There can be various reasons for this, including:

  • You are trying to install a 32bit version of the agent on a 64bit system; the 32bit version of the agentadmin tool cannot open the 64bit SSL libraries.
  • The SSL libraries are not installed.
Note

If your operating system does not include native openssl packages, you must install OpenSSL. See Release Notes › OpenSSL Requirements for further information on supported versions.

Solution

The solution depends on the cause as follows:

  • Ensure you are installing the appropriate version of the agent; if you have a 64bit operating system, you must install the 64bit agent.
  • Ensure either the operating system provides native openssl packages or OpenSSL is installed. If you are using OpenSSL, you can check that the OpenSSL libraries are in the correct location as follows and add them if they are missing:
    • On Linux systems:
      1. Check that the LD_LIBRARY_PATH environment variable is set. For example:
        $ echo $LD_LIBRARY_PATH
        
      2. Check that the OpenSSL libraries (libcrypto.so and libssl.so) are available in the path specified in this environment variable (LD_LIBRARY_PATH). 
    • On Unix and Solaris systems: 
      1. Check that either the LD_LIBRARY_PATH or LD_LIBRARY_PATH_64 environment variable (depending on whether you have a 32bit or 64bit system) is set. For example:
        $ echo $LD_LIBRARY_PATH
        $ echo $LD_LIBRARY_PATH_64
      2. Check that the OpenSSL libraries (libcrypto.so and libssl.so) are available in the path specified in the relevant environment variable (LD_LIBRARY_PATH or LD_LIBRARY_PATH_64). 
    • On Microsoft Windows systems, check that the OpenSSL libraries are in the correct location as follows (depending on whether you have a 32bit or 64bit system):
      • 32bit systems - libeay32.dll and ssleay32.dll files are in the \windows\syswow64  directory.
      • 64bit systems - libeay64.dll and ssleay64.dll files are in the \windows\system32 directory.

See Also

Best practice for installing IIS Web Policy Agents (All versions)

How do I silently remove a Web Agent (All versions)?

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

SSL in AM/OpenAM and Policy Agents

Web Agent User Guide

Related Training

N/A

Related Issue Tracker IDs

N/A


Schannel communications fail in Web Agents 4.1, 4.2 and 5.x running on Microsoft Windows 2008 R2 or 2012 with TLS 1.2 enabled

The purpose of this article is to provide assistance when Schannel (the built-in Secure Channel API for SSL/TLS communications) fails in Web Agents running on Microsoft® Windows® 2008 R2 or 2012 when TLS 1.2 is enabled. You will see a "creating security context failed (0x80090308)" error when this happens.

Symptoms

The web agent running on Microsoft Windows 2008 R2 or 2012 fails to create a connection to an AM server that only has TLS 1.2 enabled. This issue does not occur on Microsoft Windows 2016 or 2019 servers.

The following error is shown in the agent debug log when this happens:

net_client_handshake_loop(): creating security context failed (0x80090308)
wnet_connect(): failed to connect to 192.0.2.0:8443, error: -29
SSL/TLS connection to 192.0.2.0:8443 failed (operation not completed)
unable to connect to 192.0.2.0:8443

The 0x80090308 code signifies a SEC_E_INVALID_TOKEN error.

Recent Changes

N/A

Causes

The web agent cannot negotiate the acceptable cipher, which causes the connection to fail.

Solution

This issue can be resolved by applying the KB3140245 update: you can download this from: Microsoft Update Catalog: KB3140245.

See Update to enable TLS 1.1 and TLS 1.2 as default secure protocols in WinHTTP in Windows for further information on this update.

See Also

FAQ: SSL/TLS secured connections in AM/OpenAM and Policy Agents

SSL in AM/OpenAM and Policy Agents

User Guide › Configuring Bootstrap Properties

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...