How to Setup TLS

This guide will help you understand how to secure communication to Orchesto using the Transport Layer Security (TLS) protocol.

Installing TLS Certificate

When accessing Orchesto with a web browser for the first time, you can see whether you are using TLS or not in the welcome page:

Welcome - Admin Credentials

TLS secures communication between clients and Orchesto to provide privacy and data integrity. If TLS is not used, and you would like to enable it, then you will need to:

  1. install a TLS credential in Orchesto
  2. restart Orchesto

A TLS credential consists of a private encryption key and digital certificate. Both must be provided in PEM-encoded format. For example, the format of the private encryption key should be:

-----BEGIN RSA PRIVATE KEY-----
(Your Private Key)
-----END RSA PRIVATE KEY----- 

And, in turn, the format for the digital certificate should be:

-----BEGIN CERTIFICATE----- 
  (Your TSL certificate)
-----END CERTIFICATE----- 

The certificate and private keys should be named server.crt and server.key respectively, and installed in the Orchesto configuration path like so:

install -m 644 server.crt ${HOME}/.orchesto/server.crt
install -m 400 server.key ${HOME}/.orchesto/server.key

For the new credential to take effect, make sure to restart Orchesto.

Obtaining TLS Certificate

If you do not already have a TLS certificate, you need to create one and sign it. To fast-track this process, use the --auto-tls option when starting Orchesto, whereby it will create a self-signed TLS certificate and private key on the fly. For example:

orchesto --auto-tls

This options has no effect if a certificate or private key is already installed. Note that you should only use this kind of certificate for personal use, or for limited use within an organization.

Orchesto creates 2048-bit size RSA private key when generating self-signed TLS certificates, with its validity capped at 365 days.

For enhanced security, you should use a commercially signed TLS certificate. The easiest way to do so is by signing your certificate using Let's Encrypt. For even higher security, you should obtain a Extended Validation certificate instead.