snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/main/administration-guide/onboard/ssl-client-certificate.mdx

@@ -0,0 +1,133 @@
+---
+title: "SSL client certificate setup"
+---
+<PlanAvailability slug="all-commercial" />
+
+Follow these steps to configure SSL client certificates for your browser and the Mattermost desktop apps on Windows, macOS, and Linux.
+
+Before you begin, follow the [official guides to install Mattermost](/deployment-guide/deployment-guide-index) 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](/end-user-guide/collaborate/share-links#share-message-links) and [inviting people](/end-user-guide/collaborate/invite-people). - SSL client certificates are not yet supported on the Mattermost mobile apps.
+
+</Important>
+
+## Set up mutual TLS authentication for the web app
+
+1.  Create a [certificate authority (CA) key](https://en.wikipedia.org/wiki/Certificate_authority) 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.
+
+``` sh
+openssl genrsa -des3 -out ca.mattermost.key 4096
+```
+
+``` text
+pass phrase: capassword
+```
+
+``` sh
+openssl req -new -x509 -days 365 -key ca.mattermost.key -out ca.mattermost.crt
+```
+
+``` text
+Country Name: US
+State: Maryland
+Locality Name: Meade
+Organization Name: Mattermost
+Organization Unit: Smarttotem
+Common Name: example.mattermost.com
+Email Address: admin@mattermost.com
+```
+
+2.  Create the client side key for `mmuser` with a passphrase, and the certificate signing request:
+
+``` sh
+openssl genrsa -des3 -out mmuser-mattermost.key 1024
+```
+
+``` text
+passphrase: mmuser-passphrase
+```
+
+``` sh
+openssl req -new -key mmuser-mattermost.key -out mmuser-mattermost.csr
+```
+
+``` text
+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
+```
+
+3.  Sign the user's client certificate with the previously created CA certificate:
+
+``` sh
+openssl x509 -req -days 365 -in mmuser-mattermost.csr -CA ca.mattermost.crt -CAkey ca.mattermost.key -set_serial 01 -out mmuser-mattermost.crt
+```
+
+4.  Check the newly generated client certificate for `mmuser`:
+
+``` sh
+openssl x509 -in mmuser-mattermost.crt -text -noout
+```
+
+5.  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:
+
+``` text
+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;
+
+...
+```
+
+6.  Confirm the CA key for `mmuser` works by the following curl command to the proxy:
+
+``` sh
+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.
+
+7.  Generate a PKCS12 file from the CA key and certificate, to install the certificate into your client machine for your browser to use:
+
+``` sh
+openssl pkcs12 -export -out mmuser-mattermost.p12 -inkey mmuser-mattermost.key -in mmuser-mattermost.crt -certfile ca.mattermost.crt
+```
+
+``` text
+Enter Export Password: mmuser-passphrase
+```
+
+8.  Repeat steps 2-7 above for other users as needed.
+9.  Import the generated `.p12` file in step 7 into your key chain. In the Chrome browser on macOS:
+
+> 1.  Go to **Settings \> Advanced \> Privacy and security \> Manage certificates**. This opens the Keychain Access app.
+> 2.  Go to **File \> Import Items** and select the `mmuser-mattermost.p12` file.
+
+10. Go to `https://example.mattermost.com`. You should see a popup for the client certificate request.