Certificate-based authentication (Experimental)#

plans-img Available on Enterprise plans

deployment-img 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#

  1. Make sure your Mattermost server is licensed with a valid Enterprise license.

  2. In ExperimentalSettings of the config.json file, set ClientSideCertEnable to true and ClientSideCertCheck 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"
},

  1. 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

  1. Go to https://example.mattermost.com and try to log in. The server should require the x.509 cert to have an emailAddress equal to the Mattermost user’s email.