SSL configuration options

Use of TLS/SSL in service.monitor

service.monitor can handle all HTTP communication with Transport Level Security (TLS/SSL). This procedure is also explicitly recommended, but some implications must be taken into account.

service.monitor uses HTTP(S) for:

  • querying/monitoring of services

  • testing of monitoring jobs in the user interface

  • query of ArcGIS Server tokens, if necessary for authentication

  • communication with security.manager (ONLY_AUTH authentication)

  • requesting services from a monitoring source (service harvesting)

  • sending messages to webhooks (MS Teams, Slack)

With consistent validation of SSL certificates, this means that error messages can appear in different places if non-valid or untrusted certificates are used on the other side:

  • Log files

  • User interface (test and request logging)

  • Notifications

General information about SSL/TLS

When establishing connections to HTTPS endpoints through server-side Java components, it must be ensured that the TLS/SSL server certificate of the requested host is accepted and trusted by the Java Virtual Machine (JVM). Otherwise, no HTTPS connection to the server is established and the application responds incorrectly.

The configuration option security.ssl.trustAny controls under which conditions a TLS server certificate is accepted:

security.ssl.trustAny=false (empfohlen)

Only certificates that are considered trustworthy by the JVM are accepted.

It is strongly recommended keeping this setting. This is especially true for productive environments. You must ensure that server certificates from HTTPS endpoints to which connections are made are trusted. Otherwise, an error will occur when establishing a connection.

security.ssl.trustAny=true

All certificates are accepted.

The certificate does not have to be issued to the requested host or by a trusted authority. This setting should only be active in development environments.

Trusting Server Certificates

For a server certificate to be considered trustworthy by the JVM, either the specific server certificate or its root certificate must be installed directly in the Java Runtime Environment (JRE). Trusted certificates or root certificates are stored in the JRE by default in a Java keystore under [JRE_HOME]/lib/security/cacerts.

Depending on the operating system or JVM configuration, other sources of trusted certificates may be used.

The following list describes what types of server certificates are commonly used by HTTPS endpoints and what needs to be considered in terms of trustworthiness.

(A) Certificates with root certificate installed in the JRE

Productive websites that provide services via HTTPS typically have server certificates whose root certificate was issued by a Trusted Certificate Authority (CA). These root certificates are pre-installed in the JRE and are thus automatically classified as trusted.

To allow connection to an endpoint whose server certificate has a root certificate already installed in the JRE, no further steps are required.

(B) Certificates with root certificate not installed in the JRE

Occasionally, organizations use server certificates issued by their own internal CA. The associated root certificate is therefore not part of the pre-installed certificates in the JRE. Connections to HTTPS endpoints with such server certificates then fail, unless the root certificate is automatically added to all JRE installations by corporate processes.

To ensure that all server certificates issued by this organization’s internal CA are trusted, the CA’s root certificate must be added to the keystore [JRE_HOME]/lib/security/cacerts.

(C) Self-signed certificates

Self-signed server certificates, i.e. certificates that reference themselves as issuers, are often used for test purposes and should not be used in production systems. Since a self-signed server certificate is not part of the certificates already installed with the JRE, it is not trustworthy.

To allow HTTPS connections to a host that uses a self-signed server certificate, this certificate must be added to the keystore [JRE_HOME]/lib/security/cacerts.

Typical Error Messages

When establishing server-side HTTPS connections, various error situations can occur in connection with the validation of server certificates. The following sections list typical error messages that may appear in the log file of the server-side application or in the browser interfaces of the applications. In addition, their possible causes are described and solutions proposed. Depending on the concrete infrastructure in which the affected application is operated, other causes and solutions may also need to be considered.

Typical error message:

PKIX path building failed

Complete error message:

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

This error message indicates that the certificate presented by the server for the HTTPS connection is not trusted by the JVM. It may be a self-signed certificate or the root certificate is not installed in the JRE.

Possible solutions:

  • Installing the root certificate in the JRE

  • Installing the server certificate in the JRE

  • If the requested server is controlled by the same organisation as the client: Provision of a new server certificate issued by a trusted CA on the requested server

No name matching [requested.host.name] found

Complete error message:

javax.net.ssl.SSLHandshakeException:
 java.security.cert.CertificateException: No name matching maps.example.com found

This error message indicates that the host name used in the HTTPS request does not match the host name specified in the server certificate. The client (browser, Java application) compares the host name used in the request URL with the CN name of the Subject field in the server’s X509 certificate, e.g. https://maps.example.com/ with CN = www.example.com, O = Example LLC, L = Mountain Dew, ST = California, C = US.

If both names do not match (upper/lower case is not relevant), the connection will be aborted with the above error message. It is irrelevant whether the certificate would be classified as trustworthy or not. The trustworthiness check does not take place until the host names have been matched.

This problem often occurs when clients can address the same server with different names because several DNS entries exist. Especially if the client is in the same domain as the server, the inconsistent use of unqualified and fully-qualified host names in request URLs or server certificates often leads to this problem. Using the special host name localhost or IP addresses in URLs also causes this problem if the server certificate was issued on the qualified host name.

Possible solutions:

  • Use the host name in request URLs as specified in the server certificate.

  • Create and deposit a new server certificate for the host name desired by the client if, for example, it turns out that it does not make sense to use a host name (or localhost or IP address) that is not fully qualified.

  • Create and deposit a new server certificate with alternative host names (Subject Alternative DNS Names) if, for example, it turns out that the server must inevitably be accessible under different host names.

No subject alternative DNS name [requested.host.name] found

Complete error message:

javax.net.ssl.SSLHandshakeException:
 java.security.cert.CertificateException: No subject alternative DNS name matching maps.example.com found

This error message is a special case of the error message No name matching [requested.host.name] found. The only difference is that the server certificate has an additional field with alternative host names, but the host name used by the client does not correspond to the Subject CN of the server certificate, nor is it specified in the list of alternative host names (Subject Alternative DNS Names).

Possible solutions: Similar to the suggested solutions for the previous error.

Typical scenarios

Job logging shows errors

Error messages are displayed in the request history of the user interface:

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

This means that when a monitoring job was executed, an HTTP endpoint was addressed whose SSL certificate is not valid.

Possible solutions:

  • Import of the certificate into the Trust Store

  • Setting of the property security.ssl.trustAny

  • Notice to the service provider to use a valid certificate.

Fehlschlag eines Test-Requests

When a test request is executed, the following appears in the browser:

test request failed

This means that when testing a monitoring job, an HTTP endpoint was addressed whose SSL certificate is not valid.

Possible solutions:

service.monitor cannot perform authentication with security.manager (ONLY_AUTHN)

The user authenticates himself at security.manager and is redirected back to service.monitor. However, service.monitor cannot establish an (SSL) connection to security.manager to validate the cookie and in turn redirects the user back to security.manager. The result is a rapid sequence of redirects and the message in the browser err_too_many_redirects.

Possible solutions:

  • Import the certificate of the security.manager host into the Trust Store.

  • Setting of the property security.ssl.trustAny.internal.

  • Use of a valid certificate for security.manager

  • Use of HTTP for the connection of security.manager