240db4e2a7
Some checks failed
Server CI / Postgres (shard 0) (push) Has been skipped
Server CI / Postgres (shard 3) (push) Has been skipped
BuildEnv Docker Image / build-image (push) Failing after 4s
BuildEnv Docker Image / build-image-fips (push) Failing after 4s
Migration Review & Release Notes / Generate migration review & release notes (push) Failing after 3s
Server CI / Build Environment (push) Failing after 3s
Server CI / Postgres (shard 1) (push) Has been skipped
Tools CI / check-style (mattermost-govet) (push) Failing after 4s
Server CI / Postgres (shard 2) (push) Has been skipped
Tools CI / check-style (mmgotool) (push) Failing after 3s
Server CI / Elasticsearch v8 Compatibility (push) Has been skipped
Server CI / OpenSearch v2 Compatibility (push) Has been skipped
Server CI / Postgres FIPS (shard 0) (push) Has been skipped
Tools CI / Test (mattermost-govet) (push) Failing after 3s
Server CI / Postgres FIPS (shard 1) (push) Has been skipped
Server CI / Postgres FIPS (shard 2) (push) Has been skipped
Tools CI / Test (mmgotool) (push) Failing after 3s
Server CI / Postgres FIPS (shard 3) (push) Has been skipped
Server CI / Run mmctl tests (push) Has been skipped
Server CI / Run mmctl tests (FIPS) (push) Has been skipped
Server CI / Merge Postgres Test Results (push) Has been skipped
Server CI / Merge Postgres FIPS Test Results (push) Has been skipped
Server CI / Check backport migrations (push) Has been skipped
Server CI / Check generated files (push) Has been skipped
Server CI / check-style (push) Has been skipped
Server CI / Vet API (push) Has been skipped
Server CI / Build mattermost server app (push) Has been skipped
Server CI / Server CI Complete (push) Failing after 2s
Server CI / Server CI Artifacts (push) Has been skipped
Server CI / Sentry Upload (push) Has been skipped
Server CI / Server CI Report (push) Failing after 5m1s
Server CI Nightly Race / Race Detector (push) Has been skipped
CodeQL / Analyze (go) (push) Has been cancelled
CodeQL / Analyze (javascript) (push) Has been cancelled
Webapp CI Cache Warm / Warm Webapp node_modules Cache (push) Has been cancelled
E2E CI Cache Warm / Warm E2E npm Registry Cache (push) Has been cancelled
API / build (push) Has been cancelled
Web App CI / check-types (push) Has been cancelled
Web App CI / check-lint (push) Has been cancelled
Web App CI / check-i18n (push) Has been cancelled
Web App CI / check-external-links (push) Has been cancelled
Web App CI / test (platform) (push) Has been cancelled
Web App CI / test (mattermost-redux) (push) Has been cancelled
Web App CI / test (channels shard 1/4) (push) Has been cancelled
Web App CI / test (channels shard 2/4) (push) Has been cancelled
Web App CI / test (channels shard 3/4) (push) Has been cancelled
Web App CI / test (channels shard 4/4) (push) Has been cancelled
Web App CI / upload-coverage (push) Has been cancelled
Web App CI / build (push) Has been cancelled
YAML Lint / yamllint (push) Has been cancelled
Push mirrored docker images / cd/Push mirrored docker images (push) Has been cancelled
docs-cd / Build and deploy docs (push) Has been cancelled
Docs CI / build (push) Has been cancelled
E2E Cache Warm: Cypress deps / Warm Cypress deps cache (push) Has been cancelled
Scorecards supply-chain security / Scorecard analysis (push) Has been cancelled
Server CI Weekly / Postgres FIPS (push) Has been skipped
Server CI Weekly / Run mmctl tests (FIPS) (push) Has been skipped
Server CI Weekly / Postgres with binary parameters (push) Has been skipped
Server CI Weekly / Build Environment (push) Failing after 1s
Server CI Cache Warm / Warm Go Module and Build Cache (push) Failing after 2s
Server CI Nightly Race / Build Environment (push) Failing after 1s
44 lines
2.4 KiB
Plaintext
44 lines
2.4 KiB
Plaintext
---
|
|
title: "Certificate-based authentication (Experimental)"
|
|
unlisted: true
|
|
---
|
|
<PlanAvailability slug="ent-plus" />
|
|
|
|
<Important>
|
|
|
|
**Experimental certificate-based authentication has been deprecated from Mattermost v11.0.** From Mattermost v11, you must [disable this feature](/administration-guide/configure/experimental-configuration-settings#enable-client-side-certification) to start the server. Enabling this setting will prevent the server from starting.
|
|
|
|
</Important>
|
|
|
|
Prior to v11, 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.
|
|
|
|
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.
|
|
|
|
Then, follow the steps below to configure user CBA for your browser and Mattermost Desktop Apps. You can manage certificate distribution for each personal device (BYOD) and their life cycle management with a service like [OpenSSL](https://www.openssl.org/).
|
|
|
|
## Set up mutual TLS authentication for the Web App
|
|
|
|
[Setting up mutual TLS authentication](/administration-guide/onboard/ssl-client-certificate) is the first step to set up certificate-based authentication.
|
|
|
|
## 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
|
|
|
|
``` text
|
|
"ExperimentalSettings": {
|
|
"ClientSideCertEnable": true,
|
|
"ClientSideCertCheck": "secondary"
|
|
},
|
|
```
|
|
|
|
3. Restart the Mattermost server.
|
|
4. 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.
|