Outgoing HTTPS Connections

security.manager Web applications connect to other endpoints over HTTPS for the following purposes:

  • Communication between security.manager Web applications

  • Forwarding requests to protected services or requesting service metadata from them

  • Requesting geometries from services to provide spatial obligation geometries

  • Validating and requesting tokens from ArcGIS Server and Portal for ArcGIS

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 (recommended)
    Only certificates that are considered trustworthy by the JVM are accepted. It is strongly recommended to keep 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 occurs 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. Activate this setting in development environments only.

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 might 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 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 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, which reference themselves as issuers, are often used for test purposes. Do not use them in production environments. Because 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 might 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 might also need to be considered.

1. "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 might be a self-signed certificate or the root certificate is not installed in the JRE.

Possible solutions:

  • Install the root certificate in the JRE

  • Install the server certificate in the JRE

  • If the requested server is under your control: Provide a new server certificate issued by a trusted CA on the requested server.

2. "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 hostname used in the HTTPS request does not match the hostname specified in the server certificate. The client (browser, Java application) compares the hostname used in the request URL with the "CN" name of the "Subject" field in the server’s X509 certificate, for example
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 is aborted with the preceding error message. It is irrelevant whether the certificate is classified as trustworthy or not. The trustworthiness check does not take place until the hostnames 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 hostnames in request URLs or server certificates often leads to this problem. Using the special hostname "localhost" or IP addresses in URLs also causes this problem if the server certificate was issued on the qualified hostname.

Possible solutions:

  • Use the hostname in request URLs as specified in the server certificate.

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

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

3. "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 hostnames, but the hostname used by the client does not correspond to the "Subject CN" of the server certificate, nor is it specified in the list of alternative hostnames ("Subject Alternative DNS Names").

Possible solutions: Similar to the suggested solutions for the error "No name matching [requested.host.name] found".