Certificate-based authentication (experimental)#
Available on Enterprise plans
self-hosted deployments
Also available as an experimental feature in legacy Mattermost Enterprise Edition E20
Certificate-based authentication (CBA) is available as an experimental feature to identify a user or a device before granting access to Mattermost and provide an additional layer of security to access the system.
Follow these steps to configure user CBA for your browser and Mattermost Desktop Apps. Support for the Mattermost iOS and Android Apps is planned. It is expected that you can manage certificate distribution for each personal device (BYOD) and their life cycle management with a service like OpenSSL.
Before you begin, follow the official guides to install Mattermost on your system, including NGINX configuration as a proxy with SSL and HTTP/2, and a valid SSL certificate such as Let’s Encrypt.
Set up mutual TLS authentication for the Web App#
This is the first step for setting up certificate-based authentication. If you haven’t set up mutual TLS authentication yet, see our documentation to learn more.
Set up Mattermost server to log in with a client certificate#
Make sure your Mattermost server is licensed with a valid Enterprise license.
In
ExperimentalSettings
of theconfig.json
file, setClientSideCertEnable
totrue
andClientSideCertCheck
to one of the following values:
primary
- After the client side certificate is verified, user’s email is retrieved from the certificate and is used to log in without a password.secondary
- After the client side certificate is verified, user’s email is retrieved from the certificate and matched against the one supplied by the user. If they match, the user logs in with regular email/password credentials.
The config.json
file should then have the following lines
"ExperimentalSettings": {
"ClientSideCertEnable": true,
"ClientSideCertCheck": "secondary"
},
Restart the Mattermost server.
On Ubuntu 14.04 and RHEL 6:
sudo restart mattermost
On Ubuntu 16.04, Debian Stretch, and RHEL 7:
sudo systemctl restart mattermost
Go to
https://example.mattermost.com
and try to log in. The server should require the x.509 cert to have anemailAddress
equal to the Mattermost user’s email.