Security Configuration Options for Deployment – Skyline

In this article:

Overview
Obtaining or Creating a TLS Certificate
Configuring HTTPS with a TLS Certificate
Running Locally Without HTTPS
Troubleshooting

Overview

SkylineGlobe Server (SGS) should be deployed over HTTPS to encrypt communication, authenticate the server, and support browser security requirements used by TerraExplorer Fusion (TEF). You can configure HTTPS using either of the following approaches:

External TLS termination (recommended for Docker Compose and Kubernetes): Use a reverse proxy such as NGINX or a Kubernetes Ingress controller to handle HTTPS and forward requests to SGS over HTTP within the internal network.
Direct HTTPS through Kestrel (Windows): Configure the built-in Kestrel web server to handle HTTPS directly. This method requires a PFX certificate containing the TLS certificate and its private key.

The component that handles the HTTPS connection, either the reverse proxy or Kestrel, requires a TLS certificate. You can use either of the following certificate types:

CA-issued certificate: Recommended for production deployments. This certificate is issued by a trusted certificate authority (CA) and is automatically trusted by supported browsers and clients.
Self-signed certificate: Suitable for development or internal testing. A self-signed certificate encrypts communication but is not automatically trusted by browsers and other clients. You can create one using the procedure below.

For local development, SGS and TEF can also be accessed through http://localhost or http://127.0.0.1 without configuring HTTPS. See Running Locally Without HTTPS.

Obtaining or Creating a TLS Certificate

Before configuring HTTPS, obtain a certificate issued by a trusted certificate authority (CA) or create a self-signed certificate. The hostname used to access SGS must be included in the certificate.

CA-Issued Certificate

For a production deployment, obtain a certificate for the SGS hostname from a trusted CA. The required certificate format depends on how HTTPS is configured:

Docker Compose with NGINX or Kubernetes: A certificate file and its corresponding private-key file. The certificate file should include any required intermediate certificates supplied by the CA.
Kestrel on Windows: A PFX file containing both the certificate and its private key.

The examples below use the filenames tls.crt and tls.key. If your certificate files have different names, either rename them or update the corresponding configuration and commands.

Creating a Self-Signed Certificate

Use a self-signed certificate only for development or internal testing. Browsers and other clients do not automatically trust self-signed certificates and may display a security warning. For production deployments, use a certificate issued by a trusted CA.

Install OpenSSL on the computer on which you will generate the certificate:
- On Windows, download and install an appropriate OpenSSL package from Win32/Win64 OpenSSL.
- Alternatively, use a command-line environment that includes OpenSSL, such as Git Bash or Windows Subsystem for Linux (WSL).

In the folder in which you want to generate the certificate, create a file named openssl.cfg with the following contents:

[ req ]
default_bits       = 2048
prompt             = no
default_md         = sha256
distinguished_name = dn
x509_extensions    = v3_req

[ dn ]
CN = sgs.localhost
O = Local Dev

[ v3_req ]
basicConstraints = critical, CA:FALSE
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[ alt_names ]
DNS.1 = sgs.localhost

If you will access SGS using a different hostname, replace sgs.localhost in both the CN and DNS.1 entries. The hostname used to access SGS must be included in the certificate's Subject Alternative Name.

Open a command-line window in the folder containing openssl.cfg and run the following command. It creates a certificate named tls.crt and a private key named tls.key in the current folder:
```
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -config openssl.cfg
```

Configuring HTTPS with a TLS Certificate

After obtaining a CA-issued certificate or creating a self-signed certificate, follow the appropriate procedure below. The configuration procedure is the same for both certificate types.

The examples below use sgs.localhost, tls.crt, and tls.key. Replace these values as necessary with the hostname and filenames associated with your certificate.

Docker Compose

In a Docker Compose deployment, an NGINX container terminates the HTTPS connection and forwards requests to the SGS container on port 5155.

In your Docker project directory, create an nginx folder with a certs subfolder.

Windows Command Prompt
```
md nginx\certs
```
Bash, Git Bash, or WSL
```
mkdir -p nginx/certs
```
Download the NGINX configuration file (nginx.conf) and save it in the nginx folder.

This configuration instructs NGINX to:
- Listen on port 443 for HTTPS traffic.
- Use the TLS certificate and private key.
- Forward incoming requests to SGS on port 5155.
Place the generated tls.crt and tls.key files in the nginx/certs folder.
Verify that the following certificate paths are defined in the server block of nginx.conf:
```
server {
    listen 443 ssl;
    server_name sgs.localhost;

    ssl_certificate     /etc/nginx/certs/tls.crt;
    ssl_certificate_key /etc/nginx/certs/tls.key;
}
```
If you used a different hostname when creating the certificate, replace sgs.localhost with that hostname.
Verify that your Docker Compose configuration defines the NGINX service, publishes port 443, and mounts the following files or folders in the NGINX container:
- nginx/nginx.conf at /etc/nginx/nginx.conf
- nginx/certs at /etc/nginx/certs
See the SkylineGlobe Server Docker Compose NGINX example for a complete configuration.
Start or update the deployment:
```
docker compose up -d
```

Kubernetes

Ensure that a compatible Ingress controller is installed in your cluster. If necessary, follow the ingress-nginx installation instructions for your Kubernetes environment.
Open a command-line window in the folder containing the generated tls.crt and tls.key files. Create a Kubernetes TLS secret named sgs-tls-secret in the same namespace as the SGS Service and Ingress:
```
kubectl create secret tls sgs-tls-secret --cert=tls.crt --key=tls.key --namespace [NAMESPACE]
```
Replace [NAMESPACE] with the namespace used by your SGS deployment.

In ingress.yaml, reference sgs-tls-secret in the tls section. The host in the tls section must match both the host in the rules section and a hostname in the TLS certificate:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: sgs-ingress
  namespace: [NAMESPACE]
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - sgs.localhost
      secretName: sgs-tls-secret
  rules:
    - host: sgs.localhost
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: sgs-app-service
                port:
                  number: 80

Replace [NAMESPACE], sgs.localhost, the Service name, and the Service port with the values used by your deployment. See Deploying SkylineGlobe Server for the complete Kubernetes configuration.

Apply the Ingress configuration:
```
kubectl apply -f ingress.yaml
```

Kestrel: TLS Configuration Support (Windows)

On Windows, SGS can serve HTTPS directly through its built-in Kestrel web server. Kestrel requires a PFX certificate containing both the certificate and its private key.

If your certificate is already supplied as a PFX file, continue to step 2.
To convert the generated tls.crt and tls.key files to PFX, open Windows Command Prompt in the folder containing the files and run:
```
openssl pkcs12 -export -out sgs.pfx -inkey tls.key -in tls.crt -passout pass:[CERTIFICATE_PASSWORD]
```
Replace [CERTIFICATE_PASSWORD] with a password that protects the PFX file.
Store sgs.pfx in a secure location accessible to SGS.
Define the HTTPS endpoint and certificate in appsettings.json:
```
{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:5000",
        "Certificate": {
          "Path": "C:\\Path\\To\\sgs.pfx",
          "Password": "[CERTIFICATE_PASSWORD]"
        }
      }
    }
  }
}
```
- Url: Change the port or network interface if necessary.
- Path: Enter the full path to the PFX certificate file. Escape each backslash as \\ in JSON.
- Password: Enter the password used to protect the PFX file.
Protect the certificate password appropriately and do not commit a configuration file containing the actual password to source control.
Restart SGS for the configuration changes to take effect.

Running Locally Without HTTPS

For local development without HTTPS, use localhost or the loopback address 127.0.0.1 rather than a domain or machine name. Use the following addresses to access SGS and TEF:

Replace [:port] with the SGS port when a non-default port is used.

Troubleshooting

SharedArrayBuffer is not defined

SharedArrayBuffer requires HTTPS and a cross-origin-isolated browser context. Verify that the server hosting TEF returns the following response headers:
```
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```
If TEF loads resources from SGS or another server at a different origin, that server must also permit the resources to be loaded across origins. For SGS resources, verify that SGS returns:
```
Cross-Origin-Resource-Policy: cross-origin
```
Configure these headers on the component that returns the relevant response:
- Windows SGS deployment: Use the CustomResponseHeaders section of appsettings.json.
- Docker Compose or Kubernetes: Define the corresponding SGS environment settings in the Compose or Deployment YAML.
- TEF hosted separately from SGS: Configure the headers on the web server hosting TEF, such as IIS or NGINX.
These headers are defined by default in the CustomResponseHeaders section of appsettings.base.json, so no additional SGS configuration is normally required. Verify the response headers before adding or overriding them. Ensure that the headers are not also being added by a reverse proxy, Ingress controller, or inherited IIS configuration. Duplicate or conflicting headers can prevent cross-origin isolation.
Mixed-content warning

A page loaded over HTTPS cannot safely load images, videos, feature layers, 3D models, scripts, or other resources over HTTP. Most modern browsers block this mixed content. Ensure that all resources used by TEF are available over HTTPS and that their URLs use https://.
Failed to connect to the server from TerraExplorer Desktop

When publishing from TerraExplorer Desktop to SGS using a self-signed TLS certificate, TerraExplorer Desktop may display the following message: “Failed to connect to server. Server is unavailable.”

Solution: Contact Skyline support for assistance.
Unable to log in from Firefox

Firefox may remain on a “Redirecting...” page when its privacy settings prevent cookies from being shared between the domains involved in the login process.

In Firefox, open Settings > Privacy & Security and add an exception for the relevant SGS and authentication sites. If a site-specific exception does not resolve the problem, select Custom under Enhanced Tracking Protection and review the cross-site cookie setting. Limit any exception to the sites required for SGS authentication. Reload all relevant tabs after changing the setting.