FAQ
ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: SSL certificate management in AM and Agents

Last updated Sep 22, 2021

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


2 readers recommend this article

Frequently asked questions

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

Q. Does AM 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 requires a certificate in order to set up secure connections. See Configuring AM's Container for HTTPS 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 runs on is unable to trust the certificate presented by other servers and/or client applications that are trying to connect to AM 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 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 Configuring AM's Container for HTTPS. 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 (All versions) for SSL? for further information.

To connect to DS over LDAPS in this scenario, you should follow the instructions given in Preparing a Truststore (AM 7 and later) or How do I make AM 5.x and 6.x communicate with a secured LDAP server?

Q. Does AM require a specific keystore type?

A. AM 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.

In other cases where the certificates are processed by AM itself (for example, SAML2 federation or x509 certificate authentication) the keystore type does matter. The default directory for keystore files varies by version as follows:

  • AM 7 - the .keypass and .storepass files are located in /path/to/openam/security/secrets/default, and the keystore.jceks and keystore.jks files are located in /path/to/openam/security/keystores.
  • Pre-AM 7 - the keystore files (.keypass, .storepass, keystore.jceks / keystore.jks) are located in /path/to/openAM.

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 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 Agent trust the server certificate?

A. Yes, the Web 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 agent only trusts the AM 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 Properties Reference for further information on these properties.

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

A. Two-way SSL (also referred to as mutual SSL or Certificate Authentication) is where the agent provides its certificate for AM 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 Configure Server-Side and Client-Side Validation using OpenSSL for further information on these properties. Alternatively, these properties can be set as environment variables prior to installing your Web Agent as detailed in Web Agent Installer Environment Variables.

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

A. You need to add the CA signed certificate to the AM 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 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 To Configure the OAuth 2.0 Provider to Sign Client-Based Tokens for further information about this signing key.

See Also

FAQ: SAML certificate management in AM 5.x and 6.x

FAQ: SSL/TLS secured connections in AM and Agents

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

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

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

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

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

Configuring Secrets, Certificates, and Keys

The Most Common OpenSSL Commands

keytool command


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.