Import SSL Certificates in SynAdmin

This chapter describes how to import and manage SSL certificates in the WebOffice 10.9 R3 application using the WebOffice Administration Page (SynAdmin).

 

In client environments sometimes problems with secured connections may occur because the certificate of the requested server is not trusted (e.g. with self-signed certificates).

A typical log error could be:

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

 

In order to solve the problem, the available certificate of the requested server  (or a certificate located in the KeyChain or higher, e.g. the certificate of the certificate authority of the respective certificate) has to be imported into the Java trustore (certificate store).

The truststore by default (e.g. if not configured in another specific way) is .\Java\jre\lib\security\cacerts in the Java JRE currently used by WebOffice and has the password changeit.

 

The import workflow can be done manually, e.g. with the tool KeyStore Explorer (Download: http://www.keystore-explorer.org); see chapter Import of SSL/TLS-Certificates for a step-by-step instruction.

It can also be done faster by a customized BAT file that you can find on the WebOffice10.9R3-DVD in

.\Software\Miscellaneous\Automatization\Import_Certificates.bat.

 

No matter whether it is done manually or automated with the BAT file, the workflow requires deep understanding of the technical environment (Which JRE is in use? How does the KeyChain of the certificate look like? Which URL has to be used? etc.), which sometimes lead to a lack of clarity and loss of time.

 

For this reason starting with version WebOffice 10.6 R2 SP1 a new option for WebOffice administrators exists to manage certificates in the SynAdmin. The Certificates tab both displays information about the certificate store used by the WebOffice 10.9 R3 application and offers functionality to import and/or remove SSL certificates into/from the certificate store.

 

icon_cross-reference

Fine a detailed description about the displayed information in chapter Certificates Tab.

 

Import SSL certificates in SynAdmin

In the bottom part of the administration site you can check a certificate for a specific http domain using the Display Certificate Check button, and on the result page set the certificate as trusted.

Steps in SynAdmin:

1.Click Display Certificate Check

2.Enter Hostname and Port.

icon_comment

Check in the Browser if the Hostname and the Port is available!

3.Click Start Check

Now a certificate check for the certificate to be imported is done

4.Next to the listed certificate you can click Import in order to import the certificate into the certificate store of Java and WebOffice.

icon_comment

If Apache Tomcat runs under its own user, then this user must have appropriate permission rights to the path of the Java certificate store. Otherwise the import is cancelled with a corresponding error message.

By default the port is 443. So if no port is entered, it will be searched in the IIS-Trust Store. For checking the ArcGIS Server Certificates, you can enter the port 6443.

 

icon_warning

CAUTION!

If the connection to a service is secured with a certificate, the host name must match the specification in the certificate.

This applies in particular if the server uses a so-called wildcard certificate, which can be used not only for one machine but for a whole series of hosts.

Therefore, no local host name (e.g. localhost or server01) may be used, but always the complete host name (e.g. "server01.company.com).

This concerns on the one hand all services which are entered in project configuration, and on the other hand the hostnames which are entered with the tool Check certificate.

Incorrectly entered hostnames lead to the following error:

Connection failed: No matching subject alternative name found for <servername>.  

icon_comment

If a wildcard certificate is present, please make sure that the full hostname was used for the verification (e.g. server01.company.com instead of server01).

 

Hostname URL eintragen und Überprüfung ausführen

Hostname URL eintragen und Überprüfung ausführen

 

Zertifikat in beiden Zertifikatsspeichern importieren

Zertifikat in beiden Zertifikatsspeichern importieren

 

Copy an SSL certificate into the WebOffice certificate store in SynAdmin

A certificate that is located in the Java certificate store can be also copied into the WebOffice certificate store by clicking the button Copy to the right of the certificate name. Only if a certificate is located in the WebOffice certificate store, it can be assured that after a Java update (new Java certificate store) the certificate stays trusted.

 

icon_cross-reference

If the WebOffice application is exchanged during an upgrade, the existing WebOffice certificate store will be replaced by a new empty one. Therefor, it is recommended to use the script Export Customized Files to backup your WebOffice certificate store along with other customized files and reimport all of them after the upgrade.

See chapter Import of SSL/TLS-Certificates for further information regarding the management of certificates.