Skip to main content

How to Set Up HTTPS in 1Gateway

To ensure that all data exchange remains secure and standardized across organizations, 1Gateway supports encrypted communication via HTTPS (TLS/SSL).

1. Introduction​

When HTTPS is enabled, all network traffic between clients and 1Gateway is encrypted. This ensures the confidentiality and integrity of data in transit.

Recommendation

Enabling HTTPS is strongly recommended for all production deployments and any environment where 1Gateway is accessible over a network to maintain a secure integration environment.

2. Certificates and Keystores​

2.1 Certificate​

A certificate identifies the 1Gateway server and enables encrypted HTTPS communication. These are typically issued by a Certificate Authority (CA) or can be self-signed for internal development environments.

2.2 Keystore​

A keystore is a specialized file that contains the server certificate and the corresponding private key. 1Gateway loads the keystore at startup to enable HTTPS.

2.3 Supported Keystore Formats​

1Gateway supports the following formats, though one is preferred for modern deployments:

FormatFile ExtensionRecommended
PKCS12.pfx or .p12✔ Yes
JKS.jksSupported

Note: PKCS12 is the recommended format for all new 1Gateway v4 installations.

3. HTTPS Configuration Overview​

The method for providing configuration details depends on your specific installation type:

  • Windows Service: Configuration is provided via the application.properties file.
  • Docker Compose: Configuration is provided via environment variables within your docker-compose.yml.

3.1 Required HTTPS Properties​

To successfully enable HTTPS, the following properties must be defined:

PropertyDescription
server.portThe HTTPS listening port (typically 443).
server.ssl.key-storePath to your keystore file.
server.ssl.key-store-passwordThe password for the keystore (can be plaintext or encrypted).
server.ssl.key-store-typeThe keystore type (PKCS12 or JKS).

4. Encrypted Configuration Values​

1Gateway supports encrypted configuration values for sensitive settings, such as keystore passwords. This functionality prevents plaintext secrets from being stored in configuration files, as encrypted values are resolved automatically 1Gateway at startup.

4.1 Encryption Service​

1Gateway provides an internal encryption service for administrative use.

  • Endpoint: https://localhost/api/v3/crypto/encrypt?text=<value>
    • Parameter: <value> is the plaintext value you wish to encrypt.
    • Result: The service returns a secure, encrypted representation of the text.

Example: To encrypt the password 1Gateway, use the following URL: https://localhost/api/v3/crypto/encrypt?text=1Gateway

4.2 Using Encrypted Values​

Encrypted values must be wrapped using the following format: ENC(<encrypted_value>)

Example Configuration:

server.ssl.key-store-password=ENC(AbCdEfGhIjKlMnOpQrStUvWxYz)

Encrypted values are supported in the following configuration locations:

  • application.properties file (Windows installations).
  • docker-compose.yml file via environment variables (Docker installations).

5. Windows Installation (Service)​

When running 1Gateway as a Windows service, the HTTPS configuration is managed through the application.properties file located in your installation directory.

5.1 Certificate Storage Location​

For security and stability in Windows environments, certificates should be stored in the 1Gateway data directory. The recommended location is:

The recommended location is: C:\ProgramData\1Gateway\1Gateway\Data

This directory is preferred because:

  • It is accessible to the Windows service account
  • It persists across 1Gateway version upgrades since it is in the data directory
  • It is backed together with all of the 1Gateway data

5.2 Configuration Example (Windows)​

Add or update the following properties in your application.properties file:

server.port=443
server.ssl.key-store=C:/ProgramData/1Gateway/certs/1gateway.pfx
server.ssl.key-store-password=ENC(<encrypted_value>)
server.ssl.key-store-type=PKCS12
note

Use forward slashes (/) in the file path to ensure it is parsed correctly.

5.3 Applying Changes​

Changes to the configuration file are not dynamic. After updating HTTPS settings, restart the 1Gateway Windows service to apply changes.

6. Docker Installation (Docker Compose)​

When running 1Gateway using Docker Compose, HTTPS is enabled by:

  • Providing a certificate keystore via a mounted volume

  • Configuring HTTPS properties through container environment variables

The 1Gateway container reads SSL configuration directly from environment variables at startup.

6.1 Certificate Storage (Host)​

Certificates must be stored on the host machine and mounted into the 1Gateway container.

  • Recommended host directory: ./1gateway/certs
  • This directory should contain your keystore file (e.g., 1gateway.pfx).

6.2 Docker Compose Volume Mapping​

Ensure the certificate directory is mounted into the container.

volumes:
  - ./1gateway/data:/opt/1gateway/data
  - ./1gateway/config:/opt/1gateway/config
  - ./1gateway/certs:/opt/1gateway/certs

6.3 HTTPS Configuration via Environment Variables​

HTTPS is configured by enabling the SSL-related environment variables in the 1gateway service.

Example Configuration:

environment:
  - server.port=443
  - server.ssl.key-store=/opt/1gateway/certs/1gateway.pfx
  - server.ssl.key-store-password=ENC(<encrypted_value>)
  - server.ssl.key-store-type=PKCS12
note

  1. The server.ssl.key-store path must match the internal container path defined in your volume mapping.

  2. Using encrypted values (ENC format) is strongly recommended for passwords in Docker environments.

6.4 Port Mapping​

When HTTPS is enabled, the container listens on port 443 and the host must expose port 443. Ensure no other service on the host is using port 443.

ports:
  - 443:443

6.5 Full Docker Compose Example (Relevant Section)​

The following snippet is an excerpt from a standard docker-compose.yml file, specifically adapted to enable HTTPS communication for the 1Gateway server.

services:
  1gateway:
    container_name: 1gateway-server
    hostname: 1gateway
    image: [docker.1gateway.com/1gateway:stable](https://docker.1gateway.com/1gateway:stable)
    restart: always

    environment:
      # --- Core Identification ---
      - APPLICATION_INSTANCEID=1gateway
      - APPLICATION_INSTANCENAME=1gateway

      # --- MongoDB Connection ---
      - spring.data.mongodb.uri=mongodb://1gateway:1Gateway$$@svc-mongodb:27017/1gateway?authSource=admin

      # --- HTTPS Configuration ---
      - server.port=443
      - server.ssl.key-store=/opt/1gateway/certs/1gateway.pfx
      - server.ssl.key-store-password=ENC(<encrypted-password>)
      - server.ssl.key-store-type=PKCS12

      # --- JVM Options ---
      - JAVA_TOOL_OPTIONS=-XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError

    depends_on:
      - svc-mongodb
      - svc-rabbitmq

    volumes:
      - ./1gateway/data:/opt/1gateway/data
      - ./1gateway/config:/opt/1gateway/config
      - ./1gateway/certs:/opt/1gateway/certs

    ports:
      - 443:443

6.6 Applying Changes and verification​

After modifying the Docker Compose file:

docker compose down
docker compose up -d

HTTPS settings are applied at container startup.

After startup:

  1. Open a browser and navigate to: https://localhost or https://<host-name>

  2. Confirm:

    • HTTPS is active
    • The expected certificate is presented
    • No SSL-related errors appear in container logs

6.7 Notes and Best Practices​

  • Use PKCS12 (.pfx) keystores

  • Do not embed certificates inside Docker images

  • Use encrypted configuration values for all secrets

  • Restart containers after certificate renewal