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?
- Q. Why am I getting Exception: unable to find valid certification path?
- Q. Where are the Root CA certificates stored?
- Q. What is the difference between the keystore and truststore?
- Q. Can I use my own truststore rather than the default truststore?
- Q. Does AM require a specific keystore type?
- Q. How do I list the keys in my keystore?
- Q. How long do the generated self-signed certificates last?
- Q. Why does the Persistent Cookie module still issue persistent cookies after the certificate has expired?
- Q. What happens to persistent cookies that were issued before the certificate was updated?
- Q. Will the Web Agent trust the server certificate?
- Q. How do I configure the Web Agent for two-way SSL?
- Q. How do I use an existing CA signed certificate (in PEM format) in AM?
- Q. How do I get the certificate out of the keystore in PEM format?
- Q. How do I convert a PEM certificate file and private key to PKCS#12 (.pfx .p12)?
- Q. How do I convert a PKCS#12 file (.pfx .p12) that contains a private key and certificates to PEM format?
- Q. How can I create an OAuth2 provider HMAC signing key in AM 6.5 and later using keytool?
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.
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
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.
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.
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?
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.
- 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.
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.
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.
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.
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.
- 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.
- 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.
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.
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
You can add -nocerts to only output the private key or add -nokeys to only output the certificates.
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.