SSL certificates explained for GSA Server

[markvanderhurk]

SSL certificates are required to setup and use GSA Server and it's applications, such as the Lite application. In many implementation projects, we have seen that SSL certificate requirements is a 'tough' topic - merely because it requires a combination of knowledge that is sometimes scattered.

TCP Ports and instances
GSA Server instances run on a certain TCP port; each instance is bound to a certain port. A port can not be shared by multiple instances, and, the other way around, an instance can only run on one TCP port. GSA Server defaults to port 8080, unless specified differently. Worldwide, the common port for https traffic is 443. This is the only port number that will not be visible in URLs (i.e. https://gsaserver.geospatialanalysis.online/Lite is accessed on port 443, whereas https://gsaserver.geospatialanalysis.online:8080/Lite is accessed on port 8080).
The startup parameter used to specify the port used by GSA Server is /serviceport followed by the TCP port number desired, i.e. /serviceport 443

Requirements
To access both the management page (Portal) and any of the applications running on GSA Server, you will need at least an SSL certificate. Currently, most browsers will allow you to access a web page even when the certificate is not valid/validated. A warning will be displayed, usually with a (visible or hidden) option to continue. However, during the past years browser security has become more strict. It is not unimaginable that in future versions of various browsers, websites can't be accessed anymore when the SSL certificate for a website is not valid - not even allowing you to continue and accept the risk. Note: a self signed certificate is never considered valid nor safe.
It is always recommended to have a valid certificate in place for GSA Server.

Certificate trust
A certificate belongs to a chain of trust, directly or indirectly following a path to a trusted 'anchor' - a certificate authority (CA). A computer 'knows' which instances to trust. Some are managed outside of the organisation (i.e. Comodo SSL, DigiCert, Entrust Datacard, GeoTrust, GlobalSign, GoDaddy, Network Solutions, RapidSSL); in this case the Operating System (Windows, MacOS, etc) updates take care of the trust anchors being present within the Operating System. That means that i.e. Microsoft will tell your Windows installation through updates that a certain DigiCert root certificate is considered safe. Any certificate issued by a trusted CA is considered safe.
Some certificate authorities are managed inside an organisation; a well known certificate authority system is the one that is part of Microsoft Active Directory (AD-CA). Many organisations issue their own certificates for use within the organisation using AD-CA. Computers used in that organisation know (usually by group policies) that a certificate issued by the organisation's CA is considered safe as well, by trusting the organisation's CA. However, any computer not belonging to the organisation will not consider a certificate as valid, because the CA is not known to them. Therefore this way of trust only works within the organisation; a public facing website can never use this kind of trust.
The difference in certificate authorities' trust is usually referred to as 'externally trusted' vs 'internally trusted'.
GSA Server will work with both kinds of trust, as there is no technical difference in the SSL certificate.

Certificate types
There are many types of SSL certificates. Some options have to be in place, others are indifferent for GSA Server.

• Extended Validation (EV SSL), Organization Validated (OV SSL) and Domain Validated (DV SSL) are three types of SSL certificates. At least DV is required, OV/EV is allowed. So, any type will do.
• Wildcard/non-wildcard: optionally required, depending on use (see: relation to GSA Server settings)
• Enhanced Key Usage: at least Server Authentication (1.3.6.1.5.5.7.3.1)

Certificate options

• Subject: the hostname or FQDN-hostname, depending on use (see: relation to GSA Server settings)
• Subject Alternative Names (SAN): depending on use (see: relation to GSA Server settings)

Example values as used in the examples below
Please translate these to values applicable in your own environment; these example values are used to make the examples more clear

• Organization's domain: customdomain.com
• GSA Server host: server01
• GSA Server FQDN: server01.customdomain.com
• GSA Server alias: gsalite.customdomain.com, GSA Lite accessible on TCP port 443 through
  https://web.gsalite.customdomain.com/Lite

GSA Server Settings (operating mode)
GSA Server has three modes to operate on, regarding it's accessibility: https://documentation.geospatialana...8/en/c33be8a5-f166-4eee-92d7-47ab7a38692b.htm (this is the 5.2.8 documentation, please use the applicable version).

1. host name (withouth postfix, i.e. server01)
2. domain host name (with postfix, i.e. server01.customdomain.com)
3. custom host name (to use with aliases, i.e. application running on server01.customdomain.tld but have GSA accessed through gsalite.customdomain.tld)

The operating mode has impact on the SSL certificate required. It is possible to have an SSL certificate configured in a way that all three modes will work. The next paragraph will explain this using an example configuration.

Relation to GSA Server settings

1. For use with mode 1 (host name), make sure the subject of the certificate matches the hostname. If there are other requirements to the subject of the certificate, make sure the host name (example: server01) is at least added as 'DNS Name' to the Subject Alternative Name list of the certificate.
2. For use with mode 2 (domain host name), make sure the subject of the certificate matches the FQDN hostname. If there are other requirements to the subject of the certificate, make sure the FQDN host name (example: server01.customdomain.com) is at least added as 'DNS Name' to the Subject Alternative Name list of the certificate.
3. For use with mode 3 (custom host name), it is most common to have the subject set to the FQDN hostname (example: server01.customdomain.com). It is important to have the Subject Alternative Name populated with DNS Name type values containing:
   1. the FQDN hostname (example: server01.customdomain.com)
   2. the alias FQDN hostname (example: gsalite.customdomain.tld) (set in GSA portal)
   3. the combination of static prefix as set in GSA portal and the ; the value defaults to 'static' but in this example set to 'web'; add web.gsalite.customdomain.tld to the SAN list
   4. the combination of api prefix as set in GSA portal and the ; the value defaults to 'api'; add api.gsalite.customdomain.tld to the SAN list
   5. the combination of tiles prefix as set in GSA portal and the ; the value defaults to 'tiles'; add tiles.gsalite.customdomain.tld to the SAN list
4. The certificate created using 3) will work with operating modes 2 and 3; if a certificate is required for all three operating modes, add the host name (example: server01) to the SAN list.

Note: it is recommended to use 4) to create an SSL certificate, as this is the most flexible.

Load balancer and external access options
In a more complex environment, sometimes a load balancer, or external access options are added. This might impact the setup of SSL certificates. Please refer to <topic to be added 08/2021> for an example setup using Microsoft Azure App Proxy and a local load balancer.

DNS
Note: the DNS Server(s) accessed by the users of GSA have to be aware of the values set for operating mode 3. This is not a certificate requirement, but is sometimes overlooked. The DNS entries have to be set as an alias for the FQDN hostname (i.e. web.gsalite.customdomain.com needs to resolve to server01.customdomain.tld).