How to enable MAAS native TLS encryption
MAAS version 3.2 has built-in TLS support for communicating with the UI and API over HTTPS. This eliminates the need to deploy a separate TLS-terminating reverse-proxy solution in front of MAAS to provide secure access to API and UI.
TLS versions 1.2 and 1.3 are supported by MAAS. For TLSv1.2, the following ciphers are accepted:
- AES256+EECDH
- AES256+EDH
You will need to obtain your own certificates via some provider, e.g., small step↗.
About certificate auto-renewal
At the moment we don’t support automatic certificate renewal, because it depends on the PKI used at the organisation level. We do provide some examples of how to set this up, as long as you understand that these are just gratuitous helps, not supported configurations.
TLS can be enabled/disabled with the new maas config-tls command:
usage: maas config-tls [-h] COMMAND ...
Configure MAAS Region TLS.
optional arguments:
-h, --help show this help message and exit
drill down:
COMMAND
enable Enable TLS and switch to a secured mode (https).
disable Disable TLS and switch to a non-secured mode (http).
the following arguments are required: COMMAND
To enable TLS in MAAS, a private key and a X509 certificate containing the corresponding public key are required. Both key and certificate must be encoded in PEM format.
usage: maas config-tls enable [-h] [--cacert CACERT] [-p PORT] key cert
positional arguments:
key path to the private key
cert path to certificate in PEM format
optional arguments:
-h, --help show this help message and exit
--cacert CACERT path to CA certificates chain in PEM format (default: None)
-p PORT, --port PORT HTTPS port (default: 5443)
the following arguments are required: key, cert
By default, the port for HTTPS traffic will be 5443. It’s possible to specify a different one via the –port option. If your certificate is not self-signed, you can pass a cacert.pem, so that the full chain will be included in the certificate served by MAAS.
If you have HA setup, please note that every MAAS instance will use the same certificate, so you need to create one certificate with multiple domain names or IP addresses; for example:
X509v3 Subject Alternative Name:
DNS:example.com, IP Address:10.211.55.9
If for some reason you want to disable TLS, you can do it using the following command:
usage: maas config-tls disable [-h]
optional arguments:
-h, --help show this help message and exit
After this, MAAS API and UI will be again reachable on port 5240, over plain HTTP.
Using the CLI with a TLS-enabled MAAS
To connect to the MAAS API when TLS is enabled, an https URL must be provided to the maas login command, e.g.:
maas login <profile_name> https://mymaas:5443/MAAS <api_key>
usage: maas login [-h] [--cacerts CACERTS] [-k] profile-name url [credentials]
Log in to a remote API, and remember its description and credentials.
positional arguments:
profile-name The name with which you will later refer to this remote server and credentials within this tool.
url The URL of the remote API, e.g. http://example.com/MAAS/ or http://example.com/MAAS/api/2.0/ if you wish to specify the API
version.
credentials The credentials, also known as the API key, for the remote MAAS server. These can be found in the user preferences page in
the web UI; they take the form of a long random-looking string composed of three parts, separated by colons.
optional arguments:
-h, --help show this help message and exit
--cacerts CACERTS Certificate CA file in PEM format
-k, --insecure Disable SSL certificate check
If credentials are not provided on the command-line, they will be prompted
for interactively.
the following arguments are required: profile-name, url
Certificates provided via --cacerts will be stored as a part of your profile and used for next CLI commands invocations.
Once a certificate has expired, you can update it by running the same command used for enabling TLS:
$ sudo maas config-tls enable new-server-key.pem new-server.pem --port 5443
If you’re using the snap, the certificate and key must be placed in a directory that’s readable by the CLI, such as /var/snap/maas/common (e.g., if you’re using the snap version).
There is a new “Security” subsection under “Configuration” that will indicate the status of TLS in the specific server (enabled or disabled).
When TLS is enabled, the following certificate information is displayed:
- CN
- Expiration date
- Fingerprint
- Certificate
It is also possible to download certificate and configure notification reminder settings. Once the notification reminder is enabled, MAAS administrators will be notified about certificate expiration.
We recommend that you enable TLS for secure communication.
When the specified number of days remain until certificate expiration (as defined in the notification reminder), all administrators will see the certificate expiration notification. This notification is dismissible, but once it is dismissed, it won’t appear again.
A certificate expiration check runs every twelve hours. When the certificate has expired, the notification will change to “certificate has expired”.
How to auto-renew certificates
MAAS does not auto-renew certificates, but there’s no reason why we cannot provide a gratuitous example. Use at your own risk.
Set up your own certificate authority
You can setup your own Certificate Authority (CA) server that supports the ACME protocol with these components:
- step-ca from Smallstep
↗ - Caddy server with ACME support (available since version 2.5)
↗
If you have a CA server with ACME protocol support, you can use any ACME client for an automated certificate renewal and use crontab to renew on a desired time interval. Consider acme.sh↗:
$> acme.sh --issue -d mymaas.internal --standalone --server https://ca.internal/acme/acme/directory
Your cert is in: /root/.acme.sh/mymaas.internal/mymaas.internal.cer
Your cert key is in: /root/.acme.sh/mymaas.internal/mymaas.internal.key
The intermediate CA cert is in: /root/.acme.sh/mymaas.internal/ca.cer
And the full chain certs is there: /root/.acme.sh/foo/fullchain.cer
Once the certificate is issued, you can install it.
$> acme.sh --installcert -d maas.internal \
--certpath /var/snap/maas/certs/server.pem \
--keypath /var/snap/maas/certs/server-key.pem \
--capath /var/snap/maas/certs/cacerts.pem \
--reloadcmd "(echo y) | maas config-tls enable /var/snap/maas/certs/server-key.pem /var/snap/maas/certs/server.pem --port 5443"
Please note that if you have MAAS installed via snap, you need to run above command as root, in order to place cert and key under /var/snap/maas.
Another approach would be to write a bash script and pass it to a --renew-hook↗.
certbot↗ can be used to renew certificates and execute a post-renewal hook. We can use this hook to re-configure MAAS to use fresh certificates.
To create a post-renewal hook, you can put this sample script under /etc/letsencrypt/renewal-hooks/post/001-update-maas.sh.
#!/bin/bash -e
DOMAIN="maas.internal"
CERTSDIR="/etc/letsencrypt/live/$DOMAIN"
cd /var/snap/maas/common
# need to copy certs where the snap can read them
cp "$CERTSDIR"/{privkey,cert,chain}.pem .
yes | maas config-tls enable privkey.pem cert.pem --cacert chain.pem --port 5443
# we don’t want to keep private key and certs around
rm {privkey,cert,chain}.pem
Don’t forget to make the script executable:
chmod +x /etc/letsencrypt/renewal-hooks/post/001-update-maas.sh
Of course, you’ll first need to obtain a new certificate.
sudo REQUESTS_CA_BUNDLE=ca.pem certbot certonly --standalone -d maas.internal --server https://ca.internal/acme/acme/directory
Don’t worry, new certs will not run the hook, since hooks are run only on renewal.
To test the renewal process and verify that the hook is executed correctly, you can use the following command with a --dry-run flag. Please note, that the hook will be executed and existing certificates will be removed (if you are using an example hook script):
sudo REQUESTS_CA_BUNDLE=ca.pem certbot renew --standalone --server https://ca.internal/acme/acme/directory --dry-run
Please refer to the cerbot documentation↗ for more information.