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:
- If you are configuring ssoadm, you also need to ensure you have configured ssoadm to trust AM as detailed in FAQ: Installing and using ssoadm in AM (Q. How do I install the ssoadm administration tool if I am using SSL?).
- If you are trying to make AM communicate with a secured LDAP (LDAPS) server such as DS (SSL/TLS enabled), see Preparing a Truststore (AM 7 and later) or How do I make AM 5.x and 6.x communicate with a secured LDAP server? for specific instructions.
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.
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:
- 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
- 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
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:
- Run the openssl command to display certificate details for the server: $ openssl s_client -connect [hostname:port] -showcerts
- Output details for the truststore to see what certificates it contains: $ keytool -list -v -keystore [truststore] -storetype [storetype] -storepass [password]
- 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.
For ssoadm only:
- Enable message level debugging for ssoadm as detailed in How do I enable message level debugging for ssoadm in AM (All versions)?
- Configure ssoadm to trust all certificates as detailed in FAQ: Installing and using ssoadm in AM (Q. How do I configure ssoadm to trust all certificates?).
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
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 ...