How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Apr 7, 2021

The purpose of this article is to provide information on importing a certificate into the JVM truststore used by AM 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 to an external configuration store, communicating with an LDAPS server etc.


1 reader recommends this article

Overview

Like most web applications, AM 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. This allows the JVM to trust the server's SSL certificate and enables AM to make the SSL connection to the specific client:

Note

It is best practice to create a new JVM truststore with the certificates you need in your environment, and configure your container to use it, rather than use the default JVM truststore.

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 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 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 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 and 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 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. 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

FAQ: SSL/TLS secured connections in AM and Agents

FAQ: SSL certificate management in AM and Agents

Security Guide › Securing Network Communication

Security Guide › Configuring Secrets, Certificates, and Keys

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


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