Skip to main content

TLS Modes

To run ZITADEL on any kind of infrastructure, you can configure on how to handle TLS connections. There are three modes of operation: disabled, external, enabled.

Generally this command is set as argument while starting ZITADEL. For example like this:

zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled

Disabled​

With the mode disabled, you instruct ZITADEL to await all connections with plain http without TLS.

caution

Be aware this is not a secure setup and should only be used for test systems!

External​

The mode external allows you to configure ZITADEL in such a way that it will instruct its clients to use https. However ZITADEL delegates the management of TLS connections to a reverseproxy, web application firewall or a service mesh.

Enabled​

When using the mode enabled ZITADEL is setup to await incoming connections in an encrypted fashion. Whether it is from a client directly, a reverse proxy or web application firewall. This allows HTTP connections to be secured at the transport level the whole way.

If you use the mode enabled you need to configure ZITADEL with the necessary TLS settings.

TLS:
  # if enabled, ZITADEL will serve all traffic over TLS (HTTPS and gRPC)
  # you must then also provide a private key and certificate to be used for the connection
  # either directly or by a path to the corresponding file
  Enabled: true
  # Path to the private key of the TLS certificate, it will be loaded into the Key
  # and overwrite any existing value
  KeyPath: #/path/to/key/file.pem
  # Private key of the TLS certificate (KeyPath will this overwrite, if specified)
  Key: #<bas64 encoded content of a pem file>
  # Path to the certificate for the TLS connection, it will be loaded into the Cert
  # and overwrite any existing value
  CertPath: #/path/to/cert/file.pem
  # Certificate for the TLS connection (CertPath will this overwrite, if specified)
  Cert: #<bas64 encoded content of a pem file>

More Information​

Beware that ZITADEL uses HTTP/2 for all its connections. If you are using the mode external or disabled make sure to verify h2c compatibility.