How to setup TLS

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

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, you have three options:

  • Provide your own certificate
  • Let Orchesto create self-signed certificates for you
  • Configure Orchesto to use Let's Encrypt

Provide Your Own Certificate

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

Make sure to restart Orchesto for the new credential to take effect.

For enhanced security, you should obtain an Extended Validation certificate.

Let Orchesto Create Self-signed Certificates for You

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

./orchesto --create-certificates

(other mandatory start flags not mentioned here, see Appendix 1, Installation. )

This options has no effect if a certificate or private key is already installed.

Note

You should only use this kind of certificate for personal use, or for limited use within an organisation.

Note

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

Configure Orchesto to use Let's Encrypt

Tip

Using the build-in LetsEncrypt method to request a TLS certificate, requires that the Orchesto gateway is accessible over port 443 (https) from the Internet, AND that the hostname set when starting orchesto is resolvable by an external DNS

Let's Encrypt is a free, automated, and open certificate authority run by the non-profit Internet Security Research Group (ISRG). When utilising Let's Encrypt, one feature is the opportunity to manage your certificates automatically, including renewals.

To enable Let's Encrypt mode, start Orchesto with --hostnames and provide one or several (comma separated) hostnames where Orchesto can be reached. By adding --accept-le-sa you verify that you agree to Let's Encrypts Subscriber Agreement.

Example:

./orchesto --hostnames orchesto.example.com --accept-le-sa

Orchesto will then request a new certificate from Let's Encrypt the first time you access Orchesto at the provided hostname. It will also manage renewal automatically when the certificate is about to expire.

Certificates managed by Let's Encrypt is stored in the acme directory in Orchesto configuration path.