Authentication configuration settings

Available on all plans

Cloud and self-hosted deployments

Mattermost supports up to four distinct, concurrent methods of Authentication:

• An OpenID provider

• A SAML provider

• An LDAP instance (e.g., Active Directory, OpenLDAP)

• Email and Password

Access the following configuration settings in the System Console by going to Authentication, or by editing the config.json file as described in the following tables:

• Signup

• Email

• Password

• MFA

• AD/LDAP

• SAML 2.0

• OAuth 2.0

• OpenID Connect

• Guest Access

---

Signup

Available on all plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > Signup.

Enable account creation

true: (Default) New accounts can be created by an email invitation or a public team invitation link. false: Disables new account creation. Attempting to create an account through an existing email or link displays an error message.

System Config path: Authentication > Signup config.json setting: .TeamSettings.EnableUserCreation: true Environment variable: MM_TEAMSETTINGS_ENABLEUSERCREATION

Restrict account creation to specified email domains

This setting limits the email address domains that can be used to create a new account or team. You must set Require Email Verification to true for the restriction to function. This setting only affects email login. String input of a comma-separated list of domains, i.e. corp.mattermost.com, mattermost.com

System Config path: Authentication > Signup config.json setting: .TeamSettings.RestrictCreationToDomains Environment variable: MM_TEAMSETTINGS_RESTRICTCREATIONTODOMAINS

Enable open server

true: Users can create accounts on the server without an invitation. false: (Default) Users must have an invitation to create an account on the server.

System Config path: Authentication > Signup config.json setting: .TeamSettings.EnableOpenServer Environment variable: MM_TEAMSETTINGS_ENABLEOPENSERVER

Enable email invitations

true: Allows users to send email invitations. false: (Default) Disables email invitations.

System Config path: Authentication > Signup config.json setting: .ServiceSettings.EnableEmailInvitations Environment variable: MM_SERVICESETTINGS_ENABLEEMAILINVITATIONS

Invalidate pending email invites

This button invalidates email invitations that have not been accepted (by default, invitations expire after 48 hours). This option has no config.json setting or environment variable.

System Config path: Authentication > Signup config.json setting: N/A Environment variable: N/A

---

Email

Available on all plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > Email.

Enable account creation with email

true: (Default) Allows creation of team and user accounts with email and password. false: Disables creation of team and user accounts with email and password. This requries a single sign-on service to create accounts.

System Config path: Authentication > Email config.json setting: .EmailSettings.EnableSignUpWithEmail Environment variable: MM_EMAILSETTINGS_ENABLESIGNUPWITHEMAIL

Require email verification

true: Requires email verification for new accounts before allowing the user to sign-in. false: (Default) Disables email verification. This can be used to speed development by skipping the verification process.

System Config path: Authentication > Email config.json setting: .EmailSettings.RequireEmailVerification Environment variable: MM_EMAILSETTINGS_REQUIREEMAILVERIFICATION

Enable sign-in with email

true: (Default) Allows users to sign-in with email and password. false: Disables authentication with email and password, and removes the option from the login screen. Use this option to limit authentication to single sign-on services.

System Config path: Authentication > Email config.json setting: .EmailSettings.EnableSignInWithEmail Environment variable: MM_EMAILSETTINGS_ENABLESIGNINWITHEMAIL

Enable sign-in with username

true: (Default) Allows authentication with a username and password for accounts created with an email address. This setting does not affect AD/LDAP sign-in. false: Disables authenticaton with a username and removes the option from the login screen.

System Config path: Authentication > Email config.json setting: .EmailSettings.EnableSignInWithUsername Environment variable: MM_EMAILSETTINGS_ENABLESIGNINWITHUSERNAME

---

Password

Available on all plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > Password.

Minimum password length

This feature was moved to Team Edition in Mattermost v5.0, released June 16th, 2018. Prior to v5.0, this feature is available in legacy Enterprise Edition E10 and E20.

This setting determines the minimum number of characters in passwords. It must be a whole number greater than or equal to 5 and less than or equal to 64. Numerical input. Default is 5.

System Config path: Authentication > Password config.json setting: .PasswordSettings.MinimumLength Environment variable: MM_PASSWORDSETTINGS_MINIMUMLENGTH

Password requirements

This feature was moved to Team Edition in Mattermost v5.0, released June 16th, 2018. Prior to v5.0, this feature is available in legacy Enterprise Edition E10 and E20.

This setting controls password character requirements. By checking the corresponding box, passwords must contain: At least one lowercase letter At least one uppercase letter At least one number At least one symbol out of these: !"#$%&'()*+,-./:;<=>?@[]^_`|~. The error message previewed in the System Console will appear if the user attempts to set an invalid password. The default for all boxes is unchecked. The default for all settings in config.json is false.

System Config path: Authentication > Password config.json settings: .PasswordSettings.Lowercase: false, .PasswordSettings.Uppercase: false, .PasswordSettings.Number: false, .PasswordSettings.Symbol: false Environment variables: MM_PASSWORDSETTINGS_LOWERCASE, MM_PASSWORDSETTINGS_UPPERCASE, MM_PASSWORDSETTINGS_NUMBER, MM_PASSWORDSETTINGS_SYMBOL

Maximum login attempts

This setting determines the number of failed sign-in attempts a user can make before being locked out and required to go through a password reset by email. Numerical input. Default is 10.

System Config path: Authentication > Password config.json setting: .ServiceSettings.MaximumLoginAttempts: 10 Environment variable: MM_SERVICESETTINGS_MAXIMUMLOGINATTEMPTS

---

MFA

Available on all plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > MFA.

We recommend deploying Mattermost within your own private network, and using VPN clients for mobile access, so that Mattermost is secured with your existing protocols. If you choose to run Mattermost outside your private network, bypassing your existing security protocols, we recommend adding a multi-factor authentication service specifically for accessing Mattermost.

Enable multi-factor authentication

true: Users who sign-in with AD/LDAP or an email address have the option to add multi-factor authentication to their accounts. false: (Default) Disables multi-factor authentication

System Config path: Authentication > MFA config.json setting: .ServiceSettings.EnableMultifactorAuthentication: false Environment variable: MM_SERVICESETTINGS_ENABLEMULTIFACTORAUTHENTICATION

Enforce multi-factor authentication

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E10 and E20

true: Requires multi-factor authentication (MFA) for users who sign-in with AD/LDAP or an email address. New users must configure MFA. Logged in users are redirected to the MFA setup page until configuration is complete. - false: MFA is optional.	System Config path: Authentication > MFA config.json setting: .ServiceSettings.EnforceMultifactorAuthentication Environment variable: MM_SERVICESETTINGS_ENFORCEMULTIFACTORAUTHENTICATION
Note: If your system has users who authenticate with methods other than AD/LDAP and email, MFA must be enforced with the authentication provider outside of Mattermost.

---

AD/LDAP

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > AD/LDAP.

Enable sign-in with AD/LDAP

Available in legacy Enterprise Edition E10 and E20

true: Allows sign-in with AD/LDAP or Active Directory. false: (Default) Disables sign-in with AD/LDAP or Active Directory.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.Enable: false Environment variable: MM_LDAPSETTINGS_ENABLE

Enable synchronization with AD/LDAP

Available in legacy Enterprise Edition E10 and E20

true: Mattermost periodically syncs users from AD/LDAP. false: (Default) Disables AD/LDAP synchronization.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.EnableSync: false Environment variable: MM_LDAPSETTINGS_ENABLESYNC

Login field name

Available in legacy Enterprise Edition E10 and E20

This setting will display placeholder text in the login field of the sign-in page. This text can remind users to sign-in with their AD/LDAP credentials. String input. Default is AD/LDAP Username.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.LoginFieldName Environment variable: MM_LDAPSETTINGS_LOGINFIELDNAME

AD/LDAP server

Available in legacy Enterprise Edition E10 and E20

This is the domain name or IP address of the AD/LDAP server. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.LdapServer Environment variable: MM_LDAPSETTINGS_LDAPSERVER

AD/LDAP port

Available in legacy Enterprise Edition E10 and E20

This is the port Mattermost uses to connect to the AD/LDAP server. Numerical input. Default is 389.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.LdapPort: 389 Environment variable: MM_LDAPSETTINGS_LDAPPORT

Connection security

Available in legacy Enterprise Edition E10 and E20

This setting controls the type of security Mattermost uses to connect to the AD/LDAP server, with these options: None: (Default) No encryption. With this option, it is highly recommended that the connection be secured outside of Mattermost, such as by a stunnel proxy. config.json option: "" TLS: Encrypts communication with TLS. config.json option: "TLS" STARTTLS: Attempts to upgrade an existing insecure connection to a secure connection with TLS. config.json option: "STARTTLS"

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.ConnectionSecurity Environment variable: MM_LDAPSETTINGS_CONNECTIONSECURITY

Skip certificate verification

Available in legacy Enterprise Edition E10 and E20

true: Disables the certificate verification step for TLS and STARTTLS connections. Use this option for testing. Do not use this option when TLS is required in production. false: (Default) Enables certification verification.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.SkipCertificateVerification: false Environment variable: MM_LDAPSETTINGS_SKIPCERTIFICATEVERIFICATION

Private key

Available in legacy Enterprise Edition E10 and E20

Use this setting to upload the private key file from your LDAP authentication provider, if TLS client certificates are the primary authentication mechanism. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.PrivateKeyFile Environment variable: MM_LDAPSETTINGS_PRIVATEKEYFILE

Public certificate

Available in legacy Enterprise Edition E10 and E20

Use this setting to upload the public TLS certificate from your LDAP authentication provider, if TLS client certificates are the primary authentication mechanism. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.PublicCertificateFile Environment variable: MM_LDAPSETTINGS_PUBLICCERTIFICATEFILE

Bind username

Available in legacy Enterprise Edition E10 and E20

This is the username for the account Mattermost utilizes to perform an AD/LDAP search. This should be an account specific to Mattermost. Limit the permissions of the account to read-only access to the portion of the AD/LDAP tree specified in the Base DN setting. When using Active Directory, Bind Username should specify domain in "DOMAIN/username" format. String input.	System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.BindUsername Environment variable: MM_LDAPSETTINGS_BINDUSERNAME
Note: This field is required. Anonymous bind is not currently supported.

Bind password

Available in legacy Enterprise Edition E10 and E20

This is the password for the username given in the Bind Username setting. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.BindPassword Environment variable: MM_LDAPSETTINGS_BINDPASSWORD

Base DN

Available in legacy Enterprise Edition E10 and E20

This is the Base Distinguished Name of the location in the AD/LDAP tree where Mattermost will start searching for users. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.BaseDN Environment variable: MM_LDAPSETTINGS_BASEDN

User filter

Available in legacy Enterprise Edition E10 and E20

This setting accepts a general syntax AD/LDAP filter that is applied when searching for user objects. Only the users selected by the query can access Mattermost. For example, to filter out disabled users, the filter is: (&(objectCategory=Person)(!(UserAccountControl:1.2.840.113556.1.4.803:=2))). To filter by group membership, determine the distinguishedName of the group, then use group membership general syntax to format the filter. For example, if the security group distinguishedName is CN=group1,OU=groups,DC=example,DC=com, then the filter is: (memberOf=CN=group1,OU=groups,DC=example,DC=com). The user must explicitly belong to this group for the filter to apply. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.UserFilter Environment variable: MM_LDAPSETTINGS_USERFILTER

Note: This filter uses the permissions of the Bind Username account to execute the search. This account should be specific to Mattermost and have read-only access to the portion of the AD/LDAP tree specified in the Base DN field.

Group filter

Note

Available only on Enterprise plans

Available in legacy Enterprise Edition E20

This setting accepts a general syntax AD/LDAP filter that is applied when searching for group objects. Only the groups selected by the query can access Mattermost. String input. Default is (|(objectClass=group)(objectClass=groupOfNames)(objectClass=groupOfUniqueNames)).	System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.GroupFilter Environment variable: MM_LDAPSETTINGS_GROUPFILTER
Note: This filter is only used when AD/LDAP Group Sync is enabled. See AD/LDAP Group Sync for more information.

Enable admin filter

Available in legacy Enterprise Edition E20

true: Enables the Admin Filter setting that designates System Admins using an AD/LDAP filter. false: (Default) Disables the Admin Filter setting.	System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.EnableAdminFilter: false Environment variable: MM_LDAPSETTINGS_ENABLEADMINFILTER
Note: If this setting is false, no additional users are designated as System Admins by the filter. Users that were previously designated as System Admins retain this role unless the filter is changed or removed.

Admin filter

Available in legacy Enterprise Edition E20

This setting accepts an AD/LDAP filter that designates the selected users as System Admins. Users are promoted to this role on their next sign-in or on the next scheduled AD/LDAP sync. If the Admin Filter is removed, users who are currently logged in retain their Admin role until their next sign-in. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.AdminFilter Environment variable: MM_LDAPSETTINGS_ADMINFILTER

Guest filter

Available in legacy Enterprise Edition E20

This setting accepts an AD/LDAP filter to apply when searching for external users with Guest Access to Mattermost. Only users selected by the query can access Mattermost as Guests. See Guest Accounts for more information. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.GuestFilter Environment variable: MM_LDAPSETTINGS_GUESTFILTER

ID attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in the AD/LDAP server that is serves as a unique user identifier in Mattermost. The attribute should have a unique value that does not change, such as objectGUID or entryUUID. Confirm that these attributes are available in your environment before making any changes. String input.	System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.IdAttribute Environment variable: MM_LDAPSETTINGS_IDATTRIBUTE
Note: If a user’s ID Attribute changes, a new Mattermost account is created that is not associated with the previous account. If you need to change this field after users have signed-in, use the mattermost ldap idmigrate CLI tool.

Login ID attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in the AD/LDAP server that is used for signing-in to Mattermost. This is normally the same as the Username Attribute. If your team uses domain\username to sign-in to other services with AD/LDAP, you may enter domain\username in this field to maintain consistency between sites. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.LoginIdAttribute Environment variable: MM_LDAPSETTINGS_LOGINIDATTRIBUTE

Username attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in the AD/LDAP server that populates the username field in Mattermost. This attribute identifies users in the UI. For example, if a Username Attribute is set to john.smith, typing @john will show @john.smith as an auto-complete option, and posting a message with @john.smith will send a notification to that user. This is normally the same as the Login ID Attribute, but it can be mapped to a different attribute. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.UsernameAttribute Environment variable: MM_LDAPSETTINGS_USERNAMEATTRIBUTE

Email attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in AD/LDAP server that populates the email address field in Mattermost. Email notifications are sent to this address. The address may be seen by other Mattermost users depending on privacy settings. String input.

System Config path: Authentication > AD/LDAP config.json setting .LdapSettings.EmailAttribute Environment variable: MM_LDAPSETTINGS_EMAILATTRIBUTE

First name attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in the AD/LDAP server that populates the first name field in Mattermost. When set, users cannot edit their first name. When not set, users can edit their first name in their profile settings. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.FirstNameAttribute Environment variable: MM_LDAPSETTINGS_FIRSTNAMEATTRIBUTE

Last name attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in the AD/LDAP server that populates the last name field in Mattermost. When set, users cannot edit their last name. When not set, users can edit their last name as part of their profile settings. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.LastNameAttribute Environment variable: MM_LDAPSETTINGS_LASTNAMEATTRIBUTE

Nickname attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in the AD/LDAP server that populates the nickname field in Mattermost. When set, users cannot edit their nickname. When not set, users can edit their nickname as part of their profile settings. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.NicknameAttribute Environment variable: MM_LDAPSETTINGS_NICKNAMEATTRIBUTE

Position attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in the AD/LDAP server that populates the position field in Mattermost. When set, users cannot edit their position. When not set, users can edit their position as part of their profile settings. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.PositionAttribute Environment variable: MM_LDAPSETTINGS_POSITIONATTRIBUTE

Profile picture attribute

Available in legacy Enterprise Edition E10 and E20

This is the attribute in the AD/LDAP server that syncs and locks the profile picture in Mattermost. The image is updated when users sign-in, not when Mattermost syncs with the AD/LDAP server. The image is not updated if the Mattermost image already matches the AD/LDAP image. String input.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.PictureAttribute Environment variable: MM_LDAPSETTINGS_PICTUREATTRIBUTE

Group display name attribute

Note

Available only on Enterprise plans

Available in legacy Enterprise Edition E20

This is the AD/LDAP Group Display name attribute that populates the Mattermost group name field. String input.	System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.GroupDisplayNameAttribute Environment variable: MM_LDAPSETTINGS_GROUPDISPLAYNAMEATTRIBUTE
Note: This attribute is only used when AD/LDAP Group Sync is enabled and it is required. See the AD/LDAP Group Sync documentation for more information.

Group ID attribute

Note

Available only on Enterprise plans

Available in legacy Enterprise Edition E20

This is an AD/LDAP Group ID attribute that sets a unique identifier for groups. This should be a value that does not change, such as entryUUID or objectGUID. String input.	System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.GroupIdAttribute Environment variable: MM_LDAPSETTINGS_GROUPIDATTRIBUTE
Note: This attribute is only used when AD/LDAP Group Sync is enabled and it is required. See the AD/LDAP Group Sync documentation for more information.

Synchronization interval (minutes)

Available in legacy Enterprise Edition E10 and E20

This value determines how often Mattermost syncs with the AD/LDAP server by setting the number of minutes between each sync. Syncing with the AD/LDAP server will update Mattermost accounts to match any changes made to AD/LDAP attributes. Disabled AD/LDAP accounts become inactive users in Mattermost, and any active sessions are revoked. Use the AD/LDAP Synchronize Now button to immediately revoke a session after disabling an AD/LDAP account. Numerical input. Default is 60.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.SyncIntervalMinutes: 60 Environment variable: MM_LDAPSETTINGS_SYNCINTERVALMINUTES

Note: LDAP syncs require a large number of database read queries. Monitor database load and adjust the sync interval to minimize performance degradation.

Maximum page size

Available in legacy Enterprise Edition E10 and E20

This setting paginates the results of AD/LDAP server queries. Use this setting if your AD/LDAP server has a page size limit. The recommended setting is 1500. This is the default AD/LDAP MaxPageSize. A page size of 0 disables pagination of results. Numerical input. Default is 0.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.MaxPageSize: 0 Environment variable: MM_LDAPSETTINGS_MAXPAGESIZE

Query timeout (seconds)

Available in legacy Enterprise Edition E10 and E20

This setting determines the timeout period, in seconds, for AD/LDAP queries. Increase this value to avoid timeout errors when querying a slow server. Numerical input. Default is 60.

System Config path: Authentication > AD/LDAP config.json setting: .LdapSettings.QueryTimeout: 60 Environment variable: MM_LDAPSETTINGS_QUERYTIMEOUT

AD/LDAP test

Available in legacy Enterprise Edition E10 and E20

Use this button to test the connection to the AD/LDAP server. If the test succeeds, a confirmation message is displayed. If the test fails, an error message is displayed.

System Config path: Authentication > AD/LDAP config.json setting: N/A Environment variable: N/A

AD/LDAP synchronize now

Available in legacy Enterprise Edition E10 and E20

Use this button to immediately sync with the AD/LDAP server. The status of the sync is displayed in the table underneath the button (see the figure below). Following a manual sync, the next sync will occur after the time set in the Synchronization Interval.	System Config path: Authentication > AD/LDAP config.json setting: N/A Environment variable: N/A
Note: If a sync is Pending and does not complete, check that Enable Synchronization with AD/LDAP is set to true.

---

SAML 2.0

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > SAML 2.0.

Note

In line with Microsoft ADFS guidance we recommend configuring intranet forms-based authentication for devices that do not support WIA.

Enable login with SAML

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

True: Mattermost allows login using SAML. Please see documentation to learn more about configuring SAML for Mattermost.

False: Login with SAML is disabled.

This feature’s config.json setting is "Enable": false with options true and false.

Enable synchronizing SAML accounts with AD/LDAP

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

True: Mattermost periodically synchronizes SAML user attributes, including user deactivation and removal, with AD/LDAP. Enable and configure synchronization settings at Authentication > AD/LDAP. See documentation to learn more.

False: Synchronization of SAML accounts with AD/LDAP is disabled.

This feature’s config.json setting is "EnableSyncWithLdap": false with options true and false.

Ignore guest users when synchronizing with AD/LDAP

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

Available when Enable Synchronizing SAML Accounts With AD/LDAP is set to true.

True: Mattermost ignores Guest Users identified by the Guest Attribute when synchronizing with AD/LDAP on user deactivation and removal. Manage guest deactivation manually via System Console > Users. See documentation to learn more.

False: Synchronization of SAML deactivates and removes Guest Users when synchronizing with AD/LDAP.

This feature’s config.json setting is "IgnoreGuestsLdapSync": false with options true and false.

Override SAML bind data with AD/LDAP information

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

True: Mattermost overrides the SAML ID attribute with the AD/LDAP ID attribute if configured or overrides the SAML Email attribute with the AD/LDAP Email attribute if SAML ID attribute is not present. See documentation to learn more.

False: Mattermost uses the email attribute to bind users to SAML.

Note

Moving from true to false will prevent the override from happening. To prevent the disabling of user accounts, SAML IDs must match the LDAP IDs when this feature is enabled. This setting should be set to false unless LDAP sync is enabled.

This feature’s config.json setting is "EnableSyncWithLdapIncludeAuth": false with options true and false.

Identity provider metadata URL

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The URL where Mattermost sends a request to obtain setup metadata from the provider.

This feature’s config.json setting is "IdpMetadataUrl": "" with string input.

SAML SSO URL

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The URL where Mattermost sends a SAML request to start login sequence.

This feature’s config.json setting is "IdpURL": "" with string input.

Identity provider issuer URL

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The issuer URL for the Identity Provider you use for SAML requests.

This feature’s config.json setting is "IdpDescriptorUrl": "" with string input.

Identity provider public certificate

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The public authentication certificate issued by your Identity Provider.

This feature’s config.json setting is "IdpCertificateFile": "" with string input.

Verify signature

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

True: Mattermost verifies that the signature sent from the SAML Response matches the Service Provider Login URL.

False: Not recommended for production environments. For testing only.

This feature’s config.json setting is "Verify": true with options true and false.

Service provider login URL

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

Enter https://<your-mattermost-url>/login/sso/saml (example: https://example.com/login/sso/saml). Make sure you use HTTP or HTTPS in your URL depending on your server configuration. This field is also known as the Assertion Consumer Service URL.

This feature’s config.json setting is "AssertionConsumerServiceURL": "" with string input.

Service provider identifier

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The unique identifier for the Service Provider, usually the same as Service Provider Login URL. In ADFS, this must match the Relying Party Identifier.

This feature’s config.json setting is "ServiceProviderIdentifier": "" with string input.

Enable encryption

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

True: Mattermost will decrypt SAML Assertions encrypted with your Service Provider Public Certificate.

False: Not recommended for production environments. For testing only.

This feature’s config.json setting is "Encrypt": true with options true and false.

Service provider private key

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The private key used to decrypt SAML Assertions from the Identity Provider.

This feature’s config.json setting is "PrivateKeyFile": "" with string input.

Service provider public certificate

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The certificate file used to generate the signature on a SAML request to the Identity Provider for a service provider initiated SAML login, when Mattermost is the Service Provider.

This feature’s config.json setting is "PublicCertificateFile": "" with string input.

Sign request

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

When true, Mattermost signs the SAML request using your Service Provider Private Key. When false, Mattermost does not sign the SAML request.

This feature’s config.json setting is "SignRequest": "" with string input.

Signature algorithm

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The signature algorithm used to sign the request. Supported options are RSAwithSHA1, RSAwithSHA256, and RSAwithSHA512.

This feature’s config.json setting is "SignatureAlgorithm": "" with string input.

Canonical algorithm

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The canonicalization algorithm. Supported options are Canonical1.0 for Exclusive XML Canonicalization 1.0 (omit comments) (http://www.w3.org/2001/10/xml-exc-c14n#) and Canonical1.1 for Canonical XML 1.1 (omit comments) (http://www.w3.org/2006/12/xml-c14n11).

This feature’s config.json setting is "CanonicalAlgorithm": "Canonical1.0" with string input.

Email attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The attribute in the SAML Assertion that will be used to populate the email addresses of users in Mattermost.

Email notifications will be sent to this email address, and this email address may be viewable by other Mattermost users depending on privacy settings chosen by the System Admin.

This feature’s config.json setting is "EmailAttribute": "" with string input.

Username attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

The attribute in the SAML Assertion that will be used to populate the username field in Mattermost user interface. This attribute will be used within the Mattermost user interface to identify and mention users. For example, if a Username Attribute is set to john.smith a user typing @john will see @john.smith in their auto-complete options and posting a message with @john.smith will send a notification to that user that they’ve been mentioned.

This feature’s config.json setting is "UsernameAttribute": "" with string input.

Id attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The attribute in the SAML Assertion used to bind users from SAML to users in Mattermost.

This feature’s config.json setting is "IdAttribute": "" with string input.

Guest attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The attribute in the SAML Assertion used to apply a Guest role to users in Mattermost.

See the Guest Accounts documentation for more information.

This feature’s config.json setting is "GuestAttribute": "" with string input.

Enable admin attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

True: Enables System Admins to configure the SAML Assertion.

False: Disables the ability for System Admins to configure the SAML Assertion.

Admin attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The attribute in the SAML Assertion for designating System Admins. The user is automatically promoted to this role on their next login. If the Admin Attribute is removed, users who are currently logged in retain their Admin role. When they log out this is revoked and on their next login they will no longer have Admin privileges.

This attribute’s default is false and must be set to true in order for the Admin Attribute to be used.

This feature’s config.json setting is "EnableAdminAttribute": false with options true and false.

First name attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The attribute in the SAML Assertion that will be used to populate the first name of users in Mattermost.

This feature’s config.json setting is "FirstNameAttribute": "" with string input.

Last name attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The attribute in the SAML Assertion that will be used to populate the last name of users in Mattermost.

This feature’s config.json setting is "LastNameAttribute": "" with string input.

Nickname attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The attribute in the SAML Assertion that will be used to populate the nickname of users in Mattermost.

This feature’s config.json setting is "NicknameAttribute": "" with string input.

Position attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The attribute in the SAML Assertion that will be used to populate the position field for users in Mattermost (typically used to describe a person’s job title or role at the company).

This feature’s config.json setting is "PositionAttribute": "" with string input.

Preferred language attribute

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The attribute in the SAML Assertion that will be used to populate the language of users in Mattermost.

This feature’s config.json setting is "LocaleAttribute": "" with string input.

Login button text

Note

Available only on Enterprise and Professional plans

Available in legacy Enterprise Edition E20

(Optional) The text that appears in the login button on the login page. Defaults to SAML.

This feature’s config.json setting is "LoginButtonText": "" with string input.

---

OAuth 2.0

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > OAuth 2.0.

Note

OAuth 2.0 is being deprecated and will be replaced by OpenID Connect in a future release.

Settings to configure OAuth login for account creation and login.

Select OAuth 2.0 service provider

Available in legacy Enterprise Edition E20

Choose whether OAuth can be used for account creation and login. Options include:

• Do not allow login via an OAuth 2.0 provider

• GitLab (available in all plans; see GitLab Settings for details)

• Google Apps (Available in Mattermost Enterprise and Professional; see Google Settings for details)

• Office 365 (Available in Mattermost Enterprise and Professional; see Office 365 Settings for details)

This feature’s setting does not appear in config.json.

GitLab

Available on all plans

Cloud and self-hosted deployments

Enable authentication with GitLab

True: Allow team creation and account signup using GitLab OAuth. To configure, input the Secret and Id credentials.

False: GitLab OAuth cannot be used for team creation or account signup.

Note

For Enterprise subscriptions, GitLab settings can be found under OAuth 2.0

This feature’s config.json setting is "Enable": false with options true and false.

Application ID

Obtain this value by logging into your GitLab account. Go to Profile Settings > Applications > New Application, enter a Name, then enter Redirect URLs https://<your-mattermost-url>/login/gitlab/complete (example: https://example.com:8065/login/gitlab/complete and https://<your-mattermost-url>/signup/gitlab/complete.

This feature’s config.json setting is "Id": "" with string input.

Application secret key

Obtain this value by logging into your GitLab account. Go to Profile Settings > Applications > New Application, enter a Name, then enter Redirect URLs https://<your-mattermost-url>/login/gitlab/complete (example: https://example.com:8065/login/gitlab/complete and https://<your-mattermost-url>/signup/gitlab/complete.

This feature’s config.json setting is "Secret": "" with string input.

GitLab site URL

Specify the URL of your GitLab instance (example https://example.com:3000). If your GitLab instance is not set up with SSL, start the URL with http:// instead of https://.

User API endpoint

Enter https://<your-gitlab-url>/api/v3/user (example: https://example.com:3000/api/v3/user). Use HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "UserApiEndpoint": "" with string input.

Auth endpoint

Enter https://<your-gitlab-url>/oauth/authorize (example: https://example.com:3000/oauth/authorize). Use HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "AuthEndpoint": "" with string input.

Token endpoint

Enter https://<your-gitlab-url>/oauth/token (example: https://example.com:3000/oauth/token). Use HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "TokenEndpoint": "" with string input.

Google

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Enable authentication with Google by selecting Google Apps from OAuth 2.0 > Select OAuth 2.0 service provider.

True: Allow team creation and account signup using Google OAuth. To configure, input the Client ID and Client Secret credentials. See the documentation for more detail.

False: Google OAuth cannot be used for team creation or account signup.

This feature’s config.json setting is "Enable": false with options true and false.

Client ID

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your Google account.

This feature’s config.json setting is "Id": "" with string input.

Client secret

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your Google account.

This feature’s config.json setting is "Secret": "" with string input.

User API endpoint

Available in legacy Enterprise Edition E20

We recommend you use https://people.googleapis.com/v1/people/me?personFields=names,emailAddresses,nicknames,metadata as the User API Endpoint. Otherwise, enter a custom endpoint in config.json with HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "UserApiEndpoint": "https://people.googleapis.com/v1/people/me?personFields=names,emailAddresses,nicknames,metadata"

Auth endpoint

Available in legacy Enterprise Edition E20

We recommend you use https://accounts.google.com/o/oauth2/v2/auth as the Auth Endpoint. Otherwise, enter a custom endpoint in config.json with HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "AuthEndpoint": "https://accounts.google.com/o/oauth2/v2/auth" with string input.

Token endpoint

Available in legacy Enterprise Edition E20

We recommend that you use https://www.googleapis.com/oauth2/v4/token as the Token Endpoint. Otherwise, enter a custom endpoint in config.json with HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "TokenEndpoint": "https://www.googleapis.com/oauth2/v4/token" with string input.

Office 365

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Note

In line with Microsoft ADFS guidance we recommend configuring intranet forms-based authentication for devices that do not support WIA.

Enable authentication with Office 365 by selecting Office 365 from System Console > Authentication > OAuth 2.0 > Select OAuth 2.0 service provider.

True: Allow team creation and account signup using Office 365 OAuth. To configure, input the Application ID and Application Secret Password credentials. See the documentation for more detail.

False: Office 365 OAuth cannot be used for team creation or account signup.

This feature’s config.json setting is "Enable": false with options true and false.

Application ID

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your Microsoft or Office account.

This feature’s config.json setting is "Id": "" with string input.

Application secret password

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your Microsoft or Office account.

This feature’s config.json setting is "Secret": "" with string input.

Directory (tenant) ID

Available in legacy Enterprise Edition E20

This value is the ID of the application’s AAD directory.

This feature’s config.json setting is "DirectoryId": "" with string input.

User API endpoint

Available in legacy Enterprise Edition E20

We recommend using https://graph.microsoft.com/v1.0/me as the User API Endpoint. Otherwise, enter a custom endpoint in config.json with HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "UserApiEndpoint": "https://graph.microsoft.com/v1.0/me" with string input.

Auth endpoint

Available in legacy Enterprise Edition E20

We recommend using https://accounts.google.com/o/oauth2/v2/auth as the Auth Endpoint. Otherwise, enter a custom endpoint in config.json with HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "AuthEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize" with string input.

Token endpoint

Available in legacy Enterprise Edition E20

We recommend that you use https://login.microsoftonline.com/common/oauth2/v2.0/token as the Token Endpoint. Otherwise, enter a custom endpoint in config.json with HTTP or HTTPS depending on how your server is configured.

This feature’s config.json setting is "TokenEndpoint": "https://login.microsoftonline.com/common/oauth2/v2.0/token" with string input.

---

OpenID Connect

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > OpenID Connect.

Select OpenID Connect service provider

Available in legacy Enterprise Edition E20

Choose whether OpenID Connect can be used for account creation and login. Options include:

• Do not allow login via an OpenID provider

• GitLab (available in all plans; see GitLab Settings for details)

• Google Apps (Available in Mattermost Enterprise and Professional; see Google Settings for details)

• Office 365 (Available in Mattermost Enterprise and Professional; see Office 365 Settings for details)

• OpenID Connect (Other) (Available in Mattermost Enterprise and Professional; see OpenID Connect Settings for more detail)

This feature’s setting does not appear in config.json.

GitLab settings

Available on all plans

Cloud and self-hosted deployments

GitLab site URL

Available in legacy Enterprise Edition E10 and E20. Not available in Cloud Free.

Specify the URL of your GitLab instance (example https://example.com:3000). If your GitLab instance is not set up with SSL, start the URL with http:// instead of https://.

Discovery endpoint

Available in legacy Enterprise Edition E10 and E20 Not available in Cloud Free

Obtain this value by registering Mattermost as an application in your service provider account. Should be in the format https://myopenid.provider.com/{my_company}/.well-known/openid-configuration where the value of {my_company} is replaced with your organization.

Client ID

Available in legacy Enterprise Edition E10 and E20 Not available in Cloud Free

Obtain this value by registering Mattermost as an application in your service provider account.

Client secret

Available in legacy Enterprise Edition E10 and E20 Not available in Cloud Free

Obtain this value by registering Mattermost as an application in your Google account.

Google Settings

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Enable authentication with Google by selecting Google Apps from System Console > Authentication > OpenID Connect > Select service provider.

True: Allow team creation and account signup using Google OpenID Connect. To configure, input the Client ID, Client Secret, and DiscoveryEndpoint credentials. See the documentation for more detail.

False: Google OpenID Connect cannot be used for team creation or account signup.

This feature’s config.json setting is "Enable": false with options true and false.

Discovery endpoint

Available in legacy Enterprise Edition E20

This value is prepopulated with https://accounts.google.com/.well-known/openid-configuration.

This feature’s config.json setting is "DiscoveryEndpoint": "" with string input.

Client ID

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your Google account.

This feature’s config.json setting is "Id": "" with string input.

Client secret

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your Google account.

This feature’s config.json setting is "Secret": "" with string input.

Office 365 Settings

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Note

In line with Microsoft ADFS guidance, we recommend configuring intranet forms-based authentication for devices that do not support WIA.

Enable authentication with Office 365 by selecting Office 365 from System Console > Authentication > OpenID Connect > Select service provider.

True: Allow team creation and account signup using Office 365 OpenID Connect. To configure, input the Application ID and Application Secret Password credentials. See the documentation for more detail.

False: Office 365 OpenID Connect cannot be used for team creation or account signup.

This feature’s config.json setting is "Enable": false with options true and false.

Directory (tenant) ID

Available in legacy Enterprise Edition E20

This value is the ID of the application’s AAD directory.

Discovery endpoint

Available in legacy Enterprise Edition E20

This value is prepopulated with https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.

Client ID

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your Google account.

Client secret

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your Google account.

OpenID Connect (other)

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Enable authentication with a service provider by selecting OpenID Connect (Other) from System Console > Authentication > OpenID Connect > Select service provider.

True: Allow team creation and account signup using OpenID Connect. To configure, input the Client ID, Client Secret, and DiscoveryEndpoint credentials. See the documentation for more detail.

False: OpenID Connect cannot be used for team creation or account signup.

This feature’s config.json setting is "Enable": false with options true and false.

Button name

Available in legacy Enterprise Edition E20

Specify the text that displays on the OpenID login button.

This feature’s config.json setting is "ButtonText": "" with string input.

Button color

Specify the color of the OpenID login button for white labeling purposes. Use a hex code with a #-sign before the code, for example #145DBF.

This feature’s config.json setting is "ButtonColor": "" with string input.

Discovery endpoint

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your service provider account. Should be in the format https://myopenid.provider.com/{my_company}/.well-known/openid-configuration where the value of {my_company} is replaced with your organization.

This feature’s config.json setting is "DiscoveryEndpoint": "" with string input.

Client ID

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your service provider account.

This feature’s config.json setting is "Id": "" with string input.

Client secret

Available in legacy Enterprise Edition E20

Obtain this value by registering Mattermost as an application in your service provider account.

This feature’s config.json setting is "Secret": "" with string input.

---

Guest access

Available on Enterprise and Professional plans

Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > Guest Access.

Enable guest access

Available in legacy Enterprise Edition E10 and E20

True: Allow guest invitations to channels within teams. Please see Guest Accounts documentation for more information.

False: Email signup is disabled. This limits signup to Single sign-on services like OAuth or AD/LDAP.

This feature’s config.json setting is "Enable": false with options true and false.

Whitelisted guest domains

Available in legacy Enterprise Edition E10 and E20

When populated, guest accounts can only be created by a verified email from this list of comma-separated domains.

This feature’s config.json setting is "RestrictCreationToDomains": "" with string input.

Enforce multi-factor authentication

Available in legacy Enterprise Edition E10 and E20

This setting defaults to false and is read-only if multi-factor authentication is not enforced for regular users.

True: Multi-factor authentication (MFA) is required for login. New guest users will be required to configure MFA on sign-up. Logged in guest users without MFA configured are redirected to the MFA setup page until configuration is complete.

False: Multi-factor authentication for guests is optional.

This feature’s config.json setting is "EnforceMultifactorAuthentication": false with options true and false.