Console Configuration

Alternative Server Certificates

At the time of writing, ZAC 3.0+ is hosted by the controller, which is the likely direction of travel for the future, and the current preferred configuration.

As mentioned in the identity section of the Conventions reference document, you can use certificates from public CAs like Let's Encrypt and associate them with the controller config in order to present valid certificates for the ZAC single page application.

The alt_server_certs configuration key is an array of certificate information, so the first-matched server certificate is presented to the TLS client (in this case, a browser).

To configure this correctly for the ZAC, the certificate paths need to be added to the alt_server_certs array in the web listener section, under the client-management named config section.

Steps

1. Create and validate your certificates (for example with Let's Encrypt Certbot)
2. Alter the controller configuration using example below as a guide
3. Restart the ziti-controller service

See the example configuration here:

web:
  - name: client-management
    identity:
      ...
      alt_server_certs:
      - server_cert: "/etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/fullchain.pem"
        server_key:  "/etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/privkey.pem"

At this point, the controller service should use the certificates for the ZAC, removing any "Potential Security Risk" warnings.

Important note on listener

The ZAC binding must share a web listener with the edge-management binding.

If the edge-client and edge-management are not sharing a web listener (i.e. they are bound to separate web listeners) then you must bind the ZAC to the listener where edge-management binding is configured.

Further details:

Creating a DNS Record

Before generating an SSL certificate, ensure you have a valid DNS record pointing to the public IP address of your server. This can be done through your DNS provider’s control panel, dashboard, or directly via a domain registrar.

Ensure you wait for DNS propagation to complete before attempting ACME DNS-based challenge.

This may take a few minutes to a few hours, but you can use tools like Google Admin Toolbox Dig to track the progress on the propagation.

Install Let’s Encrypt CertBot

General instructions for this can be found by visiting the Let's Encrypt Documentation, and also by reviewing the documentation of Certbot. These documents go into detail about various bespoke configuratons so you can choose the right one for your scenario.

A simple way to satisfy the DNS-based challenge from Let's Encrypt is to use the Certbot DNS plugin. CertBot DNS Plugins.

These are specific to DNS providers, but you can see an example of how they should be used in this tutorial

Configure DNS Provider Authentication

CertBot requires access to your DNS provider’s API to perform DNS-based domain validation. This is because it provisions a TXT resource in the domain, as per RFC8555. For this you will need to look up how to create the token from your DNS provider.

Other mechanisms of satisfying the challenge are available. However, this method allows for better automation.

Read the documentation from CertBot DNS Plugins to determine how to configure this correctly for your setup.

Obtain an SSL Certificate

Once all the above is correct, you can run CertBot using the DNS-based challenge. The following command demonstrates the principle. You should change the DNS provider specific arguments to match your scenario.

sudo certbot certonly \
  --dns-digitalocean \
  --dns-digitalocean-credentials ~/certbot-creds.ini \
  -d <YOUR_DOMAIN_NAME>

If all goes well, this request will generate an SSL certificate for your domain, which by default will be stored in /etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/, matching the example configuration given above.