Map Active Directory Groups to Mattermost Teams with LDAP Sync

The problem: separate chat credentials and manual team invites

As an engineering organization grows, IT often manages users in Active Directory or OpenLDAP while Mattermost maintains its own local accounts. New hires need a separate Mattermost password, terminations require manual deactivation in two places, and team membership changes lag behind directory updates. The result is stale access and extra tickets for IT.

Takeaway: bind Mattermost to LDAP and sync groups to teams

Mattermost can authenticate users against an LDAP server and automatically place them into teams based on directory group membership. This means a user in the Active Directory engineering group lands in the Mattermost Engineering team at login, with no custom code required.

Configure LDAP with TLS and group mapping

LDAP (Lightweight Directory Access Protocol) is a directory protocol for querying user and group records. Mattermost reads these settings from config.json, typically located at /opt/mattermost/config/config.json on a Linux installation. Edit the file with root or mattermost service account permissions. The configuration below shows a minimal secure example; adjust the bind DN and group filter for your directory schema.

{
  "LoginSettings": {
    "LDAPServerURL": "ldaps://{{LDAP_URL}}",
    "LDAPLoginDN": "cn={{BIND_DN}},dc={{DOMAIN}}",
    "LDAPPassword": "{{BIND_PASSWORD}}",
    "LDAPGroupFilter": "(objectClass=group)",
    "GroupSync": true,
    "GroupMap": {
      "{{LDAP_GROUP}}": "{{MATTERMOST_TEAM}}"
    }
  }
}

The ldaps:// scheme encrypts the bind connection; do not use ldap:// in production because the bind password travels in plaintext. The bind DN should have read-only access to user and group objects. After saving, restart the service:

sudo systemctl restart mattermost

This command requires root or sudo privileges on a Linux host. Restarting briefly interrupts Mattermost, so schedule it during a maintenance window.

Verify sync with a test user and server logs

Create a test user in LDAP and add them to the mapped group. Then log in to Mattermost as that user. The user should appear in the target team and see its channels immediately after authentication. If the team does not appear, log out and log in again, because group membership is evaluated during authentication.

Check the Mattermost server log on the application host:

sudo tail -f /var/log/mattermost/mattermost.log | grep -E "LDAP bind successful|Group sync completed"

You need read access to the log file. Look for a line confirming the bind and another indicating group sync completed for the test username. Check for errors such as bind failures or missing group attributes, which indicate configuration problems rather than successful sync. If the user does not appear in the team, confirm the LDAP group name spelling matches the GroupMap key exactly and that the bind account can read the group membership attribute.

Trade-offs: login latency, next-login delay, and exact matches

Mattermost evaluates group sync on every login. For large directories, this can add noticeable latency because the server must query the directory during authentication. Directory changes also take effect only after the user’s next authentication, not instantly. Group mapping supports exact name matches; nested groups or custom attributes require additional scripting or a custom plugin. Mattermost releases before 5.0 do not fully support group sync, so verify your server version first.

Rollback if mapping breaks access

Because editing config.json changes server state, keep a backup before editing:

sudo cp /opt/mattermost/config/config.json /opt/mattermost/config/config.json.bak

If users lose access after enabling sync, restore the backup and restart Mattermost. Then re-test with a single account before rolling out to more users.

Closing recommendation

Enable LDAP with group sync if your organization already runs Active Directory or OpenLDAP. Enforce TLS, test with one user, monitor login times, and treat directory group changes as effective at the next login rather than immediately.