Using mTLS with Portainer
PreviousUsing your own SSL certificate with PortainerNextStream auth and activity logs to an external provider
Last updated
Was this helpful?
Last updated
Was this helpful?
Mutual TLS (or mTLS) is a certificate-based system whereby the client and server (in this case, the Portainer Edge Agent and the Portainer Server) authenticate each other cryptographically via a trusted source (a certificate authority). This can be used as an extra layer of security to protect the communications between the Edge Agent and Portainer. Under this setup, if a third-party system attempts to communicate with the Portainer Server and is not using a certificate signed by the certificate authority it will be rejected.
This article will walk you through the process of deploying the Portainer Server and the Edge Agents with mTLS support.
In order to configure Portainer with mTLS support, you will need the following:
A Portainer Server and a Portainer Edge Agent.
A certificate authority (CA). You can use your own corporate CA or a CA for which you completely control the certificate issuance policy.
The CA certificate for your certificate authority, in PEM format (mtlsca.crt).
A domain (or subdomain) you can point to your Portainer Server instance to be specifically used for mTLS. This will be the domain the server certificate is issued for.
A server certificate (mtlsserver.crt) and corresponding key (mtlsserver.key) issued by your CA for the Portainer Server, in PEM format. Ensure these are issued with serverAuth selected for extendedKeyUsage. This certificate should have the domain (or subdomain) that will be used for mTLS as the Subject Alternative Name (SAN).
A client certificate (client.crt) and corresponding key (client.key) issued by your CA for the Edge Agent, in PEM format. Ensure these are issued with clientAuth selected for extendedKeyUsage.
To use mTLS with your Edge Agents, the Portainer Server instance must be configured with mTLS support. This can either be done during the initial installation of the Portainer Server instance, or after installation through the .
When deploying your Portainer Server, you will need to make the CA certificate, server certificate and server key available to Portainer. How you do this will depend on your deployment.
On your Docker host, upload your CA certificate (mtlsca.crt), server certificate (mtlsserver.crt) and server key (mtlsserver.key) into a directory that will be bind mounted into the Portainer container. In this example we assume your certificates are located at /root/certs.
Modify your docker run command to mount the /root/certs directory to /certs and add the --mtlscacert, --mtlscert, and --mtlskey options:
This will start Portainer using your provided CA and certificates.
To add mTLS certificates to Portainer Server on Docker Swarm during installation, we recommend adding the necessary files as secrets and then referencing those secrets within the YAML used to deploy Portainer.
First, upload your CA certificate (mtlsca.crt), server certificate (mtlsserver.crt) and server key (mtlsserver.key) into a directory that will be referenced by the secret creation. In this example we assume your certificates are located at /root/certs. Once you have uploaded the files, create your secrets as follows:
Modify your Portainer YAML file to attach the secrets and add the --mtlscacert, --mtlscert and --mtlskey options:
and to add the secrets definitions to include the secrets we just created:
If it doesn't already exist, create the portainer namespace:
Next, create a secret containing the CA, certificate and matching private key:
Replace ca.crt, server.crt and server.key in the above command with the paths to your CA certificate, certificate and matching key respectively.
Install Portainer via Helm with the mtls.existingSecret parameter set to the name of the secret you just created:
If you already have Portainer Server deployed, you can configure mTLS support through the Portainer UI.
As an admin user, from the left menu select Settings then Edge Compute. Toggle on Enable Edge Compute features if it isn't already on and click Save Settings. Then scroll down to the mTLS Certificate section.
Here you can enable the use of mTLS with the Use separate mTLS cert toggle, and upload the CA certificate, server certificate and server key using the buttons for TLS CA certificate, TLS certificate and TLS key respectively.
Once you have the Portainer Server instance configured to use mTLS, you can then configure your Edge Agent deployments to use it as well.
When deploying an Edge Agent you will be provided with a command to run by the Portainer UI. We will take that command and modify it for mTLS support.
On your Docker host, upload your CA certificate (mtlsca.crt), client certificate (client.crt) and client key (client.key) into a directory that will be bind mounted into the Edge Agent container. In this example we assume your certificates are located at /root/certs.
Once the certificates are in place and the secrets created, you can begin to set up your Edge Agent within the Portainer UI.
When doing so, remember to use the domain (or subdomain) you chose for mTLS usage (and that the server certificate was issued for) as the Portainer API server URL and tunnel address (if appropriate).
When you have completed the Edge Agent setup in the Portainer UI and have your deployment command, modify the command to mount the /root/certs directory to /certs, change the EDGE_INSECURE_POLL option to 0, and add the --mtlscacert, --mtlscert, and --mtlskey options:
Run the command to deploy your Edge Agent with mTLS support.
To add mTLS certificates to the Edge Agent, we recommend adding the necessary files as secrets and then referencing those secrets within the YAML used to deploy Portainer.
First, upload your CA certificate (mtlsca.crt), client certificate (client.crt) and client key (client.key) into a directory that will be referenced by the secret creation. In this example we assume your certificates are located at /root/certs. Once you have uploaded the files, create your secrets as follows:
Once the certificates are in place and the secrets created, you can begin to set up your Edge Agent within the Portainer UI.
When doing so, remember to use the domain (or subdomain) you chose for mTLS usage (and that the server certificate was issued for) as the Portainer API server URL and tunnel address (if appropriate).
When you have completed the Edge Agent setup in the Portainer UI and have your deployment command, modify the command to change the EDGE_INSECURE_POLL option to 0 and add the --mtlscacert, --mtlscert and --mtlskey options, using the secrets we defined above:
Run the commands to deploy your Edge Agent with mTLS support.
At present, mTLS support for the Portainer Agent running on a Kubernetes environment is a work in progress. If you require instructions for deploying a Portainer Agent with mTLS on a Kubernetes environment, please .
