System Administration

Page tree

Troubleshooting Certificates

To integrate with external systems, Agiloft typically connects to an external domain or server over SSL/TLS, which requires the external domain to provide a trusted certificate. If this certificate doesn't match a certificate in  Agiloft's keystore repository, the integration will fail and produce an error:

Example

Error: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

If you experience an error like this and you host a knowledgebase on your own server, you can solve the issue by self-signing and manually importing a certificate. If your knowledgebase is hosted on  Agiloft's servers and you experience an error like this, contact the  Agiloft support team.

Manually Import a Certificate

When you manually import a certificate, it's important to follow a couple of precautions to safeguard against security concerns. In particular, only import a non-trusted or self-signed certificate if both of the following are true: 

  • You are on a dedicated server.
  • The external party is well-known and reputable, such as DocuSign or Adobe Sign.

If either of these criteria are not met, check with an IT security expert or an  Agiloft professional before importing the certificate. You're responsible for any certificates you import, so make sure they're safe.

By default, the  Agiloft keystore repository is located at $AL_HOME/jre/jre/lib/security/cacerts, which contains existing certificates and certificates you import. 


To import a certificate:

  1. Download the certificate from the external party, or request that they provide the certificate for their domain to you, preferably in PEM format. If the certificate is in a different format, you can convert it to PEM format using the third-party OpenSSL tool, but we don't discuss that process here.

  2. Once you have the certificate on your machine, run the following command with root privileges:

    $AL_HOME/jre/bin/keytool -import -trustcacerts -keystore $AL_HOME/jre/jre/lib/security/cacerts -alias CustomDomain -file $FILENAME

    For example, if you are in the  Agiloft directory and the certificate is located at /home/tom/selfsigned.pem, the command would look like this:

    [root@Agiloft]# ./jre/bin/keytool -import -trustcacerts -keystore ./jre/jre/lib/security/cacerts -alias CustomDomain -file /home/tom/selfsigned.pem

  3. When the system prompts you to trust the new certificate, type "Yes" and press enter. The certificate is now imported.

  4. Restart the Agiloft service, and integrate with the external system as normal.

  • No labels