Skip to main content

Security Configuration Options for Deployment

Arik Katz
  • Updated

In this article:

Overview

SkylineGlobe Server (SGS) should be deployed with HTTPS to ensure secure communication and browser compatibility - for TerraExplorer Fusion (TEF), which requires HTTPS for advanced browser features like SharedArrayBuffer. This technology enables high-performance applications on web pages, but it requires certain security measures to function properly. For local development, SGS may run over http://127.0.0.1, but production environments must use HTTPS (Hyper Text Transfer Protocol Secure) and possess a valid TLS (Transport Layer Security) certificate. HTTPS ensures that the data transfer between the user's browser and the website is encrypted, while the TLS certificate authenticates the website's identity, providing a double layer of security. 

You can configure HTTPS using either of the following approaches:

  • External HTTPS Termination (Recommended for Docker/Kubernetes): Use a reverse proxy like NGINX (Docker) or an Ingress controller (Kubernetes) to terminate the TLS connection. This offloads HTTPS handling from SGS and simplifies server configuration. When using this method, you must provide a TLS certificate and key to the reverse proxy. The certificate can be either:
    • Issued by a recognized third party, like a Certificate Authority (CA) (recommended for production environments). A CA-issued certificate verifies the website's identity and ensures its authenticity, providing a high level of trust and security. 
    • Self-Signed TLS Certificate (for development or internal testing): In this setup, the certificate is self-issued, rather than being obtained from a trusted CA. While a self-signed certificate can encrypt data, it lacks the third-party verification essential for full authentication. Web browsers typically display warnings for these sites, indicating a lower level of trust. See below how to create a self-signed certificate.
  • Internal HTTPS via Kestrel (for Windows): Configure SGS to serve HTTPS directly using its built-in Kestrel web server. This option requires a .pfx certificate that contains both the server’s certificate and private key in a single file. Kestrel-based HTTPS is supported in Windows deployments. 

Creating a Self-Signed Certificate

  1. Install an OpenSSL tool to create a self-signed certificate:
    • If you're deploying Kubernetes on Windows: Download and install from https://slproweb.com/products/Win32OpenSSL.html (choose the version that matches your system).
    • Alternatively: Use a terminal environment that includes OpenSSL, such as Git Bash or Windows Subsystem for Linux (WSL).
  2. Download the openssl.cfg configuration file that specifies your self-signed certificate settings, such as the Common Name (CN) sgs.localhost:
    # openssl.cfg
    [ req ]
    default_bits    = 2048
    prompt       = no
    default_md     = sha256
    distinguished_name = dn

    [ dn ]
    CN = sgs.localhost
    O = Local Dev
  3. Run the following OpenSSL command to generate a self-signed certificate and private key and store both files in a convenient local folder (e.g., tls/).
    openssl req -x509 -nodes -days 365 -newkey rsa:2048  -keyout nginx/certs/tls.key -out nginx/certs/tls.crt  -config openssl.cfg

Using the Self-Signed Certificate 

Using in:

Docker Compose

  1. Create an nginx folder inside the project folder that will be mounted as a volume inside the container - typically at /app/nginx to hold the nginx.configuration and self-signed certificate (tls.crt) and private key (tls.key) generated below. Then create a certs subfolder inside the nginx folder. In your terminal, run the following commands:
    md nginx
    md nginx\certs
  2. Download the NGINX configuration file (nginx.conf) and place it inside the nginx/ folder in your Docker project. This configuration tells NGINX to do the following:
    • Listen on port 443 for HTTPS traffic
    • Use the self-signed certificate (tls.crt) and key (tls.key)
    • Forward all incoming requests to the SkylineGlobe Server application running inside the container on port 5155
  3. Create a self-signed certificate (tls.crt) and private key (tls.key). 
  4. In your nginx.conf file, the TLS certificate (tls.crt) and key (tls.key) should be referenced under "server":
      server {
        listen 443 ssl;
        server_name sgs.localhost;
        ssl_certificate   /etc/nginx/certs/tls.crt;
        ssl_certificate_key /etc/nginx/certs/tls.key;

Kubernetes

  1. Create a self-signed certificate (tls.crt) and private key (tls.key).
  2. Use the generated certificate and key to create a Kubernetes TLS secret named sgs-tls-secret. This secret will be referenced in your Ingress configuration (ingress.yaml) to enable HTTPS:
    kubectl create secret tls sgs-tls-secret --cert=tls.crt --key=tls.key
  3. Install the Ingress Controller. This sets up the necessary Ingress infrastructure to route external traffic to your services securely over HTTPS. Make sure port 443 is not occupied by another process.
    kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml
  4. In your ingress.yaml file, the TLS secret (sgs-tls-secret) should be referenced under the tls: section, along with the host that matches the Common Name (CN) used in your certificate (e.g., sgs.localhost):
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
     name: sgs-ingress
     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

Kestrel: TLS Configuration Support (Windows)

SGS supports built-in HTTPS on Windows using the Kestrel web server. This can be configured directly in the appsettings.json file.

To enable HTTPS with Kestrel:

  1. Create a self-signed certificate (tls.crt) and private key (tls.key). 

  2. Create an sgs.pfx in your current folder with the TLS certificate and private key.
    openssl pkcs12 -export \
      -out sgs.pfx \
      -inkey tls.key \
      -in tls.crt \
      -passout pass:yourpassword

  3. Reference the generated pfx and password in your configuration file (appsettings.json)  to enable HTTPS:  "Kestrel": {
       "Endpoints": {
         "Https": {
          "Url": "https://*:5000", // 🌍 Change port or interface if needed (e.g., "https://localhost:443")
          "Certificate": {
            "Path": "Path\\To\\Certificate.pfx", // 🔐 Full path to a .pfx certificate file
            "Password": "PWD" // 🔑 Certificate password
          }     }    }

Local Server Operation Without SSL Encryption (HTTP)

  • Use localhost or http://127.0.0.1 and http://127.0.0.1/TEF instead of a domain or machine name to access both the server and the client. This is necessary to comply with browser security restrictions when operating without SSL encryption.
  • Update the public URL: Change the public URL to http://localhost or http://127.0.0.1. Then publish your projects using this updated URL. Note that this method is only suitable for testing, learning, and development on the same machine. For remote server access or broader operational use, you need to use SSL (HTTPS).

    • Windows → appsettings.json

    • Docker → docker-compose.yaml

    • Kubernetes → deployment.yaml

Troubleshooting

  • SharedArrayBuffer: The SharedArrayBuffer JavaScript Object, used to share memory across a cluster, requires specific cross-origin tags in the server's response headers. If your TerraExplorer Fusion is hosted on a server that SkylineGlobe Server is not installed on it, it will lack the necessary tags, leading to the following error: "Uncaught ReferenceError: SharedArrayBuffer is not defined."
    cors errorbig.png

    • Solution: Configure your server to ensure these tags are included in your server's responses:

      <add name="Cross-Origin-Embedder-Policy" value="require-corp" />
      <add name="Cross-Origin-Resource-Policy" value="cross-origin" />
      <add name="Cross-Origin-Opener-Policy" value="same-origin" />
  • Mixed Content: This issue arises when a webpage loaded over HTTPS includes resources (like images, videos, feature layers, 3D Models, scripts) that are loaded over an insecure HTTP connection. Such a mix can create security vulnerabilities, exposing users to malicious activity such as unauthorized tracking and on-path attacks. Most modern web browsers block such content.
    • Solution: Make sure all resources in the TEF client are loaded from HTTPS servers.
  • Failed to Connect to Server: This issue arises when attempting to publish from TerraExplorer Desktop to SGS from a secured site with a self-signed SSL certificate. The following error message is displayed: "Failed to connect to server. Server is unavailable."
    errorSSL.png
    • Solution: Contact Skyline support for assistance.
  • Unable to Log in to Server from Firefox: When attempting to log in to the server using the Firefox browser, the process fails, leaving the user stuck on a "Redirecting..." window after clicking the log-in button instead of completing the login process.
    • Solution: The problem stems from Firefox's default settings, which restrict the sharing of cookies between different domains - an essential step for the login process. To fix this, adjust Firefox's cookie settings to allow cross-site tracking cookies. This can be done by accessing the Privacy & Security section within Firefox's Settings. Here, select Custom as the Browser Privacy setting and then select Cross-site tracking cookies from the Cookies dropdown. Then select Reload All Tabs for the changes to take effect. 
      firefox.png

Related articles