Zato servers expose port 11224 for SSL API connections. By default, port 11224 uses a self-signed certificate which you can customize, or you can use your own certificate for SSL connections.
Port 11224 is used in addition to port 11223, which is used for plain-text, non-encrypted connections. If needed, you can disable the plain-text port, and that will require all of your API clients use to port 11224, in this way enforcing data encryption in transit.
Zato dashboards expose port 8184 for encrypted SSL connections. It uses the same self-signed certificate as port 11224 or the one that you uploaded. Port 8184 is used in addition to port 8183, which you can also disable.
The rest of this chapter shows how you can use your own certificates or how you can customize the self-signed ones.
First, use your own CA to create a PEM file called "zato.pem" whose contents must be a concatenation of the server's certificate, any intermediate CA certificates, and private key (in that specific order). If your CA doesn't have any intermediate certificates, don't provide any, only concatenate the server's certificate and private key. The file should look like below:
In your startup scripts, mount this file here: /opt/hot-deploy/ssl/zato.pem, e.g.:
When mounting this file, make sure it is owned by user zato inside the container, not by root
When using your own certificate with a custom domain name, you need to set the Zato_Dashboard_CSRF_Trusted_Origins environment variable to allow the Dashboard to accept SSL requests from that domain.
Without this setting, you will see "CSRF verification failed. Request aborted." when accessing the Dashboard over HTTPS on port 8184.
To configure it, if your certificate uses CN=my.dashboard, and you want to access your Dashboard at https://my.dashboard:8184, export it as below:
docker run \
-e Zato_Dashboard_CSRF_Trusted_Origins="https://my.dashboard:8184" \
--mount type=bind,source=/path/to/zato.pem,target=/opt/hot-deploy/ssl/zato.pem \
zatosource/zato-4.1
To disable non-SSL communiation, simply do not expose ports 8183 and 11223 from the container to your host. For instance, you may have configuration similar to the below in your startup scripts:
docker run \
-p 8183:8183 \ # Remove this line
-p 8184:8184 \
-p 11223:11223 \ # Remove this line
-p 11224:11224 \
zatosource/zato-4.1
Now, to make sure that only SSL is used when using your Dashboard, or when invoking your APIs, remove the lines that expose ports 8183 and 11223, and leave only ports 8184 and 11224 for SSL.
If you don't provide a zato.pem file, Zato will automatically generate a self-signed certificate on startup and save it to /opt/hot-deploy/ssl/auto.pem inside the container. The auto-generated certificates are created each time a container starts and each container has its own unique certificate and private key.
The following variables configure SSL behavior. Variables marked "Yes" in the "Auto-gen only" column apply only to auto-generated certificates and are ignored when using your own zato.pem file. Other variables apply to all SSL connections regardless of certificate source.
| Variable | Default | Auto-gen only | Description |
|---|---|---|---|
| Zato_SSL_Subject | /C=US/ST=State/L=City/O=Organization/CN=localhost | Yes | Certificate subject (e.g. your server's DNS or IP address) |
| Zato_SSL_Subject_Alt_Name | subjectAltName=DNS:localhost,IP:127.0.0.1 | Yes | Subject alternative names |
| Zato_SSL_Cert_Days | 3650 | Yes | Validity period in days |
| Zato_SSL_Key_Algorithm | ecdsa | Yes | Key algorithm (ecdsa or rsa) |
| Zato_SSL_Key_Size | 4096 | Yes | Key size for RSA keys |
| Zato_SSL_Protocols | (empty) | --- | Minimum SSL version (e.g., TLSv1.2, TLSv1.3) |
| Zato_SSL_Ciphers | (empty) | --- | Allowed cipher suites |
| Zato_SSL_DH_Params | (empty) | --- | Path to Diffie-Hellman parameters file |
| Zato_SSL_Extra_Options | (empty) | --- | Additional HAProxy SSL options |
...use a custom certificate subject to match my server's DNS or IP address?
Set the Zato_SSL_Subject environment variable:
docker run \
-e Zato_SSL_Subject="/C=GB/ST=London/L=London/O=MyCompany/CN=api.mycompany.com" \
zatosource/zato-4.1
...add multiple domain names to the certificate?
Use Zato_SSL_Subject_Alt_Name:
docker run \
-e Zato_SSL_Subject_Alt_Name="subjectAltName=DNS:api.example.com,IP:192.168.1.100" \
zatosource/zato-4.1
...use RSA instead of ECDSA?
Set Zato_SSL_Key_Algorithm=rsa:
...enforce TLS 1.3 only?
Use Zato_SSL_Protocols:
...restrict cipher suites?
Set Zato_SSL_Ciphers:
docker run \
-e Zato_SSL_Ciphers="ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384" \
zatosource/zato-4.1
...change the auto-generated certificate's validity period?
Use Zato_SSL_Cert_Days:
...add custom HAProxy SSL options?
Use Zato_SSL_Extra_Options: