SSL configuration

service.monitor can handle all HTTP communication with Transport Level Security (TLS/SSL).

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

When establishing connections to HTTPS endpoints through server-side Java components, ensure Java Virtual Machine (JVM) accept and trust the TLS/SSL server certificate of the requested host. Otherwise, no HTTPS connection to the server is established, and the application responds incorrectly.

Use the security.ssl.trustAny configuration option to control under which conditions a TLS server certificate is accepted.

security.ssl.trustAny=false (recommended): Only certificates that are considered trustworthy by the JVM are accepted.

We strongly recommend 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

So that the JVM consider a server certificate trustworthy, 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 is 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, add the CA’s root certificate to the keystore [JRE_HOME]/lib/security/cacerts.

(C) Self-signed certificates

Self-signed server certificates — 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, add this certificate 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
No name matching [requested.host.name] found
No subject alternative DNS name [requested.host.name] found

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

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

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 store a new server certificate for the host name desired by the client, for example when using a non-fully qualified host name (or localhost or IP address) is nt practical.
Create and store a new server certificate with alternative host names (Subject Alternative DNS Names), for example if 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. However, the host name used by the client does not correspond to the Subject-CN of the server certificate nor to one in its 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

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.

Test request failure

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

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

Possible solutions:

See Job logging shows errors - possible solutions

Authentication with security.manager not possible (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