Authentication configuration settings#

plans-img Available on all plans

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

Both self-hosted and Cloud admins can access the following configuration settings in System Console > Authentication. Self-hosted admins can also edit the config.json file as described in the following tables.

Signup#

plans-img Available on all plans

deployment-img 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: (Default for Cloud deployments) Allows users to send email invitations.

  • false: (Default for self-hosted deployments) Disables email invitations.

  • System Config path: Authentication > Signup

  • config.json setting: .ServiceSettings.EnableEmailInvitations: false

  • Environment variable: MM_SERVICESETTINGS_ENABLEEMAILINVITATIONS

Note: Cloud admins can’t modify this configuration setting.

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#

plans-img Available on all plans

deployment-img 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. Requires a single sign-on (SSO) service to create accounts.

  • System Config path: Authentication > Email

  • config.json setting: .EmailSettings.EnableSignUpWithEmail

  • Environment variable: MM_EMAILSETTINGS_ENABLESIGNUPWITHEMAIL

Note: Cloud admins can’t modify this configuration setting.

Require email verification#

  • true: (Default for Cloud deployments) Requires email verification for new accounts before allowing the user to sign-in.

  • false: (Default for self-hosted deployments) Disables email verification. can be used to speed development by skipping the verification process.

  • System Config path: Authentication > Email

  • config.json setting: .EmailSettings.RequireEmailVerification: false

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

  • config.json setting: .EmailSettings.EnableSignInWithEmail

  • System Config path: Authentication > Email

  • Environment variable: MM_EMAILSETTINGS_ENABLESIGNINWITHEMAIL

Note: To provide users with only a single email sign in option on the login page, ensure that the enable sign-in with username configuration setting is set to false.

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#

plans-img Available on all plans

deployment-img Cloud and self-hosted deployments

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

Minimum password length#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

plans-img Available on all plans

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

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E10 or 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: (Default) MFA is optional.

  • System Config path: Authentication > MFA

  • config.json setting: .ServiceSettings.EnforceMultifactorAuthentication: false

  • 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#

plans-img Available on Enterprise and Professional plans

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

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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

Note: Synchronization with AD/LDAP settings in the System Console can be used to determine the connectivity and availability of arbitrary hosts. System admins concerned about this can use custom admin roles to limit access to modifying these settings. See the system admin roles documentation for details.

Login field name#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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

Note: Synchronization with AD/LDAP settings in the System Console can be used to determine the connectivity and availability of arbitrary hosts. System admins concerned about this can use custom admin roles to limit access to modifying these settings. See the system admin roles documentation for details.

AD/LDAP port#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or E20

This setting controls the type of security Mattermost uses to connect to the AD/LDAP server, with these options:

  • None: (Default for self-hosted deployments) 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: (Default for Cloud deployments) 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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

plans-img-yellow Available only on Enterprise plans

Also available in legacy Mattermost 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#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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 mmctl ldap idmigrate command.

Login ID attribute#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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

plans-img-yellow Available only on Enterprise plans

Also available in legacy Mattermost 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

plans-img-yellow Available only on Enterprise plans

Also available in legacy Mattermost 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)#

Also available in legacy Mattermost Enterprise Edition E10 or 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 deactivated 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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)#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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#

Also available in legacy Mattermost Enterprise Edition E10 or 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.
../_images/ldap-sync-table.png

SAML 2.0#

plans-img Available on Enterprise and Professional plans

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

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

  • true: Enables sign-in with SAML. See SAML Single Sign-On to learn more.

  • false: (Default) Disables sign-in with SAML.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.Enable: false

  • Environment variable: MM_SAMLSETTINGS_ENABLE

Enable synchronizing SAML accounts with AD/LDAP#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

  • true: Mattermost updates configured Mattermost user attributes (ex. FirstName, Position, Email) with their values from AD/LDAP. This synchronization may deactivate Mattermost users or remove them from groups, teams, or channels. AD/LDAP synchronization must be enabled and configured through the settings under Authentication > AD/LDAP.

  • false: (Default) Disables syncing of SAML-authenticated Mattermost users with AD/LDAP.

See AD/LDAP Setup to learn more.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.EnableSyncWithLdap: false

  • Environment variable: MM_SAMLSETTINGS_ENABLESYNCWITHLDAP

Ignore guest users when synchronizing with AD/LDAP#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

  • true: When syncing with the AD/LDAP server, Mattermost does not sync any information about SAML-authenticated Guest Users from the AD/LDAP server. Manage guest deactivation manually via System Console > Users.

  • false: (Default) Syncing Mattermost with the AD/LDAP server updates Guest User attributes and deactivates and removes SAML-authenticated accounts for Guest Users that are no longer active on the AD/LDAP server.

For more information, see AD/LDAP Setup for details.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.IgnoreGuestsLdapSync: false

  • Environment variable: MM_SAMLSETTINGS_IGNOREGUESTSLDAPSYNC

Override SAML bind data with AD/LDAP information#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

  • true: If the SAML ID attribute is configured, Mattermost overrides the SAML ID attribute with the AD/LDAP ID attribute. If the SAML ID attribute is not present, Mattermost overrides the SAML Email attribute with the AD/LDAP Email attribute.

  • false: (Default) Mattermost uses the email attribute to bind users to SAML.

For more information, see AD/LDAP Setup for details.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.EnableSyncWithLdapIncludeAuth: false

  • Environment variable: MM_SAMLSETTINGS_ENABLESYNCWITHLDAPINCLUDEAUTH
Notes:

  • This setting should be false unless LDAP sync is enabled.

  • Changing this setting from true to false will disable the override.

  • SAML IDs must match LDAP IDs when the override is enabled.

Identity provider metadata URL#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting is the URL from which Mattermost requests setup metadata from the provider.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.IdpMetadataURL

  • Environment variable: MM_SAMLSETTINGS_IDPMETADATAURL

SAML SSO URL#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting is the URL where Mattermost sends a SAML request to start the login sequence.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.IdpURL

  • Environment variable: MM_SAMLSETTINGS_IDPURL

Identity provider issuer URL#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting is the issuer URL for the Identity Provider for SAML requests.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.IdpDescriptorURL

  • Environment variable: MM_SAMLSETTINGS_IDPDESCRIPTORURL

Identity provider public certificate#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

The public authentication certificate issued by your Identity Provider.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.IdpCertificateFile

  • Environment variable: MM_SAMLSETTINGS_IDPCERTIFICATEFILE

Verify signature#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

  • true: (Default) Mattermost checks that the SAML Response signature matches the Service Provider Login URL.

  • false: The signature is not verified. This is not recommended for production. Use this option for testing only.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.Verify: true

  • Environment variable: MM_SAMLSETTINGS_VERIFY

Service provider login URL#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

Enter the URL of your Mattermost server, followed by /login/sso/saml, i.e. https://example.com/login/sso/saml.

Use HTTP or HTTPS depending on the configuration of the server.

This setting is also known as the Assertion Consumer Service URL.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.AssertionConsumerServiceURL

  • Environment variable: MM_SAMLSETTINGS_ASSERTIONCONSUMERSERVICEURL

Service provider identifier#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting is the unique identifier for the Service Provider, which in most cases is the same as the Service Provider Login URL. In ADFS, this must match the Relying Party Identifier.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.ServiceProviderIdentifier

  • Environment variable: MM_SAMLSETTINGS_SERVICEPROVIDERIDENTIFIER

Enable encryption#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

  • true: (Default) Mattermost will decrypt SAML Assertions that are encrypted with your Service Provider Public Certificate.

  • false: Mattermost does not decrypt SAML Assertions. Use this option for testing only. It is not recommended for production.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.Encrypt: true

  • Environment variable: MM_SAMLSETTINGS_ENCRYPT

Service provider private key#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the private key used to decrypt SAML Assertions from the Identity Provider.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.PrivateKeyFile

  • Environment variable: MM_SAMLSETTINGS_PRIVATEKEYFILE

Service provider public certificate#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the certificate file used to sign a SAML request to the Identity Provider for a SAML login when Mattermost is initiating the login as the Service Provider.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.PublicCertificateFile

  • Environment variable: MM_SAMLSETTINGS_PUBLICCERTIFICATEFILE

Sign request#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

  • true: Mattermost signs the SAML request with the Service Provider Private Key.

  • false: Mattermost does not sign the SAML request.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.SignRequest

  • Environment variable: MM_SAMLSETTINGS_SIGNREQUEST

Signature algorithm#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting determines the signature algorithm used to sign the SAML request. Options are: RSAwithSHA1, RSAwithSHA256, RSAwithSHA512.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.SignatureAlgorithm

  • Environment variable: MM_SAMLSETTINGS_SIGNATUREALGORITHM

Canonical algorithm#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting determines the canonicalization algorithm. With these options:

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.CanonicalAlgorithm

  • Environment variable: MM_SAMLSETTINGS_CANONICALALGORITHM

Email attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting determines the attribute from the SAML Assertion that populates the user email address field in Mattermost.

Notifications are sent to this email address. This email address may be visible to other users, depending on how the System Admin has set-up user privacy.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.EmailAttribute

  • Environment variable: MM_SAMLSETTINGS_EMAILATTRIBUTE

Username attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

This setting determines the SAML Assertion attribute that populates the username field in the Mattermost UI.

This attribute identifies users in the UI. For example, if a username 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.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.UsernameAttribute

  • Environment variable: MM_SAMLSETTINGS_USERNAMEATTRIBUTE

Id attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

(Optional) This setting determines the SAML Assertion attribute used to bind users from SAML to users in Mattermost.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.IdAttribute

  • Environment variable: MM_SAMLSETTINGS_IDATTRIBUTE

Guest attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

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

See the Guest Accounts documentation for more information.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.GuestAttribute

  • Environment variable: MM_SAMLSETTINGS_GUESTATTRIBUTE

Enable admin attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

  • true: System Admin status is determined by the SAML Assertion attribute set in Admin attribute.

  • false: (Default) System Admin status is not determined by the SAML Assertion attribute.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.EnableAdminAttribute: false

  • Environment variable: MM_SAMLSETTINGS_ENABLEADMINATTRIBUTE

Admin attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

(Optional) This setting determines the attribute in the SAML Assertion for designating System Admins.

Users are automatically promoted to this role when logging in to Mattermost.

If the Admin attribute is removed, users that are logged in retain Admin status. The role is revoked only when users log out.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.AdminAttribute

  • Environment variable: MM_SAMLSETTINGS_ADMINATTRIBUTE

First name attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

(Optional) This setting determines the SAML Assertion attribute that populates the first name of users in Mattermost.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.FirstNameAttribute

  • Environment variable: MM_SAMLSETTINGS_FIRSTNAMEATTRIBUTE

Last name attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

(Optional) This setting determines the SAML Assertion attribute that populates the last name of users in Mattermost.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.LastNameAttribute

  • Environment variable: MM_SAMLSETTINGS_LASTNAMEATTRIBUTE

Nickname attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

(Optional) This setting determines the SAML Assertion attribute that populates the nickname of users in Mattermost.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.NicknameAttribute

  • Environment variable: MM_SAMLSETTINGS_NICKNAMEATTRIBUTE

Position attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

(Optional) This setting determines the SAML Assertion attribute that populates the position (job title or role at company) of users in Mattermost.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.PositionAttribute

  • Environment variable: MM_SAMLSETTINGS_POSITIONATTRIBUTE

Preferred language attribute#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

(Optional) This setting determines the SAML Assertion attribute that populates the language preference of users in Mattermost.

String input.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.LocaleAttribute

  • Environment variable: MM_SAMLSETTINGS_LOCALEATTRIBUTE

Login button text#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E20

(Optional) The text that appears in the login button on the sign-in page.

String input. Default is SAML.

  • System Config path: Authentication > SAML 2.0

  • config.json setting: .SamlSettings.LoginButtonText

  • Environment variable: MM_SAMLSETTINGS_LOGINBUTTONTEXT

OAuth 2.0#

plans-img Available on Enterprise and Professional plans

deployment-img Cloud and self-hosted deployments

Access the following configuration settings in the System Console by going to Authentication > OAuth 2.0. Settings for GitLab OAuth authentication can also be accessed under Authentication > GitLab in self-hosted deployments.

Use these settings to configure OAuth 2.0 for account creation and login.

Select OAuth 2.0 service provider#

Also available in legacy Mattermost Enterprise Edition E20

Use this setting to enable OAuth and specify the service provider, with these options:

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: N/A

  • Environment variable: N/A

GitLab OAuth 2.0 settings#

plans-img Available on all plans

deployment-img Cloud and self-hosted deployments

Note

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

Enable OAuth 2.0 authentication with GitLab#

  • true: Allows team and account creation using GitLab OAuth authentication. Input the Secret and ID credentials to configure.

  • false: (Default) Disables GitLab OAuth authentication.

  • System Config path: Authentication > OAuth 2.0 (or GitLab)

  • config.json setting: .GitLabSettings.Enable: false

  • Environment variable: MM_GITLABSETTINGS_ENABLE
GitLab OAuth 2.0 Application ID#

This setting holds the OAuth Application ID from GitLab. Generate the ID by these steps:

  1. Login to your GitLab account.

  2. Go to Profile Settings > Applications > New Application and enter a name.

  3. Enter the Redirect URLs: https://<your-mattermost-url>/login/gitlab/complete and https://<your-mattermost-url>/signup/gitlab/complete.

  4. Take the Application ID provided by GitLab and enter it in the Mattermost System Console field, config.json setting, or Environment variable.

String input.

  • System Config path: Authentication > OAuth 2.0 (or GitLab)

  • config.json setting: .GitLabSettings.Id

  • Environment variable: MM_GITLABSETTINGS_ID

Note: GitLab provides the Application Secret Key along with the the ID.
GitLab OAuth 2.0 Application secret key#

This setting holds the OAuth Application Secret Key from GitLab. The key is generated at the same time as the Application ID (see GitLab OAuth 2.0 Application ID).

Enter the key provided by GitLab in the Mattermost System Console field, config.json setting, or Environment variable.

String input.

  • System Config path: Authentication > OAuth 2.0 (or GitLab)

  • config.json setting: .GitLabSettings.Secret

  • Environment variable: MM_GITLABSETTINGS_SECRET
GitLab OAuth 2.0 site URL#

This setting holds the URL of your GitLab instance, e.g. https://example.com:3000. Use http:// if SSL is not enabled on your GitLab instance.

  • System Config path: Authentication > OAuth 2.0 (or GitLab)

  • config.json setting: N/A

  • Environment variable: N/A
GitLab OAuth 2.0 User API endpoint#

This setting holds the URL of your GitLab User API endpoint, e.g. https://<your-gitlab-url>/api/v3/user. Use http:// if SSL is not enabled on your GitLab instance.

Enter the URL in the Mattermost System Console field, config.json setting, or Environment variable.

String input.

  • System Config path: Authentication > OAuth 2.0 (or GitLab)

  • config.json setting: .GitLabSettings.UserAPIEndpoint

  • Environment variable: MM_GITLABSETTINGS_USERAPIENDPOINT
GitLab OAuth 2.0 Auth endpoint#

This setting holds the URL of your GitLab Auth endpoint, e.g. https://<your-gitlab-url>/oauth/authorize. Use http:// if SSL is not enabled on your GitLab instance.

Enter the URL in the Mattermost System Console field, config.json setting, or Environment variable.

String input.

  • System Config path: Authentication > OAuth 2.0 (or GitLab)

  • config.json setting: .GitLabSettings.AuthEndpoint

  • Environment variable: MM_GITLABSETTINGS_AUTHENDPOINT
GitLab OAuth 2.0 Token endpoint#

This setting holds the URL of your GitLab OAuth Token endpoint, e.g. https://<your-gitlab-url>/oauth/token. Use http:// if SSL is not enabled on your GitLab instance.

Enter the URL in the Mattermost System Console field, config.json setting, or Environment variable.

String input.

  • System Config path: Authentication > OAuth 2.0 (or GitLab)

  • config.json setting: .GitLabSettings.TokenEndpoint

  • Environment variable: MM_GITLABSETTINGS_TOKENENDPOINT

Google OAuth 2.0 settings#

plans-img Available on Enterprise and Professional plans

deployment-img Cloud and self-hosted deployments

Enable OAuth 2.0 authentication with Google#

  • true: Allows team and account creation using Google OAuth authentication. Input the Client ID and Client Secret credentials to configure.

  • false: (Default) Disables Google OAuth authentication.

See Google Single Sign-On implementation instructions.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .GoogleSettings.Enable: false

  • Environment variable: MM_GOOGLESETTINGS_ENABLE
Google OAuth 2.0 Client ID#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the OAuth Client ID from Google. Generate the ID by going to the Credentials section of the Google Cloud Platform APIs & Services menu and selecting Create Credentials > OAuth client ID.

See Google Single Sign-On for instructions that can be used to implement Google OAuth or OpenID authentication.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .GoogleSettings.Id

  • Environment variable: MM_GOOGLESETTINGS_ID
Google OAuth 2.0 Client secret#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the OAuth Client Secret from Google. The Secret is generated at the same time as the Client ID.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .GoogleSettings.Secret

  • Environment variable: MM_GOOGLESETTINGS_SECRET
Google OAuth 2.0 User API endpoint#

Also available in legacy Mattermost Enterprise Edition E20

We recommend 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, if available on the API server.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .GoogleSettings.UserAPIEndpoint

  • Environment variable: MM_GOOGLESETTINGS_USERAPIENDPOINT
Google OAuth 2.0 Auth endpoint#

Also available in legacy Mattermost Enterprise Edition E20

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

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .GoogleSettings.AuthEndpoint

  • Environment variable: MM_GOOGLESETTINGS_AUTHENDPOINT
Google OAuth 2.0 Token endpoint#

Also available in legacy Mattermost Enterprise Edition E20

We recommend https://www.googleapis.com/oauth2/v4/token as the Token Endpoint. Otherwise, enter a custom endpoint in config.json with HTTP, or HTTPS, if available on the server.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .GoogleSettings.TokenEndpoint

  • Environment variable: MM_GOOGLESETTINGS_TOKENENDPOINT

Office 365 OAuth 2.0 settings#

plans-img Available on Enterprise and Professional plans

deployment-img 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 OAuth 2.0 Authentication with Office 365#

  • true: Allows team and account creation using Office 365 OAuth authentication.

  • false: (Default) Disables Office 365 OAuth authentication.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .Office365Settings.Enable: false

  • Environment variable: MM_OFFICE365SETTINGS_ENABLE

Note: See the Office 365 Single Sign-On documentation for details.
Office 365 OAuth 2.0 Application ID#

Also available in legacy Mattermost Enterprise Edition E20

This setting holds the Application ID generated when configuring Office 365 as a Single Sign-On service through the Microsoft Azure Portal.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .Office365Settings.Id

  • Environment variable: MM_OFFICE365SETTINGS_ID

Note: See the Office 365 Single Sign-On documentation for details.
Office 365 OAuth 2.0 Application secret password#

Also available in legacy Mattermost Enterprise Edition E20

This setting holds the Application Secret Password generated when configuring Office 365 as a Single Sign-On service through the Microsoft Azure Portal.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .Office365Settings.Secret

  • Environment variable: MM_OFFICE365SETTINGS_SECRET

Note: See the Office 365 Single Sign-On documentation for details.
Office 365 OAuth 2.0 Directory (tenant) ID#

Also available in legacy Mattermost Enterprise Edition E20

This setting holds the Directory (tenant) ID set for Mattermost through the Azure Portal.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .Office365Settings.DirectoryId

  • Environment variable: MM_OFFICE365SETTINGS_DIRECTORYID

Note: See the Office 365 Single Sign-On documentation for details.
Office 365 OAuth 2.0 User API endpoint#

Also available in legacy Mattermost Enterprise Edition E20

We recommend https://graph.microsoft.com/v1.0/me as the User API Endpoint. Otherwise, enter a custom endpoint in config.json with http, or https, if available on the server.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .Office365Settings.UserAPIEndpoint

  • Environment variable: MM_OFFICE365SETTINGS_USERAPIENDPOINT
Office 365 OAuth 2.0 Auth endpoint#

Also available in legacy Mattermost Enterprise Edition E20

We recommend https://login.microsoftonline.com/common/oauth2/v2.0/authorize as the Auth Endpoint. Otherwise, enter a custom endpoint in config.json with http, or https, if available on the server.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .Office365Settings.AuthEndpoint

  • Environment variable: MM_OFFICE365SETTINGS_AUTHENDPOINT
Office 365 OAuth 2.0 Token endpoint#

Also available in legacy Mattermost Enterprise Edition E20

We recommend 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, if available on the server.

String input.

  • System Config path: Authentication > OAuth 2.0

  • config.json setting: .Office365Settings.TokenEndpoint

  • Environment variable: MM_OFFICE365SETTINGS_TOKENENDPOINT

OpenID Connect#

plans-img Available on all plans

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

Also available in legacy Mattermost Enterprise Edition E20

Use this setting to enable OpenID Connect, with these options:

  • System Config path: Authentication > OpenID Connect

  • config.json setting: N/A

  • Environment variable: N/A

Note: GitLab OpenID is available in all plans. All other providers require Mattermost Enterprise or Professional.

GitLab OpenID settings#

plans-img Available on Enterprise and Professional plans

deployment-img Cloud and self-hosted deployments

Enable OpenID Connect authentication with GitLab#

Also available in legacy Mattermost Enterprise Edition E10 or E20

  • true: Allows team and account creation using GitLab OpenID Connect authentication.

  • false: (Default) Disables GitLab OpenID Connect authentication.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .GitLabSettings.Enable: false

  • Environment variable: MM_GITLABSETTINGS_ENABLE

Note: See the GitLab Single Sign-On documentation for details.
GitLab OpenID site URL#

Also available in legacy Mattermost Enterprise Edition E10 or E20

This setting stores the URL of your GitLab instance, e.g. https://example.com:3000.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: N/A

  • Environment variable: N/A

Note: See Step 2 of the GitLab Single Sign-On documentation for details.
GitLab OpenID Discovery endpoint#

Also available in legacy Mattermost Enterprise Edition E10 or E20

This setting is prepopulated with the Discovery Endpoint for GitLab OpenID Connect.

String input. Default is https://gitlab.com/.well-known/openid-configuration

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .GitLabSettings.DiscoveryEndpoint

  • Environment variable: MM_GITLABSETTINGS_DISCOVERYENDPOINT

Note: See Step 2 of the GitLab Single Sign-On documentation for details.
GitLab OpenID Client ID#

Also available in legacy Mattermost Enterprise Edition E10 or E20

This setting stores the Application ID generated by GitLab.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .GitLabSettings.Id

  • Environment variable: MM_GITLABSETTINGS_ID

Note: See Step 2 of the GitLab Single Sign-On documentation for details.
GitLab OpenID Client secret#

Also available in legacy Mattermost Enterprise Edition E10 or E20

This setting stores the Application Secret Key generated by GitLab.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .GitLabSettings.Secret

  • Environment variable: MM_GITLABSETTINGS_SECRET

Note: See Step 2 of the GitLab Single Sign-On documentation for details.

Google OpenID settings#

plans-img Available on Enterprise and Professional plans

deployment-img Cloud and self-hosted deployments

Enable OpenID Connect authentication with Google#

Also available in legacy Mattermost Enterprise Edition E20

  • true: Allows team and account creation using Google OpenID authentication.

  • false: (Default) Disables Google OpenID authentication.

See Google Single Sign-On implementation instructions.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .GoogleSettings.Enable: false

  • Environment variable: MM_GOOGLESETTINGS_ENABLE
Google OpenID Discovery endpoint#

Also available in legacy Mattermost Enterprise Edition E20

This setting is prepopulated with the Discovery Endpoint for Google OpenID Connect.

See Configure Mattermost for Google Apps SSO.

String input. Default is https://accounts.google.com/.well-known/openid-configuration

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .GoogleSettings.DiscoveryEndpoint

  • Environment variable: MM_GOOGLESETTINGS_DISCOVERYENDPOINT
Google OpenID Client ID#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the Client ID generated by Google.

See Google Single Sign-On implementation instructions.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .GoogleSettings.Id

  • Environment variable: MM_GOOGLESETTINGS_ID
Google OpenID Client secret#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the Client Secret generated by Google.

See Google Single Sign-On implementation instructions.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .GoogleSettings.Secret

  • Environment variable: MM_GOOGLESETTINGS_SECRET

Office 365 OpenID settings#

plans-img Available on Enterprise and Professional plans

deployment-img 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 OpenID Connect authentication with Office 365#

Also available in legacy Mattermost Enterprise Edition E20

  • true: Allows team and account creation using Office 365 OpenID Connect authentication.

  • false: (Default) Disables Office 365 OpenID Connect authentication.

See Office 365 Single Sign-On implementation instructions.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .Office365Settings.Enable: false

  • Environment variable: MM_OFFICE365SETTINGS_ENABLE
Office 365 OpenID Directory (tenant) ID#

Also available in legacy Mattermost Enterprise Edition E20

This setting holds the Directory (tenant) ID set for Mattermost through the Microsoft Azure Portal.

See Office 365 Single Sign-On implementation instructions.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .Office365Settings.DirectoryId

  • Environment variable: MM_OFFICE365SETTINGS_DIRECTORYID
Office 365 OpenID Discovery endpoint#

Also available in legacy Mattermost Enterprise Edition E20

This setting is prepopulated with the Discovery Endpoint for Office 365 OpenID Connect.

See Office 365 Single Sign-On implementation instructions.

String input. Default is https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .Office365Settings.DiscoveryEndpoint

  • Environment variable: MM_OFFICE365SETTINGS_DISCOVERYENDPOINT
Office 365 Client ID#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the Application (client) ID generated through the Microsoft Azure Portal.

See Office 365 Single Sign-On implementation instructions.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .Office365Settings.Id

  • Environment variable: MM_OFFICE365SETTINGS_ID
Office 365 Client secret#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the Client Secret generated through the Microsoft Azure Portal.

See Office 365 Single Sign-On implementation instructions.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .Office365Settings.Secret

  • Environment variable: MM_OFFICE365SETTINGS_SECRET

OpenID Connect (other) settings#

plans-img Available on Enterprise and Professional plans

deployment-img Cloud and self-hosted deployments

Enable OpenID Connect authentication with other service providers#

plans-img Available on Enterprise and Professional plans

deployment-img Cloud and self-hosted deployments

Also available in legacy Mattermost Enterprise Edition E20

  • true: Allows team and account creation using other OpenID Connect service providers.

  • false: (Default) Disables OpenID Connect authentication with other service providers.

See OpenID Connect Single Sign-On implementation instructions.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .OpenIdSettings.Enable: false

  • Environment variable: MM_OPENIDSETTINGS_ENABLE
OpenID Connect (other) Button name#

Also available in legacy Mattermost Enterprise Edition E20

This setting is the text for the OpenID login button.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .OpenIdSettings.ButtonText

  • Environment variable: MM_OPENIDSETTINGS_BUTTONTEXT
OpenID Connect (other) Button color#

Also available in legacy Mattermost Enterprise Edition E20

This setting is the color of the OpenID login button. Use a hex code with a #-sign before the code, for example #145DBF.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .OpenIdSettings.ButtonColor

  • Environment variable: MM_OPENIDSETTINGS_BUTTONCOLOR
OpenID Connect (other) Discovery endpoint#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the Discovery Endpoint URL from the OpenID provider. The URL should be in the format of https://myopenid.provider.com/{my_organization}/ .well-known/openid-configuration.

See OpenID Connect Single Sign-On implementation instructions.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .OpenIdSettings.DiscoveryEndpoint

  • Environment variable: MM_OPENIDSETTINGS_DISCOVERYENDPOINT

Note: The Discovery Endpoint setting can be used to determine the connectivity and availability of arbitrary hosts. System admins concerned about this can use custom admin roles to limit access to modifying these settings. See the system admin roles documentation for details.
OpenID Connect (other) Client ID#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the Client ID from the OpenID provider.

See OpenID Connect Single Sign-On implementation instructions.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .OpenIdSettings.Id

  • Environment variable: MM_OPENIDSETTINGS_ID
OpenID Connect (other) Client secret#

Also available in legacy Mattermost Enterprise Edition E20

This setting stores the Client Secret from the OpenID provider.

See OpenID Connect Single Sign-On implementation instructions.

String input.

  • System Config path: Authentication > OpenID Connect

  • config.json setting: .OpenIdSettings.Secret

  • Environment variable: MM_OPENIDSETTINGS_SECRET

Guest access#

plans-img Available on Enterprise and Professional plans

deployment-img Cloud and self-hosted deployments

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

Enable guest access#

Also available in legacy Mattermost Enterprise Edition E10 or E20

  • true: Enables the guest account feature.

  • false: (Default) Disables the guest account feature.

  • System Config path: Authentication > Guest Access

  • config.json setting: .GuestAccountsSettings.Enable: false

  • Environment variable: MM_GUESTACCOUNTSSETTINGS_ENABLE

Note: See the Guest Accounts documentation for details.

Whitelisted guest domains#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Use this setting to restrict the creation of guest accounts. When set, guest accounts require a verified email address from one of the listed domains.

String input of one or more domains, separated by commas.

  • System Config path: Authentication > Guest Access

  • config.json setting: .GuestAccountsSettings.RestrictCreationToDomains

  • Environment variable: MM_GUESTACCOUNTSSETTINGS_RESTRICTCREATIONTODOMAINS

Enforce multi-factor authentication#

Also available in legacy Mattermost Enterprise Edition E10 or E20

  • true: Guests must use MFA. Guests without MFA are redirected to the setup page until MFA is configured.

  • false: (Default) MFA is not required for guests.

  • System Config path: Authentication > Guest Access

  • config.json setting: .GuestAccountsSettings.EnforceMultifactorAuthentication: false

  • Environment variable: MM_GUESTACCOUNTSSETTINGS_ENFORCEMULTIFACTORAUTHENTICATION

Note: This setting defaults to false and cannot be changed if MFA isn’t enforced for non-guest users.

Show guest tag#

  • true: (Default) Guest tags are visible in Mattermost.

  • false: Guest tags aren’t visible in Mattermost.

  • System Config path: Authentication > Guest Access

  • config.json setting: .GuestAccountsSettings.HideTags: true

  • Environment variable: MM_GUESTACCOUNTSSETTINGS_HIDETAGS

Notes:

  • See the guest accounts documentation for details.

  • This configuration setting applies to all Mattermost clients, including web, desktop app, and mobile app.