SSL and TLS Configuration

SSL and TLS Configuration#

Attention

Allegra does not natively support SSL or HTTPS configuration. To access Allegra securely via HTTPS, you must set up a reverse proxy (such as Nginx or Apache) in front of the Allegra application.

Official Allegra support does not cover SSL configuration, certificate management, or proxy troubleshooting. The following information is provided as a reference example for experienced system administrators.

Using a Reverse Proxy#

It is strongly recommended to run Allegra behind an existing web server (reverse proxy) such as Nginx or Apache. The proxy handles HTTPS encryption and forwards requests to the Allegra application running in Docker or on a local port (for example, 8080).

This setup allows you to:

  • Use standard HTTPS certificates without modifying Allegra itself

  • Expose Allegra under a friendly domain name (e.g. https://allegra.example.com)

  • Keep Allegra running securely on a local port behind your firewall

Note

Allegra itself should never be exposed directly to the Internet. Configure all encryption and access control in your chosen reverse proxy.

Network Overview#

The following diagram illustrates a typical HTTPS deployment using a reverse proxy:

+---------------------------+
|        Web Browser        |
|  (User accesses Allegra)  |
+------------+--------------+
             |
             |  HTTPS (443)
             v
+---------------------------+
|     Reverse Proxy (Nginx) |
|  Handles HTTPS & forwards |
|     requests internally   |
+------------+--------------+
             |
             |  HTTP (8080, local)
             v
+---------------------------+
|   Allegra Application     |
|  (Docker container / JVM) |
+---------------------------+

Nginx Proxy Example#

The following minimal Nginx configuration publishes Allegra securely via HTTPS and forwards all requests to a locally running instance on port 8080.

server {
    listen 80;
    server_name allegra.example.com;
    return 301 https://$host$request_uri;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl http2;
    server_name allegra.example.com;

    ssl_certificate     /etc/ssl/certs/your_cert.pem;
    ssl_certificate_key /etc/ssl/private/your_key.pem;

    client_max_body_size 100m;

    location /allegra/ {
        proxy_pass http://127.0.0.1:8080/allegra/;

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Port  443;

        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_buffering off;

        proxy_redirect http://127.0.0.1:8080/allegra/ https://$host/allegra/;

        proxy_cookie_path / /allegra;
        proxy_cookie_path /allegra "/allegra; Secure; HttpOnly; SameSite=Strict";
    }
}

Note

Replace domain and certificate paths with your own values. Keep X-Forwarded-Proto and X-Forwarded-Port so Allegra generates correct HTTPS links.

Apache Proxy Example#

For Apache2, enable the required proxy modules and define a simple forwarding configuration.

# Load required modules
a2enmod proxy
a2enmod proxy_http
a2enmod proxy_wstunnel
a2enmod ssl
a2enmod headers

<VirtualHost *:443>
    ServerName allegra.example.com

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/your_cert.pem
    SSLCertificateKeyFile /etc/ssl/private/your_key.pem

    ProxyRequests Off
    ProxyPreserveHost On

    # Forward original scheme and port
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-Port  "443"

    # Forward HTTP and WebSocket traffic
    ProxyPass        /allegra  http://127.0.0.1:8080/allegra timeout=120 keepalive=On
    ProxyPassReverse /allegra  http://127.0.0.1:8080/allegra
    ProxyPass        /allegra  ws://127.0.0.1:8080/allegra
    ProxyPassReverse /allegra  ws://127.0.0.1:8080/allegra

    # Adjust cookies and set secure flags
    ProxyPassReverseCookiePath / /allegra
    Header edit Set-Cookie "(?i)^(.*)$" "$1; Secure; HttpOnly; SameSite=Strict"
</VirtualHost>

Note

Replace domain and certificate paths with your own values. Ensure X-Forwarded-Proto and X-Forwarded-Port are set so Allegra generates correct HTTPS URLs.

Certificates and Encryption for External Connections#

Allegra also connects to external systems as a client, for example:

  1. Sending email through an SMTP server

  2. Receiving email through an IMAP or POP3 server

  3. Connecting to a directory server (LDAP, optional)

These external connections should always use encrypted protocols (SSL/TLS) to prevent passwords or sensitive data from being transmitted in plain text over the network.

Official and Self-Signed Certificates#

Encrypted communication relies on digital certificates. There are two main types:

  1. Certificates from an official Certificate Authority (CA)

  2. Self-signed certificates

Certificates issued by an official CA are automatically trusted by most browsers and Java runtimes. Self-signed certificates, however, must be manually trusted on client systems.

Installing Self-Signed Certificates#

If you use a self-signed certificate, you must make it trusted by the system or the Java environment that Allegra uses to connect to external services.

To install a certificate for use by Allegra:

  1. Obtain the certificate from your external service (e.g. your mail server). It is usually bound to a hostname such as mail.example.com.

  2. Create a keystore directory in your Allegra home folder:

    mkdir <ALLEGRA_HOME>/keystore

  3. Import the certificate into the local Allegra keystore using the keytool utility that comes with every Java installation:

    keytool -keystore <ALLEGRA_HOME>/keystore/<your.domain.com>.ks \
        -import -file theServersCertificate.cer

    The keystore file must reside in <ALLEGRA_HOME>/keystore. The file should have the extension .ks and a base name matching the hostname of the remote server.

Importing Certificates into the Java Keystore#

If the above approach does not work or if you prefer to trust the certificate system-wide, you can import it directly into the Java runtime’s default keystore.

On Windows, for example:

cd %JAVA_HOME%\bin
keytool -import -alias <alias> -file theServersCertificate.crt ^
        -keystore ..\lib\security\cacerts

You will be prompted for a password. The default Java keystore password is usually changeit (unless it has been changed).

Note

Importing self-signed certificates requires administrative rights and must be done carefully to avoid compromising system security. Always verify the certificate source before importing.