SSL client certificate setup#

Follow these steps to configure SSL client certificates for your browser and the Mattermost desktop apps on Windows, macOS, and Linux. SSL client certificates are not yet supported on the Mattermost mobile apps.

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.

For the purposes of this guide, the Mattermost server domain name is example.mattermost.com, and the user account is mmuser with email mmuser@mattermost.com and password mmuser-password.

Important

Generating the client certificates in this section is optional if you have already generated them before.
We strongly recommend configuring an SSL certificate (or a self-signed certificate) for security, privacy, compliance, as well as to avoid browser limitations that can prevent Mattermost product features from working that copy data using the user’s local clipboard, including sharing message links and inviting new members to teams.

Set up mutual TLS authentication for the web app#

Create a certificate authority (CA) key and a certificate for signing the client certificate. When establishing a TLS connection, the NGINX proxy server requests and validates a client certificate provided by the web app.

openssl genrsa -des3 -out ca.mattermost.key 4096

pass phrase: capassword

openssl req -new -x509 -days 365 -key ca.mattermost.key -out ca.mattermost.crt

Country Name: US
State: Maryland
Locality Name: Meade
Organization Name: Mattermost
Organization Unit: Smarttotem
Common Name: example.mattermost.com
Email Address: admin@mattermost.com

Create the client side key for mmuser with a passphrase, and the certificate signing request:

openssl genrsa -des3 -out mmuser-mattermost.key 1024

passphrase: mmuser-passphrase

openssl req -new -key mmuser-mattermost.key -out mmuser-mattermost.csr

Country Name: US
State: Maryland
Locality Name: Meade
Organization Name: Mattermost
Organization Unit: Smarttotem
Common Name: mmuser
Email Address: mmuser@mattermost.com

Challenge password: mmuser-passphrase

Sign the user’s client certificate with the previously created CA certificate:

openssl x509 -req -days 365 -in mmuser-mattermost.csr -CA ca.mattermost.crt -CAkey ca.mattermost.key -set_serial 01 -out mmuser-mattermost.crt

Check the newly generated client certificate for mmuser:

openssl x509 -in mmuser-mattermost.crt -text -noout

Open the file /etc/nginx/sites-available/mattermost and modify the following lines, so that the NGINX proxy server requests and verifies the client certificate:

ssl on;
ssl_certificate /etc/letsencrypt/live/example.mattermost.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.mattermost.com/privkey.pem;
ssl_client_certificate /opt/mattermost/config/ca.mattermost.crt;
ssl_verify_client on;

...

location ~ /api/v[0-9]+/(users/)?websocket$ {
 proxy_set_header X-SSL-Client-Cert $ssl_client_cert;
 proxy_set_header X-SSL-Client-Cert-Subject-DN $ssl_client_s_dn;

...

location / {
 proxy_set_header X-SSL-Client-Cert $ssl_client_cert;
 proxy_set_header X-SSL-Client-Cert-Subject-DN $ssl_client_s_dn;

...

Confirm the CA key for mmuser works by the following curl command to the proxy:

curl -v -s -k --key mmuser-mattermost.key --cert mmuser-mattermost.crt:mmuser-passphrase https://example.mattermost.com

You should see the Mattermost login page. If you see:

No required SSL certificate was sent, something went wrong. Review the above steps and try again.

Error reading X.509 key or certificate file: Decryption has failed., make sure the passphrase is included together with the certificate, because curl doesn’t prompt for it separately.

Generate a PKCS12 file from the CA key and certificate, to install the certificate into your client machine for your browser to use:

openssl pkcs12 -export -out mmuser-mattermost.p12 -inkey mmuser-mattermost.key -in mmuser-mattermost.crt -certfile ca.mattermost.crt

Enter Export Password: mmuser-passphrase

Repeat steps 2-7 above for other users as needed.
Import the generated .p12 file in step 7 into your key chain. In the Chrome browser on macOS:

Go to Settings > Advanced > Privacy and security > Manage certificates. This opens the Keychain Access app.

Go to File > Import Items and select the mmuser-mattermost.p12 file.

Go to https://example.mattermost.com. You should see a popup for the client certificate request.

Troubleshooting#

Follow this process to resolve configuration issues and to ask for help.