Product Selector

Fusion 5.9
    Fusion 5.9

    Importing Security Certificates

    There are numerous reasons that you might be required to import security certificates into the trusted keystore that the Java Virtual Machine (JVM) or the Appkit application is configured to use. These include:

    • Resources from secure servers proxied through Appkit (such as images displayed using the Media module)

    • Authentication mechanisms which require communication with secure back-ends

    • Search platforms using secure protocols for communication

    The JVM comes with a default keystore containing the root certificates for numerous Certificate Authorities (CAs). These are bodies which issue secure certificates, typically used during encrypted HTTPS communication over SSL.

    However not all certificates are recognized by the JVM when it is acting as an HTTPS client communicating with a secured server. This will usually manifest itself as an error coming from the application such as a java.security.cert.CertificateException error. If the error is coming directly from the browser (easily identifiable as a non-Java exception) then it is the user’s browser or operating system rejecting a certificate and not an Appkit related problem.

    If it is evident that the issue is that the JVM does not trust the CA that issues your SSL certificate it does not mean that the certificate is not valid, but rather that the database of valid CAs that comes with the JVM is not complete and does not include the CA root certificate. To solve this you must import the SSL certificate into the Java keystore on each VM running Appkit.

    Fusion 5.x

    Using a custom certificate for the api-gateway`

    See Create a Java Keystore for Use with Fusion for more information about the process of adding certificates to your Java KeyStore to use with the api-gateway.

    Using custom certificates for specific connectors

    See the Add additional trusted certificate(s) for connectors to allow crawling of web resources with SSL/TLS enabled section of Deploy Fusion at Scale for more information about the process of adding a custom certificate for specific connectors.

    Java SSL

    1. Download the certificate

    Download or otherwise obtain the SSL certificate CRT file for the secured server in question. If the server is accessible from a browser, an easy method to download the certificate is to use the browser’s security inspection tools (usually clicking on the padlock icon in most browsers). For example, in Safari it can be done in this way for https://www.google.co.uk:

    Safari’s certificate information

    Download the certificate by clicking on the link to the .CRT file and save it as "c:\gsa.crt", for example.

    2. Import the certificate

    1. Run the Java keytool on the machine on which you are running Appkit. This can be your local development machine or a VM or server for QA or production. Assuming you have set the JAVA_HOME environment variable as indicated below:

      %JAVA_HOME%\bin\keytool -importcert -trustcacerts -file c:\gsa.crt -keystore %JAVA_HOME%\jre\lib\security\cacerts

      • Change the path to the .CRT file if needed.

      • The default password of the JVM cacerts keystore is "changeit"

    2. Restart the application server (for example, Tomcat) and retry the action that requires communication over SSL.

    This is a purely SSL+Java configuration issue and has nothing to do with Appkit. If you Google the issue "peer not authenticated", you will find a lot of people suggesting a workaround that is to simply accept all SSL certificates in the Java HTTP client. That is a very bad idea for the reason that it bypasses SSL security and exposes the application to a MITM attack.