Mattermost AD/LDAP group sync: when directory groups should control channel access
Identity teams that want onboarding and offboarding in Mattermost to follow Active Directory or LDAP groups, rather than manual channel edits, need Mattermost AD/LDAP groups. This feature synchronizes directory groups into Mattermost groups, and those groups can then drive team and private channel membership and roles, including nested groups. The result is that a person's access to Mattermost follows the same group memberships that already govern their other systems.
Teams usually need this when the number of channels has grown beyond what anyone can curate by hand, when access must be shown in regulated access reviews, or when people join and leave often enough that manual changes lag behind reality. In these cases, a departed employee who stays in a private channel is a real exposure, and a reviewer asking who can see a channel is easier to answer when the answer is a directory group rather than a list of individual adds. Mattermost documents AD/LDAP groups as available on the Entry, Enterprise and Enterprise Advanced plans, and not on Professional. Confirm the plan that matches your seat count and feature needs with Mattermost before you design around this capability.
The decision to make first is which directory groups should be authoritative. Map each Mattermost team and private channel to one owning group, and decide whether roles such as channel admin should also come from directory groups or stay within Mattermost. Nested groups make this more powerful but also harder to audit, because a membership granted through a parent group may be less visible to the people reviewing access. Document the mapping in a table that names the directory group, the Mattermost group it creates, the teams and channels it governs and the role it grants, and have the owners of those directory groups sign off on it.
Check a few things in your own environment before enabling sync. Confirm the directory attributes and search base that Mattermost will read, and test a sample of accounts to see whether their nested memberships resolve as expected. Decide what happens to channel members who are not in any synchronized group, since manually added members may be removed or kept depending on configuration that you should verify on a test server. Plan for a group that is empty or misspelled in the directory, because an unintended sync can remove access as easily as it grants it. Record the test results so the access review can show how the mapping was verified.
Finally, plan operations around the sync. Name an owner for directory group changes, agree how quickly joiners and leavers must be reflected, and schedule a periodic review of the mapping against the channel list. Ask your implementation partner and Mattermost to confirm how sync frequency, error reporting and any limits on group counts apply to your version, since these details change between releases and should be checked against the release you run.
Which group sync options fit which team structure
This table compares the group sync choices an administrator makes when connecting directory groups to Mattermost, and what each choice changes for admins and users. Read each row against your team structure: flat teams, departmental teams, and project or cross-functional access. The main takeaway is that team membership, private channel membership and role assignment are separate decisions, and nested groups need a deliberate design before you map them.
| Option | When it fits | What it changes for administrators | What it changes for users |
|---|---|---|---|
| Map directory groups to Mattermost groups | Any organization that already manages access through AD or LDAP groups and wants one source of truth | Admins create a Mattermost group from each directory group they select, then manage membership in the directory rather than in the console; confirm exact console labels in the docs for your version | Users join or leave groups automatically when their directory membership changes, so onboarding and offboarding follow HR-driven directory updates |
| Sync groups to team membership | Departmental or business-unit teams where everyone in a directory group should see the same team channels | Admins choose which team the synced group populates and check that the team's default channels suit the whole group; confirm how the sync handles removals | Members are added to the team on sync, and removal from the directory group removes team access, which can surprise people who expected to keep history access |
| Sync groups to private channel membership | Project, incident or confidential work where access should follow a narrower group than the whole team | Admins map one directory group per private channel and review channel membership against the group's purpose; confirm whether sync can be applied to existing channels in your version | Users see only the private channels their directory groups grant, and a directory change removes access to those channels without a manual request |
| Map groups to roles | Organizations that give system or team administrators rights based on directory membership | Admins limit role-bearing groups to a small, named set and audit them on a schedule; confirm which roles the group sync can assign in your version | Users gain or lose administrative capabilities when group membership changes, so role changes should be communicated and reviewed |
| Use nested groups | Directories where departments contain sub-groups, such as regional or functional groups inside a department | Admins must confirm that the nesting depth and the group chain are resolved as expected and test with a small pilot group before wide rollout; confirm the documented behavior for your version | Users in a child group inherit membership from parent structures, which can grant access they did not expect if the directory hierarchy is loose |
| Keep flat groups only | Smaller deployments or teams where directory structure is simple and nested access would add review overhead | Admins maintain fewer mappings and find membership sources easily, but may need additional groups to model cross-cutting access | Users see a predictable set of teams and channels that match a single directory group each |
How Mattermost maps AD/LDAP groups to teams, channels and roles
The sync model has four steps, and each one is a decision you make before go-live. First, you select directory groups and have Mattermost create a matching Mattermost group for each one. Second, you link that Mattermost group to one or more teams or private channels, so the group becomes the thing that grants access. Third, membership is read from the directory at each sync, so additions and removals in Active Directory or LDAP flow into Mattermost without an administrator editing channels by hand. Fourth, groups can be mapped to roles, which is where you decide who administers a team or channel. Plan the mapping as a table with one row per directory group, the Mattermost objects it creates or feeds, and the role it grants, and have the directory owners review that table before anything syncs.
Nested groups need the most care because the directory and Mattermost may not agree on who is a member. A group that contains other groups can pull in users several levels down, and the depth at which your directory resolves membership is not the same thing as what you see in the Mattermost interface. Do not assume how a nested structure resolves. Build a representative nested layout in a staging server that mirrors your directory structure, run a sync, and check the resulting membership of a few users in each team and private channel. Confirm whether a user who belongs to a child group gets access through the parent, and record the result so the directory team knows which nesting patterns are safe to use.
Offboarding follows from the same model. A user who is removed from the directory group loses the access that group granted once the next sync runs, so the directory process is your offboarding process for Mattermost. This only works if disabled accounts and group removals are handled consistently in the directory, which is an operational question for your identity team rather than a Mattermost setting you can assume. Ask the vendor and test in staging how removals are applied on each sync cycle, including whether a removed user's team and channel membership is dropped immediately, at the next cycle, or only when the account is deactivated. The same test should cover role changes: confirm whether a demoted group member loses channel administration on the next sync, and whether manual changes made inside Mattermost are overwritten.
Licensing shapes the design. AD/LDAP groups are documented as available on the Entry, Enterprise and Enterprise Advanced plans but not on Professional, while AD/LDAP user sync is listed on the pricing page from the Professional plan. These are different features, so confirm with Mattermost which capability your plan includes before you design around group mapping. Your quote should state the plan that covers group sync, and your scope should name the directory groups, team and channel mappings, and the staging test cases that must pass before production use.
Setting up group sync in a staging server before production
This sequence proves that directory groups can drive Mattermost team and private channel membership and roles on a staging server before any change reaches production. It ends with a mapping record your access reviewers can keep. Work through each step in order and do not move on until its check passes.
Confirm the plan includes AD/LDAP groups
A system administrator checks the license on the staging server before changing any configuration. Mattermost's AD/LDAP groups documentation lists this feature on the Entry, Enterprise and Enterprise Advanced plans, and not on Professional. Professional includes AD/LDAP user sync, so a Professional customer can sync users but cannot build team and channel membership from directory groups. Confirm that the production license matches the staging license. Check: the group sync options appear in the admin console and the license tier matches what the contract covers.
Verify the directory connection with a test user
The directory administrator creates a read-only bind account and stores its password in your secrets manager. The Mattermost administrator enters the connection settings on staging and runs the built-in connection test. Then sign in with one test user and confirm that the username, email and other mapped attributes match the directory record. Confirm the exact attribute names and filters for your version in the AD/LDAP documentation, because they depend on your directory schema. Check: the connection test passes and the test user's profile shows the expected attributes.
Select the directory groups for teams and channels
The team owner and the directory owner agree on the groups that will map to teams and private channels. Choose groups that have a named owner, a clear purpose and membership that changes through an HR or access request process. Decide now how nested groups will be handled, then test one nested group in step six. List the groups you exclude and the reason for each exclusion. Check: a written list shows each group, its owner, its target team or channel and its intended role, and the team owner has approved it.
Create a test team and private channel
Create one team and one private channel on the staging server only. Name both clearly as test objects so nobody confuses them with production spaces. Do not add any production users or connect these objects to production data. The administrator who creates them becomes the only member at this point. Check: the team exists, the channel is set to private, and the member list contains only the administrators and test accounts you intended to add.
Enable group sync and map roles
In the admin console, enable group sync and link each approved directory group to the test team or private channel. For each link, choose the role that group will receive. Confirm the role options and the behavior when a group is removed or a member leaves the group in the documentation for your version. Save the configuration and note the time it was saved. Check: each mapping appears with its group name, target object and role, and the group sync status shows the link as active.
Run a sync and verify membership
Trigger a sync manually if your version's admin console allows it, or wait for the scheduled run. Confirm the sync interval and the sync log location in the documentation for your version, and do not rely on assumptions about either. Compare the team and channel member lists with the directory group membership, including roles. If you rely on nested groups, confirm that members of nested groups appear. Check: membership and roles match the directory. If anything differs, read the sync log and resolve the cause before continuing.
Test joiner, mover and leaver changes
Make three changes to test accounts in the directory: add a joiner to a mapped group, move a mover from one mapped group to another, and remove a leaver from every mapped group. After each change, run or wait for a sync and check the result in Mattermost. The joiner should gain access, the mover should lose the old access and gain the new access, and the leaver should lose access. Confirm in the documentation how a removed user's account and message history are handled, and compare that with your retention policy. Check: each of the three outcomes matches the directory change.
Record the mapping as an access-review artifact
Document the approved group-to-team and group-to-channel mapping, the role each group receives, the named owner of each group and the Mattermost version tested. Add the results from the membership check and the joiner, mover and leaver tests. Store the record with your other access-review evidence and set a date for the next review. Your auditors or assessors decide what evidence they accept, so confirm the format with them first. Check: a reviewer who has no server access can read the record and see which directory groups grant access to which team or channel, and why.
Security and operations risks in directory-driven membership
Directory-driven membership means the directory decides who sees which Mattermost teams and private channels, so a weak bind account, an over-broad group or a silent sync failure becomes an access problem. The cards below cover the controls and checks that keep sync-driven access accurate, from the bind account and transport security to removals, audit evidence and failure monitoring.
Least-privilege bind account
Mattermost authenticates to the directory with a bind account that it uses to read users and groups. Give it read access only to the containers that hold the users and groups you intend to sync, and no write rights. Confirm in your version's AD/LDAP documentation which search base and filter settings the account needs, and review the account's permissions with your directory team before go-live.
Blast radius of mis-scoped groups
A group that synchronizes into a team or private channel grants access to everything that group's members can reach there. A broad or nested group, such as one that contains a large parent group, can add far more people to a sensitive private channel than intended. Before linking a group, list its effective members, including nested members, and confirm which channels it will populate.
Handling removals and demotions
Sync should reflect offboarding and role changes, but the result depends on how the directory group membership changes and how often sync runs. Test a removal and a role demotion in a staging environment with a test user, and confirm what happens to channel membership, team membership and channel admin roles. Document the expected outcome so reviewers can compare it with observed behavior.
Audit evidence of sync-driven changes
Auditors and security teams often need to know whether a membership change came from directory sync or from a person in Mattermost. Check which audit log entries and system messages the version you run records for group-driven additions and removals, and whether they identify the group as the source. If the evidence is not clear enough for your review process, plan how you will retain and export it.
Protecting LDAP connections with TLS
The bind credentials and directory data travel from Mattermost to the directory server over the network, so the connection must be encrypted and the server certificate must be trusted by the Mattermost host. Confirm the TLS and certificate validation options available in your Mattermost version and the directory setup your environment requires. Test that the connection fails when the certificate is not trusted, rather than assuming it does.
Monitoring sync failures
If sync stops, membership stops changing, and users who should have lost access keep it. Set up monitoring or log review for sync job errors and alert the owners of the directory and Mattermost when a run fails. Also decide how long a failure can go unnoticed before someone reviews access manually, and record that threshold in your operating procedure.
Plan level and high availability trade-offs for directory sync
Before you design Active Directory or LDAP group sync for Mattermost, confirm that your plan includes the group feature, not just user sync. Mattermost documents AD/LDAP groups as available on the Entry, Enterprise and Enterprise Advanced plans, but not on Professional. The Mattermost pricing page, by contrast, lists AD/LDAP user sync as included from the Professional plan. That gap matters. A Professional deployment can sync user accounts from the directory yet have no supported way to map directory groups to teams, private channels or roles. Ask Mattermost sales to confirm in writing which entitlements apply to your seat license, and check them against the AD/LDAP groups documentation for the version you plan to run.
High availability is a second plan-level decision, and it is narrower than many teams expect. Mattermost lists high availability clustering on the Enterprise and Enterprise Advanced plans only. A cluster needs redundant application servers, redundant database servers and redundant load balancers, plus shared file storage on Amazon S3, an S3-compatible service or NAS that is mounted on every node. Local file system storage does not work correctly in a cluster and risks corrupting files. Read replicas and search replicas help with concurrent users and query latency, but writes still go to the primary database. Directory sync that writes membership changes therefore depends on the primary, and adding replicas does not remove that dependency.
The practical consequence is that group sync behavior across cluster nodes and during failover needs to be verified, not assumed. Confirm with Mattermost how the sync job is scheduled and where it runs when more than one application node is active, whether a failover interrupts a sync cycle, and how a partially applied change is recovered. Also ask whether group membership changes are applied at the next sync or require a manual action. If your offboarding process relies on removing a user from a directory group, a missed or delayed sync leaves that person with team or channel access. Plan a test in which you disable a directory account, fail over the primary application node and confirm the removal in Mattermost within the interval you have documented.
Decide early which combination you need. A Professional deployment can run user sync but should not be designed around group-driven membership unless the vendor confirms that capability for your plan. An Enterprise or Enterprise Advanced deployment can combine group sync with a clustered architecture, but it adds shared storage, load balancing and database redundancy that must be built and tested before go-live. Ask for a quote that separates the subscription, the infrastructure for shared storage and the failover testing, because each carries a different owner and a different recurring cost. Record the answers in your design document so that the offboarding control, the plan and the cluster design can be audited together.
Limits to confirm before you rely on group sync
Group sync changes who can see and post in your teams and channels, so its behavior has to match your directory design before go-live. The six points below are limits and behaviors to confirm with the Mattermost documentation or the vendor, tested on a non-production server that mirrors your directory.
Supported directory types and versions
Confirm which directory services and versions the Mattermost AD/LDAP group feature supports before you design around them. Active Directory, other LDAP directories and hosted identity services can differ in how they expose group objects, nested membership and attribute names. Ask whether the same support statement covers user sync and group sync, then test the feature against a copy of your live group structure.
Nested group depth and large directory performance
Nested groups let a parent group grant membership through child groups, but you need to know how many levels of nesting Mattermost resolves and how sync time grows as group counts and memberships rise. Ask the vendor for the supported depth and any guidance for large directories. Measure sync duration and directory load on staging against your largest organizational unit before you set a production sync schedule.
Behavior for users with no matching group
Decide what happens to an account that signs in successfully but belongs to no synced group. Confirm whether Mattermost creates the user, leaves the user without team or channel membership, or applies a default, and whether that account can see any content. This affects contractors, new hires whose group assignment lags HR changes and accounts left behind after a role change. Write the expected result into your onboarding and offboarding runbook.
Team and private channel role assignment
Confirm how group sync assigns team and private channel membership and roles, including which role a synced user receives when a directory group maps to a team or channel. Ask whether a role changed by a team or channel admin in Mattermost is overwritten at the next sync, and whether removing a user from a directory group also removes that user from the channel. Test one manual change and one sync run in a sandbox to see the result.
Seat consumption from synced users
Synced users consume seat licenses on your Mattermost subscription, so group sync can raise seat counts when directory groups grow or when broad groups map to many teams. Confirm how deactivated or removed directory accounts are counted and whether group-driven team membership changes license use on its own. Mattermost sells plans as prepaid annual subscriptions based on seat licenses, so ask sales to model seats against your directory before you set the sync scope.
Mattermost version and plan in use
Group sync behavior depends on the server release and the plan you run. Record your exact server version and check its release date and support end date, because monthly releases and Extended Support Releases have different support lengths. Confirm that AD/LDAP groups are included in your plan, since the documentation lists them on the Entry, Enterprise and Enterprise Advanced plans but not on Professional. Plan upgrades so that sync testing happens on the release you will run.
Questions buyers ask before enabling Mattermost group sync
How much does Mattermost group sync cost to set up?
The subscription is the recurring cost, and the services are the one-time cost. Mattermost sells Professional, Enterprise and Enterprise Advanced as prepaid annual subscriptions priced by seat licenses, and its pricing page lists no public prices, so you will need to contact sales for a figure. AD/LDAP group sync is available on Entry, Enterprise and Enterprise Advanced, so the plan you license sets the subscription level before any services are scoped. On the services side, the main drivers are the number of directory groups to map, how many teams and private channels they control, nested group depth, whether you run a high availability cluster (available only on Enterprise and Enterprise Advanced), and how much testing your change process requires. Ask any partner for a written scope that lists each driver, what is delivered and what is excluded, and build the quote from that scope.
How long does a Mattermost AD/LDAP group sync rollout take?
No duration is given here because the timeline depends on a scoped plan built around your directory. The biggest factors are how many groups map to teams and channels, how deep your nested groups go, how clean the existing directory structure is, and whether a high availability cluster or a separate test environment must be built first. Approval cycles matter too, since access owners must confirm who lands in which team and channel, and production change windows can set the pace. Ask for a written plan with phases, the points where your team must act, and the test exit criteria for each phase. A fixed-scope engagement lets you compare that plan with your own internal estimate on equal terms.
What access and inputs does my team need to provide?
Plan on providing four things before work starts. First, read access to the directory, usually through a bind account with the minimum rights needed to read the groups, users and nested memberships in scope, approved by your directory team. Second, a group design owner who decides which directory groups map to which teams, private channels and roles, since these mapping decisions drive most of the testing. Third, a test environment with a Mattermost server on the same licensed plan and a copy of the relevant directory groups or a dedicated test organizational unit, so changes can be checked before production. Fourth, named access owners for each team and private channel who confirm membership lists and approve exceptions. Ask the written scope to state who provides each item and by when.
Can our internal team enable Mattermost group sync alone?
Often yes, if your team already administers Mattermost, owns the directory and works with a group model that is small and well organized. Your team can read the Mattermost AD/LDAP groups documentation, configure the connection, map a few groups and test them. Specialist help tends to matter when the group count and nesting are large, when the directory has legacy attributes, when you run high availability (which requires shared file storage mounted on each node), when access owners disagree on the design, or when changes must produce audit evidence. A useful test is whether someone on your team can explain the membership result for a sample user along every nested path. Ask a partner to scope only the parts your team cannot cover in-house.
How does Mattermost handle nested AD or LDAP groups?
Mattermost documents support for nested groups in its AD/LDAP groups guide, so nested membership can be part of your mapping. Confirm the exact resolution rules and depth behavior for your server version before you design around them. Test with a sample user several levels deep and check whether the resulting team or channel membership matches what the directory shows. Nested structures often cause surprises: a group created for one purpose can grant access somewhere else, and large trees multiply the memberships your access owners must review. Decide early whether to map top-level groups, leaf groups or a deliberately flattened set, and record that choice with the access owners. Confirm the behavior in a test environment before anything reaches production.
What happens to access when a user leaves a synced group?
When a user is removed from a mapped directory group, Mattermost should remove the matching team or private channel membership on a later group sync. Confirm the exact behavior for your version, including whether roles, private channel access and posted content are handled the same way. Disabling the directory account is a separate control, so check how a deactivated user is handled in Mattermost as well. Also confirm the sync schedule and how long a change takes to reach users, because that interval defines your offboarding exposure window. Ask your access owners which memberships must be removed immediately and which can wait for review, then test a removal with a sample user in the test environment before relying on it for leavers.
Does AD/LDAP group sync work on the Professional plan?
No. Mattermost's AD/LDAP groups documentation lists these groups on Entry, Enterprise and Enterprise Advanced plans, but not on Professional. The Mattermost pricing page places AD/LDAP user sync in the Professional plan, so a Professional subscription can sync users but cannot drive team and private channel membership from directory groups. If your onboarding depends on groups, confirm the plan before buying, because subscriptions are priced by seat and a plan change alters the total subscription cost. Ask the vendor to confirm current plan contents in writing, since entitlements can change between releases. Record the plan decision in your written scope so the services quote matches the platform you actually license.
How DeployOpen scopes and delivers Mattermost group sync
DeployOpen plans and implements Mattermost AD/LDAP group synchronization inside your own infrastructure, so team and private channel membership follows your directory groups. Engagements are fixed-scope, with the group mapping, testing and handover agreed in writing before work starts.
How we scope
- Inventory which directory groups should map to Mattermost teams, private channels and roles.
- Confirm your Mattermost plan supports AD/LDAP groups, since Professional does not include them.
- Record how nested groups should flatten into team and channel membership before any build.
- Agree the written scope, deliverables and timeline with you before any configuration begins.
How we build
- Configure the directory connection and group filters in a non-production Mattermost instance first.
- Map each synchronized group to a team or private channel with the role it should receive.
- Test onboarding, role changes and offboarding with sample accounts that mirror your directory structure.
- Review how removed or disabled directory accounts lose access, and document the expected behavior.
How we hand over
- Document the group-to-team and group-to-channel mapping so your administrators can audit it.
- Provide runbooks for adding groups, changing nested membership and troubleshooting failed syncs.
- Walk your identity and platform teams through the test results and open decisions.
- Deliver configuration and test evidence in a form your compliance and security reviewers can examine.
How we support
- Offer ongoing support, upgrades and testing as a retainer after the initial handover.
- Plan regression checks of group sync whenever you move to a new Mattermost server release.
- Review directory group changes with your identity team when reorganizations or new projects occur.
- Confirm retainer scope, response expectations and upgrade handling in writing before starting.
