snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/main/administration-guide/onboard/ad-ldap-groups-synchronization.mdx

@@ -0,0 +1,357 @@
+---
+title: "AD/LDAP groups"
+---
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+<PlanAvailability slug="entry-ent" />
+
+## Overview
+
+The groups feature is useful for organizations that have many new users to onboard or that onboard users frequently and want to ensure users are added to default teams and channels that are pertinent to them. The group feature currently supports:
+
+- Creating groups by synchronization with your AD/LDAP system groups.
+- Syncing groups to pre-defined roles in Mattermost.
+- AD/LDAP nested groups.
+- Using synchronized groups to manage [membership of teams and Private channels](/administration-guide/onboard/ad-ldap-groups-synchronization#synchronize-teams-and-channels).
+
+For a technical overview of the feature by Martin Kraft, who led the development of the feature, please see [this blog post](https://developers.mattermost.com/blog/ldap-nested-groups-modelling-and-representation-in-code).
+
+You can also watch a video overview about adding users to Mattermost with AD/LDAP on [YouTube](https://www.youtube.com/watch?v=zyku2ibsG0M).
+
+<div style={{position: 'relative', paddingBottom: '50%', height: '0', overflow: 'hidden', maxWidth: '100%', height: 'auto'}}>
+   <iframe src="https://www.youtube.com/embed/zyku2ibsG0M" alt="Video about adding users to Mattermost using AD/LDAP" frameborder="0" allowfullscreen style={{position: 'absolute', top: '0', left: '0', width: '100%', height: '95%'}}></iframe>
+</div>
+
+## Pre-installation notes
+
+If you have enabled synchronization with AD/LDAP, all groups matching the default filter `(|(objectClass=group)(objectClass=groupOfNames)(objectClass=groupOfUniqueNames))` will be available to be linked in the groups list view at **System Console \> User Management \> Groups**.
+
+The group filter is an optional configuration setting available in the **User Filters** section of the AD/LDAP wizard (**System Console \> Authentication \> AD/LDAP**) and allows you to specify the groups that should have access in Mattermost. The **Group** filter is independent of the **User** filter; however, it does leverage the Base DN attribute. You may need to adjust your Base DN to ensure group objects can be searched in your AD/LDAP tree.
+
+The synchronization of groups happens with the synchronization of users, during which Mattermost queries AD/LDAP for updated account information. Please see the [Active Directory/LDAP Set up documentation](/administration-guide/onboard/ad-ldap). for more information. The group feature has no effect on users' authentication to Mattermost.
+
+## Enable AD/LDAP group synchronization
+
+To enable this feature, go to **System Console \> User Management \> Groups**.
+
+## Synchronize AD/LDAP groups to Mattermost
+
+To synchronize specific AD/LDAP groups to Mattermost, specify the `Group ID Attribute` and the `Group Display Name Attribute` (e.g., "cn" for Common Name) in the **Group Synchronization** section of the AD/LDAP wizard (**System Console \> Authentication \> AD/LDAP**).
+
+Additionally, you can specify the **Group** filter used to retrieve groups. If the **Group** filter configuration is left blank, then all groups matching the default filter `(|(objectClass=group)(objectClass=groupOfNames)(objectClass=groupOfUniqueNames))` are returned. Attribute values for **Group ID** and **Group Display Name** are case-sensitive.
+
+![Specify the group filter in the System Console by going to Authentication \> AD/LDAP.](/images/Group_filter.png)
+
+Group synchronization occurs after user synchronization and results for group synchronization are available on the synchonization status table (located at the bottom of the **AD/LDAP** configuration page). After the AD/LDAP groups have been synchronized, go to **System Console \> User Management \> Groups** to link and configure Mattermost groups.
+
+<Note>
+
+The synchronization process doesn't create Mattermost groups. Mattermost groups are created when you “link” the AD/LDAP group as outlined in the next section **Linking AD/LDAP groups to Mattermost groups**. Existing AD/LDAP users are added to the Mattermost groups on the next synchronization and new users are added on their first login.
+
+</Note>
+
+On subsequent synchronizations and once groups are linked:
+
+> - Users that have been added to an AD/LDAP group will be added to the linked Mattermost group and to teams and channels configured for that group.
+> - Mattermost groups that are linked to AD/LDAP groups no longer included in your filter are deleted.
+> - Users removed from an AD/LDAP group are removed from the linked Mattermost group, but their channel and team membership is only revoked when the channel or team is synchronized to an AD/LDAP group.
+
+![image](/images/Group_Group_Member_Sync.png)
+
+## Link AD/LDAP groups to Mattermost groups
+
+Groups that have been returned from the default filter or your AD/LDAP group filter will be available in a list view on the Groups page. The link action will create Mattermost groups corresponding to the AD/LDAP group. AD/LDAP groups linked to a Mattermost group will display the **Linked** icon. AD/LDAP groups that have not been linked to a Mattermost group will display the **Not Linked** icon. An AD/LDAP group that is not linked does not create a Mattermost group.
+
+![image](/images/Groups_listing.png)
+
+You can link groups individually by the inline **Linked** button and use the checkbox next to the group name to select multiple groups and choose **Link Selected Groups**. When selecting multiple groups with a mix of **Linked** and **Not Linked** states, the bulk action of the button will be **Link Selected Groups** until all selected are marked **Linked**. Using the bulk action speeds the process of creating Mattermost groups from your AD/LDAP Groups.
+
+If you see a **Link Failed** message, either select the message, or check the box alongside the group name to expose the inline link message and try again.
+
+![image](/images/LinkFailed.png)
+
+## Configure the linked group
+
+AD/LDAP groups that have been linked to Mattermost groups can be configured to add team and channels. To configure the group, select **Configure \> Group Configuration** and view the group profile which includes the group name. This name is automatically mapped from the AD/LDAP group common name attribute and is read-only.
+
+## Add default teams or channels for the group
+
+To add the teams and channels that you want the group members to default in, select either **Add Team** or **Add Channel** from the **Add Team or Channel** button. You can assign roles to group members using the options provided in the **Assigned Roles** column. Roles are updated on the next scheduled AD/LDAP synchronization.
+
+![image](/images/Group_Configuration.png)
+
+Channels are nested below the team they belong to in the team and channel list. The following table describes the icons available on this page and what they indicate:
+
+<table style={{width: '59%'}}>
+<colgroup>
+<col style={{width: '27%'}} />
+<col style={{width: '31%'}} />
+</colgroup>
+<thead>
+<tr>
+<th><strong>Icon</strong></th>
+<th><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><img src={useBaseUrl('/images/open_team.png')} alt="image" /></td>
+<td>Team is open for anyone to join.</td>
+</tr>
+<tr>
+<td><img src={useBaseUrl('/images/private_team.png')} alt="image" /></td>
+<td>Team isn't open for anyone to join.</td>
+</tr>
+<tr>
+<td><img src={useBaseUrl('/images/public_channel.png')} alt="image" /></td>
+<td>Public channel.</td>
+</tr>
+<tr>
+<td><img src={useBaseUrl('/images/private_channel.png')} alt="image" /></td>
+<td>Private channel.</td>
+</tr>
+</tbody>
+</table>
+
+<Note>
+
+- When a team is added, the `Town Square` and `Off-Topic` channels will also be created automatically, as well as any default channels set in the [ExperimentalDefaultChannels config setting](/administration-guide/configure/experimental-configuration-settings#default-channels).
+- When a channel is added without setting the team explicitly, the team will be shown in the **Team and Channel Membership** listing, but it won't be added to the group specifically. Because of this dependency, when the channel is removed, the team will also be removed. Teams are listed in parentheses after the channel name in the channel selector.
+
+</Note>
+
+## Synchronize teams and channels
+
+For new users, default teams and channels will be added when they log in for the first time. For existing users, default teams and channels will be added after the next scheduled AD/LDAP sychronization.
+
+It may take a few seconds to load all team and channel memberships for a user depending on the number of teams and channels the group is defaulted to. In our testing, it took six seconds for an organization with 200,000 users and 30,000 linked groups.
+
+<Note>
+
+Users aren't removed from the team or channel on subsequent synchronizations of the AD/LDAP groups. Users need to be manually removed from the team or channel per the existing functionality. They won't be automatically re-added if they were manually removed or removed themselves. To manage a team or Private channel membership with synchronized groups, please see the section below on **Disable and re-activate AD/LDAP users** for details.
+
+</Note>
+
+![image](/images/Team_Channel_Membership_Sync.png)
+
+## Remove configured teams and channels from a group
+
+To remove a team or channel configured for a group, select **Remove** to the right of the team or channel name. Users already part of the team and channel won't be removed from that channel by this action.
+
+## View users belonging to the group
+
+Users who have logged in and accessed Mattermost will be visible in the members list on the group object. Members are read-only at this time and new members can be added through management in your AD/LDAP system.
+
+![image](/images/Group_Members.png)
+
+Users can be removed from the Mattermost group on subsequent synchronizations. However, they won't be removed from teams and channels unless the team or channel is group-synchronized.
+
+<Note>
+
+When a member removes themselves manually from a channel, that action is tracked in the **Channel Member History** table. If a system admin manually forces all members in a specific LDAP group to join the teams and channels synchronized to that group, members can potentially be re-added to channels from which they were previously removed.
+
+</Note>
+
+## Disable and re-activate AD/LDAP users
+
+If a member is removed from an AD/LDAP group, deactivated in AD/LDAP, or filtered from the AD/LDAP user filter, that member loses access to Mattermost.
+
+From Mattermost v7.7, system admins can add members back to all of the member's default teams and channels in the System Console by going to **User Management \> Users**, selecting the user's role, then selecting the **Re-sync user via LDAP groups** option.
+
+<Tip>
+
+Using the Mattermost API, system admins can manually re-add all group members back into synchronized teams or channels by forcing members in an LDAP group to join the teams and channels synchronized to that group, even if members left on their own, were removed, were filtered out, or were deactivated. See our [Mattermost API documentation](https://api.mattermost.com/#operation/SyncLdap) for details on synchronizing user attribute changes in the configured AD/LDAP server with Mattermost.
+
+</Tip>
+
+## Manage groups
+
+Once a group has been configured, the default teams and channels can be changed via the **Edit** option on the group list view.
+
+## Delete groups
+
+Mattermost groups can be deleted by adjusting your AD/LDAP group filter to remove the group or by unlinking the group on the Groups listing page. If you add the group back by re-adjusting the AD/LDAP group filter and link the group again on the group configuration page, the previous team and channel configurations will be available.
+
+## Use AD/LDAP synchronized groups to manage team or private channel membership
+
+Mattermost groups created with synchronized AD/LDAP groups can be used to manage the membership of private teams and private channels. When a team or private channel is managed by synchronized groups, member users will be added and removed based on their membership to the synchronized AD/LDAP group.
+
+<Note>
+
+It is not possible to add guests to teams and channels that are managed using groups.
+
+</Note>
+
+For instance, you may have an AD/LDAP group that contains your development team that you want to synchronize to a developer team. By using this feature, new developers will get added to the team when they are added to the synchronized AD/LDAP group and they will be removed from the team when removed from the AD/LDAP group.
+
+Similarly, you may have an AD/LDAP group that contains your leadership team that you want to synchronize to a private channel for coordination and updates.
+
+This feature helps control the membership of the channel so that guests and member users outside of the synchronized group are prevented from being added to the channel mistakenly.
+
+On teams that are managed by synchronized groups, guests, and member users outside of the group are restricted from:
+
+> - Invitation through a team invite link.
+> - Invitations through an email invite.
+
+Similarly on private channels that are managed by synchronized groups, guests and member users outside of the group are restricted from:
+
+> - Invitation through a mention.
+> - Invitation through the `/invite` slash command.
+> - Being added to the channel via the **Add Members** menu option.
+
+Users can remove themselves from teams and Private channels managed by synchronized groups.
+
+### Manage membership of a team or channel with synchronized groups
+
+To manage membership of a private team with synchronized groups:
+
+1.  Go to **System Console \> User Management \> Teams**. Select the team you want to manage with group synchronization.
+2.  Under **Team Management**, enable **Sync Group Members**. If **Anyone can join this team** is enabled or if specific email domains are set, they will be disabled by the Sync Group Members feature.
+3.  Add one or more groups to the team. If there are groups already associated with default users in the team, they'll be listed.
+4.  Review the notice in the footer of the screen for any users that are not part of groups who will be removed from the team on the next synchronization.
+5.  Select **Save**. Members will be updated on the next scheduled AD/LDAP synchronization.
+
+Alternatively, you can use the mmctl tools to set the team to be managed by groups:
+
+1.  Ensure there is at least one group already associated to the team. You can view and add default teams to a group via **System Console \> User Management \> Groups \> Group Configuration**. Please see more information on adding default teams and channels [here](/administration-guide/onboard/ad-ldap-groups-synchronization#add-default-teams-or-channels-for-the-group). Additionally, you can use the mmctl to confirm if there is already a group associated to the team by running the [mmctl group team list](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-team-list) command.
+2.  Ensure **Team Settings \> General \> Allow any user with an account on this server to join this team** is set to **No**.
+3.  Convert the team to have its membership managed by synchronized groups by running the [mmctl group team enable](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-team-enable) command.
+
+To manage membership of a private channel with synchronized groups:
+
+1.  Go to **System Console \> User Management \> Channels**. Select the channel you want to manage with group synchronization.
+2.  Under **Channel Management**, enable **Sync Group Members**. Please ensure the channel is set to **private**.
+3.  Add one or more groups to the channel. If there are groups already associated with default users in the team, they'll be listed.
+4.  Review the notice in the footer of the screen for any users that are not part of groups who will be removed from the channel on the next synchronization.
+5.  Select **Save**.
+
+Members will be updated on the next scheduled AD/LDAP synchronization. Alternatively, you can use the mmctl to set a private channel to be managed by groups:
+
+1.  Ensure there is at least one group already associated to the channel. You can view and add default channels to a group via **System Console \> User Management \> Groups \> Group Configuration**. Please see more information on adding default teams and channels [here](/administration-guide/onboard/ad-ldap-groups-synchronization#add-default-teams-or-channels-for-the-group). Additionally, you can use the mmctl to view if there is already a group associated to the channel by running the [mmctl group channel list](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-channel-list) command.
+2.  Convert the team to have its membership managed by synchronized groups by running the [mmctl group channel enable](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-channel-enable) command.
+
+### Assign roles to group members
+
+Group members can be assigned predefined roles by system admins, which are applied across the group during the scheduled sychronization. The roles are:
+
+- Member (default)
+- Team admin (in teams)
+- Channel admin (in channels)
+
+The permissions for each role can be viewed and modified in **System Console \> Permissions**.
+
+**To set the Team admin role in a synced group**
+
+1.  Go to **System Console \> User Management \> Teams**.
+2.  Select **Edit** next to the team you want to configure.
+3.  Ensure that **Sync Group Members** is enabled.
+4.  Choose **Add Group** to add one or more groups to the team. If there are groups already associated to default users into the team, they will already be present.
+5.  Select the arrow next to the current role in the **Roles** column to display and select the **Team Admin** option.
+6.  Repeat as needed for any other synced groups you have added.
+7.  Select **Save**.
+
+Roles are updated on the next scheduled AD/LDAP synchronization.
+
+**To set the Channel Admin role in a synced group**
+
+1.  Go to **System Console \> User Management \> Channels**.
+2.  Select **Edit** next to the team you want to configure.
+3.  Ensure that **Sync Group Members** is enabled.
+4.  Choose **Add Group** to add one or more groups to the team. If there are groups already associated with default users in the team, they'll be listed.
+5.  Select the arrow next to the current role in the **Roles** column to display and select the **Channel Admin** option.
+6.  Repeat as needed for any other synced groups you have added.
+7.  Select **Save**.
+
+Roles are updated on the next scheduled AD/LDAP synchronization.
+
+<Note>
+
+Members who have been synced as part of a group cannot have their role changed via **View Members** in Mattermost.
+
+</Note>
+
+### Add or remove groups from teams
+
+Once team management is converted to use synchronized groups, team admins and system admins can add additional groups from **Main Menu \> Add Groups to Team**. This will add users to the next AD/LDAP synchronization, and any new users to the group will be added to the team on subsequent synchronizations. Team admins will be prevented from converting the team to a public space by enabling **Team Settings \> Allow any user with an account on this server to join this team**.
+
+Team admins and system admins can also remove groups from a team from **Main Menu \> Manage Groups**. This will disassociate the group from the team. Users are removed on the next AD/LDAP synchronization.
+
+The system admin can remove groups from **System Console \> User Management \> Teams \> Team Configuration \> Synced Groups**.
+
+### Add or remove groups from private channels
+
+Once the management of the channel is converted to be managed by synchronized groups, team admins and system admins can add additional groups from **Channel Menu \> Add Groups to Channel**. This will add users on the next AD/LDAP synchronization and any new users to the group will be added to the channel on subsequent synchronizations.
+
+Team admins and system admins can also remove groups from a team from **Main Menu \> Manage Groups**. This will disassociate the group from the team. Users are removed on the next AD/LDAP synchronization.
+
+The system admin can remove groups from **System Console \> User Management \> Channels \> Channel Configuration \> Synced Groups**.
+
+### Manage members
+
+Users are automatically removed from the team or private channel when removed from a synchronized AD/LDAP group that is managing the membership of that team or channel. Additionally, users who are not in the synchronized groups are prevented from being added through the `/invite` and mention flows within a channel.
+
+A user can remove themselves from the team or from the private channel when it is managed by synchronized groups. They can be added back by users who have permission to manage members for a team or private channel by using the `/invite` slash command or by mentioning the user in a channel.
+
+If the user is removed from a synchronized group and later re-added to the group, they can be manually added back to the team or Private channel as noted above.
+
+<Note>
+
+Users won't be added back by the AD/LDAP synchronization automatically once they remove themselves or are removed by the LDAP synchronized group.
+
+</Note>
+
+### Disable group-synchronized management of teams and private channels
+
+To remove the management of members by synchronized groups in a team, disable **Sync Group Members** under **System Console \> User Management \> Teams \> Team Management**. Alternatively, you can also run the [mmctl group team disable](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-team-disable) command.
+
+To remove the management of members by synchronized groups in a channel, disable **Sync Group Members** under **System Console \> User Management \> Channels \> Channel Management**. Alternatively, you can also run the [mmctl group channel disable](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-channel-disable) command.
+
+## Frequently asked questions
+
+### Why do my LDAP users and groups exist in Mattermost, but my groups have no members?
+
+In order for Mattermost to detect group membership correctly, and to automatically add users to the group configured in the System Console, you must use one of the following AD/LDAP attributes to represent group members in Mattermost: `member` or `uniqueMember`. These attributes use a `Distinguished Name` as the value on groups.
+
+<Note>
+
+LDAP installations that use `memberUid` to indicate group membership are not supported because `memberUid` is an attribute of an object class `posixGroup` that does not use `Distinguished Names` as the value on groups.
+
+</Note>
+
+### Why can't my existing users see the teams and channels they have been synced to?
+
+Existing Mattermost users that are members of linked Mattermost groups will be added to teams and channels on the next scheduled synchronization job that is run after teams and channels are added to the Mattermost group. You can manually initiate a synchronization from the **Sync History** section of the AD/LDAP wizard (**System Console \> Authentication \> AD/LDAP \> AD/LDAP Synchronize Now**).
+
+### How do nested groups work with AD/LDAP Group Sync?
+
+Users within nested groups are included as members of parent groups. The group filter that you specify can include any type of AD/LDAP group on your system. The `member` AD/LDAP attribute is used to determine nested groups that belong to a parent group.
+
+### How do I manage a team or private channel membership with synchronized groups?
+
+You can do this by setting the team or channel management to synced groups instead defaulting a group to a team or channel. See the section above on synchronizing teams and channels to learn more.
+
+### How do I use AD/LDAP group sync with SAML?
+
+You can use AD/LDAP group sync with SAML by enabling [SAML Synchronization with AD/LDAP](/administration-guide/onboard/sso-saml-okta#configure-saml-synchronization-with-ad-ldap). You do not need to enable sign-in with LDAP for this feature to work.
+
+However, it's critical that the unique Mattermost ID identifier that you have chosen as your attribute in your directory service (AD/LDAP) is the same for both the SAML and AD/LDAP configurations.
+
+For instance, if `ObjectGUID` has been chosen as the Mattermost ID in your AD/LDAP configuration, then an attribute that has the same value should also be mapped to the ID attribute in your SAML assertion. We also recommend that the ID attribute you select is unique and unchanging (such as a `GUID`).
+
+### Why aren’t public channels supported with synchronized groups?
+
+Public channels are available to all members to discover and join. Managing membership with synchronized groups removes the ability for Public channels to be accessible to users on the team. Private channels typically require more controlled membership management, which is why this feature applies to Private channels. Groups can be assigned to public teams and public channels as described in [this documentation](/administration-guide/onboard/ad-ldap-groups-synchronization#add-default-teams-or-channels-for-the-group).
+
+### Does a team with its membership managed by groups have any effect on public channel access?
+
+Only users that are members of groups synchronized to team are able to discover and join public channels. Private channels can also be managed by synchronized groups when a team is managed by synchronized groups.
+
+### Why don't users get readded to teams or channels once they have been removed from and then later re-added to the LDAP group?
+
+The implementation of group removals does not currently differentiate between users who have removed themselves or have been removed by the LDAP synchronization process. Our design optimizes for users who have removed themselves from a team or channel. In the future, we may add the ability for Admins to re-add users who have been removed and even prevent users from leaving a team or channel.
+
+Additionally, LDAP users who are not accessible to Mattermost based on filters will be removed from the groups and from group synced teams and channels. If they were removed from teams and channels then they would not be re-added to those teams and channels upon becoming subsequently reaccessible to Mattermost.
+
+### How can I use LDAP attributes or Groups with OpenID?
+
+At this time, LDAP data isn't compatible with OpenID. If you currently rely on LDAP to manage your users' teams, channels, groups, or attributes, you won't be able to do this automatically with users who have logged in with OpenID. If you need LDAP synced to each user, we suggest using SAML or LDAP as the login provider. Some OpenID providers can use SAML instead, like Keycloak.

docs/main/administration-guide/onboard/ad-ldap.mdx

@@ -0,0 +1,329 @@
+---
+title: "AD/LDAP setup"
+---
+<PlanAvailability slug="all-commercial" />
+
+## Overview
+
+Mattermost offers “Same Sign-On” with Microsoft AD/LDAP (formerly known as Active Directory/LDAP). Enable the same credentials used in on-prem AD/LDAP deployments to be reused in Mattermost, with optional [multi-factor authentication](/administration-guide/onboard/multi-factor-authentication).
+
+AD/LDAP is a service that stores authentication and authorization details of users on your organization's network. When you integrate your AD/LDAP system with Mattermost, users can log into Mattermost without having to create new credentials. User accounts are managed in AD/LDAP, and changes are synchronized with Mattermost.
+
+Mattermost provides a step-by-step AD/LDAP setup wizard in the System Console that guides you through the configuration process with sections and incremental testing to ensure each part of your setup works correctly before proceeding to the next step.
+
+Benefits of integrating AD/LDAP with Mattermost include:
+
+- **Single sign-on.** Users can log in to Mattermost with their AD/LDAP credentials.
+- **Centralized identity management.** Mattermost accounts can display user information from AD/LDAP, such as first and last name, email, and username.
+- **Automatic account provisioning.** A Mattermost user account is automatically created the first time a user signs in with their AD/LDAP credentials.
+- **Sync groups to predefined roles in Mattermost.** Assign team and channel roles to groups via AD/LDAP Group Sync.
+- **Compliance alignment with administrator management.** Manage Administrator access to Mattermost in the System Console using AD/LDAP filters.
+
+## Pre-installation notes
+
+If you're using AD/LDAP with **nested security groups** you need to write a PowerShell script, or similar, to flatten and aggregate the tree into a single security group to map into Mattermost.
+
+We strongly recommend the following as you prepare to set up AD/LDAP:
+
+Attribute Naming and Case Sensitivity:
+
+- Attribute names in both AD/LDAP and Mattermost configurations are **case-sensitive**.
+- Ensure that the attribute names in the AD/LDAP claim rules **exactly match** the expected attribute names in Mattermost. Case deviations will result in issues.
+
+Essential attributes:
+
+- The `NameID` element is required for user identification in SAML assertions.
+- All required attributes (e.g., `Email`, `Username`, `FirstName`, and `LastName`) must be included and correctly mapped.
+
+How to choose a stable unique identifier for `NameID`:
+
+- Using a stable and unique identifier (`EmployeeID` or `ObjectGUID`) for the `NameID` helps prevent issues in cases where user details could change over time (e.g., `LastName` or `Email`).
+- If stable, unique attributes aren't available in AD, using attributes that might change over time can result in future issues.
+
+## Getting started
+
+There are two ways to set up AD/LDAP:
+
+1.  **Configure AD/LDAP using the System Console setup wizard**
+
+> - Log in to your workspace and create a new account using email and password. This is assigned the system admin role as the first user created.
+> - Next, use the AD/LDAP setup wizard to configure AD/LDAP step-by-step, testing each section as you go, and then convert your system admin account to use the AD/LDAP login method.
+
+2.  **Configure AD/LDAP by editing \`\`config.json\`\`**
+
+> - Edit `config.json` to enable AD/LDAP based on the [AD/LDAP settings documentation](/administration-guide/configure/authentication-configuration-settings#adldap). When you log in to Mattermost the first user to log in with valid AD/LDAP credentials will be assigned the system admin role.
+
+## Configure AD/LDAP login
+
+1.  **Create a system admin account using email authentication.**
+
+> - Create a new workspace and create an account using email and password, which is automatically assigned the **system admin** role since it is the first account created. You may also assign the role to another account.
+
+2.  **Configure AD/LDAP using the setup wizard.**
+
+> - Go to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP setup wizard. The wizard is organized into sections that you can navigate through using the sidebar:
+>   - **Connection Settings**: Configure server connection details
+>   - **User Filters**: Set up user identification and filtering
+>   - **Account sync**: Map AD/LDAP attributes to Mattermost user fields
+>   - **Group Synchronization**: Configure group settings and group attributes (if using LDAP groups)
+>   - **Sync Performance**: Adjust synchronization timing and performance settings
+>   - **Sync History**: View synchronization status and manually trigger syncs
+> - Each section includes a test button that allows you to verify your configuration before proceeding to the next step. This incremental testing helps identify and resolve issues early in the setup process.
+
+3.  **Confirm that AD/LDAP sign-on is enabled.**
+
+> - After configuring AD/LDAP through the wizard, confirm that users can log in using AD/LDAP credentials.
+
+4.  **Switch your system admin account from email to AD/LDAP authentication.**
+
+> - Navigate to your profile, and select **Security \> Sign-in Method \> Switch to AD/LDAP** and log in with your AD/LDAP credentials to complete the switch.
+
+5.  **(Optional) Restrict authentication to AD/LDAP.**
+
+> - Go to **System Console \> Authentication \> Email** and set **Enable sign-in with email** to **false** and **Enable sign-in with username** to **false**.
+> - Then choose **Save** to save the changes. This should leave AD/LDAP as the only login option.
+
+6.  **(Optional) If you configured \`First Name Attribute\` and \`Last Name Attribute\` in the System Console.**
+
+> - Navigate to **System Console \> Site Configuration \> Users and Teams** and set **Teammate Name Display** to **Show first and last name**. This is recommended for a better user experience.
+
+<Note>
+
+If you've made a mistake and lock yourself out of the system somehow, you can set an existing account to system admin using the [mmctl roles](/administration-guide/manage/mmctl-command-line-tool#mmctl-roles) command.
+
+</Note>
+
+## Configure AD/LDAP synchronization
+
+<PlanAvailability slug="entry-ent" />
+
+In addition to configuring AD/LDAP sign-in, you can also configure AD/LDAP synchronization. When synchronizing, Mattermost queries AD/LDAP for relevant account information and updates Mattermost accounts based on changes to attributes (first name, last name, and nickname). When accounts are disabled in AD/LDAP users are deactivated in Mattermost, and their active sessions are revoked once Mattermost synchronizes the updated attributes.
+
+The AD/LDAP synchronization depends on email. Make sure all users on your AD/LDAP server have an email address, or ensure their account is deactivated in Mattermost.
+
+When Mattermost is configured to use AD/LDAP for user authentication, the following user attribute changes can't be made through the API: first name, last name, position, nickname, email, profile picture, or username. LDAP must be the authoritative source for these user attributes.
+
+To configure AD/LDAP synchronization with AD/LDAP sign-in:
+
+1.  Go to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP wizard and navigate to the **Connection Settings** section. Set **Enable Synchronization with AD/LDAP** to **true**.
+2.  Navigate to the **Sync Performance** section and configure the **Synchronization Interval (minutes)** to specify how often Mattermost accounts synchronize attributes with AD/LDAP. The default setting is 60 minutes.
+
+<Note>
+
+- The profile picture attribute is only synchronized when the user logs in.
+- From Mattermost v11, if a profile picture in AD/LDAP is removed, the next time the user logs in, their Mattermost profile picture is also removed and returns to the default image.
+- Additionally, after configuring profile pictures in AD/LDAP configuration, all AD/LDAP user accounts in Mattermost will synchronize to use the profile picture from AD/LDAP on their next login.
+- If you want to synchronize immediately after disabling an account, use the **AD/LDAP Synchronize Now** button in the **Sync History** section of the wizard.
+- To configure AD/LDAP synchronization with SAML sign-in, see the [SAML documentation](/administration-guide/onboard/sso-saml).
+
+</Note>
+
+<Note>
+
+- Ensure at least one AD/LDAP user is in Mattermost or the sync won't complete.
+- 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 [delegated granular administration](/administration-guide/onboard/delegated-granular-administration#edit-privileges-of-admin-roles-advanced)) documentation for details.
+
+</Note>
+
+3.  From Mattermost v10.9, you can configure Mattermost to automatically [re-add members of an LDAP group to group-synchronized teams or channels](/administration-guide/configure/authentication-configuration-settings#re-add-removed-members-on-sync) during LDAP synchronization, even if those members were previously removed. This option enables you to maintain uninterrupted collaboration and address specific organizational needs, ensuring users who were unintentionally removed due to changes in LDAP group membership, synchronization errors, or exceptions to the standard group sync rules can be seamlessly restored.
+
+> <div class="note">
+>
+> <div class="title">
+>
+> Note
+>
+> </div>
+>
+> The [mmctl ldap sync](/administration-guide/manage/mmctl-command-line-tool#mmctl-ldap-sync) command takes precedence over this server configuration setting. If you have this setting disabled, and run the mmctl command with the `--include-removed-members` flag, removed members will be re-added during LDAP synchronization.
+>
+> </div>
+
+## Configure AD/LDAP sign-in using filters
+
+Using filters assigns roles to specified users on login. To access AD/LDAP filter settings, navigate to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP wizard and go to the **User Filters** section.
+
+### User filter
+
+(Optional) Enter an AD/LDAP filter to use when searching for user objects. Only the users selected by the query will be able to access Mattermost. For AD/LDAP, the query to filter out disabled users is `(&(objectCategory=Person)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`.
+
+1.  Navigate to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP wizard.
+2.  Go to the **User Filters** section and complete the **User Filter** field.
+3.  Use the **Test Filters** button to verify your filter works correctly.
+4.  Choose **Save**.
+
+When the user accesses Mattermost, they log in with same username and password that they use for organizational logins.
+
+Filters can also be used for excluding users who belong to certain groups. For AD/LDAP, the query to filter out groups is `(&(memberof=cn=ACME_ALL,ou=Users,dc=sademo,dc=com)(!(memberof=cn=DEV_OPS,ou=Users,dc=sademo,dc=com)))`.
+
+### Guest filter
+
+(Optional) When enabled, the Guest Filter in Mattermost identifies external users whose AD/LDAP role is guest and who are invited to join your Mattermost workspace. These users will have the Guest role applied immediately upon first login instead of the default member user role. This eliminates having to manually assign the role in the System Console.
+
+If this filter is removed/changed, active guests will not be promoted to a member and will retain their Guest role. Guests can be promoted in **System Console \> User Management**.
+
+1.  Navigate to **System Console \> Authentication \> Guest Access** and set Guest Access to `true`.
+2.  Navigate to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP wizard.
+3.  Go to the **User Filters** section and expand **Configure additional filters**.
+4.  Complete the **Guest Filter** field.
+5.  Use the **Test Filters** button to verify your filter works correctly.
+6.  Choose **Save**.
+
+When a guest logs in for the first time they are presented with a default landing page until they are added to channels.
+
+See the [Guest Accounts documentation](/administration-guide/onboard/guest-accounts) for more information about this feature.
+
+### Admin filter
+
+(Optional) Enter an AD/LDAP filter to use for designating system admins. The users selected by the query will have access to your Mattermost workspace as system admins. By default, system admins have complete access to the Mattermost System Console. Existing members that are identified by this attribute will be promoted from member to system admin upon next login.
+
+The next login is based upon Session lengths set in **System Console \> Session Lengths**. It is recommended that users are demoted to members manually in **System Console \> User Management** to ensure access is restricted immediately.
+
+1.  Navigate to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP wizard.
+2.  Go to the **User Filters** section and expand **Configure additional filters**.
+3.  Set **Enable Admin Filter** to **true**.
+4.  Complete the **Admin Filter** field.
+5.  Use the **Test Filters** button to verify your filter works correctly.
+6.  Choose **Save**.
+
+<Note>
+
+If the Admin Filter is set to `false`, the member's role as system admin is retained. However if this filter is removed/changed, system admins that were promoted via this filter will be demoted to members and won't retain access to the System Console.
+
+</Note>
+
+When this filter isn't in use, members can be manually promoted/demoted via **System Console \> User Management**.
+
+<Note>
+
+The Admin Filter is evaluated only when a user signs in with AD/LDAP credentials. It isn't evaluated during scheduled AD/LDAP synchronization, and it doesn't apply to users who authenticate with SAML, even when **Enable Synchronizing SAML Accounts With AD/LDAP** is enabled. To designate system admins for SAML-authenticated users, use the [SAML Admin Attribute](/administration-guide/onboard/sso-saml#admin-attribute) instead.
+
+</Note>
+
+## Configure AD/LDAP deployments with multiple domains
+
+Organizations using multiple domains can integrate with Mattermost using a "Forest" configuration to bring together multiple domains. Please see [Forests as Collections of Domain Controllers that Trust Each Other](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc759073(v=ws.10)?redirectedfrom=MSDN) for more information.
+
+For forest configurations that contain multiple domains which do NOT share a common root, you can search across all of the domains using the Global Catalog. To do so, update your `config.json` as follows:
+
+- Set the LdapPort to 3268 (instead of 389)
+- Set the BaseDN to " " (A single space character)
+
+See [Global Catalog and LDAP Searches](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-2000-server/cc978012(v=technet.10)?redirectedfrom=MSDN) for additional details.
+
+## Troubleshooting/FAQ
+
+The following are frequently asked questions and troubleshooting suggestions on common error messages and issues. It is recommended that you check your logs for errors as they can provide an idea of what the issue is.
+
+### If the **Test Connection** button fails, how can I troubleshoot the connection?
+
+Check that your AD/LDAP connection settings are correct by running an AD/LDAP user query in an external system. See [LDAP Connection Test Example](https://ldaptool.sourceforge.net/). If the AD/LDAP connection is verified to be working outside of Mattermost, try the following:
+
+- Check your AD/LDAP system to verify your `Bind Username` format.
+- Check your **AD/LDAP Port** and **Connection Security** settings in the System Console. (**AD/LDAP Port** set to 389 typically uses **Connection Security** set to `None`. **AD/LDAP Port** set to 636 typically ties to **Connection Security** set to **TLS**).
+- If you're seeing `x509: certificate signed by unknown authority` in your logs, try installing an intermediate SSL certificate or have your LDAP server send the complete certificate chain.
+
+If these options don't work, please [contact our support team](https://mattermost.com/support/).
+
+### When I first set up and synchronize AD/LDAP, are the users automatically created in Mattermost?
+
+No, each user is created on their first login.
+
+### When I try to synchronize AD/LDAP, why does the status show as `Pending` and not complete?
+
+Go to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP wizard, navigate to the **Connection Settings** section, and make sure that the **Enable Synchronization with AD/LDAP** setting is set to **true**.
+
+If the issue persists, try selecting the **Test Filters** button to test that the User Filter is correctly formatted. Refer to this [document](/administration-guide/configure/authentication-configuration-settings#user-filter) for guidance on setting a correct syntax format.
+
+Make sure that you also have at least one AD/LDAP user in Mattermost or the synchronization will not complete.
+
+### What's the difference between the Username Attribute, ID Attribute, and Login ID Attribute?
+
+There are three AD/LDAP attributes that apear to be similar but serve a different purpose:
+
+1.  **Username Attribute:** Used within the Mattermost user interface to identify and mention users. For example, if **Username Attribute** is set to `john.smith`, a user typing `@john` will see `@john.smith` in their autocomplete options and posting a message with `@john.smith` will send a notification to that user that they’ve been mentioned.
+2.  **ID Attribute:** Used as the unique identifier in Mattermost. It should be an AD/LDAP attribute with a value that does not change, such as `ObjectGUID`. If a user's ID attribute changes, it will create a new Mattermost account unassociated with their old one. If you need to change this field after users have already logged in, use the [mattermost ldap idmigrate mmctl tool](/administration-guide/manage/mmctl-command-line-tool#mmctl-ldap-idmigrate).
+3.  **Login ID Attribute:** The attribute in the AD/LDAP server used to log in to Mattermost. Normally this attribute is the same as the **Username Attribute** field above, or another field that users can easily remember.
+
+### How do I deactivate users?
+
+If a user has logged into Mattermost through AD/LDAP or SAML, you can choose how they are deactivated, whether manually or automatically.
+
+There are three main ways to do this:
+
+1.  **User deletion:** If the user is completely removed from the AD/LDAP server, they will be deactivated in Mattermost on the next synchronization.
+2.  **User filter:** Set the [user filter](/administration-guide/configure/authentication-configuration-settings#user-filter) to only select the subset of AD/LDAP users you want to have access to Mattermost. When someone is removed from the selected group, they will be deactivated in Mattermost on the next synchronization.
+3.  **Manually deactivate**: Go to **System Console \> User Management \> Users**, select a user's role, and select **Deactivate**. When you manually deactivate a user, they can reactivate themselves by logging back in.
+
+For AD/LDAP, to filter out deactivated users you must set the user filter to:
+
+`(&(objectCategory=Person)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
+
+Filters can also be used for excluding users who belong to certain groups. For AD/LDAP, the query to filter out groups is:
+
+`(&(memberof=cn=ACME_ALL,ou=Users,dc=sademo,dc=com)`
+
+`(!(memberof=cn=DEV_OPS,ou=Users,dc=sademo,dc=com)))`
+
+When a user is deactivated in Mattermost via options one or two above, all the user's current sessions are revoked and they will be unable to log in or access Mattermost.
+
+### Can I connect to multiple AD/LDAP servers?
+
+There is currently no built-in way to connect to multiple AD/LDAP servers. You will need to connect the instances in a forest before connecting to Mattermost. Consider upvoting the [feature request](https://portal.productboard.com/mattermost/33-what-matters-to-you) on our forum.
+
+### When trying to log in, I see the error `AD/LDAP not available on this server`
+
+This indicates that there is a problem somewhere with your configuration. We recommend that you check your Mattermost configuration settings to ensure that AD/LDAP is enabled, and the settings are correct.
+
+If you're still having issues, you can [contact support](https://mattermost.com/support/) for additional troubleshooting.
+
+### I see the error `User not registered on AD/LDAP server`
+
+This means the query sent back to the AD/LDAP server returned no results. We recommend that you:
+
+1.  Check that the user credentials were entered properly - you should log in with the field set as the [\*ID Attribute\*](/administration-guide/configure/authentication-configuration-settings#id-attribute).
+2.  Check that the user account exists in the AD/LDAP server.
+3.  Check the AD/LDAP configuration settings are correct.
+
+If you're still having issues, you can [contact Mattermost Support](https://mattermost.com/support/) for additional troubleshooting.
+
+### I updated a user account in AD/LDAP, and they can no longer log in to Mattermost
+
+If the user can no longer log in to Mattermost with their AD/LDAP credentials - for example, they get an error message `An account with that email already exists`, or a new Mattermost account is created when they try to log in - this means the **ID Attribute** for their account has changed.
+
+The issue can be fixed by changing the value of the field used for the **ID Attribute** back to the old value. If you're currently using a field that sometimes changes for an **ID Attribute** (e.g. username, email that changes when someone gets married), we recommend you switch to using a non-changing field such as a GUID.
+
+To do this, you can set the [Login ID Attribute](/administration-guide/configure/authentication-configuration-settings#id-attribute) to whatever you would like users to log in with (e.g. username or email).
+
+<Note>
+
+Currently the value is case sensitive. If the **ID Attribute** is set to the username and the username changes from `John.Smith` to `john.smith`, the user will experience problems logging in.
+
+</Note>
+
+### I see the log error `LDAP Result Code 4 "Size Limit Exceeded"`
+
+This indicates that your AD/LDAP server configuration has a maximum page size set and the query coming from Mattermost is returning a result set in excess of that limit.
+
+To address this issue you can set the [max page size](/administration-guide/configure/authentication-configuration-settings#maximum-page-size) in your Mattermost configuration to match the limit on your AD/LDAP server. This will return a sequence of result sets that do not exceed the max page size, rather than returning all results in a single query. A max page size setting of 1500 is recommended.
+
+If the error is still occurring, it is likely that no AD/LDAP users have logged into Mattermost yet. Ensure that at least one AD/LDAP user has logged into Mattermost and re-run the synchronization. The error should disappear at that point.
+
+### I see the log error `Missing NameID Element`
+
+This indicates that the AD/LDAP server configuration doesn't include the `NameID` element in the SAML assertion. The `NameID` element is required for user identification in SAML assertions. Ensure the `NameID` is mapped to a unique user identifier, such as the user's email address or another stable attribute that isn't subject to change over time.
+
+### I see the log error `Username Attribute is Missing`
+
+The `Username` attribute in the SAML assertion was either missing or is incorrectly named. Verify that all required attributes are included in the SAML assertion. Attribute names are case-sensitive and must match exactly what Mattermost expects. Update the claim rules in AD/LDAP to correctly map LDAP attributes to the expected outgoing claim types, ensuring proper casing (e.g., `Username` instead of `UserName`).
+
+### Can the Enter ID User Filter read security groups?
+
+Yes it can, but make sure that:
+
+- Permissions are correctly configured on the service account you are using.
+- Each user object is a direct member of the security group.
+
+### How do I know if an AD/LDAP sync job fails?
+
+Mattermost provides the status of each AD/LDAP sync job in the **Sync History** section of the AD/LDAP wizard (**System Console \> Authentication \> AD/LDAP**). Here you can see the number of users updated and if the job succeeded or failed.

docs/main/administration-guide/onboard/advanced-permissions.mdx

@@ -0,0 +1,232 @@
+---
+title: "Advanced permissions"
+---
+<PlanAvailability slug="all-commercial" />
+
+Mattermost system admins using Mattermost Cloud or Mattermost Server can use Advanced Permissions to customize which users can perform specific actions, such as creating teams, managing channels, and configuring webhooks. The Mattermost permission system is based on a modified RBAC (role-based access control) architecture, using roles to determine which users have the ability to perform various actions.
+
+Two permission schemes are provided in Mattermost:
+
+- **System Scheme**: Applies permissions universally across all teams and channels.
+- **Team Override Schemes**: Allow admins to customize permissions for each team.
+
+This document describes the types of permissions that can be given to users of Mattermost using schemes as well as channel settings and roles. The [permissions backend documentation](/administration-guide/onboard/advanced-permissions-backend-infrastructure) provides additional technical details around permissions.
+
+## Permissions structure
+
+The Mattermost System Console provides a number of elements for Admins to control the permissions in their system.
+
+### System scheme
+
+You can set the default permissions granted to system admins, team admins, channel admins, guests (if enabled), and all members. The permissions granted in the System Scheme apply system-wide, meaning:
+
+- **Guests:** If Guest Accounts are enabled, permissions apply to guest users in all channels, in all teams.
+- **All Members:** Permissions apply to all members, including admins, in all channels, in all teams.
+- **Channel Administrators:** Permissions apply to all channel admins in all channels, in all teams.
+- **Team Administrators:** Permissions apply to all team admins, in all teams.
+
+To override the System Scheme default permissions in a specific team, you must set up a Team Override Scheme.
+
+You can access the System Scheme interface by going to **System Console \> User Management \> Permissions \> System Scheme**.
+
+![image](/images/system-scheme.png)
+
+### Team override scheme
+
+<PlanAvailability slug="entry-adv" />
+
+On systems with multiple [Mattermost teams](/end-user-guide/collaborate/organize-using-teams#single-team-versus-multiple-teams), each team may operate and collaborate in a unique way. Team Override Schemes give Admins the flexibility to tailor permissions to the needs of each team.
+
+When you use this permission scheme:
+
+- The permissions granted in a Team Override Scheme apply only in the teams which are assigned to the scheme.
+- The System Scheme does not apply to teams that are added to a Team Override Scheme.
+- Teams can only belong to one Team Override Scheme.
+
+You can access the Team Override Scheme interface by going to **System Console \> User Management \> Permissions \> Team Override Schemes**.
+
+![image](/images/team-scheme.png)
+
+## Channel permissions
+
+The channel permissions interface is accessed in **System Console \> User Management \> Channels**.
+
+### Advanced access controls
+
+<PlanAvailability slug="entry-adv" />
+
+See the [team and channel management](/administration-guide/manage/team-channel-members#advanced-access-controls) documentation for details on available channel access controls.
+
+## Recipes
+
+This section provides some examples of common permissions use cases for team management, channel management, and overall permissions.
+
+### Team management
+
+<PlanAvailability slug="entry-adv" />
+
+#### Ensure users only see each other when in the same team or channel
+
+Example: A classified organization wants to use Mattermost teams for classified projects. In each project, team members can't know about members outside of their project, and [@mentions](/end-user-guide/collaborate/mention-people) can't disclose the names of people outside of a classified project.
+
+Use the [mmctl permissions remove](/administration-guide/manage/mmctl-command-line-tool#mmctl-permissions-remove) command to revoke the `view_member` permission from the `system_user` role: `mmctl permissions remove system_user view_member`.
+
+#### Only allow admins, in a specific team, to add members
+
+Example: In Team A, only allow system and team admins to add new team members. As the default for all other teams, allow all users to add and invite new members.
+
+1.  Go to **System Console \> User Management \> Permissions**.
+2.  Select **Edit Scheme**.
+3.  In the **All Members \> Teams** panel, check the box for **Add Team Members**. This sets the system default for all teams.
+4.  Select **Save**.
+5.  Select the back arrow to return to the **Permission Schemes** menu.
+6.  Select **New Team Override Scheme**.
+
+> 1.  Name and describe the scheme. For example, `Authorized Personnel Only` with description `Restrict adding team members to eam and System Admins.`
+> 2.  Select **Add Teams** to add Team B to the **Select teams to override permissions** list, locate Team B, then select **Add**.
+> 3.  In the **All Members** panel, uncheck the box for **Add Team Members**.
+> 4.  In the **Team Administrators** panel, check the box for **Add Team Members**.
+
+7.  Select **Save**.
+8.  Select the back arrow to return to the **Permission Schemes** menu.
+
+### Public and private channel management
+
+<PlanAvailability slug="entry-adv" />
+
+#### Restrict who can rename & edit channels
+
+Example: As the default for the entire system, restrict renaming channels and editing headers and purposes to admins only.
+
+1.  Go to **System Console \> User Management \> Permissions**.
+2.  Select **Edit Scheme**.
+3.  In the **All Members** panel, uncheck the box for **Manage Public Channels \> Manage Channel Settings**.
+
+The **Manage Channel Settings** option is now only available to channel admins, team admins, and system admins.
+
+#### Restrict who can create channels in specific teams
+
+Example: In Team C, restrict public channel creation to admins. As the default for all other teams, allow everyone to create public channels.
+
+1.  Go to **System Console \> User Management \> Permissions**.
+2.  Select **Edit Scheme**.
+3.  In the **All Members** panel, in the **Manage Public Channels** menu, check the box for **Create Channels**. This sets the system default to allow creation of public channels on all teams.
+4.  Select **Save**.
+5.  Select the arrow to return to the **Permission Schemes** interface.
+6.  Select **New Team Override Scheme**.
+
+> 1.  Name and describe the scheme. For example, `Contractor Scheme` with description `Restrict public channel creation to Admins only`.
+> 2.  Select **Add Teams** to add Team B to the **Select teams to override permissions** list, locate Team B, then select **Add**.
+> 3.  In the **All Members** panel, in the **Manage Public Channels** section, uncheck the box for **Create Channels**.
+> 4.  In the **Team Administrators** panel, in the **Manage Public Channels** section, check the box for **Create Channels**.
+
+### Convert public channels to private channels
+
+#### Allow anyone to convert public channels to private channels
+
+Example: Set the default setting to allow all members, team admins, and channel admins to convert public channels to private.
+
+1.  Go to **System Console \> User Management \> Permissions**.
+2.  Select **Edit Scheme**.
+3.  In the **All Members** panel, uncheck the box for **Manage Public Channels \> Convert Channels**.
+
+This permission is applied to all other roles (excluding the Guest role). When this permission is not enabled for all members, it must be manually applied to team admins and channel admins if required.
+
+### Read-only channels
+
+<PlanAvailability slug="entry-adv" />
+
+#### Members can participate but guests can only read and react
+
+1.  Go to **System Console \> User Management \> Channels**.
+2.  Select **Edit** next to the name of the channel you want to configure.
+3.  In the **Create Posts** panel, uncheck **Guests**.
+4.  In the **Post Reactions** panel, uncheck **Guests** if required.
+5.  Select **Save**.
+
+The channel is available for all members and guests to access, but guests can only read messages and react to them.
+
+#### Create an announcement channel where only channel admins can post
+
+1.  Create a new channel (either public or private).
+2.  Navigate to **System Console \> User Management \> Channels**.
+3.  Select **Edit** next to the name of the channel you just created (you may need to search for it).
+4.  In the **Create Posts** panel, uncheck **Guests** and **Members**.
+5.  In the **Post Reactions** panel, uncheck **Guests** and **Members**.
+6.  Select **Save**.
+
+The channel is available for all members and guests to access but only admins can post.
+
+### Message management
+
+#### Restrict who can delete messages
+
+Example: As the default for the entire system, restrict deleting posts to only system and team admins.
+
+1.  Go to **System Console \> User Management \> Permissions**.
+2.  Select **Edit Scheme**.
+3.  In the **All Members** and **Channel Administrators** panels, in the **Delete Posts** section, uncheck the boxes for **Delete Own Posts** and **Delete Others' Posts**.
+4.  In the **Channel Administrators** and **Team Administrators** panels, in the **Delete Posts** section, check the boxes for **Delete Own Posts** and **Delete Others' Posts**.
+
+#### Restrict who can edit messages
+
+Example: As the default for the entire system, only allow users to edit their own posts for five minutes after posting.
+
+1.  Go to **System Console \> User Management \> Permissions**.
+2.  Select **Edit Scheme**.
+3.  In the **All Members**, **Channel Administrators**, and **Team Administrators** panels, in the **Manage Posts** section, check the box for **Edit Posts**.
+4.  From any panel, select the gear button to set the global time limit to `300` seconds.
+
+#### Restrict who can edit post attachments
+
+From Mattermost v11.8, system admins can use the **Edit Attachments** permission to control whether users can add or remove file attachments when editing posts.
+
+The **Edit Attachments** permission is separate from **Edit Own Posts**. Users with permission to edit a post can still update the post text, but they can't add or remove file attachments unless **Edit Attachments** is also enabled.
+
+By default, **Edit Attachments** is granted to users who have permission to edit posts.
+
+To allow users to edit post text without changing attachments:
+
+1.  Go to **System Console \> User Management \> Permissions**.
+2.  Select **Edit Scheme**.
+3.  In the applicable role panel, go to **Manage Posts**.
+4.  Enable **Edit Own Posts**.
+5.  Disable **Edit Attachments**.
+6.  Select **Save**.
+
+If a user sees **Post attachments cannot be edited** when editing a post, they don't have permission to add or remove attachments for that post.
+
+### Integration management
+
+From Mattermost v11.2, the System Console provides enhanced controls for managing integrations (webhooks, slash commands, OAuth apps), including separate permissions for managing your own integrations versus other users' integrations.
+
+#### Restrict who can manage webhooks and slash commands
+
+Example: As the default for the entire system, only allow system admins to create, edit and delete integrations.
+
+1.  Go to **System Console \> User Management \> Permissions**.
+2.  Select **Edit Scheme**.
+3.  In the **All Members** and **Team Administrators** panels, in the **Integrations & Customizations** section, uncheck the boxes for **Manage Incoming Webhooks**, **Manage Outgoing Webhooks**, and **Manage Slash Commands**.
+
+## Administration tools
+
+There are a number of API and mmctl tools available for admins to help in configuring and troubleshooting the permissions system:
+
+1.  Reset all permissions to the default on new installations using the [mmctl permissions reset](/administration-guide/manage/mmctl-command-line-tool#mmctl-permissions-reset) command.
+2.  Use the [GetAllRoles](https://api.mattermost.com/#tag/roles/operation/GetAllRoles) API endpoint to get a list of all roles.
+3.  Add permissions to a role using the [mmctl permissions add](/administration-guide/manage/mmctl-command-line-tool#mmctl-permissions-add) command.
+
+## Backend infrastructure
+
+Technical admins or developers looking for a deeper understanding of the permissions backend can refer to our [permissions backend documentation](/administration-guide/onboard/advanced-permissions-backend-infrastructure).
+
+## Glossary
+
+- **Permission:** The ability to execute certain actions. Permissions are granted to roles.
+- **Roles:** A set of permissions. Users or groups are assigned to roles.
+- **Group:** A set of users, usually synced from AD/LDAP. Groups are assigned to roles in the context of teams, channels, or system-wide.
+- **Default Roles:** All Members, Guests (if enabled), channel admins, team admins, system admins.
+- **System Scheme:** A set of default roles that apply system-wide.
+- **Team Override Scheme:** A set of default roles that apply only in the team specified. Permissions granted to roles in a Team Override Scheme overrides roles in the System Scheme.
+- **System-wide:** Applies across the entire system, including all teams of which the user is a member.
+- **Team-wide:** Applies in a specific team only.

docs/main/administration-guide/onboard/certificate-based-authentication.mdx

@@ -0,0 +1,43 @@
+---
+title: "Certificate-based authentication (Experimental)"
+unlisted: true
+---
+<PlanAvailability slug="ent-plus" />
+
+<Important>
+
+**Experimental certificate-based authentication has been deprecated from Mattermost v11.0.** From Mattermost v11, you must [disable this feature](/administration-guide/configure/experimental-configuration-settings#enable-client-side-certification) to start the server. Enabling this setting will prevent the server from starting.
+
+</Important>
+
+Prior to v11, certificate-based authentication (CBA) is available as an experimental feature to identify a user or a device before granting access to Mattermost and provide an additional layer of security to access the system.
+
+Before you begin, follow the [official guides to install Mattermost](/deployment-guide/deployment-guide-index) on your system, including NGINX configuration as a proxy with SSL and HTTP/2, and a valid SSL certificate such as Let's Encrypt.
+
+Then, follow the steps below to configure user CBA for your browser and Mattermost Desktop Apps. You can manage certificate distribution for each personal device (BYOD) and their life cycle management with a service like [OpenSSL](https://www.openssl.org/).
+
+## Set up mutual TLS authentication for the Web App
+
+[Setting up mutual TLS authentication](/administration-guide/onboard/ssl-client-certificate) is the first step to set up certificate-based authentication.
+
+## Set up Mattermost server to log in with a client certificate
+
+1.  Make sure your Mattermost server is licensed with a valid Enterprise license.
+2.  In `ExperimentalSettings` of the `config.json` file, set `ClientSideCertEnable` to `true` and `ClientSideCertCheck` to one of the following values:
+
+- `primary` - After the client side certificate is verified, user's email is retrieved from the certificate and is used to log in without a password.
+- `secondary` - After the client side certificate is verified, user's email is retrieved from the certificate and matched against the one supplied by the user.
+
+If they match, the user logs in with regular email/password credentials.
+
+The `config.json` file should then have the following lines
+
+``` text
+"ExperimentalSettings": {
+    "ClientSideCertEnable": true,
+    "ClientSideCertCheck": "secondary"
+},
+```
+
+3.  Restart the Mattermost server.
+4.  Go to `https://example.mattermost.com` and try to log in. The server should require the x.509 cert to have an `emailAddress` equal to the Mattermost user's email.

docs/main/administration-guide/onboard/common-converting-oauth-to-openidconnect.mdx

@@ -0,0 +1,14 @@
+---
+unlisted: true
+---
+{/* Snippet include; not intended to be a standalone page */}
+
+Using the System Console, Mattermost Enterprise and Professional customers can migrate OAuth configuration to the OpenID Connect standard. A one-time, one-click conversion tool is available within the existing **OAuth 2.0** page. You can also go to **System Console \> Authentication \> OpenID Connect**.
+
+Select **Convert to OpenID Connect** to migrate your active service provider configuration to the new standard. No further changes are required.
+
+<Note>
+
+\- Inactive service providers configured for OAuth 2.0 are also migrated to the new OpenID Connect standard.
+
+</Note>

docs/main/administration-guide/onboard/connected-workspaces.mdx

@@ -0,0 +1,356 @@
+---
+title: "Connected workspaces"
+---
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PlanAvailability slug="entry-ent" />
+
+Communicate across organizations, as well as external partners and vendors using Mattermost by synchronizing messages, emoji reactions, and file sharing in real-time through secured, connected Mattermost workspaces.
+
+Connected workspaces in Mattermost behave like regular public and private channels and offer the same user experience and functionality. All members using secure connections, including local members and remote members, can [send and receive channel messages](/end-user-guide/collaborate/send-messages), [use emojis](/end-user-guide/collaborate/react-with-emojis-gifs) to react to messages, [share files](/end-user-guide/collaborate/share-files-in-messages), and [search message history](/end-user-guide/collaborate/search-for-messages). Content is synchronized across all participating Mattermost instances.
+
+A channel's permissions and access continues to be governed by each server separately. [Advanced access control](/administration-guide/manage/team-channel-members#advanced-access-controls) permissions can be applied to a shared channel, and be in effect on the local Mattermost server while not being in effect on a remote Mattermost server.
+
+## Set up connected workspaces
+
+The process of connecting Mattermost workspaces involves the following 5 steps:
+
+1.  Ensure that all Mattermost Enterprise servers are running v10.2 or later.
+2.  [Enable the connected workspaces functionality](#enable-connected-workspaces) for each Mattermost Enterprise instance you want to connect.
+3.  System admins must [create a secure and trusted connection](#create-a-secure-connection) with other Mattermost Enterprise instances using the System Console or slash commands. This process involves creating a password-protected, encrypted invitation, creating a strong decryption password, then sending the invitation and password to the admin of a remote Mattermost instance. From Mattermost v11.0, remote cluster invitations use PBKDF2 key derivation for enhanced security.
+4.  When a remote system admin receives the invitation, they must [accept the invitation](#accept-a-connection-invitation) using the System Console or slash commands.
+5.  Once a trusted relationship is established between 2 Mattermost servers, system admins or users with the **Shared Channel Manager** role can [share specific public or private channels](#share-channels-with-secure-connections) with secure connections.
+
+<Note>
+
+- System admins can create secure connections with other Mattermost Enterprise instances. System admins or users with the **Shared Channel Manager** [delegated administration role](/administration-guide/onboard/delegated-granular-administration) can share channels with secured connections.
+- System admins creating secure connections must use Mattermost to generate a password-protected encrypted invitation code. However, sending secure connection invitations is not completed using Mattermost. System admins must have an independent way to extend the secure connection invitation, such as by email.
+- A channel shared by a host organization cannot be shared from the receiving organization to another organization. Organizations can't share a channel originating from another organization.
+
+</Note>
+
+## Enable connected workspaces
+
+System admins must enable connected workspaces functionality for their Mattermost instance. Ensure the following configuration settings are set to `true` in `config.json`:
+
+- `ConnectedWorkspacesSettings.EnableRemoteClusterService = true`
+- `ConnectedWorkspacesSettings.EnableSharedChannels = true`
+
+See the [Site Configuration Settings](/administration-guide/configure/site-configuration-settings#enable-connected-workspaces) documentation for details.
+
+<Note>
+
+Following an upgrade to Mattermost v10.2 or later, existing configuration values for shared channels, including `EnableSharedChannels` and `EnableRemoteClusterService` are automatically converted to [connected workspace configuration settings](/administration-guide/configure/site-configuration-settings#enable-connected-workspaces) in the `config.json` file. The [deprecated shared channels experimental settings](/administration-guide/configure/deprecated-configuration-settings#shared-channels-settings) remain in the `config.json` file to support backwards compatibility.
+
+</Note>
+
+## Create a secure connection
+
+<Tabs>
+<TabItem value="system-console" label="System Console">
+
+Only system admins can create workspace connections using the System Console.
+
+1.  Go to **Site Configuration \> Connected Workspaces**.
+2.  Under **Connected Workspaces**, select **Add a connection**, and then select **Create a connection**.
+3.  Specify the **Organization Name** for this connection. The remote system admin must specify this name when accepting a connection invitation.
+4.  Select the **Destination Team** as the default team where shared channels will be added. This team will be used as the default location for organizing shared channels from this connected workspace.
+5.  Select **Save**.
+
+An invitation consisting of a password-protected AES 256-bit encrypted code blob is generated. From Mattermost v11.0, password protection uses PBKDF2 key derivation for enhanced security. The connection is labeled as **Connection Pending** until the remote system admin accepts the invitation.
+
+</TabItem>
+<TabItem value="slash-commands" label="Slash Commands">
+
+By default, only system admins can use slash commands to create workspace connections. You can delegate channel sharing capabilities using the built-in **Shared Channel Manager** [delegated administration role](/administration-guide/onboard/delegated-granular-administration). Alternatively, you can grant the ability to **Manage Shared Channels** to Mattermost users by modifying permissions of the [system scheme](/administration-guide/onboard/advanced-permissions#system-scheme) or [team override scheme](/administration-guide/onboard/advanced-permissions#team-override-scheme).
+
+System admins can [run the following slash command](/integrations-guide/run-slash-commands) to create a secure connection invitation:
+
+`/secure-connection create --name <--displayname> --password`
+
+For example:
+
+`/secure-connection create --name AcmeUS --displayname "AcmeUSA" --password examplepassword`
+
+This slash command creates an invitation consisting of a password-protected AES 256-bit encrypted code blob for a remote Mattermost entity known locally as `AcmeUS` with a password of `examplepassword`. From Mattermost v11.0, password protection uses PBKDF2 key derivation for enhanced security. Within Mattermost, this shared connection displays to the local system admin based on the `name` and `displayname` provided.
+
+</TabItem>
+</Tabs>
+
+
+### Extend the invitation
+
+You must use a system, other than Mattermost, to share invitation codes and passwords. We strongly recommend sharing invitation codes separately from passwords to ensure that no one has all of the data necessary to take action if the message were compromised. Ensure the remote Mattermost instance can access your Mattermost workspace URL.
+
+<Tabs>
+<TabItem value="system-console" label="System Console">
+
+Once you've created a connection in the System Console, you're prompted to share the invitation code and password with the system admin of the remote Mattermost server you want to connect with. Copy both the invitation code and password to a safe location, then select **Done**.
+
+</TabItem>
+<TabItem value="slash-commands" label="Slash Commands">
+
+Copy the invitation code blob in the System message, then share the code blob and the decryption password to the remote Mattermost system admin you want to securely connect with.
+
+</TabItem>
+</Tabs>
+
+
+## Accept a connection invitation
+
+<Tabs>
+<TabItem value="system-console" label="System Console">
+
+1.  Go to **Site Configuration \> Connected Workspaces**.
+2.  Under **Connected Workspaces**, select **Add a connection**, and then select **Accept an invitation**.
+3.  Specify the **Organization Name** for this invitation. This must be the same name specified when creating the connection.
+4.  Select the **Destination Team** where shared channels will be added. This team will serve as the default location for organizing shared channels from this connected workspace.
+5.  Paste the encrypted invitation code and password you've been provided to connect with the remote workspace.
+6.  Select **Accept**.
+
+The system admin who accepts the connection invitation is automatically added to all shared channels.
+
+</TabItem>
+<TabItem value="slash-commands" label="Slash Commands">
+
+Run the following slash command to accept a secure connection invitation from a remote Mattermost instance:
+
+`/secure-connection accept --name --displayname --password --invite [code blob]`
+
+For example:
+
+`/secure-connection accept --name AcmeUS --displayname "AcmeUSA" --password examplepassword --invite [code-blob]`
+
+This slash command accepts a secure connection invitation from `AcmeUS`.
+
+</TabItem>
+</Tabs>
+
+
+## Share channels with secure connections
+
+Once a connection is established between two Mattermost servers, system admins or users with the **Shared Channel Manager** role can share channels across secured workspaces.
+
+<Tabs>
+<TabItem value="system-console" label="System Console">
+
+1.  Under **Shared Channels**, select **Add channels**.
+2.  Specify the channels you want to share between Mattermost servers.
+
+Shared channels and members of those shared channels display a shared <img src={useBaseUrl('/img/ui/circle-multiple-outline_F0695.svg')} alt="Shared icon indicates channels and their members that are shared across connected Mattermost servers." /> icon to distinguish them from channels and channel members of the local server.
+
+</TabItem>
+<TabItem value="slash-commands" label="Slash Commands">
+
+Run the following slash command to specify the public or private channels to share:
+
+`/share-channel invite --connectionID <--readonly>`
+
+You can extend an invitation that permits remote members to participate in the channel based on their channel and member permissions.
+
+Alternatively, you can extend a read-only invitation to a secure connection by appending the optional `--readonly` parameter to this command. Remote members can't post or reply to messages within shared read-only channels.
+
+<Tip>
+
+To convert a read-only shared channel to a participation channel, remove the original secured connection from the channel, then re-extend an invitation to that secure connection while omitting the optional `--readonly` parameter. For example:
+
+`/share-channel invite --connectionID`
+
+This slash command invites the shared connection to the current channel based on its `connectionID`.
+
+See [Reviewing Secure Connection Status](#review-connection-status) to find the `connectionID` for a shared connection.
+
+</Tip>
+
+</TabItem>
+</Tabs>
+
+
+## Direct message delivery
+
+From Mattermost v10.10, creating a direct or group message with remote users across connected workspaces is only available when the feature flag `EnableSharedChannelsDMs` is enabled.
+
+When `EnableSharedChannelsDMs` is disabled, the direct message option on a user's profile is disabled and unavailable to ensure users can't attempt direct messages with remote users when connected workspaces isn't enabled on the other Mattermost instance.
+
+## Plugin component interaction
+
+From Mattermost v10.10, plugin interactions such as slash commands, interactive buttons, and other plugin-generated components aren't displayed or accessible in shared channels by default to ensure a consistent experience across different Mattermost instances.
+
+System admins can enable the `EnableSharedChannelsPlugins` feature flag to enable these plugin interactions in shared channels. When plugin components are enabled in shared channels, we recommend ensuring that all connected Mattermost instances have the same plugins installed and configured to avoid inconsistent user experiences. Plugin behaviors can vary between instances if different plugin versions or configurations are used.
+
+## Remote user discovery
+
+From Mattermost v10.10, remote users across connected workspaces can be discovered for direct or group messages when the feature flag `EnableSyncAllUsersForRemoteCluster` is enabled. This feature implements global user synchronization between connected Mattermost instances, making remote users discoverable without requiring them to post in a shared channel first. When enabled, Mattermost uses cursor-based synchronization to efficiently sync user information between connected instances. The system:
+
+- Synchronizes users in configurable batch sizes to prevent timeouts and reduce memory usage
+- Tracks synchronization progress using timestamps to enable efficient resumption
+- Filters out users from their original cluster to prevent syncing users back to their home instance
+- Only syncs users that have been updated since the last synchronization
+
+The feature includes configuration options for [automatically syncing users when connections are established](/administration-guide/configure/site-configuration-settings#sync-users-on-connection-open) and [controlling batch processing sizes](/administration-guide/configure/site-configuration-settings#global-user-sync-batch-size) for optimal performance.
+
+When `EnableSyncAllUsersForRemoteCluster` is disabled, remote users are only discoverable in the DM/GM creation modal after they have participated in a shared channel.
+
+<Note>
+
+Enabling these features can increase the load on your Mattermost server’s CPU, memory, and database due to frequent updates, database queries, and API communication. Excessive sync frequency and retries can overwhelm system resources, potentially causing performance degradation or instability. Monitor your system carefully when enabling these features.
+
+</Note>
+
+## Channel membership synchronization
+
+From Mattermost v10.10, channel membership synchronization between connected workspaces is controlled by the feature flag `EnableSharedChannelsMemberSync`. When this feature flag is enabled, channel membership changes are automatically synchronized across all connected workspaces that share the same channel.
+
+When `EnableSharedChannelsMemberSync` is enabled:
+
+- Users added to a shared channel on one workspace are automatically added to the corresponding shared channel on all connected workspaces
+- Users removed from a shared channel on one workspace are automatically removed from the corresponding shared channel on all connected workspaces
+- Membership changes are processed in configurable batch sizes to optimize performance and prevent timeouts
+- The system uses cursor-based synchronization to efficiently track and sync membership changes
+
+The feature includes a configuration option for [controlling batch processing sizes for member synchronization](/administration-guide/configure/site-configuration-settings#member-sync-batch-size) to ensure optimal performance during large membership changes.
+
+When `EnableSharedChannelsMemberSync` is disabled, channel membership changes are not synchronized between connected workspaces, and users must be manually added or removed from shared channels on each workspace.
+
+<Note>
+
+Enabling these features can increase the load on your Mattermost server’s CPU, memory, and database due to frequent updates, database queries, and API communication. Excessive sync frequency and retries can overwhelm system resources, potentially causing performance degradation or instability. Monitor your system carefully when enabling these features.
+
+</Note>
+
+## Manage connections and invitations
+
+System admins can [edit](#edit-a-connected-workspace) or [delete](#delete-a-connected-workspace) a connected workspace, [review connection status](#review-connection-status), and [regenerate invitation codes and passwords](#regenerate-invitation-codes-for-pending-connections) for pending connections.
+
+### Edit a connected workspace
+
+In the System Console, system admins can change the **Organization Name**, the **Destination Team** (which serves as the default location for organizing shared channels from this connected workspace), or channels shared with a remote Mattermost instance as well as channels shared with your local Mattermost instance.
+
+1.  Under **Connected Workspaces**, identify the connected workspace you want to change.
+2.  Select the **More** <img src={useBaseUrl('/img/ui/dots-horizontal_F01D8.svg')} alt="Use the More icon to access additional message options." className="theme-icon" /> icon to the right of the connected workspace, and then select **Edit**.
+
+### Remove all connections from the current channel
+
+Run the following slash command to remove all secure connections from the current channel:
+
+`/share-channel unshare`
+
+This slash command removes all secure connections from the current channel. A System message notifies you that the channel is no longer shared. Secure connections may continue to be invited to other shared channels.
+
+### Delete a connected workspace
+
+Deleting a connected server severs the trust relationship between the local Mattermost server and the remote Mattermost server.
+
+From Mattermost v10.10, removing a shared channel from a connected workspace removes the channel from all connected workspaces. The channel is deleted from both the local and remote Mattermost servers. Prior to Mattermost v10.10, removing a shared channel from a connected workspace stops synchronizing the channel with the remote Mattermost server; however, the channel continues to function for local users.
+
+<Tabs>
+<TabItem value="system-console" label="System Console">
+
+1.  Under **Connected Workspaces**, identify the connected workspace you want to remove.
+2.  Select the **More** <img src={useBaseUrl('/img/ui/dots-horizontal_F01D8.svg')} alt="Use the More icon to access additional message options." className="theme-icon" /> icon to the right of the connected workspace, and then select **Delete**.
+
+</TabItem>
+<TabItem value="slash-commands" label="Slash Commands">
+
+Using slash commands, you can uninvite or delete a secure connection from your Mattermost instance.
+
+Run the following slash command to uninvite a secure connection:
+
+`/share-channel uninvite --connectionID`
+
+This slash command removes a secure connection from the current channel based on its `connectionID`. The secure connection may continue to be invited to other shared channels.
+
+Run the following slash command to delete a secure connection:
+
+`/secure-connection remove --connectionID`
+
+For example:
+
+`/secure-connection remove --connectionID`
+
+This slash command severs the trust relationship between the local Mattermost server and a remote Mattermost server based on its `connectionID` and removes the secure connection from all shared Mattermost channels.
+
+</TabItem>
+</Tabs>
+
+
+### Review connection status
+
+<Tabs>
+<TabItem value="system-console" label="System Console">
+
+Under **Connected Workspaces**, you can review all connected workspaces and their current status as one of: **Connected**, **Offline**, or **Connection Pending**.
+
+</TabItem>
+<TabItem value="slash-commands" label="Slash Commands">
+
+Run the following slash command to review the current status of all secure connections established for your Mattermost instance:
+
+`/secure-connection status`
+
+Status details include:
+
+- Connection ID
+- Connection URL
+- Description
+- Invite accepted (Yes/No)
+- Online (Yes/No)
+- Last ping timestamp (UTC)
+- Deleted
+
+</TabItem>
+</Tabs>
+
+
+### Regenerate invitation codes for pending connections
+
+When using the System Console to manage connected workspaces, system admins can re-generate invitation codes and passwords for pending connections.
+
+1.  Under **Connected Workspaces**, identify the pending connection whose invitation and password you want to regenerate.
+2.  Select the **More** <img src={useBaseUrl('/img/ui/dots-horizontal_F01D8.svg')} alt="Use the More icon to access additional message options." className="theme-icon" /> icon to the right of the connected workspace, and then select **Regenerate invitation code**.
+
+<Note>
+
+Regenerating doesn't invalidate the existing password, and the existing password can continue to be used in addition to the newly-generated password. Once a connection invitation is accepted and the workspace displays a status of **Connected**, invitation codes and passwords can't be regenerated.
+
+</Note>
+
+## Frequently Asked Questions
+
+### Are special characters supported in secure connection names?
+
+No. When using slash commands, `--name` can include periods, hyphens, and/or underscores. You must surround `--name` using quotation marks (") when the value contains spaces.
+
+### What happens if two Mattermost instances contain different emojis?
+
+In cases where one Mattermost instance has different emojis than another instance, emoji text displays in place of a missing emoji image.
+
+### Is a Display Name required for all secure connections?
+
+No. When using slash commands, `--displayname` is optional. When omitted, `--name` is displayed and used instead.
+
+### What information is synchronized between connected workspaces?
+
+By default, member status and availability for all members of shared channels is synchronized between connected workspaces.
+
+When a user is added to a shared channel, member status is synchronized within a few seconds of the member's status changing. Status updates aren't immediate and don't necessarily display in real-time.
+
+When using Mattermost in a web browser, Mattermost polls the server every minute. Refreshing the browser page triggers immediate synchronization.
+
+By default, a maximum of 50 messages are synchronized at a time, and [this value is configurable](/administration-guide/configure/site-configuration-settings#default-maximum-posts-per-sync).
+
+Channel as well as member status and availability synchronization [can be disabled](/administration-guide/configure/site-configuration-settings#disable-shared-channel-status-sync).
+
+From Mattermost v10.10, channel membership can be synchronized between connected workspaces when the feature flag `EnableSharedChannelsMemberSync` is enabled. When a user is added to or removed from a shared channel on one workspace, that membership change is automatically applied to the corresponding shared channel on all connected workspaces. This ensures consistent channel membership across all participating Mattermost instances. Additionally, connected workspaces also synchronize message priority, message acknowledgements, and persistent notifications between connected servers. This ensures that important message indicators and user interactions are consistently reflected across all connected workspace instances.
+
+### Do connection interruptions affect message synchronization?
+
+Yes. A System message is posted in the channel visible to all channel members when message synchronization is interrupted for more than 5 minutes. Once connectivity is restored, a full synchronization will happen for all missed messages, including direct messages and channel links.
+
+### What happens if two secure connections share the same usernames?
+
+In cases where members share the same usernames across Mattermost secure connections, usernames on the local server instance are appended with the secure connection name of the remote server.
+
+For example, if multiple members named John Smith exist after two Mattermost instances establish a secure connection with one another, all remote John Smith members include their Secure Connection ID following their username to help differentiate members across multiple Mattermost instances.

docs/main/administration-guide/onboard/convert-oauth20-service-providers-to-openidconnect.mdx

@@ -0,0 +1,17 @@
+---
+title: "Convert OAuth 2.0 service providers to OpenID Connect"
+---
+import Inc0_common_converting_oauth_to_openidconnect from './common-converting-oauth-to-openidconnect.mdx';
+
+<PlanAvailability slug="all-commercial" />
+
+<Inc0_common_converting_oauth_to_openidconnect />
+
+## Configuring OpenID Connect Single Sign-On
+
+For details on configuring Mattermost to use a service provider as a Single Sign-on (SSO) service for team creation, account creation, and user sign-in using OpenID Connect in your self-hosted deployment, refer to the following documentation:
+
+- [OpenID Connect Single Sign-On](/administration-guide/onboard/sso-openidconnect)
+- [GitLab Single Sign-On](/administration-guide/onboard/sso-gitlab)
+- [Google Apps Single Sign-On](/administration-guide/onboard/sso-google)
+- [Entra ID Single Sign-On](/administration-guide/onboard/sso-entraid)

docs/main/administration-guide/onboard/corporate-directory-integration.mdx

@@ -0,0 +1,61 @@
+---
+title: "Corporate directory integration"
+---
+Mattermost offers advanced security and authentication options for integrating with corporate directories. This guide outlines the options available.
+
+## Basic authentication
+
+By default, Mattermost offers authentication via email and password, which offers basic features including:
+
+- Account sign up using email and password.
+- Password reset via email.
+- Ability to use the same credentials to log into web, desktop, and mobile app experiences.
+- Ability to use a username and password in place of email and password.
+
+## Security features for authentication
+
+A core set of features is available with all authentication options to help increase security:
+
+- Ability to [set session length](/administration-guide/configure/environment-configuration-settings#session-lengths) to define how long a user can use Mattermost before needing to re-enter credentials.
+- Ability for users to remotely sign out of devices.
+- Ability for IT admin to force sign out of a user from devices.
+- Ability to set rate limits on authentication API calls to deter password-guessing attacks.
+- Ability to require multi-factor authentication on log in.
+- For advanced deployments, password requirements for length and special characters can be added.
+
+## AD/LDAP authentication
+
+[AD/LDAP](/administration-guide/onboard/ad-ldap) is the most popular corporate directory integration option for deploying Mattermost behind a corporate firewall. Features include:
+
+- Account creation using AD/LDAP credentials.
+- AD/LDAP user filters to define which users get access to Mattermost in the form of a query.
+- Ability to use a low-privileged AD/LDAP account to run queries over a secure TLS or STARTTLS connection.
+- Attribute mapping to place First Name, Last Name, Nickname, and other attributes from AD/LDAP into Mattermost.
+- Customization of login screen to specify whether users are logging in with email, username, or other attribute.
+- Synchronization with AD/LDAP to disable, enable, and update Mattermost users based on AD/LDAP.
+
+<Note>
+
+\- New user accounts are created when new users log in with their AD/LDAP credentials. You can optionally pre-create user accounts using the [bulk import](/administration-guide/onboard/bulk-loading-data) tool. - If you're using email or username and password authentication [users can switch to AD/LDAP manually](/administration-guide/onboard/ad-ldap#getting-started), and the conversion to AD/LDAP can also be done using the [mmctl user migrate auth](/administration-guide/manage/mmctl-command-line-tool#mmctl-user-migrate-auth) command by an IT admin.
+
+</Note>
+
+For very large AD/LDAP instances you can also configure max page size to divide a Mattermost AD/LDAP query into several pieces to not overtax the authentication server when synchronizing.
+
+## Authentication options outside of a private network
+
+When deploying Mattermost to a DMZ location outside the security of a private network, additional authentication options include:
+
+- [Okta integration via SAML](/administration-guide/onboard/sso-saml-okta)
+- [OneLogin integration via SAML](/administration-guide/onboard/sso-saml-onelogin)
+- [Active Directory Federation Services via SAML](/administration-guide/onboard/sso-saml-adfs)
+- [SAML 2.0 authentication](/administration-guide/onboard/sso-saml)
+- [Google Apps](/administration-guide/onboard/sso-google)
+- [Entra ID](/administration-guide/onboard/sso-entraid)
+- [OpenID Connect](/administration-guide/onboard/sso-openidconnect)
+
+Generic OAuth is not currently supported.
+
+## Future authentication methods
+
+Mattermost releases new improvements monthly. Several additional authentication methods are planned, but not yet scheduled. If you're an enterprise interested in deploying with an option not yet provided in our documentation, talk to a [Mattermost Expert](https://mattermost.com/contact-sales/) to discuss further.

docs/main/administration-guide/onboard/delegated-granular-administration.mdx

@@ -0,0 +1,299 @@
+---
+title: "Delegated granular administration"
+---
+<PlanAvailability slug="ent-plus" />
+
+Mattermost supports the creation and customization of system administration roles with specific granular permissions and System Console access. This allows senior administrators in large organizations to delegate and de-centralize specialized administration and administrative tasks with specific admin roles.
+
+These admin roles permit granular access to specific areas of the System Console and related API endpoints. These roles enable users to perform certain administrative tasks without requiring access to all system administration areas. These system roles never supersede the user's original role or the user's permissions configured by the Permissions scheme.
+
+<Warning>
+
+Even when a role is set to **No Access** or **Read Only** for a System Console page, granting **Can Edit** on any System Console page enables access to the underlying configuration endpoint (`PUT /api/v4/config/patch`). This means a user with write access in one area can modify configuration values across all areas. Administrators should assign **Can Edit** permissions with caution.
+
+</Warning>
+
+## Available roles
+
+A system admin can configure the following delegated granular administration roles in the System Console. Each role has a set of default permissions, which can be adjusted as needed.
+
+- **System Manager:** This role can be configured to have read/write permissions in different management areas.
+- **User Manager:** This role can be configured to have read/write to all the user management areas and to authentication
+- **Custom Group Manager** This role has permissions to [create, edit, restore, and delete custom user groups](/end-user-guide/collaborate/organize-using-custom-user-groups). This role can be used to assign individual users the ability to manage custom groups when **Custom Groups** permissions are removed for **All Members** via **System Console \> Permissions \> Edit Scheme \> Custom Groups**.
+- **Shared Channel Manager** This role has the `manage_shared_channels` permission, allowing assigned users to share and unshare channels with existing connections to remote servers.
+- **Viewer:** The Viewer role can view all areas of the System Console, and can be configured with write access where needed.
+
+When a user is assigned a system role, they have role-based access to the System Console and the underlying API endpoints. Each role has a different set of default permissions, and what users can access or view depends on the role they've been assigned.
+
+The table below lists the default permissions for each role. Admins should carefully review and configure these settings to align with their organization's needs. Particular caution should be exercised with Permissions write access, as it enables modifications to the permissions of any role, except for the delegated granular administrator roles.
+
+<table style={{width: '73%'}}>
+<colgroup>
+<col style={{width: '19%'}} />
+<col style={{width: '20%'}} />
+<col style={{width: '33%'}} />
+</colgroup>
+<tbody>
+<tr>
+<td><strong>System role</strong></td>
+<td><strong>Read/Write access</strong></td>
+<td><strong>Read Only access</strong></td>
+</tr>
+<tr>
+<td>System Manager</td>
+<td><ul><li>User Management<ul><li>Groups</li><li>Teams</li><li>Channels</li><li>Permissions</li></ul></li><li>Environment</li><li>Site Configuration</li><li>Integrations</li></ul></td>
+<td><ul><li>Edition/License</li><li>Reporting</li><li>Authentication</li><li>Plugins</li></ul></td>
+</tr>
+<tr>
+<td>User Manager</td>
+<td><ul><li>User Management<ul><li>Groups</li><li>Teams</li><li>Channels</li></ul></li></ul></td>
+<td><ul><li>(User Management) Permissions</li><li>Authentication</li></ul></td>
+</tr>
+<tr>
+<td>Custom Group Manager</td>
+<td>Custom User Groups</td>
+<td>N/A</td>
+</tr>
+<tr>
+<td>Shared Channel Manager</td>
+<td>Shared Channels</td>
+<td>N/A</td>
+</tr>
+<tr>
+<td>Viewer</td>
+<td>N/A</td>
+<td><ul><li>All pages within the System Console</li></ul></td>
+</tr>
+</tbody>
+</table>
+
+## Assign admin roles
+
+There are two ways to assign roles:
+
+1.  In the System Console under **User Management \> Delegated Granular Administration**.
+2.  Using the [mmctl tool](/administration-guide/manage/mmctl-command-line-tool). This can be done either locally or remotely.
+
+<table style={{width: '99%'}}>
+<colgroup>
+<col style={{width: '18%'}} />
+<col style={{width: '47%'}} />
+<col style={{width: '30%'}} />
+<col style={{width: '2%'}} />
+</colgroup>
+<tbody>
+<tr>
+<td><strong>You want to</strong></td>
+<td><strong>Using the System Console</strong></td>
+<td><strong>Using mmctl</strong></td>
+<td></td>
+</tr>
+<tr>
+<td>Assign roles</td>
+<td>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration &gt; Assigned People</strong></td>
+<td><code>mmctl permissions role assign [role_name] [username...]</code></td>
+<td></td>
+</tr>
+<tr>
+<td>Grant the System Manager role to a user</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>System Manager</strong> role.</li><li>Under <strong>Assigned People</strong>, select <strong>Add People</strong>.</li><li>Search for and select the user name, then select <strong>Add</strong> to grant the System Manager role to that user.</li></ol></td>
+<td><code>mmctl permissions role assign system_manager user-name</code></td>
+<td></td>
+</tr>
+<tr>
+<td>Grant the User Manager role to two users</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>User Manager</strong> role.</li><li>Under <strong>Assigned People</strong>, select <strong>Add People</strong>.</li><li>Search for and select the two users, then select <strong>Add</strong> to grant the User Manager role to those users.</li></ol></td>
+<td><code>mmctl permissions role assign system_user_manager user-name1 user-name2</code></td>
+<td></td>
+</tr>
+<tr>
+<td>Grant the Viewer role to a user</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>Viewer</strong> role.</li><li>Under <strong>Assigned People</strong>, select <strong>Add People</strong>.</li><li>Search for and select the user name, then select <strong>Add</strong> to grant the Viewer role to that user.</li></ol></td>
+<td><code>mmctl permissions role assign system_read_only_admin user-name</code></td>
+<td></td>
+</tr>
+<tr>
+<td>Grant the Custom Group Manager role to two users</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>Custom Group Manager</strong> role.</li><li>Under <strong>Assigned People</strong>, select <strong>Add People</strong>.</li><li>Search for and select the two users, then select <strong>Add</strong> to grant the Custom Group Manager role to those users.</li><li>All users have the ability to create custom user groups by default. When you assign users to the Custom Group Manager role, you must manually remove these permissions from all users by going to <strong>System Console &gt; User Management &gt; Permissions &gt; Edit Scheme</strong>. Under <strong>All Members</strong>, clear all of the <strong>Custom Groups</strong> permissions, including <strong>Create</strong>, <strong>Manage members</strong>, <strong>Edit</strong>, and <strong>Delete</strong>.</li></ol></td>
+<td><code>mmctl permissions role assign system_custom_group_admin user-name1 user-name2</code></td>
+<td></td>
+</tr>
+<tr>
+<td>Grant the Shared Channel Manager role to a user</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>Shared Channel Manager</strong> role.</li><li>Under <strong>Assigned People</strong>, select <strong>Add People</strong>.</li><li>Search for and select the user name, then select <strong>Add</strong> to grant the Shared Channel Manager role to that user.</li></ol></td>
+<td colspan="2"><dl><dt><code>mmctl permissions role assign system_shared_channel_manager user-name</code></dt><dd><h3 id="section">|</h3></dd></dl></td>
+</tr>
+<tr>
+<td>Remove the System Manager role from a single user</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>System Manager</strong> role.</li><li>Under <strong>Assigned People</strong>, search for the user, then select <strong>Remove</strong>.</li></ol></td>
+<td><code>mmctl permissions role unassign system_manager bob-smith</code></td>
+<td></td>
+</tr>
+</tbody>
+</table>
+
+## Edit privileges of admin roles (advanced)
+
+System admins can grant read/write access to other areas of the System Console, as well as remove read/write access (including default access), for all system roles except the Custom Group Manager and Shared Channel Manager roles.
+
+There are two ways to assign roles:
+
+1.  In the System Console under **User Management \> Delegated Granular Administration**.
+2.  Using the [mmctl tool](/administration-guide/manage/mmctl-command-line-tool). This can be done either locally or remotely.
+
+<table style={{width: '100%'}}>
+<colgroup>
+<col style={{width: '18%'}} />
+<col style={{width: '49%'}} />
+<col style={{width: '31%'}} />
+</colgroup>
+<tbody>
+<tr>
+<td><strong>You want to</strong></td>
+<td><strong>Using the System Console</strong></td>
+<td><strong>Using mmctl</strong></td>
+</tr>
+<tr>
+<td>Edit role privileges</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>System Manager</strong>, <strong>User Manager</strong>, or <strong>Viewer</strong> role.</li><li>For each set of privileges, select the access level as <strong>Can edit</strong>, <strong>Read only</strong>, or <strong>No access</strong>.</li></ol><div class="note"><p>If you set privilege subsections to different access levels, then the privilege access level displays as <strong>Mixed Access</strong>.</p></div></td>
+<td><code>mmctl permissions add [role_name] [permission...]</code> <code>mmctl permissions reset system_read_only_admin</code></td>
+</tr>
+<tr>
+<td>Grant write access to the Authentication section of the System Console for all users with the User Manager role</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>User Manager</strong> role.</li><li>Under <strong>Privileges &gt; Authentication</strong> select <strong>Can edit</strong>, then select <strong>Save</strong>.</li></ol></td>
+<td><code>mmctl permissions add system_user_manager sysconsole_write_authentication</code></td>
+</tr>
+<tr>
+<td>Grant read-only access to the Authentication section of the System Console for all users with the User Manager role</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>. then select the <strong>User Manager</strong> role.</li><li>Under <strong>Privileges &gt; Authentication</strong> select <strong>Read only</strong>, then select <strong>Save</strong>.</li></ol></td>
+<td><code>mmctl permissions remove system_user_manager sysconsole_read_authentication</code></td>
+</tr>
+<tr>
+<td>Remove write access to the Authentication section of the System Console for all users with the User Manager role</td>
+<td><ol type="1"><li>Go to <strong>System Console &gt; User Management &gt; Delegated Granular Administration</strong>, then select the <strong>User Manager</strong> role.</li><li>Under <strong>Privileges &gt; Authentication</strong> select <strong>No access</strong>, then choose <strong>Save</strong>.</li></ol></td>
+<td><code>mmctl permissions remove system_user_manager sysconsole_write_authentication</code></td>
+</tr>
+<tr>
+<td>Reset a role to its default set of permissions</td>
+<td>This is completed using the mmctl tool only.</td>
+<td><code>mmctl permissions reset [role_name]</code> For example, to reset the permissions of the <code>system_read_only_admin</code> role: <code>mmctl permissions reset system_read_only_admin</code></td>
+</tr>
+</tbody>
+</table>
+
+## Admin roles and privileges
+
+#### Roles
+
+- `system_manager`
+- `system_user_manager`
+- `system_custom_group_admin`
+- `system_shared_channel_manager`
+- `system_read_only_admin`
+
+#### Privileges
+
+<table style={{width: '83%'}}>
+<colgroup>
+<col style={{width: '20%'}} />
+<col style={{width: '62%'}} />
+</colgroup>
+<thead>
+<tr>
+<th>System Console section</th>
+<th>Permissions</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>About</td>
+<td><blockquote><ul><li>PERMISSION_SYSCONSOLE_READ_ABOUT_EDITION_AND_LICENSE</li><li>PERMISSION_SYSCONSOLE_WRITE_ABOUT_EDITION_AND_LICENSE</li></ul></blockquote></td>
+</tr>
+<tr>
+<td>Reporting</td>
+<td><dl><dt><strong>System Statistics</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_REPORTING_SITE_STATISTICS</li><li>PERMISSION_SYSCONSOLE_WRITE_REPORTING_SITE_STATISTICS</li></ul></dd><dt><strong>Team Statistics</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_REPORTING_TEAM_STATISTICS</li><li>PERMISSION_SYSCONSOLE_WRITE_REPORTING_TEAM_STATISTICS</li></ul></dd><dt><strong>Server Logs</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_REPORTING_SERVER_LOGS</li><li>PERMISSION_SYSCONSOLE_WRITE_REPORTING_SERVER_LOGS</li></ul></dd></dl></td>
+</tr>
+<tr>
+<td>User Management</td>
+<td><dl><dt><strong>Users</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_USERMANAGEMENT_USERS</li><li>PERMISSION_SYSCONSOLE_WRITE_USERMANAGEMENT_USERS</li></ul></dd><dt><strong>Groups</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_USERMANAGEMENT_GROUPS</li><li>PERMISSION_SYSCONSOLE_WRITE_USERMANAGEMENT_GROUPS</li></ul></dd><dt><strong>Teams</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_USERMANAGEMENT_TEAMS</li><li>PERMISSION_SYSCONSOLE_WRITE_USERMANAGEMENT_TEAMS</li></ul></dd><dt><strong>Channels</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_USERMANAGEMENT_CHANNELS</li><li>PERMISSION_SYSCONSOLE_WRITE_USERMANAGEMENT_CHANNELS</li></ul></dd><dt><strong>Permissions</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_USERMANAGEMENT_PERMISSIONS</li><li>PERMISSION_SYSCONSOLE_WRITE_USERMANAGEMENT_PERMISSIONS</li></ul></dd></dl></td>
+</tr>
+<tr>
+<td>Environment</td>
+<td><dl><dt><strong>Web Server</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_WEB_SERVER</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_WEB_SERVER</li></ul></dd><dt><strong>Database</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_DATABASE</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_DATABASE</li></ul></dd><dt><strong>Elasticsearch</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_ELASTICSEARCH</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_ELASTICSEARCH</li></ul></dd><dt><strong>File Storage</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_FILE_STORAGE</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_FILE_STORAGE</li></ul></dd><dt><strong>Image Proxy</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_IMAGE_PROXY</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_IMAGE_PROXY</li></ul></dd><dt><strong>SMTP</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_SMTP</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_SMTP</li></ul></dd><dt><strong>Push Notification Server</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_PUSH_NOTIFICATION_SERVER</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_PUSH_NOTIFICATION_SERVER</li></ul></dd><dt><strong>High Availability</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_HIGH_AVAILABILITY</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_HIGH_AVAILABILITY</li></ul></dd><dt><strong>Rate Limiting</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_RATE_LIMITING</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_RATE_LIMITING</li></ul></dd><dt><strong>Logging</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_LOGGING</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_LOGGING</li></ul></dd><dt><strong>Session Lengths</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_SESSION_LENGTHS</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_SESSION_LENGTHS</li></ul></dd><dt><strong>Performance Monitoring</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_PERFORMANCE_MONITORING</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_PERFORMANCE_MONITORING</li></ul></dd><dt><strong>Developer</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_ENVIRONMENT_DEVELOPER</li><li>PERMISSION_SYSCONSOLE_WRITE_ENVIRONMENT_DEVELOPER</li></ul></dd></dl></td>
+</tr>
+<tr>
+<td>Site Configuration</td>
+<td><dl><dt><strong>Customization</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_CUSTOMIZATION</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_CUSTOMIZATION</li></ul></dd><dt><strong>Localization</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_LOCALIZATION</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_LOCALIZATION</li></ul></dd><dt><strong>Users and Teams</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_USERS_AND_TEAMS</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_USERS_AND_TEAMS</li></ul></dd><dt><strong>Notifications</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_NOTIFICATIONS</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_NOTIFICATIONS</li></ul></dd><dt><strong>Announcement Banner</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_ANNOUNCEMENT_BANNER</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_ANNOUNCEMENT_BANNER</li></ul></dd><dt><strong>Emoji</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_EMOJI</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_EMOJI</li></ul></dd><dt><strong>Posts</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_POSTS</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_POSTS</li></ul></dd><dt><strong>File Sharing and Downloads</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_FILE_SHARING_AND_DOWNLOADS</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_FILE_SHARING_AND_DOWNLOADS</li></ul></dd><dt><strong>Public Links</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_PUBLIC_LINKS</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_PUBLIC_LINKS</li></ul></dd><dt><strong>Notices</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_SITE_NOTICES</li><li>PERMISSION_SYSCONSOLE_WRITE_SITE_NOTICES</li></ul></dd></dl></td>
+</tr>
+<tr>
+<td>Authentication</td>
+<td><dl><dt><strong>Signup</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_AUTHENTICATION_SIGNUP</li><li>PERMISSION_SYSCONSOLE_WRITE_AUTHENTICATION_SIGNUP</li></ul></dd><dt><strong>Email</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_AUTHENTICATION_EMAIL</li><li>PERMISSION_SYSCONSOLE_WRITE_AUTHENTICATION_EMAIL</li></ul></dd><dt><strong>Password</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_AUTHENTICATION_PASSWORD</li><li>PERMISSION_SYSCONSOLE_WRITE_AUTHENTICATION_PASSWORD</li></ul></dd><dt><strong>MFA</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_AUTHENTICATION_MFA</li><li>PERMISSION_SYSCONSOLE_WRITE_AUTHENTICATION_MFA</li></ul></dd><dt><strong>AD/LDAP</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_AUTHENTICATION_MFA</li><li>PERMISSION_SYSCONSOLE_WRITE_AUTHENTICATION_MFA</li></ul></dd><dt><strong>SAML 2.0</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_AUTHENTICATION_SAML</li><li>PERMISSION_SYSCONSOLE_WRITE_AUTHENTICATION_SAML</li></ul></dd><dt><strong>OpenID Connect</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_AUTHENTICATION_OPENID</li><li>PERMISSION_SYSCONSOLE_WRITE_AUTHENTICATION_OPENID</li></ul></dd><dt><strong>Guest Access</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_AUTHENTICATION_GUEST_ACCESS</li><li>PERMISSION_SYSCONSOLE_WRITE_AUTHENTICATION_GUEST_ACCESS</li></ul></dd></dl></td>
+</tr>
+<tr>
+<td>Plugin</td>
+<td><blockquote><ul><li>PERMISSION_SYSCONSOLE_READ_PLUGINS</li><li>PERMISSION_SYSCONSOLE_WRITE_PLUGINS</li></ul></blockquote></td>
+</tr>
+<tr>
+<td>Integrations</td>
+<td><dl><dt><strong>Integration Management</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_INTEGRATIONS_INTEGRATION_MANAGEMENT</li><li>PERMISSION_SYSCONSOLE_WRITE_INTEGRATIONS_INTEGRATION_MANAGEMENT</li></ul></dd><dt><strong>Bot Accounts</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_INTEGRATIONS_BOT_ACCOUNTS</li><li>PERMISSION_SYSCONSOLE_WRITE_INTEGRATIONS_BOT_ACCOUNTS</li></ul></dd><dt><strong>GIF (Beta)</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_INTEGRATIONS_GIF</li><li>PERMISSION_SYSCONSOLE_WRITE_INTEGRATIONS_GIF</li></ul></dd><dt><strong>CORS</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_INTEGRATIONS_CORS</li><li>PERMISSION_SYSCONSOLE_WRITE_INTEGRATIONS_CORS</li></ul></dd></dl></td>
+</tr>
+<tr>
+<td>Compliance</td>
+<td><dl><dt><strong>Data Retention Policy</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_COMPLIANCE_DATA_RETENTION_POLICY</li><li>PERMISSION_SYSCONSOLE_WRITE_COMPLIANCE_DATA_RETENTION_POLICY</li></ul></dd><dt><strong>Compliance Export</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_COMPLIANCE_COMPLIANCE_EXPORT</li><li>PERMISSION_SYSCONSOLE_WRITE_COMPLIANCE_COMPLIANCE_EXPORT</li></ul></dd><dt><strong>Compliance Monitoring</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_COMPLIANCE_COMPLIANCE_MONITORING</li><li>PERMISSION_SYSCONSOLE_WRITE_COMPLIANCE_COMPLIANCE_MONITORING</li></ul></dd><dt><strong>Custom Terms of Service</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_COMPLIANCE_CUSTOM_TERMS_OF_SERVICE</li><li>PERMISSION_SYSCONSOLE_WRITE_COMPLIANCE_CUSTOM_TERMS_OF_SERVICE</li></ul></dd></dl></td>
+</tr>
+<tr>
+<td>Experimental</td>
+<td><dl><dt><strong>Features</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_EXPERIMENTAL_FEATURES</li><li>PERMISSION_SYSCONSOLE_WRITE_EXPERIMENTAL_FEATURES</li></ul></dd><dt><strong>Feature Flags</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_EXPERIMENTAL_FEATURE_FLAGS</li><li>PERMISSION_SYSCONSOLE_WRITE_EXPERIMENTAL_FEATURE_FLAGS</li></ul></dd><dt><strong>Bleve</strong></dt><dd><ul><li>PERMISSION_SYSCONSOLE_READ_EXPERIMENTAL_BLEVE</li><li>PERMISSION_SYSCONSOLE_WRITE_EXPERIMENTAL_BLEVE</li></ul></dd></dl></td>
+</tr>
+</tbody>
+</table>
+
+## Frequently Asked Questions
+
+#### Can a User Manager or System Manager reset an administrator’s email or password without their knowledge?
+
+This is not possible with the default privileges of these roles. The ability to reset passwords or email addresses of administrators is limited to system admins.
+
+#### Can a User Manager or System Manager access the configuration file?
+
+Yes. However, they will only have access to read actual values and modify values in accordance with their permissions. If appropriate read permissions do not exist, the default key values will be displayed.
+
+#### Are all actions of admin roles logged?
+
+Every change made by any admin is included in the audit log.
+
+#### Can a System Manager change their own permissions or elevate their role?
+
+No. System Managers can't elevate their role, and aren't able to elevate other members' roles.
+
+#### Can any of the new roles view API keys/passwords or other sensitive information within the System Console (such as SMTP, AWS, Elastic Search)?
+
+No, password information is only visible to system admins and is obfuscated for other roles.
+
+#### If download links for compliance exports are enabled in the System Console, can a Read Only Admin download the reports?
+
+Only roles that are explicitly granted access to **System Console \> Compliance** have access to download compliance reports.
+
+#### Can any of the new roles force-join Private channels?
+
+Yes at this time they can, however, we will be improving on this behavior in the future with a prompt that lets them know they are entering a private channel. We are also planning on adding a permission which would remove the ability to access Private channels.
+
+#### Can I create a new role or clone an existing role?
+
+No, but we are actively seeking feedback on this capability.
+
+#### Can I use an LDAP filter to assign these roles?
+
+No, but we are considering this functionality for a future enhancement.
+
+#### Can I rename the roles?
+
+This is being considered for future development.
+
+#### Can a System Manager or User Manager demote or deactivate another Admin or Manager?
+
+A System or User Manager can demote or deactivate another System or User Manager, but can't demote or deactivate a system admin.
+
+#### Can a System Manager or User Manager assign or unassign admin roles?
+
+Only the system admin has access to edit system roles.

docs/main/administration-guide/onboard/guest-accounts.mdx

@@ -0,0 +1,176 @@
+---
+title: "Guest accounts"
+---
+<PlanAvailability slug="all-commercial" />
+
+Guest accounts in Mattermost are a way to collaborate with individuals, such as vendors and contractors, outside of your organization by controlling their access to channels and team members. For example, guest accounts can be used to collaborate with customers on a support issue or work on a website project with resources from an external design firm.
+
+<Important>
+
+- A system admin must [enable guest access](/administration-guide/configure/authentication-configuration-settings#guest-access) before guests can be invited.
+- Mattermost Enterprise and Professional customers can [control who can invite guests](/administration-guide/onboard/advanced-permissions) in their organization. By default, only system admins can invite guests.
+- Guest accounts don't all consume a licensed seat in the same way. Guests in exactly one active channel are treated as single-channel guests and don't count toward the primary paid seat count. They're free up to a 1:1 ratio with licensed seats. Guests in multiple active channels continue to count as activated users for billing purposes. Direct messages and group messages don't affect whether a guest is counted as a single-channel guest. Only active channels count toward guest channel access for billing. Archived channels are excluded.
+- You'll identify guest users in Mattermost based on their **GUEST** badge next to their name and profile picture. Channels that contain guests also display the message **\*This channel has guests** in the channel header.
+
+</Important>
+
+## Guests account limits
+
+Guests can:
+
+- Pin messages to channels
+- Use slash commands (excluding restricted commands such as invite members, rename channels, change headers, etc)
+- Favorite channels
+- Mute channels
+- Update their profile
+- Use different authentication methods than other users
+- Leave channels to which they were added (including Town Square).
+
+Guests cannot:
+
+- Discover public channels
+- Join open teams
+- Create direct messages or group messages with members who aren’t within the same channel
+- Invite people
+- Create channel checklists
+
+## Guest authentication
+
+Guests can access the Mattermost server via email invitation, and be authenticated using AD/LDAP, SAML 2.0, or magic link passwordless authentication.
+
+Before you proceed, ensure that the authentication method you wish to use is correctly configured on your server and enabled in Mattermost. For configuration steps and technical documentation, see [Active Directory/LDAP setup](/administration-guide/onboard/ad-ldap) and [SAML Single-Sign-On](/administration-guide/onboard/sso-saml).
+
+Converting a member user to a guest won't change the channels they are in. However, they will be restricted from discovering additional channels and are unable to direct message/group message users outside of the channels they are in. They can be added to channels by system admins and other roles that have the correct permissions to invite guests.
+
+### Configure magic links for guests
+
+<PlanAvailability slug="entry-ent" />
+
+From Mattermost v11.3, magic links allow guest users to access Mattermost without a password by using a secure link sent to their email address. This provides a streamlined passwordless authentication option for guest users.
+
+To configure magic link authentication for guests:
+
+1.  Ensure [guest access is enabled](/administration-guide/configure/authentication-configuration-settings#enable-guest-magic-link-authentication) in **System Console \> Authentication \> Guest Access**.
+2.  Set **Enable passwordless authentication for guests using magic links via email** to **True**.
+3.  Select **Save**.
+
+When a guest is initially invited to Mattermost, they will receive an email with a link that allows them to log in without a password. The link expires in 48 hours for security purposes. When that guest returns to Mattermost and enters their email address, Mattermost sends them a new link to their email address that expires in 5 minutes. See the [magic link login for guests](/end-user-guide/access/access-your-workspace#magic-link-login-for-guests) documentation for details on how guests can use magic links to log in.
+
+### Configure AD/LDAP authentication
+
+When enabled, the **Guest Filter** in Mattermost identifies external users whose AD/LDAP role is `guest` and who are invited to join your Mattermost server. These users will have the `guest` role applied immediately upon first login instead of the default member user role. This eliminates having to manually assign the role in the System Console.
+
+1.  Go to **System Console \> Authentication \> Guest Access** to enable guest access.
+2.  Go to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP wizard, navigate to the **User Filters** section, then expand **Configure additional filters**.
+3.  Complete the **Guest Filter** field.
+4.  Select **Save**.
+
+If a Mattermost guest user has the `guest` role removed in the AD/LDAP system, the synchronization process will not automatically promote them to a member user role. This is done manually via **System Console \> User Management**. If a member user has the **Guest Attribute** added, the synchronization processes will automatically demote the member user to the guest role.
+
+When a guest logs in without having any channels assigned to their account, they're advised to talk to a Mattermost system admin.
+
+### Configure SAML 2.0 authentication
+
+When enabled, the **Guest Attribute** in Mattermost identifies external users whose SAML assertion is guest and who are invited to join your Mattermost server. These users will have the `guest` role applied immediately upon first login instead of the default member user role. This eliminates having to manually assign the role in the System Console.
+
+If a Mattermost guest user has the guest role removed in the SAML system, the synchronization processes will not automatically promote them to a member user role. This is done manually via **System Console \> User Management**. If a member user has the **Guest Attribute** added, the synchronization processes will automatically demote the member user to the guest role.
+
+1.  Go to **System Console \> Guest Access** to enable guest access.
+2.  Go to **System Console \> Authentication \> SAML 2.0**.
+3.  Complete the **Guest Attribute** field.
+4.  Select **Save**.
+
+When a guest logs in without having any channels assigned to their account, they're advised to talk to a Mattermost system admin.
+
+## Manage guests
+
+See the following documentation to learn more about managing guests:
+
+- [invite people](/end-user-guide/collaborate/invite-people) to teams and channels
+- [manage channel members](/end-user-guide/collaborate/manage-channel-members#remove-other-members-from-a-channel)
+- [remove people from teams](/end-user-guide/collaborate/organize-using-teams#remove-people-from-teams)
+
+<Tip>
+
+You can also use the `/kick` or `/remove` slash commands to remove a guest from a channel.
+
+</Tip>
+
+When a guest has been removed from all channels within a team, and if they belong to other teams, they will default into the last channel on the last team they have accessed. If they are removed from all channels on all teams, they'll be taken to a screen letting them know they have no channels assigned.
+
+### Promote and demote user roles
+
+System admins can demote a user from a member to a guest by updating the user's role in **System Console \> User Management \> Users**. Select the member, then select **Demote to Guest**. All system and custom roles assigned to the demoted user are removed. System admins should also purge all of the demoted guest's sessions by selecting the guest user, then selecting **Revoke Sessions**.
+
+The demoted guest user retains their existing channel and team memberships, but is restricted from discovering public channels and collaborating with users outside of the channels they're in. This is useful if you're already collaborating with external contractors, and want to restrict their abilities within Mattermost.
+
+System admins can also promote a guest to member by updating their role in **System Console \> User Management \> Users**. Select the guest, then select **Promote to Member**.
+
+<Note>
+
+You can filter the list in **System Console \> User Management \> Users** to view **Guests (all)**, **Guests in a single channel**, or **Guests in multiple channels**.
+
+</Note>
+
+### Disable guest accounts
+
+To disable the guest accounts feature, go to **System Console \> Authentication \> Guest Access**, then set **Enable Guest Access** to **False**. To deactivate individual guest accounts, go to **System Console \> User Management \> Users**. Select a user, then select **Deactivate**. You can re-activate individual guest accounts by selecting **Activate**.
+
+- When a single guest account is deactivated or the guest account feature is disabled, guests are marked as `deactivated`, are logged out of Mattermost, and all guest sessions are revoked. In Mattermost Server versions prior to 5.18, disabling the guest account feature leaves current guest accounts as activated until they are manually deactivated.
+- If you're using AD/LDAP and the guest access setting is disabled, the `guest` filter and existing guest users in System Console are deactivated. Additionally, no new guests can be invited or added using the filter as an authentication method. If a previous guest's credentials match the user filter (the only filter which is active when guest access is disabled), they will be reactivated and promoted to a member user upon their next login.
+- Similarly, for SAML, when the guest access setting is disabled, the `guest` attribute and existing guest users in System Console are deactivated. Additionally, no new guests can be invited or added using the attribute as an authentication method. If a previous guest's credentials match the user attribute (the only attribute which is active when guest access is disabled), they will be reactivated and promoted to a member user upon their next login.
+
+You can disable individual guest accounts in **System Console \> User Management** via **Manage Members**. When a single guest account is disabled or the feature is disabled, the guest will be marked as `deactivated`, be logged out of Mattermost, and all their sessions will be revoked.
+
+### Reinstate guest accounts
+
+When guest access is re-enabled for AD/LDAP, the `guest` filter is reinstated.
+
+New users matching the `guest` filter will be authenticated as new guest users on login.
+
+Previous guest users will be activated with the next synchronization. If their credentials still match the `guest` filter, they will retain their guest status. If they no longer match the `guest` filter but do match the `user` filter, they will be not be promoted to member user automatically on login - this must be done manually. If a previous guest was reactivated as a member user when guest access was disabled, and now are identified by the `guest` filter once again, they will automatically be demoted to Guest upon their login.
+
+Similarly, for SAML, when guest access is re-enabled, the SAML `guest` attribute is reinstated. New users matching the `guest` attribute will be authenticated as new guest users on login.
+
+Previous guest users will be activated with the next synchronization. If their credentials still match the `guest` attribute, they will retain their guest status. If they no longer match the `guest` attribute but do match the `user` filter, they will be not be promoted to member user automatically on login - this must be done manually. If a previous guest was reactivated as a member user when guest access was disabled, and now are identified by the `guest` attribute once again, they will automatically be demoted to guest upon their login.
+
+## Frequently asked questions
+
+### How am I charged for guest accounts?
+
+Guest billing depends on how many channels a guest can access:
+
+- Guests in exactly one active channel are treated as single-channel guests. They don't count toward the primary paid seat count and are free up to a 1:1 ratio with your licensed seats.
+- Guests in multiple active channels continue to count as activated users.
+- Direct messages and group messages don't change whether a guest is treated as a single-channel guest.
+- Only active channels count toward guest channel access for billing. Archived channels are excluded.
+
+If your single-channel guest count exceeds the 1:1 allowance, Mattermost shows soft warnings to system admins. Guest creation and guest access aren't blocked.
+
+### Why doesn’t Mattermost have single-channel guests?
+
+Mattermost now supports single-channel guests.
+
+Guests who belong to exactly one active channel are counted separately from your primary paid seat count and are free up to a 1:1 ratio with licensed seats. Guests who belong to multiple active channels continue to count as activated users. Direct messages and group messages don't change whether a guest is treated as a single-channel guest. Only active channels count toward guest channel access for billing. Archived channels are excluded.
+
+If the number of single-channel guests exceeds the 1:1 allowance, Mattermost shows dismissible warning indicators to system admins on the relevant reporting and license pages. Mattermost doesn't block adding guests or starting the server when this limit is exceeded.
+
+### Can I set an expiration date for guests?
+
+Currently, you cannot. This feature may be added at a later stage.
+
+### Can MFA be applied selectively?
+
+If MFA is enforced for your users, it can be applied to guest accounts. Guests can configure MFA in by going to their profile picture and selecting **Profile \> Security**. If MFA is not enforced for your users, it can't be applied to guest accounts.
+
+### Has the guest accounts feature been reviewed by an external security firm?
+
+The guest account feature was reviewed by the Mattermost security team. We do not have an external firm review scheduled but will include this feature in future reviews.
+
+### How can I validate my guests' identity?
+
+Guests can be authenticated via SAML and/or AD/LDAP to ensure that only the named guest can log in. Alternatively, you can whitelist domains via **System Console \> Authentication \> Guest Access \> Whitelisted Guest Domains**.
+
+### Can I restrict guests' ability to upload content?
+
+It is not currently possible to selectively disable upload/download functionality as it is a server-wide configuration.

docs/main/administration-guide/onboard/managing-team-channel-membership-using-ad-ldap-sync-groups.mdx

@@ -0,0 +1,106 @@
+---
+title: "Manage team and channel membership with AD/LDAP sync groups"
+---
+<PlanAvailability slug="ent-plus" />
+
+Mattermost groups created with [synchronized AD/LDAP groups](/administration-guide/onboard/ad-ldap-groups-synchronization) can be used to manage the membership of private teams and private channels. When a team or private channel is managed by synchronized groups, users will be added and removed based on their membership to the synchronized AD/LDAP group.
+
+For instance, you may have an AD/LDAP group that contains your development team that you want to synchronize to a developer team. By using this feature, new developers will get added to the team when they are added to the synchronized AD/LDAP group and they will be removed from the team when removed from the AD/LDAP group.
+
+Similarly, you may have an AD/LDAP group that contains your leadership team that you want to synchronize to a private channel for coordination and updates. This feature will help control the membership of the channel so that users outside of the synchronized group are prevented from being added to the channel mistakenly.
+
+On teams that are managed by synchronized groups, users outside of the group are restricted from:
+
+> - Invitation through a team invite link
+> - Invitation through an email invite
+
+Similarly on private channels that are managed by synchronized groups, users outside of the group are restricted from:
+
+> - Invitation through a mention
+> - Invitation through the `/invite` slash command
+> - Being added to the channel with **Add members**
+
+Users can remove themselves from teams and private channels managed by synchronized groups.
+
+## Managing membership of a team or channel with synchronized groups
+
+To manage membership of a private team with synchronized groups:
+
+1.  Navigate to **System Console \> User Management \> Teams**.
+2.  Select the team you want to manage with group synchronization.
+3.  Under **Team Management**, enable **Sync Group Members**. If **Anyone can join this team** is enabled or if specific email domains are set, they will be disabled by the sync group members feature.
+4.  Add one or more groups to the team. If there are groups already associated to default users into the team, they will already be present.
+5.  Review the notice in the footer of the screen for any users that are not part of groups who will be removed from the team on the next synchronization.
+6.  Select **Save**. Members will be updated on the next scheduled AD/LDAP synchronization.
+
+Alternatively you can use the mmctl tools to set the team to be managed by groups:
+
+1.  Ensure there's at least one group already associated to the team. You can view and add default teams to a group via **System Console \> User Management \> Groups \> Group Configuration**. See the [mmctl group team list](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-team-list) documentation for more information on adding default teams and channels and confirming whether if there is already a group associated to the team.
+2.  Ensure **Team Settings \> General \> Allow any user with an account on this server to join this team** is set to `No`.
+3.  Convert the team to have its membership managed by synchronized groups by running the [mmctl group team enable](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-team-enable) command.
+
+To manage membership of a private channel with synchronized groups:
+
+1.  Navigate to **System Console \> User Management \> Channels**.
+2.  Select the channel you want to manage with group synchronization.
+3.  Under **Channel Management**, enable **Sync Group Members**. Please ensure the channel is set to `private`.
+4.  Add one or more groups to the channel. If there are groups already associated to default users in the channel, they'll already be present.
+5.  Review the notice in the footer of the screen for any users that are not part of groups who will be removed from the channel on the next synchronization.
+6.  Select **Save**. Members will be updated on the next scheduled AD/LDAP synchronization.
+
+Alternatively you can use the mmctl tool to set a private channel to be managed by groups:
+
+1.  Ensure there's at least one group already associated to the channel. You can view and add default channels to a group via **System Console \> User Management \> Groups \> Group Configuration**. See our [AD/LDAP](/administration-guide/onboard/ad-ldap-groups-synchronization#add-default-teams-or-channels-for-the-group) documentation for more information on adding default teams and channels. Additionally, you can use the mmctl to view if there is already a group associated to the channel by running the [mmctl group channel list](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-channel-list) command.
+2.  Convert the team to have its membership managed by synchronized groups by running the [mmctl group channel enable](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-channel-enable) command.
+
+## Add or remove groups from teams
+
+Once the management of the team is converted to be managed by synchronized groups, a team admin or system admin can add additional groups from **Main Menu \> Add Groups to Team**. This will add users on the next AD/LDAP synchronization and any new users to the group will be added to the team on subsequent synchronizations. Team admins will be prevented from changing the team to public by enabling **Team Settings \> Allow any user with an account on this server to join this team**.
+
+Team admins or system admins can also remove groups from a team from **Main Menu \> Manage Groups**. This will disassociate the group from the team. Users are removed on the next AD/LDAP synchronization.
+
+The system admin can also remove groups from **System Console \> User Management \> Teams \> Team Configuration \> Synced Groups**.
+
+## Add or remove groups from private channels
+
+Once the management of the channel is converted to be managed by synchronized groups, a team admin or system admin can add additional groups from **Channel Menu \> Add Groups to Channel**. This will add users on the next AD/LDAP synchronization and any new users to the group will be added to the channel on subsequent synchronizations.
+
+Team admins and system admins can also remove groups from a team from **Main Menu \> Manage Groups**. This will disassociate the group from the team. Users are removed on the next AD/LDAP synchronization.
+
+The system admin can also remove groups from **System Console \> User Management \> Channels \> Channel Configuration \> Synced Groups**.
+
+## Managing members
+
+Users are automatically removed from the team or private channel when removed from a synchronized AD/LDAP group that is managing the membership of that team or channel. Additionally, users who are not in the synchronized groups are prevented from being added through the `/invite` and mention flows within a channel.
+
+A user can remove themselves from the team or from the private channel when it is managed by synchronized groups. They can be added back by users who have permission to manage members for a team or private channel by using the `/invite` slash command or by mentioning the user in a channel.
+
+If the user is removed from a synchronized group and later readded to the group, they can be manually added back to the team or private channel as noted above.
+
+<Note>
+
+Users will not be automatically added back by the AD/LDAP synchronization once they remove themselves or are removed by the LDAP synchronized group.
+
+</Note>
+
+## Disabling group synchronized management of teams and private channels
+
+To remove the management of members by synchronized groups in a team, disable **Sync Group Members** under **System Console \> User Management \> Teams \> Team Management**, or run the [mmctl group team disable](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-team-disable) command.
+
+To remove the management of members by synchronized groups in a channel, disable **Sync Group Members** under **System Console \> User Management \> Channels \> Channel Management**, or run the [mmctl group channel disable](/administration-guide/manage/mmctl-command-line-tool#mmctl-group-channel-disable) command.
+
+## Frequently asked questions
+
+**Why aren’t public channels supported with this feature?**
+
+Public channels are available to all members to discover and join. Managing membership with synchronized groups removes the ability for public channels to be accessible to users on the team. Private channels typically require a more controlled membership management, which is why this feature applies to Private channels. Groups can be assigned to public teams and public channels as described in [this documentation](/administration-guide/onboard/ad-ldap-groups-synchronization#add-default-teams-or-channels-for-the-group).
+
+**Does a team with its membership managed by groups have any effect on Public channel access?**
+
+Only users that are members of groups synchronized to team are able to discover and join public channels. Private channels can also be managed by synchronized groups when a team is managed by synchronized groups.
+
+**Why don't users get readded to teams or channels once they have been removed from and then later re-added to the LDAP group?**
+
+The implementation of group removals does not currently differentiate between users who have removed themselves or have been removed by the LDAP synchronization process. Our design optimizes for users who have removed themselves from a team or channel. In the future, we may add the ability for admins to re-add users who have been removed, and even prevent users from leaving a team or channel.
+
+Additionally, LDAP users who aren't accessible to Mattermost based on filters will be removed from the groups and from group-synced teams and channels. If they were removed from teams and channels then they will not be re-added to those teams and channels upon becoming subsequently re-accessible to Mattermost.

docs/main/administration-guide/onboard/migrate-from-rocketchat.mdx

@@ -0,0 +1,303 @@
+---
+title: "Migrate from Rocket.Chat"
+---
+<PlanAvailability slug="all-commercial" />
+
+## Overview
+
+Mattermost provides a migration path from Rocket.Chat, bringing your users, channels, messages, threads, direct messages, reactions, and file attachments into a self-hosted Mattermost environment.
+
+Rocket.Chat has no hosted "export workspace" feature. Instead, you export the underlying MongoDB database with `mongodump` and transform that dump into a Mattermost bulk import file using the `mmetl` tool. This means the export step is a database operation that typically requires access to the Rocket.Chat server and its MongoDB instance.
+
+The migration is a multi-step process:
+
+1.  [Preparations](#1-preparations) — scope the migration, gather MongoDB and attachment-storage details, and prepare the Mattermost server.
+2.  [Export your Rocket.Chat data](#2-export-your-rocketchat-data) — produce a `mongodump` of the Rocket.Chat database.
+3.  [Transform the export](#3-transform-the-export-for-mattermost) — validate with `mmetl check rocketchat` and convert with `mmetl transform rocketchat`.
+4.  [Import into Mattermost](#4-import-into-mattermost) — upload and process the archive with `mmctl`.
+5.  [Validate, test, and go live](#5-validate-test-and-go-live) — verify the trial import before scheduling the production cutover.
+
+<Note>
+
+These instructions describe a *best effort* migration designed to preserve the majority of your messages, files, and channel structure. Manual adjustments are often required, and larger deployments should plan for multiple trial runs in a staging environment before a production import. Consider [talking to a Mattermost expert](https://mattermost.com/contact-sales/) if your organization needs migration support.
+
+</Note>
+
+## 1. Preparations
+
+This guide assumes you already have a Mattermost server deployed and ready to accept your data. If not, review the [deployment documentation](/deployment-guide/server/deploy-server#deployment-options) first.
+
+### Scope definition
+
+- **Data history**: Decide how much history you need. Because `mongodump` captures the whole database, scoping is done mainly through what you migrate and validate rather than by trimming the export.
+- **Export size**: The size of your Rocket.Chat database and attachments directly affects processing and import time. Plan for longer iteration cycles on large deployments.
+- **File attachments**: Consider excluding very large or non-critical attachments with `--skip-attachments` for early test runs to speed up iteration.
+
+### Rocket.Chat / MongoDB prerequisites
+
+- You need access to the Rocket.Chat MongoDB instance and the `mongodump` tool from the [MongoDB Database Tools](https://www.mongodb.com/docs/database-tools/).
+- Identify the database name (commonly `meteor`) and the connection URI.
+- The transform reads these collections from the dump: `users`, `rocketchat_room`, `rocketchat_message`, and `rocketchat_subscription` (all required), plus `rocketchat_uploads` and `rocketchat_uploads.chunks` (for attachments).
+
+<Note>
+
+This tool was validated against **Rocket.Chat v8.5**. Rocket.Chat changes its MongoDB schema between versions, so exports from other versions may parse differently. If you hit unexpected parse errors, check for a newer `mmetl` release before assuming the export is at fault.
+
+</Note>
+
+### Attachment storage: GridFS vs. FileSystem
+
+Rocket.Chat can store uploaded files in one of two ways. Confirm which your deployment uses (**Admin \> Settings \> File Upload \> Storage Type**) before you export, because it changes how you run the transform:
+
+- **GridFS** (stored inside MongoDB): attachments are captured directly in the `mongodump` (`rocketchat_uploads.chunks.bson`) and extracted automatically. No extra flag needed.
+- **FileSystem** (stored on disk): the `mongodump` contains only file metadata. You must also copy the Rocket.Chat uploads directory and point `--uploads-dir` at it during the transform.
+
+### Infrastructure considerations
+
+- **Test environment**: Always run the migration in a development or staging environment first. Most migrations require several iterations.
+- **Operating system**: `mmetl` is supported on Linux and macOS. Windows (including WSL) is not recommended.
+- **Storage requirements**: Ensure you have room for the `mongodump` output, the transformed import file, and the extracted attachments. Plan for several times the size of your Rocket.Chat data.
+- **File storage**: Imports into AWS S3 (or S3-compatible storage) typically complete faster than local or NFS storage for large datasets.
+
+### Mattermost server considerations
+
+- **Fresh server**: The most reliable imports happen on a fresh installation. If importing into an existing server, never import over an existing team, and back up the database and data directory first.
+- **Server version**: Run the latest supported version of [Mattermost](/product-overview/mattermost-server-releases).
+- **The target team must already exist** in Mattermost and be set to **Public Team**.
+- **Configuration settings**: Before importing, adjust:
+  - `TeamSettings.MaxChannelsPerTeam` and `TeamSettings.MaxUsersPerTeam`: set well above the number of channels/users you are migrating.
+  - `EmailSettings.EnableSignUpWithEmail` and `EmailSettings.EnableSignInWithEmail`: both `true`.
+  - `FileSettings.MaxFileSize`: higher than the largest file in your export.
+  - `ElasticsearchSettings.EnableIndexing`, `EnableSearching`, and `EnableAutocomplete`: set to `false` during the import, then purge and reindex afterward.
+
+## 2. Export your Rocket.Chat data
+
+Export the Rocket.Chat MongoDB database with `mongodump`. Replace the URI and database name to match your deployment:
+
+``` sh
+mongodump --uri="mongodb://localhost:3001/meteor" --out=/tmp/rc-dump
+```
+
+This creates a subdirectory named after the database (for example `/tmp/rc-dump/meteor`) containing the `.bson` files. That database subdirectory — not the parent — is what you pass to `--dump-dir` in the next step.
+
+If your deployment uses **FileSystem** storage for attachments, also copy the Rocket.Chat uploads directory to a known location so you can reference it with `--uploads-dir`.
+
+## 3. Transform the export for Mattermost
+
+[Download the latest release of mmetl](https://github.com/mattermost/mmetl/releases/) for your OS and architecture. Run `mmetl help` to learn more about the tool.
+
+### Validate the export
+
+Before transforming, check the integrity of the dump:
+
+``` sh
+./mmetl check rocketchat --dump-dir /tmp/rc-dump/meteor
+```
+
+This reports structural issues (for example, missing required collections or invalid records) that would cause the transform or import to fail. Details are written to `check-rocketchat.log`.
+
+`check rocketchat` accepts the same `--guest-handling` flag as the transform, so you can preview how guest users will be treated before running the full transform.
+
+### Run the transform
+
+Convert the dump into a Mattermost bulk import file. Replace `<TEAM-NAME>` with your Mattermost team name, which must be one word and lowercase (a team named `My Team` becomes `my-team`):
+
+``` sh
+./mmetl transform rocketchat --team <TEAM-NAME> --dump-dir /tmp/rc-dump/meteor --output mattermost_import.jsonl
+```
+
+For **FileSystem** attachment storage, add `--uploads-dir`:
+
+``` sh
+./mmetl transform rocketchat --team <TEAM-NAME> --dump-dir /tmp/rc-dump/meteor --uploads-dir /path/to/rocketchat/uploads --output mattermost_import.jsonl
+```
+
+The tool produces a [.jsonl](https://jsonlines.org/examples) file containing your users, channels, and posts, plus a `data` folder containing the extracted attachments.
+
+A successful run ends with a summary line in `transform-rocketchat.log` like:
+
+``` text
+Transformation succeeded! Users: 152, Public channels: 48, Private channels: 12, Posts: 39184
+```
+
+If the run stops with an error instead — for example, `the RocketChat export contains bot users but --bot-owner was not specified` — no valid import file is produced. Resolve the error (see the flags below) and re-run.
+
+<Tip>
+
+**Iterate incrementally.** Run a small trial first: transform, import into a fresh or restored trial target, and confirm a few channels look right before committing to a full production import. Re-running the same import avoids duplicate posts only when the records' identity fields are unchanged; not every imported entity is deduplicated. Don't rely on re-importing into a modified trial target to reset it.
+
+</Tip>
+
+### Useful transform flags
+
+- `--uploads-dir <PATH>`: Path to the Rocket.Chat FileSystem uploads directory. Required when attachments are not stored in GridFS.
+- `--bot-owner <USERNAME>`: Username of the Mattermost user who will own all imported bots. **Required if the export contains any bot users** — the transform errors out otherwise.
+- `--guest-handling <MODE>`: How to migrate Rocket.Chat guest users (default `guest`):
+  - `guest` — migrate them as Mattermost guests. Highest fidelity, but the destination server must have Guest Accounts **licensed** (Professional/Enterprise) and **enabled** (`GuestAccountsSettings.Enable`); otherwise the accounts won't behave correctly.
+  - `user` — migrate them as regular Mattermost members. Works everywhere, but grants guests full member permissions.
+  - `skip` — drop guest users entirely, along with their memberships and authored posts.
+- `--skip-attachments` / `-a`: Skip extracting file attachments. Useful for faster iteration while testing.
+- `--attachments-dir <PATH>`: Directory for extracted attachments (default `data`).
+- `--default-email-domain <DOMAIN>`: When a user's email is missing, generate one from their username and this domain (for example `example.com`).
+- `--skip-empty-emails`: Allow users with empty emails. Note that this produces invalid import data that must be corrected before importing.
+- `--debug`: Emit `DEBUG`-level detail to `transform-rocketchat.log` to help diagnose slow or failing runs.
+
+## 4. Import into Mattermost
+
+Package the `.jsonl` file and `data` folder into a single zip:
+
+``` sh
+zip -r mattermost-bulk-import.zip data mattermost_import.jsonl
+```
+
+Validate the archive locally before uploading:
+
+``` sh
+mmctl import validate ./mattermost-bulk-import.zip
+```
+
+Ensure `mmctl` is installed and [authenticated](/administration-guide/manage/mmctl-command-line-tool#mmctl-auth). Then choose an upload method.
+
+### Standard upload
+
+For most imports, upload through `mmctl`:
+
+``` sh
+mmctl import upload ./mattermost-bulk-import.zip
+mmctl import list available
+```
+
+Process the import using the name returned by `import list available`:
+
+``` sh
+mmctl import process <IMPORT FILE NAME>
+```
+
+Check the job status. If it shows `pending`, wait and re-run. The `--json` flag is required to see error messages:
+
+``` sh
+mmctl import job show <JOB ID> --json
+```
+
+### Large imports (file store method)
+
+For large archives (multiple GB), uploading through `mmctl` is slow and error-prone. Instead, place the archive directly into the server's import directory and let the server process it in place:
+
+1.  Copy `mattermost-bulk-import.zip` (with a unique name) into `data/import` in the Mattermost file store — the local data directory, or the `import` prefix of your S3 bucket.
+2.  Run `mmctl import list available` to confirm the server sees the file.
+3.  Run `mmctl import process <IMPORT FILE NAME>` and monitor with `mmctl import job show <JOB ID> --json`.
+
+This avoids re-uploading gigabytes through the API and is the recommended path for large migrations.
+
+### Fixing unread channels and threads
+
+After importing, messages may appear unread for all users. The following fix is for PostgreSQL deployments only.
+
+<Important>
+
+Back up the Mattermost database before running these statements. Test the backup and the SQL in a non-production environment first.
+
+</Important>
+
+``` sql
+begin;
+UPDATE channelmembers
+SET
+    msgcount = channels.totalmsgcount,
+    lastupdateat = channels.lastpostat,
+    lastviewedat = channels.lastpostat,
+    msgcountroot = channels.totalmsgcountroot
+FROM channels
+WHERE channelmembers.channelid = channels.id;
+
+INSERT INTO preferences (UserId, Category, Name, Value)
+SELECT
+    cm.userid,
+    'channel_approximate_view_time',
+    cm.channelid,
+    cm.lastupdateat::text
+FROM
+    channelmembers cm
+ON CONFLICT (userid, category, name)
+DO UPDATE SET
+    Value = EXCLUDED.Value;
+
+update preferences set value = 'false' where category = 'direct_channel_show';
+update preferences set value = 'false' where category = 'group_channel_show';
+
+commit;
+```
+
+### Placeholder emails and account activation
+
+Mattermost accounts are created from the emails and usernames in the export. Where an email is missing, a placeholder (for example `username@local`) is generated and must be corrected by a system administrator. Search the final `.jsonl` file for placeholder emails before importing.
+
+Users activate their accounts through Mattermost's **Password Reset** screen using their email address:
+
+- **Imports performed by a system administrator**: emails are automatically verified, and users can reset their password immediately.
+- **Imports performed by a non-administrator**: users must verify their email address before resetting their password.
+
+See how to [migrate user authentication to LDAP or SAML](/administration-guide/manage/mmctl-command-line-tool#mmctl-user-migrate-auth) if you use SSO.
+
+## 5. Validate, test, and go live
+
+Before production cutover, validate a fresh or restored trial import end to end:
+
+1.  Compare the transform and import logs with source counts for users, channels, posts, and attachments, and investigate errors or unexpected omissions.
+2.  Sign in as representative users and verify public and private channels, direct and group messages, threads, reactions, files, mentions, permissions, and authentication.
+3.  Recreate integrations and custom emoji, then purge and rebuild the search index before testing search.
+4.  Back up the production Mattermost database and file store, schedule a maintenance window, stop writes in Rocket.Chat, create a final export, and repeat the validated process on a fresh or restored production target.
+5.  After final verification, update DNS or client configuration, invite users to activate their accounts, and keep the Rocket.Chat deployment read-only until the migration is accepted.
+
+## What migrates and what doesn't
+
+For core collaboration data — posts, threads, reactions, attachments, users, and channels — you can expect high fidelity. Integrations and Rocket.Chat-specific features do not carry over.
+
+| Content type | Migrates? | Notes |
+|----|----|----|
+| Posts and threads | Yes | Rocket.Chat threads become Mattermost threaded replies. Oversized posts are split into continuation replies rather than truncated. |
+| Public channels | Yes | Display name, purpose (description), and header (topic) are preserved. |
+| Private channels | Yes |  |
+| Discussions | Yes (converted) | Rocket.Chat discussions are converted to standalone Mattermost channels (public or private, matching the discussion's visibility). The parent-child relationship is not preserved. |
+| 1:1 direct messages | Yes | Map directly. Self-DMs are preserved as a direct channel with yourself. |
+| Group DMs (3–8 members) | Yes (converted) | Become Mattermost **Group Messages** — functionally equivalent, different terminology. |
+| Group DMs (over 8 members) | Converted | Mattermost group messages support at most 8 members, so larger group DMs are converted to **private channels**. |
+| Reactions | Yes | Emoji skin-tone modifiers are stripped to a default rendering. Custom emoji require matching names (see below). |
+| File attachments | Yes | From GridFS or FileSystem storage. Auto-generated thumbnails are skipped to avoid duplicates. |
+| Users | Yes | Inactive Rocket.Chat users are imported as deactivated accounts. |
+| Bots | Yes | Reassigned to the `--bot-owner` user. |
+| Channel mentions | Best effort | `#channel` references are translated to Mattermost `~channel` links where the channel exists. |
+| Join / leave / add / remove events | Yes | Converted to Mattermost system messages. |
+| Custom emoji images | No | Reaction *names* are preserved, but the emoji images are not imported (see below). |
+| Guest users | Configurable | Controlled by `--guest-handling` (default `guest`). By default, Rocket.Chat guest accounts are imported as Mattermost [guest users](/administration-guide/onboard/guest-accounts) — this requires Guest Accounts to be **licensed** (Professional/Enterprise) and [guest access](/administration-guide/configure/authentication-configuration-settings#guest-access) enabled on the target server. Use `--guest-handling user` to import them as regular members instead (no guest licensing needed), or `--guest-handling skip` to drop them entirely. |
+| Encrypted (E2E) channels | No | End-to-end encrypted rooms are skipped entirely, including their messages. |
+| Apps, integrations, slash commands, webhooks | No | Recreate using Mattermost [integrations](/integrations-guide/integrations-guide-index). |
+| Avatars, user status, custom profile fields | No | Users update their profiles in Mattermost after import. |
+| Pinned/starred messages, topic-change and mute events | No | These Rocket.Chat-specific records are not migrated. |
+
+### Custom emoji
+
+Custom emoji images are **not** imported with your messages — only the emoji *names* used in reactions are preserved. A reaction is stored as text (`:emoji-name:`) and resolved at render time:
+
+- If a custom emoji with the same name exists in Mattermost, the reaction renders correctly.
+- If not, it shows as a placeholder until the emoji is added.
+
+Because resolution happens at render time, you can add custom emoji to Mattermost **at any time** — before or after the import — and reactions on historical messages will render once a matching name exists. Names must match exactly.
+
+## FAQ
+
+**Do I need to create users before importing?** No. `mmetl` and the import process handle user creation and ordering automatically.
+
+**What happens if I run the same import twice?** Re-running the same import avoids duplicate posts when identity fields are unchanged, but not every entity is deduplicated and edits to identifying fields can create additional records. Use a fresh or restored trial target for each test run.
+
+**Where do all my channels and DMs go?** Into the single team you specify with `--team`. Rocket.Chat has no multi-workspace concept, so there is no team-mapping step.
+
+**How are attachments stored, and why do I need `--uploads-dir`?** Rocket.Chat stores files either in MongoDB (GridFS) or on disk (FileSystem). GridFS files are captured in the `mongodump` automatically; FileSystem files are not, so you point `--uploads-dir` at the uploads directory. See [Attachment storage](#attachment-storage-gridfs-vs-filesystem).
+
+**Why are some channels missing after import?** End-to-end encrypted rooms are skipped and their messages are not migrated. Check `transform-rocketchat.log` for skipped rooms.
+
+**Do I need to import custom emoji before messages?** No. Emoji resolve at render time, so you can add them whenever.
+
+**How do I handle a very large import?** Use the file store method — copy the archive directly into the server's `data/import` directory rather than uploading through `mmctl`. See [Large imports](#large-imports-file-store-method).
+
+**I hit a parse error. Is my export broken?** Possibly not. Rocket.Chat changes its MongoDB schema between versions (this tool was validated against v8.5). Run `mmetl check rocketchat` first, and check for a newer `mmetl` release before assuming the data is at fault.

docs/main/administration-guide/onboard/migrate-from-slack.mdx

@@ -0,0 +1,416 @@
+---
+title: "Migrate from Slack"
+---
+<PlanAvailability slug="all-commercial" />
+
+## Overview
+
+Mattermost provides a reliable migration path from Slack, enabling you to bring your organization’s collaboration history into a secure, self-hosted Mattermost environment. The migration process supports full workspaces, including users, channels and message history, direct messages, and threads so your teams can continue working without losing valuable context.
+
+This process generally involves preparing your environment, exporting data from Slack, converting that data into a compatible format, and then importing it into Mattermost. Migrating from Slack is a multi-step process that can be complex, particularly for larger organizations or those with multiple Slack workspaces.
+
+Additionally, please consider that Slack's data control policies or export capabilities may change at any time, or they may charge fees to customers for exporting data stored in Slack. Support for negotiating export of customer IP from Slack Enterprise can be requested by contacting a [Mattermost Expert](https://mattermost.com/contact-sales/).
+
+1.  [Preparations](#1-preparations):
+    - Answer key scoping questions.
+    - Gather environment and export details.
+    - Validate Mattermost server capacity and configuration.
+    - Back up your Mattermost environment before importing.
+2.  [Export Slack data](#2-export-slack-data):
+    - Generate an export from Slack.
+3.  [Transform the export for Mattermost](#3-transform-the-export-for-mattermost):
+    - Validate the Slack export using `mmetl check slack`.
+    - Use the `mmetl` tool to parse and transform Slack exports.
+4.  [Import into Mattermost](#4-import-data-into-mattermost):
+    - Upload and process transformed archives with `mmctl`.
+5.  Validate and test:
+    - Confirm channel and user data imported correctly.
+    - Run database queries to fix any unread states.
+6.  Go live:
+    - Communicate the cutover plan to users.
+
+### Migration timeline
+
+These instructions outline a *best effort* migration path designed to preserve the majority of your messages, files, and workspace structure. Mattermost provides tools and guidance to help streamline the process, but manual adjustments during the data transformation and import steps are often required. Successful migration depends on careful planning and dedicating sufficient time, technical resources, and technical skills to the effort.
+
+Depending on the size and complexity of your Slack environment, a full migration can take anywhere from several days to multiple weeks of dedicated effort. Larger organizations with multiple workspaces, extensive message history, and many files should expect the process to require significant iteration and testing before completion. It’s important to plan for this timeline in advance by allocating the necessary resources, scheduling time for trial imports in a development environment, and coordinating across teams. Building in extra time for adjustments during the transformation and import steps will help ensure a smoother transition and reduce disruption to your users.
+
+Scoping the migration appropriately during the preparation step can significantly reduce processing time and allow for faster iteration. Before beginning, carefully consider what data is essential to bring over to Mattermost. Many organizations find that not every channel or file needs to be migrated, and focusing only on what is truly needed can save substantial processing time and manual effort. By setting clear boundaries early, you’ll minimize the amount of data that requires manual intervention and testing, which in turn shortens the migration timeline and helps avoid unnecessary complexity.
+
+<Note>
+
+Consider [talking to a Mattermost expert](https://mattermost.com/contact-sales/) if your organization needs support migrating from Slack to Mattermost.
+
+</Note>
+
+## Migrations Steps
+
+### 1. Preparations
+
+Before beginning the migration, it’s important to properly prepare your environment. Careful preparation helps reduce processing time, allows for faster iteration, and minimizes the chance of running into avoidable issues during the import.
+
+This document assumes you already have a Mattermost Server deployed that is ready to accept your Slack data. If not, consider the recommendations in this section in conjunction with the appropriate [deployment documentation](/deployment-guide/server/deploy-server#deployment-options) to make informed decisions about your supporting database and file storage infrastructure.
+
+#### Scope definition
+
+Start by defining the scope of your migration:
+
+- **Slack edition**: Migrating from Slack Enterprise Grid involves additional [steps and planning](#faq).
+- **Data history**: Decide how much history is necessary to import. Importing a smaller time window (e.g., the last six months) can significantly reduce complexity and processing time.
+- **Export size**: Consider the size of your Slack export file as you progress through this guide. File size directly impacts how long the import will take - for example, files under ~25 GB often complete within a day, while exports over 100 GB can take several days, significantly lengthening the time between iterations and the overall timeline to complete the migration.
+- **File attachments**: Consider whether you can exclude very large or non-critical attachments (for example, public software download packages, videos, or outdated media assets) to reduce import size and speed up processing.
+
+#### Infrastructure considerations
+
+The environment where you run the import can significantly affect performance:
+
+- **Test environment**: Always run the migration in a development or staging environment first. Most migrations require multiple iterations before a production import is successful.
+- **Operating system**: The `mmetl` tool is supported on Linux and macOS. Windows is not supported, and we do not recommend using Windows Subsystem for Linux (WSL) since the file system is not performant enough for the heavier processes involved in migration.
+- **Storage requirements**: Ensure your server can store both the Slack export archive and the fully unpacked data. As a best practice, plan for at least three times the size of your Slack export in available server storage.
+- **File Storage**: Imports into S3 file storage typically complete faster than imports into local storage or NFS. For large imports, we recommend using AWS S3 or another S3-compatible storage service for best performance.
+
+#### Mattermost server considerations
+
+Carefully preparing your environment and making these adjustments up front will help ensure the migration proceeds smoothly and reduces the need for repeated trial-and-error.
+
+- **Fresh server**: The most reliable imports happen on a fresh Mattermost installation. If importing into an existing server, never import over an existing team.
+- **Server version**: Make sure you are running the latest supported version of [Mattermost](/product-overview/mattermost-server-releases) to benefit from the most up-to-date functionality and fixes.
+- **Backups**: When importing into an already existing Mattermost environment, back up both the Mattermost database and the data directory before starting. If an import fails, you’ll need to roll back or reset.
+  - If merging multiple Slack workspaces into a single team is the desired end-result, we recommend completing the import to separate teams, validating the results, then using [mmctl](/administration-guide/manage/mmctl-command-line-tool#mmctl-channel-move) to move channels between teams.
+- **Configuration settings**: Adjust the following settings before starting the import:
+  - `TeamSettings.MaxChannelsPerTeam`: Set this to a number much higher than the number of channels you are migrating.
+  - `TeamSettings.MaxUsersPerTeam`: Set this to a number much higher than the number of users you are migrating.
+  - **Team Settings \> Allow any user with an account on this server to join this team**: Ensure this is enabled for the team receiving the import.
+  - `EmailSettings.EnableSignUpWithEmail` and `EmailSettings.EnableSignInWithEmail`: Both must be set to `true`
+  - `FileSettings.MaxFileSize`: Set this higher than the largest file in your Slack export.
+  - `ElasticsearchSettings.EnableIndexing`, `ElasticsearchSettings > EnableSearching` and `ElasticsearchSettings.EnableAutocomplete`: All must be set to `false` during the import to prevent performance issues. After the import, you can purge and reindex before enabling Elasticsearch.
+
+### 2. Export Slack data
+
+Slack offers two ways to [export your data from their product](https://slack.com/help/articles/201658943-Export-your-workspace-data).
+
+1.  **Public channels export** - Contains only public channel messages and file links. Available on all Slack plans. Generate this from **Slack \> Admin \> Workspace settings \> Security \> Import & export data \> Export**.
+2.  **All channels and conversations export** - Contains all messages including public channels, private channels, DMs, and group messages. Available on Business+ (requires application approval from the workspace primary owner) and Enterprise Grid plans.
+
+You will receive a zip file containing the following contents:
+
+- Channels (`channels.json`)
+- Users (`users.json`)
+- Direct messages (`dms.json`) (All channels export)
+- Private channels (`groups.json`) (All channels export)
+- Group direct messages (`mpims.json`) (All channels export)
+- App activity logs (`integration_logs.json`)
+- Folders containing posts for every public channel
+- Folders containing posts for every private channel (All channels export)
+
+<Note>
+
+- Refer to the [Slack help article](https://slack.com/help/articles/220556107-How-to-read-Slack-data-exports) for additional details on zip file contents.
+- As a proprietary SaaS service, Slack is able to change its export format quickly and without notice.
+- Workspaces on the Slack Free plan can only export file links from the last 90 days.
+
+</Note>
+
+<Important>
+
+Avoid unzipping and rezipping the Slack export. Doing so can modify the directory structure of the archive which could cause issues with the import process.
+
+</Important>
+
+### 3. Transform the export for Mattermost
+
+Now that you have a Slack export file, let's convert it into Mattermost's bulk import format using the import preparation tool `mmetl`.
+
+[Download the latest release of mmetl](https://github.com/mattermost/mmetl/releases/) for your OS and architecture. Run `mmetl help` to learn more about using the tool.
+
+#### Validate the Slack export
+
+Before transforming, validate the integrity of your Slack export using the `mmetl check` command:
+
+``` sh
+./mmetl check slack --file <SLACK EXPORT FILE>
+```
+
+This checks for structural issues in the export archive and reports any problems that may cause the transform or import to fail.
+
+#### Run the transform
+
+Run the command below to create a Mattermost bulk import file. Replace `<TEAM-NAME>` with the name of your team in Mattermost. Note that the name needs to be one word and lowercase (i.e. if you named your team `My Team`, `<TEAM-NAME>` would be `my-team`).
+
+<Note>
+
+The team must already exist on your Mattermost server before importing, and **Allow any user with an account on this server to join this team** must be enabled for that team.
+
+</Note>
+
+``` sh
+./mmetl transform slack --team <TEAM-NAME> --file <SLACK EXPORT FILE> --output mattermost_import.jsonl
+```
+
+The tool outputs a [.jsonl](https://jsonlines.org/examples) file containing all of your users, channels, and posts. It also creates a `data` folder that contains all of your attachments. It doesn't matter what you name the `.jsonl` file. You can name it what you want with the `--output` flag as shown above. It just needs to be a `.jsonl` file.
+
+#### Useful transform flags
+
+The `mmetl transform slack` command supports several optional flags that can help with common migration scenarios:
+
+- `--skip-attachments` / `-a`: Skip copying attachments from the import file. Useful for faster iteration when testing the import process before including attachments.
+- `--allow-download` / `-l`: Allow downloading attachments from URLs.
+- `--default-email-domain <DOMAIN>`: When a user's email is missing from the export, generate one from their username and the provided domain (e.g., `--default-email-domain example.com`).
+- `--skip-empty-emails`: Allow users with empty email addresses to be included in the output. Note that this results in invalid import data that will need to be manually corrected before importing.
+- `--discard-invalid-props` / `-p`: Discard posts with invalid properties. By default, such posts are kept but imported without their properties.
+
+#### Debug transform
+
+The `mmetl transform` process produces a `transform-slack.log` file that records INFO level output by default.
+
+If you run the import commands with the `--debug` flag, the log will include additional `DEBUG` level entries. These entries provide more granular detail on each phase of the process, which can help identify where the transformation may be slowing down or failing.
+
+#### MMETL parsing phases
+
+When parsing a Slack export file with the `mmetl` tool, the process runs through four phases. You can track progress by monitoring the log output during each phase. Understanding these phases helps set expectations for how long the parsing step may take.
+
+**1. Reading the import file**
+
+In this phase, `mmetl` reads through the Slack export file. Example log line:
+
+`&#123;"file":"parse.go:359","level":"info","msg":"Processing file 1 of 10335: aluminum-white-lightbulb/","time":"2024-03-11T20:41:09-04:00"&#125;`
+
+This step usually takes 5–10 minutes depending on the size of the export archive.
+
+**2. Converting user mentions**
+
+During this phase, `mmetl` converts Slack user mentions into Mattermost-compatible format. Example log line:
+
+`&#123;"file":"parse.go:224","level":"debug","msg":"Slack Import: converting user mentions for channel touchscreen-headphones-sleek. 1 of 400","time":"2024-03-11T20:41:10-04:00"&#125;`
+
+This step can be time-consuming on large imports and may take several hours.
+
+**3. Converting channel mentions**
+
+In this phase, channel references are updated. Example log line:
+
+`&#123;"file":"parse.go:259","level":"debug","msg":"Slack Import: converting channel mentions for channel robust-smart-home-device-matrix. 95 of 400","time":"2024-03-11T20:41:48-04:00"&#125;`
+
+This step typically completes in about half the time required for user mentions.
+
+**4. Converting post markup**
+
+Finally, Slack message formatting is converted into Mattermost-compatible Markdown. Example log line:
+
+`&#123;"file":"parse.go:330","level":"debug","msg":"Slack Import: converting markdown for channel vertex-robust-vacuum. 120 of 400","time":"2024-03-11T20:41:58-04:00"&#125;`
+
+This is the fastest step and usually completes quickly.
+
+### 4. Import data into Mattermost
+
+You can upload the export through Mattermost's API from the server or from another computer using mmctl commands. The server will save the import in its file store before running the import (e.g. AWS S3), so there will be time spent uploading/downloading the file in this case.
+
+The migration is idempotent, meaning that you can run multiple imports that contain the same posts, and there won't be duplicated created posts in Mattermost. Each post is imported with the correct user/author and `created_at` value from your Slack instance.
+
+Ensure you have the Mattermost command line tool `mmctl` installed. This allows you to perform different tasks that communicate to Mattermost's API. You'll also want to [configure authentication](/administration-guide/manage/mmctl-command-line-tool#mmctl-auth) for the tool.
+
+To prepare our files to be uploaded to the server, we need to put both the `.jsonl` file and `data` folder together into a zip file.
+
+``` sh
+zip -r mattermost-bulk-import.zip data mattermost_import.jsonl
+```
+
+Validate the import file locally before uploading. This checks the file structure and content without needing to upload it to the server:
+
+``` sh
+mmctl import validate ./mattermost-bulk-import.zip
+```
+
+Then we can upload the zip file to our Mattermost server. These files can be very large, so getting them onto the server can be challenging. You have two primary options for this step:
+
+- You can use the `mmctl` tool:
+
+  ``` sh
+  mmctl import upload ./mattermost-bulk-import.zip
+  ```
+
+- Alternatively, you can move the file directly to the data directory under `data/import` and give it a unique name.
+
+Run this command to list the available imports:
+
+``` sh
+mmctl import list available
+```
+
+Run this command to process the import. Replace `<IMPORT FILE NAME>` with the name you got from the `mmctl import list available` command:
+
+``` sh
+mmctl import process <IMPORT FILE NAME>
+```
+
+Finally, run this command to view the status of the import process job. If the job status shows as `pending`, then wait before running the command again. The `--json` flag is required to view the possible error message. Replace `<JOB ID>` with the id you got from the `mmctl import job list` command:
+
+``` sh
+mmctl import job show <JOB ID> --json
+```
+
+#### Debug imports
+
+You can use the `mmctl import job show` command to view any relevant errors that may have occurred.
+
+#### Fixing unread channels and threads
+
+After importing, all messages may appear as unread for users. To resolve this issue, run the following SQL queries directly against the Mattermost database:
+
+``` sql
+begin;
+UPDATE channelmembers
+SET
+    msgcount = channels.totalmsgcount,
+    lastupdateat = channels.lastpostat,
+    lastviewedat = channels.lastpostat,
+    msgcountroot = channels.totalmsgcountroot
+FROM channels
+WHERE channelmembers.channelid = channels.id;
+
+INSERT INTO preferences (UserId, Category, Name, Value)
+SELECT
+    cm.userid,
+    'channel_approximate_view_time',
+    cm.channelid,
+    cm.lastupdateat
+FROM
+    channelmembers cm
+ON CONFLICT (userid, category, name)
+DO UPDATE SET
+    Value = EXCLUDED.Value;
+
+update preferences
+  set value = false
+  where category = 'direct_channel_show';
+
+update preferences
+  set value = false
+  where category = 'group_channel_show';
+
+commit;
+```
+
+#### Address placeholder emails
+
+During the import process, the emails and usernames from Slack are used to create new Mattermost accounts. If emails are not present in the Slack export archive, then placeholder values will be generated and the system admin will need to update these manually. We recommend administrators search the final import `jsonl` file for `user` lines with `@example.com` in the email property to address and resolve the missing information prior to import.
+
+### Email verification behavior
+
+The email verification process during Slack import depends on who performs the import:
+
+**System administrator imports:**
+
+- Email addresses are automatically verified during the import process.
+- Users can immediately use the **Password Reset** feature to set their password.
+- No email verification steps are required before password reset.
+
+**Non-administrator imports:**
+
+- Email addresses remain unverified after import.
+- Users must first verify their email addresses before they can reset their password.
+- Additional email verification steps are required before account access.
+
+### Account activation
+
+- Slack users activate their new Mattermost accounts by using Mattermost's **Password Reset** screen with their email addresses from Slack to set new passwords for their Mattermost accounts. See the instructions on how to [migrate user authenticatation to LDAP or SAML](/administration-guide/manage/mmctl-command-line-tool#mmctl-user-migrate-auth).
+  - For imports performed by System Admins: Users can immediately use the **Password Reset** feature (no email verification is required).
+  - For imports performed by non-administrators: Users must first verify their email addresses, then use the **Password Reset** feature.
+- Once logged in, Mattermost users will have access to previous Slack messages in the public channels imported from Slack.
+
+## FAQ
+
+What additional considerations are there for Slack Enterprise Grid? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Slack Enterprise Grid combines multiple workspaces under a single management plane and the associated export reflects that complexity. An Enterprise Grid export is a single archive containing all workspaces and shared channels.
+
+Mattermost does not support shared channels between teams, so Slack Shared Channels must be mapped to a single team in Mattermost. We can create this mapping by determining the originating teams in Slack and creating a `team.json` mapping file for use with `mmetl`. Because of the manual effort required to identify and map team IDs, Enterprise Grid migrations are typically more time-consuming than single-workspace migrations. Plan additional time and resources to complete this step successfully.
+
+#### Export structure
+
+At the root level, you’ll see shared channels that span across Slack workspaces, and under `/teams/` you’ll find per-workspace data such as channels and users files. A typical structure looks like:
+
+``` text
+Enterprise Grid Export/
+├── channel1/
+│   ├── 2023-01-01.json
+│   └── 2023-01-02.json
+├── channel2/
+│   ├── 2023-05-01.json
+│   └── 2023-05-02.json
+├── teams/
+│   ├── team1/
+│   │   ├── channel3/
+│   │   │   ├── 2023-05-01.json
+│   │   │   └── 2023-05-02.json
+│   │   ├── channels.json
+│   │   ├── mpims.json
+│   │   ├── dms.json
+│   │   ├── users.json
+│   │   └── groups.json
+│   └── team2/
+│       ├── channel4/
+│       │   ├── 2023-05-01.json
+│       │   └── 2023-05-02.json
+│       ├── channels.json
+│       ├── mpims.json
+│       ├── dms.json
+│       ├── users.json
+│       └── groups.json
+├── channels.json
+├── org_users.json
+├── mpims.json
+├── dms.json
+└── groups.json
+```
+
+#### Mapping shared channels to Mattermost teams
+
+1.  Download the full Enterprise Grid export from Slack.
+2.  To determine where each shared channel belongs in Mattermost, look for a `team` attribute on the first post in each shared channel. These `team` values map the channel back to its originating workspace in Slack. This is where each shared channel will live in Mattermost once imported.
+
+> ``` json
+> &#123;
+>   "client_msg_id": "",
+>   "type": "",
+>   "text": "",
+>   "user": "U1",
+>   "ts": "1695219722.430309",
+>   "blocks": [  ],
+>   "team": "team1",
+>   "user_team": "team1",
+>   "source_team": "team1",
+>   "user_profile": &#123; &#125;
+> &#125;,
+> ```
+
+3.  Create a `teams.json` file that maps Slack team IDs to each `team` attribute you found above. For example:
+
+> ``` json
+> &#123;
+>     "T0001" : "team1",
+>     "T0002" : "team2"
+> &#125;
+> ```
+
+4.  Run the `mmetl grid-transform` command to split the Enterprise Grid export into per-team files:
+
+> ``` bash
+> ./mmetl grid-transform -f slackexport.zip -t teams.json
+> ```
+
+This process outputs a new archive for each team defined in `teams.json`. Once split, you can continue the standard Mattermost import process on each file.
+
+### Are there features of Slack that are not supported for migration to Mattermost?
+
+The Slack import process focuses on preserving core collaboration data such as messages, files, channels, and users. However, certain Slack features are not supported by the Mattermost product and thus will not be migrated using the import tools in this document:
+
+- **Slack apps and integrations**: Installed apps, bots, slash commands, webhooks, workflow builder and other integrations do not migrate. Most integrations supported by Slack can be recreated using the [integration and automation](/integrations-guide/integrations-guide-index) options in Mattermost.
+- **Starred conversations**: Starred conversations are not preserved.
+- **User groups**: User groups from Slack are not preserved, however they can be recreated in Mattermost using the [Custom Groups](/end-user-guide/collaborate/organize-using-custom-user-groups) feature.
+- **Threaded conversations**: Slack threads are mostly supported, however some threading relationships may not always be preserved given the differences in how Mattermost and Slack threading works.
+- **Canvases**: Canvases are not supported in Mattermost and will not be migrated.
+- **User presence and profiles**: User status (online/away), profile pictures, and custom profile fields do not carry over. Users will need to update their profiles in Mattermost.
+- **Channel memberships for deactivated users**: Deactivated or deleted Slack users are not migrated to Mattermost.
+
+Because of these limitations, some manual reconfiguration is typically required after the import, especially for workflows and integrations. Support from a [Mattermost expert is available](https://mattermost.com/contact-sales/) for your Slack migration.

docs/main/administration-guide/onboard/migrate-gitlab-omnibus.mdx

@@ -0,0 +1,131 @@
+---
+title: "Migrate from GitLab Omnibus to standalone Mattermost"
+---
+## Overview
+
+GitLab has announced the [deprecation of Mattermost from the GitLab Omnibus package](https://docs.gitlab.com/update/deprecations/#mattermost-bundled-with-linux-package) with GitLab 19.0. As part of this transition, GitLab will continue to support Mattermost **up to version 10.11 ESR** within the Omnibus installation until the final removal date.
+
+To ensure continuity and long-term support, organizations using Mattermost within GitLab Omnibus should plan to migrate to a **standalone Mattermost installation**. This approach provides ongoing access to the latest Mattermost releases, security updates, and enterprise capabilities independent of GitLab’s release cycle.
+
+Migrating to a standalone deployment also enables greater flexibility in managing infrastructure, upgrading PostgreSQL, and scaling Mattermost independently to meet performance and compliance requirements.
+
+## Prerequisites
+
+Before you begin:
+
+- Administrative (root or sudo) access to the GitLab Omnibus server.
+- A new standalone **PostgreSQL** server prepared and accessible.
+- Sufficient disk space for the Mattermost database dump.
+- A planned maintenance window, as Mattermost downtime is required.
+- A current full backup of your Mattermost instance, including database and file storage.
+
+## Migration Steps
+
+Follow the steps below to safely migrate from GitLab Omnibus to a standalone Mattermost installation.
+
+<Note>
+
+The following procedure assumes your Mattermost database name is `mattermost_production` and your PostgreSQL user is `mmuser`. Adjust as needed for your environment.
+
+</Note>
+
+### Step 1: Create a Database Dump from GitLab Omnibus
+
+Use the GitLab Omnibus PostgreSQL tools to create a dump of the Mattermost database. Run this command on the GitLab server:
+
+``` bash
+sudo gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql --no-owner mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz
+```
+
+This will create a compressed SQL dump file of your Mattermost database.
+
+### Step 2: Prepare the New PostgreSQL Server
+
+Set up your new PostgreSQL server following the official [Mattermost database preparation guidelines](/deployment-guide/server/prepare-database). This includes:
+
+- Installing the correct PostgreSQL version supported by your Mattermost server.
+- Creating a new Mattermost database and user with appropriate permissions.
+
+### Step 3: Transfer and Restore the Database Dump
+
+Transfer the database dump file to your new PostgreSQL server, then restore it:
+
+``` bash
+zcat /tmp/mattermost_dbdump.sql.gz | psql -U mmuser -d mattermost
+```
+
+Verify that the database restoration completes successfully without errors.
+
+### Step 4: Update Mattermost Configuration
+
+On your standalone Mattermost server, update the `config.json` file to point to the new PostgreSQL server. Locate the `SqlSettings.DataSource` parameter and update it as follows:
+
+``` json
+"SqlSettings": {
+    "DriverName": "postgres",
+    "DataSource": "postgres://mmuser:password@new-postgres-server:5432/mattermost?sslmode=disable&connect_timeout=10"
+}
+```
+
+Ensure that credentials, hostnames, and connection settings match your new PostgreSQL configuration.
+
+### Step 5: Migrate the Mattermost Application and Data
+
+To move Mattermost application files from the GitLab server to a new standalone server:
+
+1.  **Install the same or newer version** of Mattermost on the new server. See [Deploy the Mattermost server](/deployment-guide/server/deploy-server#deployment-options).
+
+2.  **Copy your existing configuration and data** from the GitLab Omnibus instance:
+
+    ``` bash
+    # On the GitLab server
+    sudo cp /var/opt/gitlab/mattermost/config/config.json /tmp/
+    sudo cp -r /var/opt/gitlab/mattermost/data /tmp/mattermost_data
+
+    # Transfer to new Mattermost server
+    scp /tmp/config.json mattermost@new-server:/opt/mattermost/config/
+    scp -r /tmp/mattermost_data mattermost@new-server:/opt/mattermost/data/
+    ```
+
+3.  Ensure permissions are correctly set on the new server:
+
+    ``` bash
+    sudo chown -R mattermost:mattermost /opt/mattermost
+    ```
+
+### Step 6: Start Mattermost
+
+Start the Mattermost service on your new standalone installation:
+
+``` bash
+sudo systemctl start mattermost
+```
+
+Mattermost will now connect to your standalone PostgreSQL database.
+
+### Step 7: Verify the Migration
+
+After starting Mattermost, perform the following checks:
+
+- Confirm that Mattermost starts successfully with no database connection errors.
+- Review server logs for any startup or connection issues.
+- Log into Mattermost and verify that all teams, channels, and users are present.
+- Post test messages and upload files to confirm functionality.
+- Validate user authentication and permissions.
+- Confirm that database queries are directed to the new PostgreSQL server.
+
+## Important Considerations
+
+- Always maintain a **full backup** of your Mattermost database before migration.
+- Schedule a **maintenance window** to minimize user disruption.
+- Validate performance and monitoring configurations post-migration.
+- Ensure that your new PostgreSQL server follows Mattermost’s security and tuning best practices.
+
+## Troubleshooting
+
+If you encounter errors during the migration:
+
+- Review PostgreSQL logs for permission or connection issues.
+- Verify that the Mattermost PostgreSQL user has full access to the restored database.
+- Ensure that the `config.json` file contains the correct database connection string.
+- Restart the Mattermost service and check `mattermost.log` for detailed errors.

docs/main/administration-guide/onboard/migrating-to-mattermost.mdx

@@ -0,0 +1,77 @@
+---
+title: "Migration guide"
+---
+<PlanAvailability slug="all-commercial" />
+
+Migrations help you move your Mattermost deployment or data from one environment to another with minimal disruption. Whether you’re transitioning your Mattermost server to new infrastructure, restructuring your database, or moving from another collaboration platform like Slack, this guide provides step-by-step instructions for each supported path. Use the sections below to quickly find the scenario that matches your needs and follow the recommended process to ensure a smooth migration.
+
+To change the database or container images an existing deployment runs on, see [data export and infrastructure migration](/administration-guide/manage/admin/migration) instead.
+
+[Book a live demo](https://mattermost.com/request-demo/) or [talk to a Mattermost expert](https://mattermost.com/contact-sales/) to explore tailored solutions for your organization's secure collaboration needs. Or try Mattermost yourself with a [1-hour preview](https://mattermost.com/sign-up/) for instant access to a live sandbox environment.
+
+## Move Mattermost to a new server
+
+The following instructions migrate Mattermost from one server to another by backing up and restoring the Mattermost database and `config.json` file. For these instructions, `SOURCE` refers to the Mattermost server *from which* your system will be migrated and `DESTINATION` refers to the Mattermost server *to which* your system will be migrated.
+
+1.  Back up your SOURCE Mattermost server. See [Backup and Disaster Recovery documentation](/deployment-guide/backup-disaster-recovery).
+2.  Upgrade your SOURCE Mattermost server to the latest major build version. See [Upgrading Mattermost Server documentation](/administration-guide/upgrade/upgrading-mattermost-server).
+3.  Install the latest major build of Mattermost server as your `DESTINATION`.
+
+> - Make sure your new instance is properly configured and tested. The database type (MySQL or PostgreSQL) and version of `SOURCE` and `DESTINATION` deployments need to match.
+> - Stop the `DESTINATION` server using `sudo stop mattermost`, then back up the database and `config.json` file.
+
+4.  Migrate database from `SOURCE` to `DESTINATION`. Backup the database from the `SOURCE` Mattermost server and restore it in place of the database to which the `DESTINATION` server is connected.
+5.  Migrate `config.json` from `SOURCE` to `DESTINATION`. Copy `config.json` file from `SOURCE` deployment to `DESTINATION`.
+6.  If you use local storage (`FileSettings.DriverName` is set to `local`), migrate `./data` from `SOURCE` to `DESTINATION`.
+
+> - Copy the `./data` directory from `SOURCE` deployment to `DESTINATION`.
+> - If you use a directory other than `./data`, copy that directory instead.
+
+7.  Start the `DESTINATION` deployment by running `sudo start mattermost`. Then go to the **System Console**, make a minor change, and save it to upgrade your `config.json` schema to the latest version using default values for any new settings added.
+8.  Test that the system is working by going to the URL of an existing team. You may need to refresh your Mattermost browser page in order to get the latest updates from the upgrade.
+
+Once your migration is complete and verified, you can optionally [upgrade the Team Edition of Mattermost to Enterprise Edition using the upgrade guide](/administration-guide/upgrade/upgrading-mattermost-server#upgrade-team-edition-to-enterprise-edition).
+
+## Move from Slack
+
+See the [Migrate from Slack](/administration-guide/onboard/migrate-from-slack) documentation for details on migrating from Slack to Mattermost.
+
+## Move from Rocket.Chat
+
+See the [Migrate from Rocket.Chat](/administration-guide/onboard/migrate-from-rocketchat) documentation for details on migrating from Rocket.Chat to Mattermost.
+
+## Move from Jabber
+
+BrightScout helped a major U.S. Federal Agency rapidly migrate from Jabber to Mattermost and open sourced their Extract, Transform and Load (ETL) tool at [https://github.com/Brightscout/mattermost-etl](https://github.com/Brightscout/mattermost-etl). Read more about their [case study](https://mattermost.com/blog/u-s-federal-agency-migrates-from-jabber-to-mattermost-the-open-source-way/) online.
+
+## Move from Pidgin
+
+In some cases, people are using Pidgin clients with different backends to communicate. To continue using Pidgin with a Mattermost backend, consider using [Mattermost ETL tool](https://github.com/Brightscout/mattermost-etl), created by BrightScout, to migrate data from your existing backend into Mattermost.
+
+Then use the [Pidgin-Mattermost plugin](https://github.com/EionRobb/purple-mattermost) (complete with an installer for end user machines) to continue to support legacy Pidgin users while offering a whole new Mattermost experience on web, mobile, and PC.
+
+## Move from Bitnami
+
+Bitnami uses MySQL, and renames the Mattermost database tables by converting the names to all lower case. For example, in non-Bitnami installations, the Users table is named `Users`, but in Bitnami, the table is `users` (with a lowercase `u`). As a result, when you migrate your data from Bitnami to a non-Bitnami installation, you must modify the MySQL startup script so that it starts MySQL in lowercase table mode.
+
+You can modify the script by adding the `--lower-case-table-names=1` switch to the MySQL start command. The location of the start-up script generally depends on how you installed MySQL, whether by using the package manager for the operating system, or by manually installing MySQL. You must modify the start-up script before migrating the data.
+
+For more information about letter case in MySQL table names and the `--lower-case-table-names` switch, see the [Identifier Case Sensitivity](https://dev.mysql.com/doc/refman/5.7/en/identifier-case-sensitivity.html) topic in the MySQL documentation.
+
+## Move from bespoke messaging solutions
+
+Mattermost is often selected to replace bespoke solutions by IT and DevOps teams as a stable, enterprise-grade, commercially-supported solution on an open source platform that meets and exceeds the flexibility and innovation of bespoke solutions.
+
+Migrating from bespoke messengers to Mattermost can be challenging. Because of the difficulty of upgrading and maintaining bespoke solutions, the format for storing data is unpredictable, and the community around any single legacy release is small.
+
+If your data in the bespoke messenger is vital, consider:
+
+1.  [Mattermost bulk import tool](/administration-guide/onboard/bulk-loading-data): Use the Mattermost bulk import tool to ETL from your bespoke system to Mattermost.
+2.  [Mattermost ETL framework from BrightScout](https://github.com/Brightscout/mattermost-etl): Consider the Mattermost ETL framework from BrightScout to custom-configure an adapter to plug in to the bulk import tool mentioned above.
+3.  **Legacy Slack import:** If you only recently switched from Slack to a bespoke tool, consider going back to import the data and users from the old Slack instance directly into Mattermost, leveraging the extensive support for Slack-import provided.
+4.  **Export to Slack, then import to Mattermost:** [Export Flowdock, Campfire, Chatwork, Hall, or CSV files to Slack](https://slack.com/help/articles/217872578-Import-data-from-one-Slack-workspace-to-another) and then export to a Slack export file and import the file into Mattermost.
+
+If your data in the bespoke messenger is not vital, consider:
+
+1.  **Parallel systems:** Running Mattermost in parallel with your bespoke system until the majority of workflow and collaboration has moved to Mattermost
+2.  **Hard switch:** Announce a "hard switch" to Mattermost after a period of time of running both systems in parallel. Often this has been done due to security concerns in bespoke products or products nearing end-of-life.

docs/main/administration-guide/onboard/migration-announcement-email.mdx

@@ -0,0 +1,33 @@
+---
+title: "Migration announcement email"
+---
+<PlanAvailability slug="all-commercial" />
+
+To notify your end users of your migration to Mattermost, we created a sample email template that you can use.
+
+Remember to replace all the items in bold with your information.
+
+## Email template
+
+To: End users
+
+Subject: Moving to Mattermost
+
+Hi all,
+
+As some of you already know, we are moving from **\[System\]** to Mattermost as our collaboration platform. We have imported our existing users and data into Mattermost so we can continue to communicate, share files and collaborate.
+
+To get started:
+
+1.  Open a browser on your computer, go to **\[Mattermost URL\]** and select “I forgot my password” to set your new password for Mattermost using the email address you used on the previous system.
+2.  Once you reset your password, use your email and new password to log in.
+3.  [Download](https://mattermost.com/apps) the Mattermost apps for desktop and mobile. Refer to the [Use Mattermost](/end-user-guide/end-user-guide-index) end user documentation on how to get up and running quickly.
+4.  Remember to bookmark the URL so you can use it to log in next time!
+
+Questions?
+
+If you have any questions, feel free to post in the **\[~Mattermost channel\]** or email us at **\[Support email\]**.
+
+Happy collaborating!
+
+**\[Sign-off\]**

docs/main/administration-guide/onboard/multi-factor-authentication.mdx

@@ -0,0 +1,44 @@
+---
+title: "Multi-factor authentication"
+---
+<PlanAvailability slug="all-commercial" />
+
+Multi-factor authentication (MFA) is a secondary layer of user authentication applied to your Mattermost server that applies to all users on all teams within your Mattermost workspace.
+
+With MFA enabled, users need to provide a secure one-time code in addition to their username and password in order to log in to Mattermost. MFA is useful in organizations that have specific security and compliance policies. It can also be used in organizations where Mattermost is not behind a firewall and doesn't have access to existing MFA infrastructure.
+
+Mattermost offers a smartphone-based MFA check in addition to email-password or Active Directory/LDAP authentication to log in to the Mattermost server.
+
+Supported devices include iOS, Android, or other devices that are able to install a software-based authenticator such as FreeOTP, Google Authenticator, Microsoft Authenticator, 1Password, LastPass, or a similar app. After the app is installed, the device does not require internet access.
+
+<Note>
+
+As the MFA implementation relies on Time-based One-time passwords (TOTP) ensure that your server system time is accurate. If there is a discrepancy, users may not be able to log in successfully.
+
+</Note>
+
+## Enabling MFA
+
+System admins can enable this option by going to **System Console \> Authentication \> MFA**, then setting **Enable Multi-factor Authentication** to **true**.
+
+Once enabled, users can choose to [set up multi-factor authentication](/end-user-guide/preferences/manage-your-security-preferences) on their account by selecting **Profile \> Security \> Multi-factor Authentication** from their profile picture.
+
+### Disabling MFA
+
+System admins can disable this option by going to **System Console \> Authentication \> MFA**. When **Enable Multi-factor Authentication** is set to **false**, users can't opt to use or disable multi-factor authentication on their account via **Profile \> Security \> Multi-factor Authentication**.
+
+MFA can be disabled for user accounts using the API. See the [Mattermost API Reference](https://api.mattermost.com/#tag/users/paths/~1users~1&#123;user_id&#125;~1mfa/put) for details.
+
+## Enforcing MFA
+
+Admins can fulfill Multi-Factor Authentication (MFA) compliance requirements by enforcing an MFA requirement for login with email and LDAP accounts. Go to **System Console \> Authentication \> MFA**, then set **Enforce Multi-factor Authentication** to **true**.
+
+When MFA enforcement is set to **true**, users with email or LDAP authentication who don't have MFA set up will be directed to the MFA setup page when they log in to Mattermost. They will not be able to access the site until MFA setup is complete. Any new users will be required to set up MFA during the sign up process.
+
+Users will not be able to remove MFA from their account while enforcement is on.
+
+<Note>
+
+Turning on MFA enforcement prevents users from accessing the site until set up is complete. We recommended that you turn on enforcement during non-peak hours when people are less likely to be using Mattermost.
+
+</Note>

docs/main/administration-guide/onboard/onboard-index.mdx

@@ -0,0 +1,21 @@
+---
+title: "Onboard users"
+sidebar_label: "Onboard users"
+---
+Getting your organization into Mattermost: connect the identity provider your users already have, and get their accounts in.
+
+Access control for a workspace that's already running, including permissions and roles, is covered in [access control](/administration-guide/manage/admin/user-management).
+
+## Authentication
+
+- [Single sign-on](/administration-guide/onboard/corporate-directory-integration) - Connect Mattermost to your identity provider using SAML, OpenID Connect, or OAuth 2.0.
+- [AD/LDAP](/administration-guide/onboard/ad-ldap) - Synchronize accounts and groups from Active Directory or LDAP.
+- [Multi-factor authentication](/administration-guide/onboard/multi-factor-authentication) - Require a second factor at sign-in.
+- [SSL client certificate setup](/administration-guide/onboard/ssl-client-certificate) - Configure mutual TLS authentication for browsers and the desktop apps.
+
+## Accounts
+
+- [Provisioning workflows](/administration-guide/onboard/user-provisioning-workflows) - Choose how accounts are created, updated, and deactivated.
+- [Guest accounts](/administration-guide/onboard/guest-accounts) - Give people outside your organization access to specific channels.
+
+To pre-provision accounts in bulk, to bring teams, channels, and message history in from another system, or to move an existing deployment onto different infrastructure, see [Migrate](/administration-guide/manage/admin/migration).

docs/main/administration-guide/onboard/ssl-client-certificate.mdx

@@ -0,0 +1,133 @@
+---
+title: "SSL client certificate setup"
+---
+<PlanAvailability slug="all-commercial" />
+
+Follow these steps to configure SSL client certificates for your browser and the Mattermost desktop apps on Windows, macOS, and Linux.
+
+Before you begin, follow the [official guides to install Mattermost](/deployment-guide/deployment-guide-index) on your system, including NGINX configuration as a proxy with SSL and HTTP/2, and a valid SSL certificate such as Let's Encrypt.
+
+For the purposes of this guide, the Mattermost server domain name is `example.mattermost.com`, and the user account is `mmuser` with email `mmuser@mattermost.com` and password `mmuser-password`.
+
+<Important>
+
+\- Generating the client certificates in this section is optional if you have already generated them before. - We strongly recommend configuring an SSL certificate (or a self-signed certificate) for security, privacy, compliance, as well as to avoid browser limitations that can prevent Mattermost product features from working that copy data using the user's local clipboard, including [sharing message links](/end-user-guide/collaborate/share-links#share-message-links) and [inviting people](/end-user-guide/collaborate/invite-people). - SSL client certificates are not yet supported on the Mattermost mobile apps.
+
+</Important>
+
+## Set up mutual TLS authentication for the web app
+
+1.  Create a [certificate authority (CA) key](https://en.wikipedia.org/wiki/Certificate_authority) and a certificate for signing the client certificate. When establishing a TLS connection, the NGINX proxy server requests and validates a client certificate provided by the web app.
+
+``` sh
+openssl genrsa -des3 -out ca.mattermost.key 4096
+```
+
+``` text
+pass phrase: capassword
+```
+
+``` sh
+openssl req -new -x509 -days 365 -key ca.mattermost.key -out ca.mattermost.crt
+```
+
+``` text
+Country Name: US
+State: Maryland
+Locality Name: Meade
+Organization Name: Mattermost
+Organization Unit: Smarttotem
+Common Name: example.mattermost.com
+Email Address: admin@mattermost.com
+```
+
+2.  Create the client side key for `mmuser` with a passphrase, and the certificate signing request:
+
+``` sh
+openssl genrsa -des3 -out mmuser-mattermost.key 1024
+```
+
+``` text
+passphrase: mmuser-passphrase
+```
+
+``` sh
+openssl req -new -key mmuser-mattermost.key -out mmuser-mattermost.csr
+```
+
+``` text
+Country Name: US
+State: Maryland
+Locality Name: Meade
+Organization Name: Mattermost
+Organization Unit: Smarttotem
+Common Name: mmuser
+Email Address: mmuser@mattermost.com
+
+Challenge password: mmuser-passphrase
+```
+
+3.  Sign the user's client certificate with the previously created CA certificate:
+
+``` sh
+openssl x509 -req -days 365 -in mmuser-mattermost.csr -CA ca.mattermost.crt -CAkey ca.mattermost.key -set_serial 01 -out mmuser-mattermost.crt
+```
+
+4.  Check the newly generated client certificate for `mmuser`:
+
+``` sh
+openssl x509 -in mmuser-mattermost.crt -text -noout
+```
+
+5.  Open the file `/etc/nginx/sites-available/mattermost` and modify the following lines, so that the NGINX proxy server requests and verifies the client certificate:
+
+``` text
+ssl on;
+ssl_certificate /etc/letsencrypt/live/example.mattermost.com/fullchain.pem;
+ssl_certificate_key /etc/letsencrypt/live/example.mattermost.com/privkey.pem;
+ssl_client_certificate /opt/mattermost/config/ca.mattermost.crt;
+ssl_verify_client on;
+
+...
+
+location ~ /api/v[0-9]+/(users/)?websocket$ {
+ proxy_set_header X-SSL-Client-Cert $ssl_client_cert;
+ proxy_set_header X-SSL-Client-Cert-Subject-DN $ssl_client_s_dn;
+
+...
+
+location / {
+ proxy_set_header X-SSL-Client-Cert $ssl_client_cert;
+ proxy_set_header X-SSL-Client-Cert-Subject-DN $ssl_client_s_dn;
+
+...
+```
+
+6.  Confirm the CA key for `mmuser` works by the following curl command to the proxy:
+
+``` sh
+curl -v -s -k --key mmuser-mattermost.key --cert mmuser-mattermost.crt:mmuser-passphrase https://example.mattermost.com
+```
+
+You should see the Mattermost login page. If you see:
+
+> - `No required SSL certificate was sent`, something went wrong. Review the above steps and try again.
+> - `Error reading X.509 key or certificate file: Decryption has failed.`, make sure the passphrase is included together with the certificate, because curl doesn't prompt for it separately.
+
+7.  Generate a PKCS12 file from the CA key and certificate, to install the certificate into your client machine for your browser to use:
+
+``` sh
+openssl pkcs12 -export -out mmuser-mattermost.p12 -inkey mmuser-mattermost.key -in mmuser-mattermost.crt -certfile ca.mattermost.crt
+```
+
+``` text
+Enter Export Password: mmuser-passphrase
+```
+
+8.  Repeat steps 2-7 above for other users as needed.
+9.  Import the generated `.p12` file in step 7 into your key chain. In the Chrome browser on macOS:
+
+> 1.  Go to **Settings \> Advanced \> Privacy and security \> Manage certificates**. This opens the Keychain Access app.
+> 2.  Go to **File \> Import Items** and select the `mmuser-mattermost.p12` file.
+
+10. Go to `https://example.mattermost.com`. You should see a popup for the client certificate request.

docs/main/administration-guide/onboard/sso-entraid.mdx

@@ -0,0 +1,107 @@
+---
+title: "Entra ID Single Sign-On"
+---
+<PlanAvailability slug="all-commercial" />
+
+## Configuring EntraID as a Single Sign-On (SSO) service
+
+<Note>
+
+- This documentation covers configuring Entra ID for **OpenID Connect** authentication. If you need to configure Entra ID for **SAML** authentication instead, see the [Configure SAML with Microsoft Entra ID](/administration-guide/onboard/sso-saml-entraid) documentation.
+- The system must be using SSL as Microsoft only allows OAuth redirect URIs that are SSL-enabled.
+
+</Note>
+
+Follow these steps to configure Mattermost to use your Entra ID logon credentials and Azure Active Directory account as a Single Sign-on (SSO) service for team creation, account creation, and sign-in.
+
+### Step 1: Register an application in Azure Portal
+
+1.  Log in to the [Azure Portal](https://portal.azure.com/) with the account that relates to the Azure Active Directory tenant where you want to register the application. You can confirm the tenant in the top right corner of the portal.
+2.  In the left-hand navigation pane, select the **Microsoft EntraID**, then toward the bottom select **Add application registrations**.
+3.  Give your new registration a **Name**.
+4.  Define which **Supported account types** can access the application. For example, if this is to be only accessed from your enterprise's Azure AD accounts, then select **Accounts in this organizational directory only**.
+5.  Define the **Redirect URI** as Web client, then input the URL with the host name that will be specific to your Mattermost service followed by `/signup/office365/complete`. An example below is: `https://your.mattermost.com/signup/office365/complete`
+
+![image](/images/AzureApp_New_Registration.png)
+
+![image](/images/AzureApp_SetupMenuv2.png)
+
+Once the App Registration has been created, you can configure it further. See the standard [Azure AD documentation](https://learn.microsoft.com/en-gb/azure/active-directory/develop/quickstart-register-app) for reference.
+
+### Step 2: Generate a new client secret in Azure Portal
+
+1.  From the overview page of the newly created **Registered App**, select **Certificates and Secrets** from the menu, then select the button to generate a **New Client secret**.
+
+![image](/images/AzureApp_Client_Secret_Setup.png)
+
+2.  Provide a description, define the expiry for the token, then select **Add**.
+
+![image](/images/AzureApp_Client_Secret_Expiry.png)
+
+3.  Store the **value** of the new secret somewhere secure.
+4.  In Azure Portal, select **Overview** from the menu, then copy and paste both the Application (client) ID and the Directory (tenant) ID to a temporary location. You will enter these values as an **Application ID** and as part of an **Auth Endpoint** and **Token Endpoint** URL in the Mattermost System Console.
+
+![image](/images/AzureApp_App_Directory_IDsv2.png)
+
+5.  Grant admin concent for the configured permissions under **App Registrations \> \<Your App\> \> Manage \> API Permissions**
+
+![image](/images/AzureApp_App_Directory_Grant_Admin_Consent.png)
+
+### Step 3: Configure Mattermost for Entra ID SSO
+
+1.  Log in to Mattermost, then go to **System Console \> Authentication \> OpenID Connect**.
+2.  Select **Entra ID** as the service provider.
+3.  Paste the **Directory (tenant) ID** from the Azure Portal as the **Directory (tenant) ID** in Mattermost.
+4.  The **Discovery Endpoint** for OpenID Connect with Entra ID is prepopulated with `https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration`.
+5.  Paste the **Application (client) ID** from the Azure Portal as the **Client ID** in Mattermost.
+6.  Paste the **client secret** value from the Azure Portal as the **Client Secret** in Mattermost.
+7.  Select **Save**.
+
+<Note>
+
+When Mattermost is configured to use OpenID Connect or OAuth 2.0 for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect or OAuth 2.0 must be the authoritative source for these user attributes.
+
+</Note>
+
+### Note about Microsoft Active Directory Tenants
+
+A Microsoft Active Directory (AD) tenant is a dedicated instance of Azure Active Directory (Azure AD) that you own and would have received when signing up for a Microsoft cloud service, such as Azure or Entra ID. Tenants are commonly used by organizations who want to store information about their users, such as passwords, user profile data, and permissions. See the [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-create-new-tenant) documentation to learn more about getting an Azure AD tenant.
+
+To allow your Azure AD users to log in to Mattermost using Entra ID SSO, you must register Mattermost in the Microsoft Azure AD tenant that contains the users' information. The registration can be done from the [Microsoft Azure portal](https://portal.azure.com). The steps to register the Mattermost account in the tenant should be similar to those provided above, and you can find more information about [integrating apps with Azure AD here](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant).
+
+If you don't register Mattermost in the Microsoft Azure AD tenant your organization uses, Entra ID SSO will likely fail for your users.
+
+<Note>
+
+If you do not use Azure Active Directory, you may register Mattermost with your Entra ID or Azure account (a personal, work, or school account), then set up Entra ID SSO with Mattermost using the steps provided above.
+
+</Note>
+
+### Configure Mattermost `config.json` for Entra ID SSO
+
+Instead of using the System Console, you can add the Entra ID settings directly to the `config.json` file on your Mattermost server.
+
+1.  Open `config.json` as *root* in a text editor. It’s usually in `/opt/mattermost/config` but it might be elsewhere on your system.
+2.  Locate the `Office365Settings` section, then add or update the following information:
+
+``` text
+"Office365Settings": {
+      "Enable": false,
+      "Secret": "i.hddd6Pu3--5dg~cRddddqOrBdd1a",
+      "Id": "28ddd714-1f2f-4f9c-9486-90b8dddd27",
+      "Scope": "profile openid email",
+      "AuthEndpoint": "",
+      "TokenEndpoint": "",
+      "UserApiEndpoint": "",
+      "DiscoveryEndpoint": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
+      "DirectoryId": "common"
+}
+```
+
+3.  Save your changes, then restart your Mattermost server. After the server restarts, users must change their login method before they can log in with Entra ID.
+
+## Frequently Asked Questions
+
+### How can I use LDAP attributes or Groups with OpenID?
+
+At this time, LDAP data isn't compatible with OpenID. If you currently rely on LDAP to manage your users' teams, channels, groups, or attributes, you won't be able to do this automatically with users who have logged in with OpenID. If you need LDAP synced to each user, we suggest using SAML or LDAP as the login provider. Some OpenID providers can use SAML instead, like Keycloak.

docs/main/administration-guide/onboard/sso-gitlab.mdx

@@ -0,0 +1,64 @@
+---
+title: "GitLab Single Sign-On"
+---
+<PlanAvailability slug="all-commercial" />
+
+## Configuring GitLab as a Single Sign-On (SSO) service
+
+Follow these steps to configure Mattermost to use GitLab as a Single Sign-on (SSO) service for team creation, account creation, and user login.
+
+<Important>
+
+\- Only the default GitLab SSO is officially supported. - "Double SSO", where GitLab SSO is chained to other SSO solutions, is not supported. It may be possible to connect GitLab SSO with AD, LDAP, SAML, or MFA add-ons in some cases, but because of the special logic required, they're not officially supported, and they're known not to work in some cases. - [Mattermost Free (self-hosted only)](/product-overview/editions-and-offerings) supports the OAuth 2.0 standard. - [Mattermost Professional](/product-overview/editions-and-offerings) and [Mattermost Enterprise](/product-overview/editions-and-offerings) support the OpenID Connect standard.
+
+</Important>
+
+### Step 1: Add a Mattermost application to your GitLab account
+
+1.  Log in to your GitLab account, then go to `https://&#123;gitlab-site-name&#125;/profile/applications`. For *&#123;gitlab-site-name&#125;* use the name of your GitLab instance. If you're using GitLab itself as your service provider, use `gitlab.com`.
+2.  Add a new application:
+
+> 1.  In the **Name** field, enter `Mattermost`.
+> 2.  In the **Redirect URI** field, add the following two lines using your own value for *&#123;mattermost-site-name&#125;*.
+>
+> > ``` text
+> > https://&#123;mattermost-site-name&#125;/login/gitlab/complete
+> > https://&#123;mattermost-site-name&#125;/signup/gitlab/complete
+> > ```
+> >
+> > If your GitLab instance is not set up to use SSL, your URIs must begin with `http://` instead of `https://`.
+>
+> 3.  Select scopes.
+>     - For Mattermost Team Edition, select `read_user`.
+>     - For Mattermost Enterprise, select `read_user`, `openid`, `profile`, and `email`.
+
+3.  Select **Save application**.
+4.  Keep the GitLab window open. You need the *Application Id* and *Application Secret Key* when you configure Mattermost.
+
+### Step 2: Configure Mattermost for GitLab SSO
+
+1.  Log in to Mattermost, then go to **System Console \> Authentication \> OpenID Connect**.
+2.  Select **GitLab** as the service provider.
+3.  Enter the **GitLab Site URL** of your GitLab instance. If your GitLab instance is not set up to use SSL, start the URL with `http://` instead of `https://`. If you are using GitLab itself as your provider, use `gitlab.com`.
+4.  The **Discovery Endpoint** for OpenID Connect with GitLab is prepopulated with `https://gitlab.com/.well-known/openid-configuration`.
+5.  Paste the **Application ID** from GitLab as the **Client ID** in Mattermost.
+6.  Paste the **Application Secret Key** from GitLab as the **Client Secret** in Mattermost.
+7.  Update the `config.json` file and specify the scopes you selected in GitLab under the `GitLabSettings` property. At a minimum, `openid` is a required scope for Mattermost Enterprise and Professional, and `read_user` is a required scope for Mattermost Team Edition. Mattermost Team Edition does not work with scopes other than `read_user`. Changes to this setting require a server restart before taking effect.
+8.  Select **Save**.
+
+<Note>
+
+- When Mattermost is configured to use OpenID Connect or OAuth 2.0 for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect or OAuth 2.0 must be the authoritative source for these user attributes.
+- If you are using Mattermost behind a load balancer and you have SSL configured, you may need to set <code>X-Forwarded-Proto</code> header to https at your load balancer.
+
+</Note>
+
+### (Optional) Step 3: Force users to sign up using SSO only
+
+To force all users to sign-up with SSO only, set **System Console \> Authentication \> Email \> Enable sign-in with email** to `false` Users must change their login method before they can log in to Mattermost with GitLab.
+
+## Frequently Asked Questions
+
+### How can I use LDAP attributes or Groups with OpenID?
+
+At this time, LDAP data isn't compatible with OpenID. If you currently rely on LDAP to manage your users' teams, channels, groups, or attributes, you won't be able to do this automatically with users who have logged in with OpenID. If you need LDAP synced to each user, we suggest using SAML or LDAP as the login provider. Some OpenID providers can use SAML instead, like Keycloak.

docs/main/administration-guide/onboard/sso-google.mdx

@@ -0,0 +1,86 @@
+---
+title: "Google Single Sign-On"
+---
+<PlanAvailability slug="all-commercial" />
+
+## Configuring Google Apps as a Single Sign-On (SSO) service
+
+Follow these steps to configure Mattermost to use Google as a Single Sign-on (SSO) service for team creation, account creation, and login.
+
+<Note>
+
+The [Google People API](https://developers.google.com/people) has replaced the Google+ API, which was deprecated by Google as of March 7th, 2019 [per their notice](https://developers.google.com/+/api-shutdown).
+
+</Note>
+
+### Step 1: Create OpenID Connect project in Google API Manager
+
+1.  Go to Google Cloud Platform.
+2.  Select **Credentials** in the left-hand sidebar.
+3.  Select **Create Credentials**, then select **OAuth client ID**.
+4.  Select the **Web application** as the application type.
+5.  Enter `Mattermost-<your-company-name>` as the **Name**, replacing `<your-company-name>` with the name of your organization.
+6.  Under **Authorized redirect URIs**, select **Add URL**, then enter `&#123;your-mattermost-url&#125;/signup/google/complete`. For example: `http://localhost:8065/signup/google/complete`.
+7.  Select **Create**.
+8.  Copy and paste the **Your Client ID** and **Your Client Secret** values to a temporary location. You will enter these values in the Mattermost System Console.
+
+![image](/images/create-google-sso-credentials.png)
+
+![image](/images/select-google-sso-web-app.png)
+
+![image](/images/google-sso-web-app-name.png)
+
+![image](/images/google-sso-redirect-uri.png)
+
+![image](/images/google-sso-credentials.png)
+
+### Step 2: Enable Google People API
+
+Go to the [Google People API](https://developers.google.com/people), then select **Enable** in the header. This might take a few minutes to propagate through Google's systems.
+
+### Step 3: Configure Mattermost for Google Apps SSO
+
+1.  Log in to Mattermost, then go to **System Console \> Authentication \> OpenID Connect**.
+2.  Select **Google Apps** as the service provider.
+3.  The **Discovery Endpoint** for OpenID Connect with Google Apps is prepopulated with `https://accounts.google.com/.well-known/openid-configuration`.
+4.  Paste in the **Client ID** from Google in Mattermost.
+5.  Paste in the **Client Secret** from Google in Mattermost.
+6.  Select **Save**.
+
+<Note>
+
+When Mattermost is configured to use OpenID Connect or OAuth 2.0 for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect or OAuth 2.0 must be the authoritative source for these user attributes.
+
+Username and email address changes made in Google Workspace are not automatically synced to Mattermost.
+
+</Note>
+
+### Configure Mattermost `config.json` for Google Apps SSO
+
+Instead of using the System Console, you can add the Google settings directly to the `config.json` file directly on your Mattermost server.
+
+1.  Open `config.json` as *root* in a text editor. It’s usually in `/opt/mattermost/config`, but it might be elsewhere on your system.
+2.  Locate the `GoogleSettings` section, then add or update the following information:
+
+``` text
+"GoogleSettings": {
+      "Enable": true,
+      "Secret": "P-k9R-7E7ayX9LdddddWdXVg",
+      "Id": "1022ddddd5846-bkddddd4a1ddddd9d88j1kb6eqc.apps.googleusercontent.com",
+      "Scope": "profile openid email",
+      "AuthEndpoint": "",
+      "TokenEndpoint": "",
+      "UserApiEndpoint": "",
+      "DiscoveryEndpoint": "https://accounts.google.com/.well-known/openid-configuration",
+      "ButtonText": "",
+      "ButtonColor": ""
+}
+```
+
+3.  Save your changes, then restart your Mattermost server. After the server restarts, users must change their login method before they can log in with Google Apps.
+
+## Frequently Asked Questions
+
+### How can I use LDAP attributes or Groups with OpenID?
+
+At this time, LDAP data isn't compatible with OpenID. If you currently rely on LDAP to manage your users' teams, channels, groups, or attributes, you won't be able to do this automatically with users who have logged in with OpenID. If you need LDAP synced to each user, we suggest using SAML or LDAP as the login provider. Some OpenID providers can use SAML instead, like Keycloak.

docs/main/administration-guide/onboard/sso-openidconnect.mdx

@@ -0,0 +1,37 @@
+---
+title: "OpenID Connect Single Sign-On"
+---
+<PlanAvailability slug="all-commercial" />
+
+Mattermost provides OpenID Connect support for [GitLab](/administration-guide/onboard/sso-gitlab), [Google Apps](/administration-guide/onboard/sso-google), and [Entra ID](/administration-guide/onboard/sso-entraid). With OpenID Connect, users can also use their login to Keycloak, Atlassian Crowd, Apple, Microsoft, Salesforce, Auth0, Ory.sh, Facebook, Okta, OneLogin, and Azure AD, as well as others, as a Single Sign-on (SSO) service for team creation, account creation, and user login.
+
+Follow these steps to configure a service provider using OpenID Connect.
+
+## Step 1: Create an OpenID Connect Application
+
+1.  Follow service provider documentation for creating an OpenID Connect application. Most OpenID Connect service providers require authorization of all redirect URIs.
+2.  In the appropriate field, enter `&#123;your-mattermost-url&#125;/signup/openid/complete` For example: `http://domain.com/signup/openid/complete`
+3.  Copy and paste values for the **Discovery Endpoint**, **Client ID**, and **Client Secret** values to a temporary location. You will enter these values when you configure Mattermost.
+
+## Step 2: Configure Mattermost for an OpenID Connect SSO
+
+1.  Log in to Mattermost, then go to **System Console \> Authentication \> OpenID Connect**.
+2.  Select **OpenID Connect (Other)** as the service provider.
+3.  Enter the **Discovery Endpoint**.
+4.  Enter the **Client ID**.
+5.  Enter the **Client Secret**.
+6.  Specify a **Button Name** and **Button Color** for the OpenID Connect option on the Mattermost login page.
+7.  Select **Save**.
+8.  Restart your Mattermost server to see the changes take effect.
+
+<Note>
+
+\- When Mattermost is configured to use OpenID Connect for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect must be the authoritative source for these user attributes. - Admins can configure Mattermost to use the `preferred_username` claim from the OpenID token as the Mattermost username. Enable the **Use preferred username** option in the provider's settings under **System Console \> Authentication \> OpenID Connect**. See the [authentication configuration settings](/administration-guide/configure/authentication-configuration-settings#openid-connect) for details. - 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 [delegated granular administration](/administration-guide/onboard/delegated-granular-administration#edit-privileges-of-admin-roles-advanced)) documentation for details.
+
+</Note>
+
+## Frequently Asked Questions
+
+### How can I use LDAP attributes or Groups with OpenID?
+
+At this time, LDAP data isn't compatible with OpenID. If you currently rely on LDAP to manage your users' teams, channels, groups, or attributes, you won't be able to do this automatically with users who have logged in with OpenID. If you need LDAP synced to each user, we suggest using SAML or LDAP as the login provider. Some OpenID providers can use SAML instead, like Keycloak.

docs/main/administration-guide/onboard/sso-saml-adfs-msws2016.mdx

@@ -0,0 +1,216 @@
+---
+title: "Configure SAML with Microsoft ADFS using Microsoft Windows Server 2016"
+---
+import Inc0_sso_saml_before_you_begin from './sso-saml-before-you-begin.mdx';
+import Inc1_sso_saml_faq from './sso-saml-faq.mdx';
+import Inc2_sso_saml_ldapsync from './sso-saml-ldapsync.mdx';
+
+<PlanAvailability slug="all-commercial" />
+
+This document provides steps to configure SAML 2.0 with Microsoft ADFS for Mattermost and Microsoft Windows Server 2016.
+
+<Inc0_sso_saml_before_you_begin />
+
+## Prerequisites
+
+- An Active Directory instance where all users have specified email and username attributes. For Mattermost servers running 3.3 and earlier, users must also have their first name and last name attributes specified.
+- A running Microsoft Server. The screenshots used in this guide are from Microsoft Server 2012R2, but similar steps should work for other versions.
+- An SSL certificate to sign your ADFS login page.
+- ADFS installed on your Microsoft Server. You can find a detailed guide for deploying and configuring ADFS in [this Microsoft article](https://learn.microsoft.com/en-us/previous-versions/dynamicscrm-2016/deployment-administrators-guide/gg188612(v=crm.8)?redirectedfrom=MSDN).
+
+On your ADFS installation, open the ADFS console. Select **Service**, then select **Endpoints**. In the **Type** column, search for `SAML 2.0/WS-Federation` and note down the value of **URL Path** column. This is also known as the **SAML SSO URL Endpoint** in this guide. If you chose the defaults for the installation, this will be `/adfs/ls`.
+
+## Add a relying party trust
+
+1.  Open the ADFS management snap-in, then select **AD FS \> Relying Party Trusts \> Add Relying Party Trust** from the right sidebar. You can also right-click **Relying Party Trusts**, then select **Add Relying Party Trust** from the context menu.
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_000.png)
+
+2.  On the **Welcome** screen of the configuration wizard, select **Claims aware**, then select **Start**.
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_001.png)
+
+3.  On the **Select Data Source** screen, select **Enter data about the relying party manually**.
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_002.png)
+
+4.  On the **Specify Display Name** screen, enter a **Display Name** (e.g., `Mattermost`). You can add optional notes.
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_003.png)
+
+5.  On the **Configure Certificate** screen, leave the certificate settings at their default values.
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_004.png)
+
+If you would like to set up encryption for your SAML connection, select **Browse**, then upload your Service Provider Public Certificate.
+
+> ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_005.png)
+
+6.  On the **Configure URL** screen, select **Enable Support for the SAML 2.0 WebSSO protocol**, then enter the **SAML 2.0 SSO service URL** in the following format:`https://<your-mattermost-url>/login/sso/saml` where `<your-mattermost-url>` should typically match the [Mattermost Site URL](/administration-guide/configure/environment-configuration-settings#site-url).
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_006.png)
+
+7.  On the **Configure Identifiers** screen, enter the **Relying party trust identifier**. This identifies the claims being requested. The **SAML 2.0 SSO service URL** format should be `https://<your-mattermost-url>/login/sso/saml` where `<your-mattermost-url>` matches your [Mattermost Site URL](/administration-guide/configure/environment-configuration-settings#site-url). Then choose **Next**.
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_007.png)
+    >
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_008.png)
+
+This string must match the **Service Provider Identifier** string. For more information about the Relying party trust identifier and how prefix matching is applied see [this documentation](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/how-uris-are-used-in-ad-fs).
+
+Add your **SAML 2.0 SSO service URL** using this same process.
+
+8.  On the **Choose Access Control Policy** screen, select the access control policy suitable for your environment. This guide assumes the default values **Permit everyone** and an unchecked box.
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_009.png)
+
+9.  On the **Ready to Add Trust** screen, review your settings.
+
+    > ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_010.png)
+
+10. On the **Finish** screen, select **Configure claims issuance policy for this application**, then select **Close**.
+
+    ![image](/images/SSO-SAML-ADFS_add-new-relying-party-trust_011.png)
+
+## Create claim rules
+
+1.  In the **Issuance Transform Rules** tab of the **Claim Rules** editor, select **Add Rule…**.
+
+    > ![image](/images/SSO-SAML-ADFS_create-claim-rules_001.png)
+
+2.  On the **Choose Rule Type** screen, select **Send LDAP Attributes as Claims** from the drop-down menu, then select **Next**.
+
+    > ![image](/images/SSO-SAML-ADFS_create-claim-rules_002.png)
+
+3.  On the **Configure Claim Rule** screen, enter a **Claim Rule Name** of your choice, select **Active Directory** as the **Attribute Store**, then add the following mapping:
+
+> - From the **LDAP Attribute column**, select `E-Mail-Addresses`. From the **Outgoing Claim Type**, type `Email`.
+> - From the **LDAP Attribute column**, select `E-Mail-Addresses`. From the **Outgoing Claim Type**, type `Name ID`.
+> - From the **LDAP Attribute column**, select `Given-Name`. From the **Outgoing Claim Type**, type `FirstName`.
+> - From the **LDAP Attribute column**, select `Surname`. From the **Outgoing Claim Type**, type `LastName`.
+> - From the **LDAP Attribute column**, select `SAM-Account-Name`. From the **Outgoing Claim Type**, type `Username`.
+
+The `FirstName` and `LastName` attributes are optional.
+
+Select **Finish** to add the rule.
+
+The entries in the **Outgoing Claim Type** column can be modified. The entries may contain dashes but no spaces. They are used to map the corresponding fields in Mattermost.
+
+> ![image](/images/SSO-SAML-ADFS_create-claim-rules_003.png)
+
+4.  Select **Add Rule** to create another new rule.
+
+5.  On the **Choose Rule Type** screen, select **Transform an Incoming Claim** from the drop-down menu, then select **Next**.
+
+    > ![image](/images/SSO-SAML-ADFS_create-claim-rules_004.png)
+
+6.  On the **Configure Claim Rule** screen, enter a **Claim Rule Name** of your choice, then:
+
+> - Select **Name ID** for the **Incoming claim type**
+> - Select **Unspecified** for the **Incoming name ID format**
+> - Select **E-Mail Address** for the **Outgoing claim type**
+
+Select **Pass through all claim values**, then select **Finish**.
+
+> ![image](/images/SSO-SAML-ADFS_create-claim-rules_005.png)
+
+7.  Select **Finish** to create the claim rule, then select **OK** to finish creating rules.
+8.  Open Windows PowerShell as an administrator, then run the following command:
+
+> `Set-ADFSRelyingPartyTrust -TargetName <display-name> -SamlResponseSignature "MessageAndAssertion"`
+
+where `<display-name>`is the name you specified in step 4 when you added a relying party trust. In this example, `<display-name>` would be `mattermost`.
+
+This action adds the signature to SAML messages, making verification successful.
+
+## Export identity provider certificate
+
+Next, export the identity provider certificate, which will be later uploaded to Mattermost to finish SAML configuration.
+
+1.  Open the ADFS management snap-in, select **AD FS \> Service \> Certificates**, then double-click on the certificate under **Token-signing**. You can also right-click the field, then select **View Certificate** in the context menu.
+
+    > ![image](/images/SSO-SAML-ADFS_export-id-provider-cert_001.png)
+
+2.  On the **Certificate** screen, open the **Details** tab, select **Copy to File**, then select **OK**.
+
+    > ![image](/images/SSO-SAML-ADFS_export-id-provider-cert_003.png)
+
+3.  On the **Certificate Export Wizard** screen, select **Next**.
+
+    > ![image](/images/SSO-SAML-ADFS_export-id-provider-cert_004.png)
+
+4.  Select **Base-64 encoded X.509 (.CER)**, then select **Next** again.
+
+    > ![image](/images/SSO-SAML-ADFS_export-id-provider-cert_005.png)
+
+5.  On the **Certificate Export Wizard** screen, select **Browse** to specify the location where you want the Identity Provider Certificate to be exported, then specify the file name.
+
+    > ![image](/images/SSO-SAML-ADFS_export-id-provider-cert_006.png)
+
+6.  Select **Save**. On the **Certificate Export Wizard** screen, verify the file path is correct, then select **Next**.
+
+7.  In the **Completing the Certificate Export Wizard**, select **Finish**, then select **OK** to confirm the export was successful.
+
+    > ![image](/images/SSO-SAML-ADFS_export-id-provider-cert_007.png)
+
+## Configure SAML Sign-On for Mattermost
+
+Create a metadata URL by appending "FederationMetadata/2007-06/FederationMetadata.xml" to the root URL of the ADFS server, for example: `https://<adfs.domain.com>/federationmetadata/2007-06/FederationMetadata.xml>`.
+
+Next, start the Mattermost server, then log in to Mattermost as a system admin. Go to **System Console \> Authentication \> SAML**, paste the metadata URL in the **Identity Provider Metadata URL** field, then select **Get SAML Metadata from IdP**.
+
+This populates the **SAML SSO URL** and the **Identity Provider Issuer URL** fields automatically. The Identity Provider Public Certificate is also downloaded from the server and set locally.
+
+The following fields can be selected:  
+- Set **Enable Login With SAML 2.0** to **true**.
+- Set **Enable Synchronizing SAML Accounts With AD/LDAP** to suit your environment.
+- Set **Override SAML bind data with AD/LDAP information** to suit your environment.
+
+If you don't plan to use a metadata URL, you can manually enter the following fields:  
+- For **SAML SSO URL** use the `SAML 2.0/W-Federation URL ADFS Endpoint` you copied at the beginning of the process.
+
+- For **Identity Provider Issuer URL** use the `Relying party trust identifier` from ADFS.
+
+- For **Identity Provider Public Certificate** use the`X.509 Public Certificate`.
+
+  ![image](/images/SSO-SAML-ADFS_configure-saml_001.png)
+
+2.  Configure Mattermost to verify the signature.
+
+> - Set **Verify Signature** to `true`.
+>
+> - For **Service Provider Login URL** use the `SAML 2.0 SSO service URL` you specified in ADFS.
+>
+>   ![image](/images/SSO-SAML-ADFS_configure-saml_002.png)
+
+3.  Enable encryption.
+
+> - Set **Enable Encryption** to `true`.
+>
+> - For **Service Provider Private Key** use the Service Provider Private Key generated at the start of this process.
+>
+> - For **Service Provider Public Certificate** use the Service Provider Public Certificate you generated at the start of this process.
+>
+> - Set **Sign Request** to suit your environment.
+>
+>   ![image](/images/SSO-SAML-ADFS_configure-saml_003.png)
+
+4.  Set attributes for the SAML Assertions, which will be used to update user information in Mattermost. Attributes for email and username are required and should match the values you entered in ADFS earlier. See [documentation on SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20) for more detail.
+
+For Mattermost servers running 3.3 and earlier, the first name and last name attributes are also required fields.
+
+> ![image](/images/SSO-SAML-ADFS_configure-saml_004.png)
+
+5.  Select **Save**.
+6.  (Optional) If you configured `First Name` Attribute and the `Last Name` Attribute, go to **System Console \> Site Configuration \> Users and Teams**, then set **Teammate Name Display** to **Show first and last name**. This is recommended for a better user experience.
+
+You’re done! If you’d like to confirm SAML SSO is successfully enabled, switch your system admin account from email to SAML-based authentication from your profile picture via **Profile \> Security \> Sign-in Method \> Switch to SAML SSO**, then log in with your SAML credentials to complete the switch.
+
+We also recommend that you post an announcement about how the migration will work to your users.
+
+You may also configure SAML for ADFS by editing the `config.json` file to enable SAML based on [SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20). You must restart the Mattermost server for the changes to take effect.
+
+<Inc1_sso_saml_faq />
+
+<Inc2_sso_saml_ldapsync />
+   :start-after: :nosearch:

docs/main/administration-guide/onboard/sso-saml-adfs.mdx

@@ -0,0 +1,201 @@
+---
+title: "Configure SAML with Microsoft ADFS for Windows Server 2012"
+---
+import Inc0_sso_saml_before_you_begin from './sso-saml-before-you-begin.mdx';
+import Inc1_sso_saml_ldapsync from './sso-saml-ldapsync.mdx';
+import Inc2_sso_saml_faq from './sso-saml-faq.mdx';
+
+<PlanAvailability slug="all-commercial" />
+
+The following process provides steps to configure SAML 2.0 with Microsoft ADFS for Mattermost.
+
+<Inc0_sso_saml_before_you_begin />
+
+The following are basic requirements to use ADFS for Mattermost:  
+- An Active Directory instance where all users have a specified email and username attributes. For Mattermost servers running 3.3 and earlier, users must also have their first name and last name attributes specified.
+- A Microsoft Server running. The screenshots used in this guide are from Microsoft Server 2012R2, but similar steps should work for other versions.
+- An SSL certificate to sign your ADFS login page.
+- ADFS installed on your Microsoft Server. You can find a detailed guide for deploying and configuring ADFS in [this Microsoft article](https://learn.microsoft.com/en-us/previous-versions/dynamicscrm-2016/deployment-administrators-guide/gg188612(v=crm.8)?redirectedfrom=MSDN).
+
+On your ADFS installation, note down the value of the **SAML 2.0/W-Federation URL** in ADFS Endpoints section, also known as the **SAML SSO URL Endpoint** in this guide. If you chose the defaults for the installation, this will be `/adfs/ls/`.
+
+## Add a relying party trust
+
+1.  In the ADFS management sidebar, go to **AD FS \> Trust Relationships \> Relying Party Trusts**, then select **Add Relying Party Trust**. A configuration wizard opens for adding a new relying party trust.
+
+    > ![image](/images/adfs_1_add_new_relying_party_trust.png)
+
+2.  On the **Welcome** screen, select **Start**.
+
+    > ![image](/images/adfs_2_start_wizard.png)
+
+3.  On the **Select Data Source** screen, select **Enter data about the relying party manually**.
+
+    > ![image](/images/adfs_3_select_data_source.png)
+
+4.  On the **Specify Display Name** screen, enter a **Display Name** to recognize the trust, such as `Mattermost`, then add any notes you want to make.
+
+    > ![image](/images/adfs_4_specify_display_name.png)
+
+5.  On the **Choose Profile** screen, select **AD FS profile**.
+
+    > ![image](/images/adfs_5_choose_profile.png)
+
+6.  On the **Configure Certificate** screen, leave the certificate settings at their default values.
+
+    > ![image](/images/adfs_6_configure_certificate_default.png)
+
+However, if you would like to set up encryption for your SAML connection, select **Browse**, then upload your Service Provider Public Certificate.
+
+> ![image](/images/adfs_7_configure_certificate_encryption.png)
+
+7.  On the **Configure URL** screen, select **Enable Support for the SAML 2.0 WebSSO protocol**, then enter the **SAML 2.0 SSO service URL**, similar to `https://<your-mattermost-url>/login/sso/saml` where `<your-mattermost-url>` should typically match the [Mattermost Site URL](/administration-guide/configure/environment-configuration-settings#site-url).
+
+    > ![image](/images/adfs_8_configure_url.png)
+
+8.  On the **Configure Identifiers** screen, enter the **Relying party trust identifier** (also known as the **Identity Provider Issuer URL**) of the form `https://<your-idp-url>/adfs/services/trust`, then click **Add**.
+
+    > ![image](/images/adfs_9_configure_identifiers.png)
+
+9.  On the **Configure Multi-factor Authentication Now** screen, you may enable multi-factor authentication. This is beyond the scope of this documentation.
+
+    > ![image](/images/adfs_10_configure_mfa.png)
+
+10. On the **Choose Issuance Authorization Rules** screen, select **Permit all users to access this relying party**.
+
+    ![image](/images/adfs_11_authorization.png)
+
+11. On the **Ready to Add Trust** screen, review your settings.
+
+    ![image](/images/adfs_12_ready_to_add_trust.png)
+
+12. On the **Finish** screen, select **Open the Edit Claim Rules dialog for this relying party trust when the wizard closes**, then select **Close**. You exit the configuration wizard, and a **Claim Rules** editor opens.
+
+    ![image](/images/adfs_13_finish_trust.png)
+
+## Create claim rules
+
+1.  In the **Issuance Transform Rules** section of the **Claim Rules** editor, select **Add Rule…** to open an **Add Transform Claim Rule Wizard**.
+
+    > ![image](/images/adfs_14_claim_rules_editor.png)
+
+2.  On the **Choose Rule Type** screen, select **Send LDAP Attributes as Claims** from the drop-down menu, then select **Next**.
+
+    > ![image](/images/adfs_15_choose_rule_type.png)
+
+3.  In the **Configure Claim Rule** screen, enter a **Claim Rule Name** of your choice, select **Active Directory** as the **Attribute Store**, then complete the following:
+
+> - From the **LDAP Attribute column**, select `E-Mail-Addresses`. From the **Outgoing Claim Type**, type `Email`.
+> - From the **LDAP Attribute column**, select `E-Mail-Addresses`. From the **Outgoing Claim Type**, type `Name ID`.
+> - From the **LDAP Attribute column**, select `Given-Name`. From the **Outgoing Claim Type**, type `FirstName`.
+> - From the **LDAP Attribute column**, select `Surname`. From the **Outgoing Claim Type**, type `LastName`.
+> - From the **LDAP Attribute column**, select `SAM-Account-Name`. From the **Outgoing Claim Type**, type `Username`.
+
+The `FirstName` and `LastName` attributes are optional.
+
+Select **Finish** to add the rule.
+
+Note that the entries in the **Outgoing Claim Type** column can be chosen to be something else. They can contain dashes but no spaces. They will be used to map the corresponding fields in Mattermost later.
+
+> ![image](/images/adfs_16_configure_claim_rule.png)
+
+4.  Create another new rule by selecting **Add Rule**.
+
+5.  On the **Choose Rule Type** screen, select **Transform an Incoming Claim** from the drop-down menu, then select **Next**.
+
+    > ![image](/images/adfs_17_transformation_of_incoming_claim.png)
+
+6.  On the **Configure Claim Rule** screen, enter a **Claim Rule Name** of your choice, then:
+
+> - Select **Name ID** for the **Incoming claim type**.
+> - Select **Unspecified** for the **Incoming name ID format**.
+> - Select **E-Mail Address** for the **Outgoing claim type**.
+
+Select **Pass through all claim values**, then select **Finish**.
+
+> ![image](/images/adfs_18_configure_incoming_claim.png)
+
+7.  Select **Finish** to create the claim rule, then select **OK** to finish creating rules.
+8.  Open Windows PowerShell as an administrator, then run the following command:
+
+> `Set-ADFSRelyingPartyTrust -TargetName <display-name> -SamlResponseSignature "MessageAndAssertion"`
+
+where `<display-name>` is the name you specified in step 4 when adding a relying party trust. In this example, `<display-name>` would be `mattermost`.
+
+This action adds the signature to SAML messages, making verification successful.
+
+## Export identity provider certificate
+
+Next, export the identity provider certificate, which will be later uploaded to Mattermost to finish SAML configuration.
+
+1.  In the ADFS management sidebar, go to **AD FS \> Service \> Certificates**, then double click on the certificate under **Token-signing**. Alternatively, you can right-click on the field, then select **View Certificate**.
+
+    > ![image](/images/adfs_19_export_idp_cert_start.png)
+
+2.  On the **Certificate** screen, go to the **Details** tab, then select **Copy to File**, followed by **OK**. This opens a **Certificate Export Wizard**.
+
+    > ![image](/images/adfs_20_export_idp_cert_copy.png)
+
+3.  On the **Certificate Export Wizard** screen, select **Next**, then, select the option **Base-64 encoded X.509 (.CER)**, and select **Next** again.
+
+    > ![image](/images/adfs_21_export_idp_cert_wizard.png)
+
+4.  On the **Certificate Export Wizard** screen, select **Browse** to specify the location where you want the Identity Provider Certificate to be exported, then specify the file name.
+
+    > ![image](/images/adfs_21-2_export_idp_cert_wizard.png)
+
+5.  Select **Save**. In the **Certificate Export Wizard** screen, verify the file path is correct, then select **Next**.
+
+6.  In the **Completing the Certificate Export Wizard**, select **Finish**, then select **OK** to confirm the export was successful.
+
+    > ![image](/images/adfs_21-3_export_idp_cert_wizard.png)
+
+## Configure SAML Sign-On for Mattermost
+
+Create a metadata URL by appending "FederationMetadata/2007-06/FederationMetadata.xml" to the root URL of the ADFS server, for example: `https://<adfs.domain.com>/federationmetadata/2007-06/FederationMetadata.xml>`.
+
+Next, start the Mattermost server and log in to Mattermost as a system admin. Go to **System Console \> Authentication \> SAML**, paste the metadata URL in the **Identity Provider Metadata URL** field, then select **Get SAML Metadata from IdP**.
+
+This populates the **SAML SSO URL** and the **Identity Provider Issuer URL** fields automatically. The Identity Provider Public Certificate is also downloaded from the server and set locally.
+
+Alternatively you can enter the following fields manually:  
+- **SAML SSO URL**: **SAML 2.0/W-Federation URL** ADFS Endpoint you copied earlier.
+
+- **Identity Provider Issuer URL**: `Relying party trust identifier` from ADFS you specified earlier.
+
+- **Identity Provider Public Certificate**: `X.509 Public Certificate` you downloaded earlier.
+
+  ![image](/images/adfs_22_mattermost_basics.png)
+
+2.  Configure Mattermost to verify the signature. The **Service Provider Login URL** is the SAML 2.0 SSO service URL you specified in ADFS earlier.
+
+    > ![image](/images/adfs_23_mattermost_verification.png)
+
+3.  Enable encryption by uploading the Service Provider Private Key and Service Provider Public Certificate you generated earlier.
+
+    > ![image](/images/adfs_24_mattermost_encryption.png)
+
+4.  Configure Mattermost to sign SAML requests using the Service Provider Private Key.
+
+5.  Set attributes for the SAML Assertions, which will be used to update user information in Mattermost. Attributes for email and username are required and should match the values you entered in ADFS earlier. See [documentation on SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20) for more detail.
+
+For Mattermost servers running 3.3 and earlier, the `FirstName` and `LastName` attributes are also required fields.
+
+> ![image](/images/adfs_25_mattermost_attributes.png)
+
+6.  (Optional) Customize the login button text.
+
+> ![image](/images/adfs_26_mattermost_login_button.png)
+
+7.  Select **Save**.
+8.  (Optional) If you configured a `FirstName` and `LastName` Attribute, go to **System Console \> Site Configuration \> Users and Teams**, then set **Teammate Name Display** to **Show first and last name**. This is recommended for a better user experience.
+
+If you’d like to confirm SAML SSO is successfully enabled, switch your system admin account from email to SAML-based authentication from your profile picture via **Profile \> Security \> Sign-in Method \> Switch to SAML SSO**, then log in with your SAML credentials to complete the switch.
+
+We recommend that you post an announcement about how the migration will work for your users.
+
+You may also configure SAML for ADFS by editing the `config.json` file to enable SAML based on [SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20). You must restart the Mattermost server for the changes to take effect.
+
+<Inc1_sso_saml_ldapsync />
+
+<Inc2_sso_saml_faq />

docs/main/administration-guide/onboard/sso-saml-before-you-begin.mdx

@@ -0,0 +1,10 @@
+---
+title: "Before you begin"
+unlisted: true
+---
+{/* Snippet include: imported by every SAML identity provider page. */}
+
+Before you begin, you need to generate encryption certificates for encrypting the SAML connection.
+
+1.  You can use the [Bash script](https://github.com/mattermost/docs/tree/master/source/scripts/generate-certificates) from the `mattermost/docs` repository on GitHub, or any other suitable method. See the [generate self-signed certificates](https://github.com/mattermost/docs/blob/master/source/scripts/generate-certificates/gencert.md) documentation for details on generating a self-signed x509v3 certificate for use with multiple URLs / IPs.
+2.  Save the two files that are generated. They are the private key and the public key. In the System Console, they are referred to as the **Service Provider Private Key** and the **Service Provider Public Certificate** respectively.

docs/main/administration-guide/onboard/sso-saml-entraid.mdx

@@ -0,0 +1,156 @@
+---
+title: "Configure SAML with Microsoft Entra ID"
+---
+import Inc0_sso_saml_before_you_begin from './sso-saml-before-you-begin.mdx';
+import Inc1_sso_saml_ldapsync from './sso-saml-ldapsync.mdx';
+import Inc2_sso_saml_faq from './sso-saml-faq.mdx';
+
+<PlanAvailability slug="all-commercial" />
+
+This page provides guidance on configuring SAML with Microsoft Entra ID for Mattermost.
+
+<Tip>
+
+- Need to configure Entra ID for **OpenID Connect** authentication instead? See the [Entra ID Single Sign-On](/administration-guide/onboard/sso-entraid) documentation for details.
+- See the [supported SAML encryption methods](/administration-guide/configure/authentication-configuration-settings#supported-saml-encryption-methods) in the authentication configuration settings documentation.
+
+</Tip>
+
+<Inc0_sso_saml_before_you_begin />
+
+## Prerequisites
+
+- A Microsoft Entra tenant containing applicable user data.
+- A verified custom domain for your tenant. See Microsoft's [Add your custom domain name to your tenant](https://learn.microsoft.com/en-us/entra/fundamentals/add-custom-domain) documentation for details.
+- A Microsoft Entra ID P1 or P2 license.
+- An account with at least the **Application Administrator** role in your Entra tenant.
+
+## Set up an enterprise app for Mattermost SSO in Entra ID
+
+1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) with an account that has at least the **Application Administrator** role.
+2. In the left navigation menu, select **Entra ID > Enterprise applications**.
+3. Select **+ New application**.
+4. Select **+ Create your own application**.
+5. In the **What's the name of your app?** field, enter **Mattermost**.
+6. Under **What are you looking to do with your application?**, select **Integrate any other application you don't find in the gallery (Non-gallery)**.
+7. Select **Create**. Entra provisions the application; this may take a few seconds.
+8. In the **Mattermost** enterprise application settings, select **Manage > Users and groups**, then assign the approved users and/or groups that should have access to Mattermost.
+
+   <Warning>
+
+   Alternatively, you can select **Manage > Properties**, set **Assignment required?** to **No**, then select **Save**. This grants Mattermost access to **all users in your Entra tenant** — evaluate whether this aligns with your organization's access control requirements before proceeding.
+
+   </Warning>
+
+9. In the **Mattermost** enterprise application settings, select **Manage > Single sign-on**, then select **SAML** under **Select a single sign-on method**.
+10. Select **Edit** in the **Basic SAML Configuration** section, then set the fields below and select **Save**:
+
+    - **Identifier (Entity ID)**: `https://<your-mattermost-url>`
+    - **Reply URL (Assertion Consumer Service URL)**: `https://<your-mattermost-url>/login/sso/saml`
+    - **Sign on URL**: `https://<your-mattermost-url>/login`
+
+11. Select **Edit** in the **Attributes & Claims** section, then configure the required claim and additional claims as described below.
+
+    **How Entra claims map to Mattermost**
+
+    The SAML assertion Entra sends to Mattermost contains a set of *claims* — name/value pairs describing the user. Mattermost reads these claims based on the attribute names you configure in **System Console > Authentication > SAML 2.0 > Attributes** (for example, **Email Attribute**, **Username Attribute**, **First Name Attribute**).
+
+    The **Claim name** you set in Entra must match the value you enter in the corresponding Mattermost attribute field exactly, character for character. The **Value** (also called **Source attribute**) tells Entra which user property to send — for example, `user.mail` sends the user's email address.
+
+    a. **Required claim — Unique User Identifier (Name ID)**
+
+       Set the **Name identifier format** and **Source attribute** values as required for your environment. The Name ID is part of the SAML assertion, but Mattermost account binding is controlled by the **Id Attribute (SAML)** setting if you configure it, or by email otherwise. If you want immutable user binding in Mattermost, add a separate `Id` claim under **Additional claims** and set its **Value** (source attribute) to an immutable Entra attribute such as `user.objectid`. `user.userprincipalname` is also a common choice for Name ID when a human-readable identifier is preferred, with the trade-off that renames in Entra can orphan the corresponding Mattermost account if you rely on it for identity matching.
+
+    b. **Additional claims**
+
+       By default, Entra populates this section with four claims using the `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/...` namespace. These work, but we recommend replacing them with short, readable names that match the attribute fields in Mattermost. To edit a claim, select it, update the **Name** field (and clear the **Namespace** field), then save.
+
+       <Important>
+
+       Mattermost matches each attribute by its **full claim name**, including the namespace, exactly as it appears in the SAML assertion. By default, Entra emits its built-in claims under the namespace `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/` — so the claim that appears in the **Claim name** column as `emailaddress` is actually sent in the assertion as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`.
+
+       Entering only the short name (for example, `email` or `name`) in a Mattermost attribute field will **not** match, and login will fail with an error such as `SAML login was unsuccessful because one of the attributes is incorrect... <attribute> attribute is missing`.
+
+       You have two options:
+
+       - **Clear the namespace** on each claim in Entra ID (the approach shown in the table below) so the claim name becomes the short value (for example, `email`), then enter that same short value in Mattermost; **or**
+       - **Leave the default namespace** in Entra ID and enter the fully-qualified claim name in Mattermost (for example, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`).
+
+       If a login fails, the safest way to confirm the exact claim names being sent is to capture and decode the SAML response from the browser (for example, with the [SAML-tracer](https://addons.mozilla.org/firefox/addon/saml-tracer/) browser extension) and read the `Name` attribute of each `<Attribute>` element.
+
+       </Important>
+
+       The following claim configuration covers a typical Mattermost setup (using the clear-namespace option):
+
+       | Mattermost attribute field | Entra claim name | Entra source attribute |
+       |:---|:---|:---|
+       | Email Attribute | `email` | `user.mail` |
+       | Username Attribute | `username` | `user.mailnickname` |
+       | First Name Attribute | `firstname` | `user.givenname` |
+       | Last Name Attribute | `lastname` | `user.surname` |
+       | Position Attribute | `position` | `user.jobtitle` |
+
+       <Note>
+
+       Use `user.mailnickname` rather than `user.userprincipalname` as the source for the username claim. The user principal name is typically formatted as an email address (`user@domain.com`), but Mattermost usernames cannot contain the `@` character, so SAML logins using `user.userprincipalname` will fail. The mail nickname is the local part of the email address (the portion before `@`) and maps cleanly to a valid Mattermost username.
+
+       If your organization doesn't populate `mailnickname` consistently, another option is a custom Entra attribute or a transformation that strips the domain from the UPN.
+
+       </Note>
+
+       After editing, your **Attributes & Claims** page should look similar to the screenshot below:
+
+       ![Entra Attributes & Claims page showing simplified claim names](/images/entra-attributes-and-claims.png)
+
+       The **Guest**, **Admin**, **Nickname**, and **Preferred Language** attributes are also configurable in Mattermost if you want to drive them from Entra. Use the same pattern: pick a short claim name in Entra, set its source attribute, and enter the matching claim name in the corresponding Mattermost attribute field.
+
+12. Select **Edit** in the **SAML Certificates** section. Select **Sign SAML response and assertion** for **Signing Option** and **SHA-256** for **Signing Algorithm**, then select **Save**.
+13. Select the **Certificate (Base64)** Download link in the **SAML Certificates** section. This is the **Identity Provider Public Certificate** to be uploaded to Mattermost.
+14. In the **Mattermost** enterprise application settings, select **Security > Token encryption**. Select **Import Certificate** to import the Service Provider certificate. If you used the Bash script referenced in the **Before you begin** section, this is the `mattermost-x509.crt` file. The Import dialog says to upload a certificate with a file extension `.cer`, but `.crt` files are also accepted. Upload the file then select **Add**.
+15. Select the `...` to the right of the imported certificate details, select **Activate token encryption certificate**, then select **Yes** to activate.
+16. Copy the **Tenant ID** for use in the Mattermost **SAML 2.0** URL settings.
+
+    <Note>
+
+    Entra exposes three different GUIDs during this setup, and it's easy to confuse them. The **Tenant ID** identifies your entire Entra directory, while the **Application ID** and **Object ID** (visible on the enterprise application's **Properties** page) identify the Mattermost SAML application within that directory. Mattermost uses the Tenant ID and Application ID; the Object ID is not used.
+
+    </Note>
+
+    To find the Tenant ID, select **Entra ID** from the admin center home, then locate the **Tenant ID** value in the **Basic information** panel on the **Overview** page.
+
+    ![Where to find the Tenant ID](/images/entra-tenant-id.png)
+
+17. Copy the **Application ID** for use in the **Identity Provider Metadata URL** setting in the Mattermost **SAML 2.0** settings.
+
+    To find the Application ID, select **Entra ID > Enterprise applications** from the left navigation menu, select the **Mattermost** application, then copy the **Application ID** from the **Properties** page (shown alongside the Object ID, which is not needed).
+
+## Configure SAML Sign-On for Mattermost
+
+1.  In the Mattermost **System Console**, select **Authentication \> SAML 2.0**.
+2.  Set **Enable Login With SAML 2.0** to **True**.
+3.  Set **Identity Provider Metadata URL**: `https://login.microsoftonline.com/<your-tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<your-app-id>`
+4.  Select **Get SAML Metadata From IdP** to verify that the SAML metadata can be retrieved successfully.
+5.  Set **SAML SSO URL**: `https://login.microsoftonline.com/<your-tenant-id>/saml2`
+6.  Set **Identity Provider Issuer URL** (trailing slash is required): `https://sts.windows.net/<your-tenant-id>/`
+7.  Choose the **Identity Provider Public Certificate** file from step 13 of **Set up an enterprise app for Mattermost SSO in Entra ID** then upload.
+8.  Set **Verify Signature** to **True**.
+9.  Set **Service Provider Login URL**: `https://<your-mattermost-url>/login/sso/saml`
+10. Set **Service Provider Identifier**: `https://<your-mattermost-url>`
+11. Set **Enable Encryption** to **True**.
+12. Choose your **Service Provider Private Key** file then upload. If you used the Bash script referenced in the **Before you begin** section, this is the `mattermost-x509.key` file.
+13. Choose your **Service Provider Public Certificate** then upload. If you used the Bash script referenced in the **Before you begin** section, this is the `mattermost-x509.crt` file.
+14. Set **Sign Request** to **True** if you want Mattermost to sign outbound AuthnRequests sent to Entra ID — this is distinct from Entra signing its SAML responses and assertions (configured in step 12 of the Entra setup). If enabled, set **Signature Algorithm** to **RSAwithSHA256** (Entra ID requires RSA-SHA256 for signed requests) and upload Mattermost's public certificate to Entra ID for request verification: in the enterprise application, select **SAML Certificates**, then upload the `mattermost-x509.crt` file under **Verification certificates**.
+
+<Note>
+
+The **Test single sign-on with Mattermost SAML** tool in Microsoft Entra ID does not sign the request even if **Sign Request** is set to **True** in Mattermost. Depending on your security settings and key length, the Entra ID testing tool may successfully sign in while an actual sign in request from your Mattermost login page results in the error **AADSTS90015: Requested query string is too long.** since Entra ID handles the initial request with an HTTP GET redirect rather than HTTP POST.
+
+</Note>
+
+15. Set attribute settings to match the attributes configured in step 11 of the **Set up an enterprise app for Mattermost SSO in Entra ID** section. Each value must match the **full claim name** sent in the assertion, including the namespace, exactly. See the **important** note under step 11 for details and a common failure mode.
+16. Set the **Login Button Text** to suit your environment.
+17. Select the **Save** button.
+
+<Inc1_sso_saml_ldapsync />
+
+<Inc2_sso_saml_faq />

docs/main/administration-guide/onboard/sso-saml-faq.mdx

@@ -0,0 +1,67 @@
+---
+title: "Frequently Asked Questions"
+unlisted: true
+---
+{/* Snippet include: imported by every SAML identity provider page. */}
+
+## What encryption options are supported for SAML?
+
+See the [supported SAML encryption methods](/administration-guide/configure/authentication-configuration-settings#supported-saml-encryption-methods) in the authentication configuration settings documentation.
+
+## How to bind authentication to Id attribute instead of email
+
+Alternatively, you can use an `Id` attribute instead of email to bind the user. We recommend choosing an ID that is unique and will not change over time.
+
+Configuring with an `Id` attribute allows you to reuse an email address for a new user without the old user's information being exposed. For instance, if a user with an email address [joe.smith@mattermost.com](mailto:joe.smith@mattermost.com) was once an employee, a new employee named Joe Smith can use the same email. This configuration is also useful when a user's name changes and their email needs to be updated.
+
+This process was designed with backwards compatibility to email binding. Here is the process applied to new account creations and to accounts logging in after the configuration:
+
+- A user authenticated with SAML is bound to the SAML service user using the Id Attribute (as long as it has been configured) or bound by email using the email received from SAML.
+- When the user tries to login and the SAML server responds with a valid authentication, then the server uses the "Id" field of the SAML authentication to search the user.
+- If a user bound to that ID already exists, it logs in as that user.
+- If a user bound to that ID does not exist, it will search base on the email.
+- If a user bound to the email exists, it logs in with email and updates the autentication data to the ID, instead of the email.
+- If a user bound to the ID or email does not exist, it will create a new Mattermost account bound to the SAML account by ID and will allow the user to log in.
+
+<Note>
+
+Existing accounts won't update until they log in to the server.
+
+</Note>
+
+## Why does login fail with "one of the attributes is incorrect" / "`<attribute>` attribute is missing"?
+
+A login failure with the error `SAML login was unsuccessful because one of the attributes is incorrect. Please contact your System Administrator.` — accompanied in the server logs by a detail such as `email attribute is missing` or `name attribute is missing` — means the assertion from your Identity Provider (IdP) did not contain an attribute whose name **exactly** matches what you configured in the Mattermost SAML attribute settings.
+
+Mattermost matches each attribute by its full `Name` (or `FriendlyName`) as it appears in the assertion, character-for-character. The named attribute in the error message is the value you entered in Mattermost that could not be found.
+
+This most often happens because the IdP sends attributes under a namespace. For example, Microsoft Entra ID emits its built-in claims under `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/` by default, so an attribute that looks like `email` in the Entra ID admin UI is actually sent in the assertion as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/email`. Entering only `email` in Mattermost will not match.
+
+To resolve this:
+
+- Capture and decode the SAML response (for example, with the [SAML-tracer](https://addons.mozilla.org/firefox/addon/saml-tracer/) browser extension) and read the `Name` attribute of each `<Attribute>` element in the `<AttributeStatement>`.
+- Set each Mattermost attribute field to the **exact** `Name` value from the assertion — including any namespace prefix — or reconfigure the IdP to emit the claim under the short name you want to use in Mattermost.
+
+## Can SAML via Microsoft ADFS be configured with Integrated Windows Authentication (IWA)?
+
+Yes. IWA is supported on the browser, with support added to iOS and Android mobile apps in Q2/2019 (mobile apps v1.18 and later).
+
+However, IWA is not supported on the Mattermost Desktop Apps due to a limitation in Electron. As a workaround you may create a browser desktop shortcut for quick access to Mattermost, just like a Desktop App.
+
+## Can I provision and deprovision users who log in via SAML?
+
+Yes, but this relies on AD/LDAP to do so. Currently, we do not support SCIM. See ["How do I deactivate users?"](/administration-guide/onboard/ad-ldap#how-do-i-deactivate-users) for more information.
+
+## How do I migrate users from one authentication method (e.g. email) to SAML?
+
+See the [mmctl user migrate-auth](/administration-guide/manage/mmctl-command-line-tool#mmctl-user-migrate-auth) command documentation for details.
+
+## How is SAML different from OAuth 2.0 and OpenId Connect?
+
+OAuth 2.0 was primarily intended for delegated authorization, where an app is authorized to access resources, such as Google contact list. It doesn’t deal with authentication.
+
+OpenID Connect is built on top of OAuth 2.0, which supports authentication and thus direct SSO.
+
+SAML is like OpenID Connect, except typically used in enterprise settings. OpenID Connect is more common in consumer websites and web/mobile apps.
+
+Learn more at [https://hackernoon.com/demystifying-oauth-2-0-and-openid-connect-and-saml-12aa4cf9fdba](https://hackernoon.com/demystifying-oauth-2-0-and-openid-connect-and-saml-12aa4cf9fdba).

docs/main/administration-guide/onboard/sso-saml-keycloak.mdx

@@ -0,0 +1,274 @@
+---
+title: "Configure SAML with Keycloak"
+---
+import Inc0_sso_saml_ldapsync from './sso-saml-ldapsync.mdx';
+import Inc1_sso_saml_faq from './sso-saml-faq.mdx';
+
+<PlanAvailability slug="all-commercial" />
+
+The following process provides steps to configure SAML with Keycloak for Mattermost.
+
+See the [supported SAML encryption methods](/administration-guide/configure/authentication-configuration-settings#supported-saml-encryption-methods) in the authentication configuration settings documentation.
+
+## Set up Keycloak for Mattermost SSO
+
+<Note>
+
+This was tested with Keycloak v26.4.0. We recommend adding Mattermost as a client to your primary realm.
+
+</Note>
+
+1.  Log in to Keycloak as an administrator.
+2.  Select **Clients**, then **Create client**. You'll use this client ID in a later step.
+
+> - **Client type**: `SAML`
+> - **Client ID**: `mattermost`
+
+3.  Click **Next** and update the following values:
+
+> - **Root URL**: `http://your-mattermost-url.com`
+> - **Home URL**: `/login/sso/saml`
+> - **Valid redirect URIs**: `/login/sso/saml`
+
+4.  **Save** the client.
+5.  Under the **Settings** tab, update the following values:
+
+> - **Enabled**: **On**
+> - **Name ID format**: `email`
+> - **Force Name ID format**: **On**
+>
+> ![In Keycloak, create the Mattermost client, specify the Client ID and Client Protocol, then save your changes.](/images/keycloak_1_client_settings.png)
+>
+> ![In Keycloak, create the Mattermost client, specify the Client ID and Client Protocol, then save your changes.](/images/keycloak_1_client_settings_2.png)
+
+6.  Under the **Signature and Encryption** section, update the following values:
+
+> - **Sign Documents**: **Off**
+> - **Sign Assertions**: **On**
+> - **Signature Algorithm**: `RSA_SHA256`
+> - **SAML signature key name**: `NONE`
+> - **Canonicalization Method**: `EXCLUSIVE`
+> - **Encryption Algorithm**: `AES_256_GCM`
+> - **Key Transport Algorithm**: `RSA_OAEP_MGF1P`
+> - **Digest method for RSA-OAEP**: `SHA1`
+>
+> ![In Keycloak, configure the Signature and Encryption settings for the Mattermost client.](/images/keycloak_1_client_signature_encryption.png)
+>
+> <div class="note">
+>
+> <div class="title">
+>
+> Note
+>
+> </div>
+>
+> Earlier versions of this documentation recommended `RSA_SHA1`. Use `RSA_SHA256` instead. [NIST SP 800-131A](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) set December 31, 2013 as the deadline after which SHA-1 is disallowed for digital signature generation. Revision 2 of that publication, published in March 2019, allows SHA-1 signature generation only where NIST protocol-specific guidance specifically permits it. A Keycloak server running in FIPS mode returns a `500` error when it tries to sign the assertion with `RSA_SHA1`. Mattermost validates `RSA_SHA256`-signed assertions, and Keycloak derives the signature digest method from the signature algorithm you select here.
+>
+> </div>
+
+7.  Navigate to the **Keys** tab.
+
+> - **Client signature required**: **Off**
+>
+> - **Encrypt Assertions**: **On**
+>
+>   1.  Click **Generate**
+>   2.  Download the **private.key** file.
+>   3.  Click **Confirm**
+>
+>   ![In Keycloak, on the Keys tab, generate new keys for encryption.](/images/keycloak_2_saml_keys.png)
+>
+>   <div class="warning">
+>
+>   <div class="title">
+>
+>   Warning
+>
+>   </div>
+>
+>   Leave **Client signature required** off, as shown above. Mattermost does sign its authentication requests when you enable **Sign Request** in step 4 of the Mattermost section below, but Keycloak validates those signatures only if you also import the Mattermost service provider certificate as a signing key on this tab. Turning **Client signature required** on without importing that certificate causes Keycloak to reject Mattermost's authentication requests.
+>
+>   </div>
+>
+>   <div class="note">
+>
+>   <div class="title">
+>
+>   Note
+>
+>   </div>
+>
+>   **If your Keycloak server runs in FIPS mode**, the **Archive Format** list offers only `BCFKS`, because `PKCS12` and `JKS` are unavailable. Export the `BCFKS` keystore, then convert it to `PKCS12` before you continue:
+>
+>   ```console
+>   keytool -importkeystore -srckeystore keystore.bcfks -srcstoretype BCFKS -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath /path/to/bc-fips-<version>.jar -destkeystore keystore.p12 -deststoretype PKCS12
+>   ```
+>
+>   Point `-providerpath` at your Bouncy Castle FIPS JAR. `keytool` prompts for the source and destination store passwords. The converted `keystore.p12` then works with the extraction commands in step 4 of Configure SAML in Mattermost below.
+>
+>   Convert the whole keystore as shown above rather than looking for a way to export the key on its own, because `keytool` has no command that exports a private key by itself.
+>
+>   As an alternative, generating the keypair locally and importing only the certificate into Keycloak avoids the keystore conversion entirely, and works on FIPS and non-FIPS servers alike:
+>
+>   ```console
+>   openssl req -x509 -newkey rsa:2048 -nodes -days 1095 -subj "/CN=mattermost" -keyout mattermost.key -out mattermost.crt
+>   ```
+>
+>   Keep `-nodes`, because Mattermost can't read a passphrase-protected private key. Set `-days` explicitly, because it defaults to 30. Keep `-keyout` and `-out`, because without them the certificate goes to standard output and the private key goes to a configuration-dependent default filename.
+>
+>   Import only `mattermost.crt` into the encryption keys section of this tab, then upload both files in step 4 below and skip the `openssl pkcs12` extraction commands, since you already have the files those commands would have produced.
+>
+>   </div>
+>
+>   Next, click **Export** and update the following values and download the keystore.p12 file.
+>
+>   - **Archive Format**: `PKCS12`
+>   - **Key Alias**: `mattermost`
+>   - **Key Password**: `mattermost`
+>   - **Store Password**: `mattermost`
+>
+>   ![In Keycloak, on the Keys tab, generate new keys, export using the values documented, then select Download.](/images/keycloak_2_saml_keys_2.png)
+
+8.  Navigate to the **Client scopes** tab.
+
+    First we add the predefined mappers for email, first name, and last name.
+
+    1.  Select **mattermost-dedicated**
+    2.  Click **Add predefined mapper**
+    3.  Select the **X500 email**, **X500 givenName**, and **X500 surname** attributes.
+    4.  Click **Add**.
+
+    Next, we add the mappers for username and id.
+
+    1.  Select **Add Mapper** -\> **By Configuration** -\> User Property.
+    2.  Set **Name** to `Username`.
+    3.  Set **Property** to `username` (This is case sensitive and must be lowercase).
+    4.  Set **SAML Attribute Name** to `username`.
+    5.  Select **Save**.
+
+    ![In Keycloak, on the Mappers tab, create a protocol mapper, then save your changes.](/images/keycloak_4_create_username_attribute.png)
+
+    6.  Repeat the above steps and use the custom property of `id` to create the ID Attribute.
+
+    ![In Keycloak, on the Mappers tab, create a protocol mapper for the ID attribute, then save your changes.](/images/keycloak_4_create_id_attribute.png)
+
+<Note>
+
+If you're planning to sync your SAML users with LDAP within Mattermost, the ID value used here must match with your Mattermost LDAP `ID Attribute`.
+
+</Note>
+
+Once done your Mappers should look like this:
+
+![Example of protocol mapper configuration.](/images/keycloak_4_create_username_attribute_finished.png)
+
+9.  Get the metadata URL from Keycloak:
+
+    1.  Within your Realm, select **Realm Settings**.
+    2.  At the bottom of the **General** tab you should see a **SAML 2.0 Identity Provider Metadata** endpoint. Right-click and copy this URL. Store for the next step.
+
+    ![Within your Realm, select Realm Settings. At the bottom of the General tab, you should see a SAML 2.0 Identify Provider Metadata endpoint. Copy this URL for the next step.](/images/keycloak_5_export_metadata.png)
+
+## Configure SAML in Mattermost
+
+1.  In the Mattermost **System Console** go to **Authentication \> SAML**.
+
+2.  Set the **Identity Provider Metadata URL** to the value you copied from the step above and select **Get SAML Metadata from IdP**. The metadata import will populate fields related to your Keycloak configuration.
+
+    If you have any issues with this import, you can check the `mattermost.log` file for more information. [Enable debug logging](/administration-guide/manage/logging#how-do-i-enable-debug-logging) and try again.
+
+    > ![In Mattermost, configure SAML in the System Console by going to Authentication \> SAML. Set the Identity Provider Metadata URL to the value you copied in the previous step. When you select Get SAML Metadata from IdP, fields related to your Keycloak configuration are populated.](/images/keycloak_6_get_metadata.png)
+
+<Note>
+
+- If Mattermost does not correctly pull the **Identity Provider Public Certificate** you can manually add it by opening the metadata URL in a browser, copying the certificate value, and use a tool like [OneLogin's X.509 formatter](https://www.samltool.com/format_x509cert.php) that can format the certificate for you. Then save the correctly formatted certificate to a file and upload it to the **Identity Provider Public Certificate** field in the Mattermost System Console.
+- If Mattermost can not pull the metadata and is throwing a connection issue enable debug logging and see if you need to add your Keycloak url to the **Allowed Untrusted Internal Connections** list in the System Console under **Environment \> Developer** and restart the server. See the [Allowed Untrusted Internal Connections](/administration-guide/configure/environment-configuration-settings#allow-untrusted-internal-connections) documentation for details.
+
+</Note>
+
+3.  Set the below fields:
+
+    - **Verify Signature**: **false**
+    - **Service Provider Login URL**: `http://your-mattermost-url.com/login/sso/saml`
+    - **Service Provider Identifier**: `mattermost`
+
+    The Service Provider Identifier will match the **Client ID** that you configured in the second Keycloak step.
+
+    ![In the System Console, configure SAML as documented, where the Service Provider Identifier matches the Client ID you configured in Keycloak.](/images/keycloak_7_mattermost_config.png)
+
+4.  Configure the Encryption using the key you downloaded in step 6 of the Keycloak config.
+
+    1.  Generate the `.crt` file from the `.p12` file.
+
+    ``` console
+    openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.crt -nodes -legacy
+    ```
+
+    2.  Generate the `.key` file from the `.p12` file.
+
+    ``` console
+    openssl pkcs12 -password pass:mattermost -in keystore.p12 -out mattermost.key -nodes -nocerts -legacy
+    ```
+
+    3.  Upload both of these files within the Mattermost System Console. Make sure to select **Upload**.
+
+    > - **Service Provider Private Key**: `mattermost.key`
+    > - **Service Provider Private Certificate**: `mattermost.crt`
+    > - **Sign Request**: **true**
+    > - **Signature Algorithm**: `RSAwithSHA256`
+    > - **Canonicalization Algorithm**: `Exclusive XML Canonicalization 1.0 (omits comments)`
+    >
+    > ![In the System Console, upload both the Service Provider Private Key and the Service Provider Private Certificate.](/images/keycloak_8_mattermost_encryption.png)
+
+5.  Set attributes for the SAML Assertions, which will update user information in Mattermost.
+
+    The attributes below are from steps 7 and 8 above. These values must be the **SAML Attribute Name** within Keycloak. See [documentation on SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20) for more details.
+
+    - **Email Attribute**: `email`
+    - **Username Attribute**: `username`
+    - **Id Attribute**: `id`
+
+    ![Set attributes for the SAML assertions which updates user information in Mattermost.](/images/keycloak_9_mattermost_attributes.png)
+
+6.  Select **Save**.
+
+To confirm SAML is working correctly, log out of Mattermost or open Mattermost in a new Incognito Browser Window and select **Sign in with SAML** on the login page and login with an existing Keycloak account.
+
+If you have existing users in Mattermost that are going to be migrated to SAML login, make sure to plan for user migration and update your users accordingly.
+
+You may also configure SAML for Keycloak by editing `config.json`. Before starting the Mattermost server, edit `config.json` to enable SAML based on [SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20). You must restart the Mattermost server for the changes to take effect.
+
+## Configuing a SAML user as a Guest in Keycloak
+
+1.  In Mattermost, go to **System Console \> Authentication \> SAML**.
+
+2.  Set the **Guest Attribute** to designate which SAML users are guests.
+
+    ![In Mattermost, configure the SAML guest attribute](/images/mm-guset-config.png)
+
+3.  In the Keycloak administration interface, add a user attribute mapper for guests.
+
+> 1.  Select **Clients** from the LHS menu.
+> 2.  Select **mattermost** from the list.
+>
+> > - Select the *Client Scopes* tab
+> > - Select *mattermost dedicated* from the list of scopes
+> > - Click the *Add mapper* drop down and select *By configuration*
+> > - Select *User Attribute* on the model that opens
+> > - Add values for *Name*, *User Attribute* and *SAML Attribute Name* as shown
+> >
+> > ![\<Add attribute mapper\>](/images/keycloak-mapper-details.png)
+
+4.  In Keycloak specify which users are guest by adding the attribute under **User details**
+
+> 1.  Select **Users** from the LHS menu.
+> 2.  Select the username of the desired user.
+> 3.  Select the **Attribute** tab and select **+ add an attribute**.
+> 4.  Add the key and value.
+>
+> > ![An example of adding an attribute to a user.](/images/guest-user-attribute.png)
+
+<Inc0_sso_saml_ldapsync />
+
+<Inc1_sso_saml_faq />
+:start-after: :nosearch:

docs/main/administration-guide/onboard/sso-saml-ldapsync.mdx

@@ -0,0 +1,56 @@
+---
+title: "Configure SAML synchronization with AD/LDAP"
+unlisted: true
+---
+{/* Snippet include: imported by every SAML identity provider page. */}
+
+In addition to configuring SAML sign-in, you can optionally configure synchronizing SAML accounts with AD/LDAP. When configured:
+
+- Mattermost queries AD/LDAP for relevant account information and updates SAML accounts based on changes to attributes (first name, last name, and nickname)
+- Accounts disabled in AD/LDAP are deactivated in Mattermost, and their active sessions are revoked once Mattermost synchronizes attributes.
+
+To configure SAML synchronization with AD/LDAP:
+
+1.  Go to **System Console \> Authentication \> SAML 2.0**, then set **Enable Synchronizing SAML Accounts With AD/LDAP** to **true**.
+
+2.  Go to **System Console \> Authentication \> AD/LDAP** to open the AD/LDAP wizard, navigate to the **Connection Settings** section, then set **Enable Synchronization with AD/LDAP** to **true**.
+
+3.  To ignore guest users when sychronizing, go to **System Console \> Authentication \> SAML 2.0**, then set **Ignore Guest Users when Synchronizing with AD/LDAP** to **true**.
+
+4.  Set the rest of the AD/LDAP settings based on [configuration settings documentation](/administration-guide/configure/authentication-configuration-settings#adldap) to connect Mattermost with your AD/LDAP server.
+
+    If you don't want to enable AD/LDAP sign-in, go to **System Console \> Authentication \> AD/LDAP** wizard, navigate to the **Connection Settings** section, then set **Enable sign-in with AD/LDAP** to **false**.
+
+5.  To specify how often Mattermost synchronizes SAML user accounts with AD/LDAP, go to **System Console \> Authentication \> AD/LDAP** wizard, navigate to the **Sync Performance** section, then set a **Synchronization Interval** in minutes. The default setting is 60 minutes. If you want to synchronize immediately after disabling an account, go to the **Sync History** section and select **AD/LDAP Synchronize Now**.
+
+6.  To confirm that Mattermost can successfully connect to your AD/LDAP server, go to **System Console \> Authentication \> AD/LDAP** wizard, navigate to the **Connection Settings** section, then select **Test Connection**.
+
+Once the synchronization with AD/LDAP is enabled, user attributes are synchronized with AD/LDAP based on their email address. If a user with a given email address doesn't have an AD/LDAP account, they will be deactivated in Mattermost on the next AD/LDAP sync.
+
+To re-activate the account:
+
+1.  Add the user to your AD/LDAP server.
+2.  Purge all caches in Mattermost by going to **System Console \> Environment \> Web Server**, then select **Purge All Caches**.
+3.  Run AD/LDAP synchronization by going to **System Console \> Authentication \> AD/LDAP** wizard, navigating to the **Sync History** section, then select **AD/LDAP Synchronize Now**.
+4.  Purge all caches again in Mattermost by going to **System Console \> Environment \> Web Server**, then select **Purge All Caches** again. This re-activates the account in Mattermost.
+
+<Note>
+
+\- If a user is deactivated from AD/LDAP, they will be deactivated in Mattermost on the next sync. They will be shown as "Deactivated" in the System Console users list, all of their sessions will expire and they won't be able to log back in to Mattermost. - If a user is deactivated from SAML, their session won't expire until they're deactivated from AD/LDAP. However, they won't be able to log back in to Mattermost. - SAML synchronization with AD/LDAP is designed to pull user attributes such as first name and last name from your AD/LDAP, not to control authentication. In particular, the user filter cannot be used to control who can log in to Mattermost, this should be controlled by your SAML service provider's group permissions.
+
+</Note>
+
+See [technical description of SAML synchronization with AD/LDAP](/administration-guide/onboard/sso-saml-technical) for more details.
+
+## Override SAML data with AD/LDAP data
+
+Alternatively, you can choose to override SAML bind data with AD/LDAP information. For more information on binding a user with the SAML ID Attribute, please refer to this [documentation](/administration-guide/onboard/sso-saml-okta#how-to-bind-authentication-to-id-attribute-instead-of-email).
+
+This process overrides SAML email address with AD/LDAP email address data or SAML Id Attribute with AD/LDAP Id Attribute if configured. We recommend using this configuration with the SAML ID Attribute to help ensure new users are not created when the email address changes for a user.
+
+To ensure existing user accounts do not get disabled in this process, ensure the SAML IDs match the LDAP IDs by exporting data from both systems and comparing the ID data. Mapping ID Attributes for both AD/LDAP and SAML within Mattermost to fields that hold the same data will ensure the IDs match as well.
+
+1.  Set the SAML `Id Attribute` by going to **System Console \> Authentication \> SAML 2.0 \> Id Attribute**.
+2.  Set **System Console \> Authentication \> SAML 2.0 \> Override SAML bind data with AD/LDAP information** to **true**.
+3.  Set **System Console \> Authentication \> SAML 2.0 \> Enable Synchronizing SAML Accounts With AD/LDAP** to **true**.
+4.  Run AD/LDAP sync by going to **System Console \> Authentication \> AD/LDAP** wizard, navigating to the **Sync History** section, then select **AD/LDAP Synchronize Now**.

docs/main/administration-guide/onboard/sso-saml-okta.mdx

@@ -0,0 +1,126 @@
+---
+title: "Configure SAML with Okta"
+---
+import Inc0_sso_saml_before_you_begin from './sso-saml-before-you-begin.mdx';
+import Inc1_sso_saml_ldapsync from './sso-saml-ldapsync.mdx';
+import Inc2_sso_saml_faq from './sso-saml-faq.mdx';
+
+<PlanAvailability slug="all-commercial" />
+
+The following process provides steps to configure SAML 2.0 with Okta for Mattermost.
+
+See the [supported SAML encryption methods](/administration-guide/configure/authentication-configuration-settings#supported-saml-encryption-methods) in the authentication configuration settings documentation.
+
+<Inc0_sso_saml_before_you_begin />
+
+## Set Up a connection app for Mattermost Single Sign-On
+
+1.  Log in to Okta as an administrator.
+
+2.  Switch to the **Classic UI**, using the drop-down in the upper left.
+
+3.  Go to **Admin Dashboard \> Applications \> Add Application**.
+
+4.  Select **Create New App**, then choose **SAML 2.0** as the Sign on method.
+
+    > ![In Okta, switch to the Classic UI, then go to the Admin Dashboard \> Applications \> Add Application to create a new app. Choose SAML 2.0 as the Sign on method.](/images/okta_1_new_app.png)
+
+5.  Enter **General Settings** for the application, including **App name** and **App logo** (optional). It's recommended to display the application icon to users, including in the Okta Mobile app. If you’d like to use a Mattermost logo for the application, you can download one [from our page](https://handbook.mattermost.com/operations/operations/publishing/publishing-guidelines/brand-and-visual-design-guidelines).
+
+    > ![In Okta, under General Settings, enter an App name and an optional logo. Mattermost recommends displaying the application icon to users and within the Okta mobile app. Select Next to continue.](/images/okta_2_general_settings.png)
+
+6.  Enter **SAML Settings**, including:
+
+> - **Single sign on URL:** `https://<your-mattermost-url>/login/sso/saml` where `https://<your-mattermost-url>` should typically match the [Mattermost Site URL](/administration-guide/configure/environment-configuration-settings#site-url).
+>
+> - **Audience URI:** For instance, `mattermost`
+>
+> - **Name ID format:** `unspecified`
+>
+> - **Application username:** `Email`
+>
+>   > ![In Okta, under Configure SAML, enter required SAML settings.](/images/okta_3_initial_saml_settings.png)
+
+7.  To set up encryption for your SAML connection, select **Show Advanced Settings**.
+
+    ![In Okta, under Configure SAML, set up encryption for your SAML connection by selecting Show Advanced Settings.](/images/okta_4_initial_saml_settings.png)
+
+8.  Set **Assertion Encryption** as **Encrypted**, then upload the Service Provider Public Certificate you generated earlier to the **Encryption Certificate** field.
+
+    > ![In Advanced Settings, set the Assertion Encryption as Encrypted, then upload the generated Service Provider Public Certificate to the Encryption Certificate field](/images/okta_5_advanced_saml_settings.png)
+
+9.  Enter attribute statements used to map attributes between Okta and Mattermost. For more information on which attributes are configurable, see our [documentation on SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20). Email and username attributes are required. For SAML with Okta, an [ID attribute](/administration-guide/configure/authentication-configuration-settings#id-attribute) is also required, and that ID must be mapped to `user.id`.
+
+    > ![Enter attribute statements used to map attributes between Okta and Mattermost. Email and username attributes are required. Okta also requires an ID attribute that must be mapped to user.id.](/images/okta_6_attribute_statements.png)
+
+10. Select **Next**. Then, set Okta support parameters for the application. Recommended settings:
+
+> - **I’m an Okta customer adding an internal app**
+>
+> - **This is an internal app that we have created**
+>
+>   > ![Set recommended Okta support parameters for the application, including I'm an Okta customer adding an internal app and This is an internal app that we have created.](/images/okta_7_support_configuration.png)
+
+11. Select **Finish**.
+
+12. In the Mattermost System Console, go to **Authentication \> SAML 2.0**, then set **Override SAML bind data with AD/LDAP information** to **false** if currently set to **true**. You can re-enable [this configuration setting](/administration-guide/configure/authentication-configuration-settings#override-saml-bind-data-with-adldap-information) later when once setup is complete.
+
+13. On the next screen, select the **Sign On** tab, then select **View Setup Instructions**.
+
+14. Select the **Identity Provider metadata** link, then copy the link from the browser URL field. This will be used during the SAML configuration steps in the next section.
+
+    ![In the Mattermost System Console, after disabling the Override SAML bind data with AD/LDAP information setting, select the Sign On tab, then select View Setup Instructions. Select the Identity Provider metadata link, then copy the link from the browser URL field to a convenient location.](/images/okta_8_view_instructions.png)
+
+15. Take note of **Identity Provider Single Sign-On URL** (also known as **SAML SSO URL**), and the Identity Provider Issuer, as both may be needed to configure SAML for Mattermost.
+
+16. Download the X.509 Certificate file and save it. You may need to upload it to Mattermost in a later step.
+
+    ![Download the X.509 certificate file and save it. You'll upload this certificate file to Mattermost later.](/images/okta_9_view_instructions.png)
+
+## Configure SAML Sign-On for Mattermost
+
+Start the Mattermost server and log in to Mattermost as a system admin. Go to **System Console \> Authentication \> SAML 2.0**, then paste the copied Identity Provider Metadata URL in the **Identity Provider Metadata URL** field and select **Get SAML Metadata from IdP**.
+
+This populates the **SAML SSO URL** and the **Identity Provider Issuer URL** fields automatically. The Identity Provider Public Certificate is also downloaded from the server and set locally.
+
+Alternatively you can enter the following fields manually:  
+- **SAML SSO URL:** `Identity Provider Single Sign-On URL` from Okta, specified earlier.
+
+- **Identity Provider Issuer URL:** `Identity Provider Issuer` from Okta, specified earlier.
+
+- **Identity Provider Public Certificate:** X.509 Public Certificate file you downloaded from Okta earlier.
+
+  > ![In the Mattermost System Console, go to Authentication \> SAML 2.0 to manually enter the SAML SSO URL and Identity Provider Issuer URL, and upload the Identity Provider Public Certificate manually.](/images/okta_10_mattermost_basics.png)
+
+2.  Configure Mattermost to verify the signature. The **Service Provider Login URL** is the `Single sign on URL` you specified in Okta earlier.
+
+    > ![On the SAML 2.0 page, configure Mattermost to verify the signature, and set the Service Provider Login ULR as the Single sign on URL configured in Okta.](/images/okta_11_mattermost_verification.png)
+
+3.  Enable encryption based on the parameters provided earlier.
+
+    > ![On the SAML 2.0 page, enable encryption and upload both the Service Provider Private Key and the Service Provider Public Certificate.](/images/okta_12_mattermost_encryption.png)
+
+4.  Configure Mattermost to sign SAML requests using the Service Provider Private Key.
+
+5.  Set attributes for the SAML Assertions used to update user information in Mattermost.  
+    - Attributes for Email, Username, and Id are required and should match the values you entered in Okta earlier.
+
+    ![Set attributes for the SAML Assertions used to update user information in Mattermost.  Attributes for Email, Username, and Id are required and should match the values set in Okta.](/images/okta_13_mattermost_attributes.png)
+
+6.  (Optional) Customize the login button text.
+
+    > ![You can customize the login button text. By default, the text displays as "With SAML".](/images/okta_14_mattermost_login_button.png)
+
+7.  Select **Save**.
+
+8.  (Optional) If you configured `First Name` Attribute and `Last Name` Attribute, go to **System Console \> Site Configuration \> Users and Teams**, then set **Teammate Name Display** to **Show first and last name**. This is recommended for a better user experience.
+
+Once complete, and to confirm SAML SSO is successfully enabled, switch your system admin account from email to SAML-based authentication from your profile picture via **Profile \> Security \> Sign-in Method \> Switch to SAML SSO**, then log in with your SAML credentials to complete the switch.
+
+We also recommend that you post an announcement for your users to explain how the migration will work.
+
+You may also configure SAML for Okta by editing the `config.json` file to enable SAML based on [SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20). You must restart the Mattermost server for the changes to take effect.
+
+<Inc1_sso_saml_ldapsync />
+
+<Inc2_sso_saml_faq />

docs/main/administration-guide/onboard/sso-saml-onelogin.mdx

@@ -0,0 +1,174 @@
+---
+title: "Configure SAML with OneLogin"
+---
+import Inc0_sso_saml_before_you_begin from './sso-saml-before-you-begin.mdx';
+import Inc1_sso_saml_ldapsync from './sso-saml-ldapsync.mdx';
+import Inc2_sso_saml_faq from './sso-saml-faq.mdx';
+
+<PlanAvailability slug="all-commercial" />
+
+The following process provides steps to configure SAML 2.0 with OneLogin for Mattermost.
+
+See the [supported SAML encryption methods](/administration-guide/configure/authentication-configuration-settings#supported-saml-encryption-methods) in the authentication configuration settings documentation.
+
+<Inc0_sso_saml_before_you_begin />
+
+## Create a OneLogin connection app for Mattermost SSO
+
+1.  Add a SAML test connector app.
+
+> 1.  Log in to OneLogin as an administrator.
+> 2.  Go to **Apps \> Add Apps**.
+> 3.  Search for "SAML Test Connector", then select **SAML Test Connector (Advanced)**.
+>
+> ![In OneLogin, go to Apps \> Add Apps, search for SAML Test Connector, then select the matching result in the list](/images/onelogin_1_new_app.png)
+>
+> 4.  In the **Display Name** field, enter a name for the application, then optionally upload an app icon. You can use the Mattermost logo for the icon, which you can download from [Branding Guidelines](https://handbook.mattermost.com/operations/operations/publishing/publishing-guidelines/brand-and-visual-design-guidelines) page.
+>
+> ![Enter a display name for the application in the Display Name field. You can optionally upload an app icon. Ensure the Visible in portal option is enabled, and save your OneLogin changes.](/images/onelogin_2_basic_configuration.png)
+>
+> 5.  Make sure that the **Visible in portal** option is enabled.
+> 6.  Select **Save**.
+
+2.  Configure the app.
+
+> 1.  Select the **Configuration** tab, then enter the following values:
+>
+> > - **RelayState**: leave blank
+> > - **Audience**: leave blank
+> > - **Recipient**: `https://<your-mattermost-url>/login/sso/saml` where `https://<your-mattermost-url>` should typically match the [Mattermost Site URL](/administration-guide/configure/environment-configuration-settings#site-url).
+> > - **ACS (Consumer) URL Validator**: `https:\/\/<your-mattermost-url>\/login\/sso\/saml`
+> > - **ACS (Consumer) URL**: `https://<your-mattermost-url>/login/sso/saml`
+>
+> ![In OneLogin, select the Configuration tab to configure the SSO integration with required values.](/images/onelogin_3_configuration_1.png)
+>
+> 2.  In System Console, [enable encryption](/administration-guide/configure/authentication-configuration-settings#enable-encryption), then select **Save**. You're redirected to the **Info** tab. From there, select the **Configuration** tab to access the **SAML Encryption** field.
+> 3.  Paste the Public Key that you generated earlier into the **SAML Encryption** field at the bottom of the page. This field displays in OneLogin only when encryption is enabled in Mattermost.
+>
+> ![In the Mattermost System Console, enable encryption and save your changes. When you return to OneLogin, return to the Configuration tab, access the SAML Encryption field, and paste the generated Public Key into the SAML Encryption field. This field isn't visible in OneLogin until encryption is enabled in Mattermost. Save your OneLogin changes.](/images/onelogin_4_configuration_2.png)
+>
+> 4.  Select **Save**.
+
+3.  Enter the attribute parameters. The following attributes are recommended:
+
+<table style={{width: '26%'}}>
+<colgroup>
+<col style={{width: '14%'}} />
+<col style={{width: '11%'}} />
+</colgroup>
+<thead>
+<tr>
+<th>Name</th>
+<th>Value</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>ID</td>
+<td>UUID</td>
+</tr>
+<tr>
+<td>Email</td>
+<td>Email</td>
+</tr>
+<tr>
+<td>FirstName</td>
+<td>First Name</td>
+</tr>
+<tr>
+<td>LastName</td>
+<td>Last Name</td>
+</tr>
+<tr>
+<td>Name ID value</td>
+<td>Email</td>
+</tr>
+<tr>
+<td>Username</td>
+<td>Username</td>
+</tr>
+</tbody>
+</table>
+
+> Attribute parameters map attributes between OneLogin and Mattermost. For more information on which attributes are configurable, see our [documentation on SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20).
+>
+> *Email* attributes are required.
+>
+> 1.  Select the **Parameters** tab.
+> 2.  Select **Add Parameter**.
+>
+> ![In OneLogin, select the Parameters tab, then select Add parameter. Map attribute parameters between OneLogin and Mattermost. Email attributes are required.](/images/onelogin_5_parameters_add.png)
+>
+> 3.  In the **Field name** field, enter an attribute parameter such as `Email`.
+> 4.  Select the **Include in SAML assertion** checkbox.
+> 5.  Select **Save**.
+>
+> ![For each field you map in OneLogin, ensure the Include in SAML assertion flag is enabled.](/images/onelogin_6_parameters_add_2.png)
+>
+> 6.  Select **Edit**.
+> 7.  In the **Value** field, select the OneLogin value that corresponds to the attribute parameter.
+>
+> ![For each field you map in OneLogin, select the OneLogin value that corresponds to the attribute parameter.](/images/onelogin_7_parameters_add_3.png)
+>
+> 8.  Repeat the steps above to add any other attributes that you need. After you've added all the attributes you want to use, the parameter list should look similar to the following image:
+>
+> > ![Example of attribute parameters mapped between OneLogin and Mattermost.](/images/onelogin_8_parameters_add_4.png)
+
+4.  Copy the SSO information.
+
+> 1.  Select the **SSO** tab.
+> 2.  Copy the values in the **Issuer URL** and **SAML 2.0 Endpoint (HTTP)** fields, then save them for later use.
+>
+> ![In OneLogin, select the SSO tab, copy the Issuer URL and SAML 2.0 Endpoint (HTTP) values to a convenient location.](/images/onelogin_9_sso.png)
+>
+> 3.  Select **View Details** to view the X.509 certificate.
+> 4.  Make sure that the **X.509 PEM** option is selected in the drop-down.
+>
+> ![On the SSO tab in OneLogin, select View Details to access the X.509 certificate. Ensure that the X.509 PEM option is selected. Select Download and save the file in a convenient location.](/images/onelogin_10_sso_certificate.png)
+>
+> 5.  Select **DOWNLOAD**, then save the file in a convenient location for later use.
+
+5.  Save all your changes.
+
+## Configure SAML Sign-On for Mattermost
+
+1.  Start the Mattermost server, then log in to Mattermost as a system admin. Go to **System Console \> Authentication \> SAML**.
+
+> 1.  Enter the **OneLogin Issuer URL** into the **Identity Provider Metadata URL** field.
+> 2.  Select **Get SAML Metadata from IdP** to download the metadata.
+
+2.  Configure Mattermost to verify the signature.
+
+> 1.  In the **Verify Signature** field, select **True**.
+> 2.  In the **Service Provider Login URL**, enter `https://<your-mattermost-url>/login/sso/saml`.
+>
+> ![On the System Console SAML page, enable the Verify Signature option by setting it to true, then enter your specific Service Provider Login URL based on your Mattermost URL](/images/okta_11_mattermost_verification.png)
+
+3.  Configure Mattermost to sign SAML requests using the Service Provider Private Key.
+4.  Enable encryption.
+
+> 1.  In the **Enable Encryption** field, select **True**.
+> 2.  In the **Service Provider Private Key** field, upload the private key that you generated earlier.
+> 3.  In the **Service Provider Public Certificate** field, upload the public key that you generated earlier.
+>
+> ![On the System Console SAML page, enable encryption, then upload both the private and public generated keys.](/images/okta_12_mattermost_encryption.png)
+
+5.  Set attributes for the SAML Assertions, which are used for updating user information in Mattermost.
+
+> The **Email Atttribute** field and the **Username Attribute** field are required, and should match the values that you entered earlier when you configured the SAML Test Connector on OneLogin.
+>
+> ![On the System Console SAML page, set attributes for the SAML Assertions used to update user information in Mattermost. Both Email Attribute and Username Attribute are required, and should match the values entered when configuring the SAML Test Connector in OneLogin.](/images/okta_13_mattermost_attributes.png)
+
+6.  (Optional) Customize the login button text.
+7.  Select **Save**.
+8.  (Optional) If you configured `First Name` Attribute and `Last Name` Attribute, go to **System Console \> Site Configuration \> Users and Teams**, then set **Teammate Name Display** to **Show first and last name**. This is recommended for a better user experience.
+
+To confirm that SAML SSO is successfully enabled, switch your system admin account from email to SAML-based authentication from your profile picture via **Profile \> Security \> Sign-in Method \> Switch to SAML SSO**, then log in with your SAML credentials to complete the switch.
+
+We also recommend that you post an announcement to your users detailing how the migration will work.
+
+You can also configure SAML for OneLogin by editing the `config.json` file to enable SAML based on [SAML configuration settings](/administration-guide/configure/authentication-configuration-settings#saml-20). You must restart the Mattermost server for the changes to take effect.
+
+<Inc1_sso_saml_ldapsync />
+
+<Inc2_sso_saml_faq />

docs/main/administration-guide/onboard/sso-saml-technical.mdx

@@ -0,0 +1,186 @@
+---
+title: "SAML Single Sign-On: technical documentation"
+---
+<PlanAvailability slug="all-commercial" />
+
+Security Assertion Markup Language (SAML) is an open standard that allows identity providers (IdP), like OneLogin, to pass authorization credentials to service providers (SP), like Mattermost.
+
+In simpler terms, it means you can use one set of credentials to log in to many different sites. With a SAML identity provider account, you can log in to Mattermost and other sites securely with the same account.
+
+The main benefit is that it helps administrators centralize user management by controlling which sites users have access to with their SAML identity provider credentials.
+
+Mattermost supports using a single metadata URL to retrieve configuration information for the Identity Provider using your single sign-on URL to generate an IdP metadata URL. The IdP metadata XML file contains the IdP certificate, the entity ID, the redirect URL, and the logout URL.
+
+Using this URL populates the SAML SSO URL and the Identity Provider Issuer URL fields in the configuration process automatically and the Identity Provider Public Certificate is also downloaded from the server and set locally.
+
+This is currently supported for Okta and Microsoft ADFS server 2012 and 2016.
+
+For detailed steps, view the [Configure SAML with Okta](/administration-guide/onboard/sso-saml-okta), [Configure SAML with Microsoft ADFS for Windows Server 2012](/administration-guide/onboard/sso-saml-adfs), and [Configure SAML with Microsoft ADFS using Microsoft Windows Server 2016](/administration-guide/onboard/sso-saml-adfs-msws2016) documentation. See the [supported SAML encryption methods](/administration-guide/configure/authentication-configuration-settings#supported-saml-encryption-methods) in the authentication configuration settings documentation.
+
+## SAML providers
+
+**Identity Providers (IdP)**: An identity provider performs the authentication. When a user clicks to log in, the identity provider confirms who the user is, and sends data to the service provider with the proper authorization to access the site.
+
+*Examples*: OneLogin, Okta, Microsoft Active Directory (ADFS) or Azure.
+
+**Service Providers (SP)**: A service provider gets authentication and authorization information from an IdP. Once received, it gives the user access to the system and logs the user in.
+
+*Examples*: Mattermost, Zendesk, Zoom, Salesforce.
+
+## SAML request (AuthNRequest)
+
+When Mattermost initiates an SP-initiated SAML request flow, it generates a **HTTP-Redirect** binding request to the IdP that contains an XML payload as a base64 string
+
+``` text
+bM441nuRIzAjKeMM8RhegMFjZ4L4xPBHhAfHYqgnYDQnSxC++Qn5IocWuzuBGz7JQmT9C57nxjxgbFIatiqUCQN17aYrLn/mWE09C5mJMYlcV68ibEkbR/JKUQ+2u/N+mSD4/C/QvFvuB6BcJaXaz0h7NwGhHROUte6MoGJKMPE=
+```
+
+AuthNRequests can also be signed by Mattermost, in which case the XML payload is similar to:
+
+<Note>
+
+From Mattermost v11, the default signature algorithm has been updated from SHA-1 to SHA-256 for improved security. The example below reflects the new default SHA-256 algorithm.
+
+</Note>
+
+``` XML
+<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:samlsig="https://www.w3.org/2000/09/xmldsig#" ID="_u5mpjadp1fdozfih4cj8ap4brh" Version="2.0" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="http://localhost:8065/login/sso/saml" IssueInstant="2019-06-08T16:00:31Z">
+    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">https://www.okta.com/exkoxukx1D8OIfY03356</saml:Issuer>
+    <samlsig:Signature Id="Signature1">
+        <samlsig:SignedInfo>
+            <samlsig:CanonicalizationMethod Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#"></samlsig:CanonicalizationMethod>
+            <samlsig:SignatureMethod Algorithm="https://www.w3.org/2000/09/xmldsig#rsa-sha256"></samlsig:SignatureMethod>
+            <samlsig:Reference URI="#_u5mpjadp1fdozfih4cj8ap4brh">
+                <samlsig:Transforms>
+                    <samlsig:Transform Algorithm="https://www.w3.org/2000/09/xmldsig#enveloped-signature"></samlsig:Transform>
+                </samlsig:Transforms>
+                <samlsig:DigestMethod Algorithm="https://www.w3.org/2000/09/xmldsig#sha256"></samlsig:DigestMethod>
+                <samlsig:DigestValue></samlsig:DigestValue>
+            </samlsig:Reference>
+        </samlsig:SignedInfo>
+        <samlsig:SignatureValue></samlsig:SignatureValue>
+        <samlsig:KeyInfo>
+            <samlsig:X509Data>
+                <samlsig:X509Certificate>MIIFmzCCA4OgAwIBAgIJAIusvV3gZIwiMA0GCSqGSIb3DQEBCwUAMGIxCzAJBgNVBAYTAlVTMRIwEAYDVQQHDAlQYWxvIEFsdG8xEzARBgNVBAoMCk1hdHRlcm1vc3QxDzANBgNVBAsMBkRldk9wczEZMBcGA1UEAwwQYmFzZS5leGFtcGxlLmNvbTAeFw0xOTA2MDcxMjQ0MTdaFw0yOTA2MDQxMjQ0MTdaMGIxCzAJBgNVBAYTAlVTMRIwEAYDVQQHDAlQYWxvIEFsdG8xEzARBgNVBAoMCk1hdHRlcm1vc3QxDzANBgNVBAsMBkRldk9wczEZMBcGA1UEAwwQYmFzZS5leGFtcGxlLmNvbTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBALAfDj+RyByszTOPRL4b+cilNF/3PB1I0CG3TNzgllgy5CwRGHLKn5/t8rPsJoWLKOUGenzVdXWuoVi3jyl5FZ1N60CBbXfmSWk20dSIkcYCcYEgs1BTBqKKYFw2dV4M0oppzNtlq7A0Glpg/gpaR/2TXEPAhOsUfORC2qAdJt9ev0AQjp5V0TkIKMZz8oo33Coi38TG5r/LG+ihRbpWzO7j9Rc2S5I6bczvG4wOg7nVKG+B5XBvuU9PjSqgxpd/F/fYf+ggAEru58E+VM4veCRV8vSPbBqDG4FMPV6DiA+tH/70n6zuPCS3soxX00kjKtP80QD6UgzvM2NN7PHiNlf0Zj6VCU3VdjEnypg7dzlHJuyyaAaTD5nSfkecamEoJpq7kaUB7uTmBHELRUhOOy24f54HnP72vnxicZL8cWsOkJwQAqIGzBxQ7J0uX4Os71WrV2YIur8QVk6KN6MBPxfiCh3xO/R+cycgx0aMrWZoyzOzP7NCTM5MNE41C48xeGviyCtUID4xiBow+xo6IDUaiCoUVJhz579ore8ic70a19DD0qHy4SpBvrUwCO54kvkgn6HjYlLC/k8nFM9F9W9wVAQD/QwIjd7EtLZLGgbU61Jv3q4kZxxq270hogCRY0lmI3RxkedGHhetF7kaizrikW5zJQEeido/ir37HhX5AgMBAAGjVDBSMBIGA1UdEwEB/wQIMAYBAf8CAQAwPAYDVR0RBDUwM4IQbG9ncy5leGFtcGxlLmNvbYITbWV0cmljcy5leGFtcGxlLmNvbYcEwKgAAYcEfwAAATANBgkqhkiG9w0BAQsFAAOCAgEAH1O91BABHXZjrU7v1OwG+GbU/4TYZqBXXNxax++OFSRCkEEoNKGg49R6J7lY4lrm12zBlw+oGSyjIOerzi39/dcxDkKpzyhGvEN4mExbDlybmdCVrHPeWgZl7uwqn4Bj1xiu97M6eMthgxJE7KVNDGDHthGL0/fTlONIh3qS7Far33hLHJJKy3+lC1MDB8cNltV3mf/ctHCx5Wa0bfZId0MJgd/seP0WU1HCf3kIxhnhsnOYs32xu7EGiM4/lgnquVd/q/f99ueSaDSHrep373/w2ce9iF3U0qcLd2iP8ayF/daGeW1dVPL9R10Oe4BpRjMkjlLwhZdjJeKSg9GBa2GXUEn1Ru9vpSw/C10no3Qx/6ZHweYbSmJ6hBg4T0nDBp6iVS1eQULNXxDuDWb26U0ESOO5jK8ATywuc45o0bqdvD1XOrGYGfGnofx7ofRWwKHWfltvxurnbsyo2vH6nM6K41K2DpVdyQOKAGvKe/oCWfdi+WyBQJGWcIp2OTC1XyWHv7JsY3lo04+islkHEcqJyd8Rf8GWmRHdXz0WzGiZbxWzAuvRRWnzM31VAws8kQBHTBwIJlJoGX4AXfEvPi+NTxkntf8cQdJucK9ZZbP4ycXHULO4LneyJoJ9Q7nxX11xWv7BDWxxclOXy6tyUkg9Fjb7pQ/HCVvGhRzilVU=</samlsig:X509Certificate>
+            </samlsig:X509Data>
+        </samlsig:KeyInfo>
+    </samlsig:Signature>
+</samlp:AuthnRequest>
+```
+
+## SAML responses
+
+There are different types of SAML responses sent by the IdP to the SP. The response contains the Assertion with the NameID and attributes of a user.
+
+Below is a table of the different types of responses. Each response type is fully supported except when the SAML assertion is signed while the SAML response itself is not:
+
+<table>
+<thead>
+<tr>
+<th>Signed SAML Response</th>
+<th>Signed SAML Assertion</th>
+<th>Encrypted SAML Assertion</th>
+<th>Supported by Mattermost</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Yes</td>
+<td>Yes</td>
+<td>Yes</td>
+<td>Yes</td>
+</tr>
+<tr>
+<td>Yes</td>
+<td>Yes</td>
+<td>No</td>
+<td>Yes</td>
+</tr>
+<tr>
+<td>Yes</td>
+<td>No</td>
+<td>Yes</td>
+<td>Yes</td>
+</tr>
+<tr>
+<td>Yes</td>
+<td>No</td>
+<td>No</td>
+<td>Yes</td>
+</tr>
+<tr>
+<td>No</td>
+<td>Yes</td>
+<td>Yes</td>
+<td>Partially, validation of assertion signature not supported</td>
+</tr>
+<tr>
+<td>No</td>
+<td>Yes</td>
+<td>No</td>
+<td>Partially, validation of assertion signature not supported</td>
+</tr>
+<tr>
+<td>No</td>
+<td>No</td>
+<td>Yes</td>
+<td>Yes</td>
+</tr>
+<tr>
+<td>No</td>
+<td>No</td>
+<td>No</td>
+<td>Yes</td>
+</tr>
+</tbody>
+</table>
+
+For example XML responses for each type, see the [OneLogin SAML response examples](https://www.samltool.com/generic_sso_res.php).
+
+## Technical description of SAML synchronization with AD/LDAP
+
+When enabled, SAML synchronization with AD/LDAP occurs in phases:
+
+1.  Get all the current LDAP users from the Mattermost database who have `Users.AuthService` set to `ldap`. This is a SQL query issued against the Mattermost database: `SELECT * FROM Users WHERE AuthService = 'ldap'`.
+2.  Get all the current SAML users from the Mattermost database who have `Users.AuthService` set to `saml`. This is a SQL query issued against the Mattermost database: `SELECT * FROM Users WHERE AuthService = 'saml'`.
+3.  Get all the current LDAP users from the LDAP server as defined by `LdapSettings.UserFilter`. This is an [LDAP query](https://github.com/mattermost/mattermost/blob/master/server/scripts/ldap-check.sh) issued against the LDAP server. Users are retrieved in batches as defined by `LdapSettings.MaxPageSize`.
+4.  Update LDAP attributes. For each existing Mattermost user retrieved in step 1, attempt to find a match against the list of LDAP users from step 3. To find matches, `Users.AuthData` field of the Mattermost user is compared against the `LdapSettings.IdAttribute` LDAP setting.
+
+> - If any attribute of the user has changed, that attribute is copied from the LDAP server and the user is marked as updated.
+> - If the corresponding `LdapSettings.IdAttribute` is not found, the user is assumed to be deleted from the LDAP server, and deactivated from Mattermost by setting the `Users.DeleteAt` field to a valid timestamp.
+
+5.  Update SAML attributes. For each existing Mattermost user retrieved in step 2, attempt to find a match against the list of LDAP users from step 3. To find matches, `SamlSettings.Email` is compared against the `LdapSettings.EmailAttribute` LDAP setting.
+
+> - If any attribute of the user has changed, that attribute is copied from the LDAP server and the user is marked as updated.
+> - If the corresponding `LdapSettings.EmailAttribute` is not found, the user is assumed to be deleted from the LDAP server, and deactivated from Mattermost by setting the `Users.DeleteAt` field to a valid timestamp.
+
+## Frequently Asked Questions
+
+### How can I obtain a SAML metadata XML file consumed by Mattermost?
+
+You can obtain the XML file by calling the Mattermost RESTful API endpoint at `/api/v4/saml/metadata`.
+
+For other useful SAML API calls, see the [API reference](https://api.mattermost.com/#tag/SAML).
+
+### Can I update user attributes using the API?
+
+No. When Mattermost is configured to use SAML for user authentication, the following user attribute changes can't be made through the API: first name, last name, position, nickname, email, profile image, or username. SAML must be the authoritative source for these user attributes.
+
+### Why does the ObjectGUID of a user in Mattermost differ from what I'm seeing in ADFS?
+
+The Active Directory Object-Guid attribute (LDAP display name `objectGUID`) is a 16 byte array which can be displayed in different ways. However, only Microsoft changes the encoding of the ObjectGUID. All the others keep it the same except for the different base (octal, decimal, hex), as follows:
+
+1.  The `ldapsearch` linux command displays it as base 64: `Hrz/HqNKnU+lCNTYHx9Ycw==`. This is also the format used in LDIF files.
+2.  The [LDAP Golang package Mattermost uses](https://github.com/go-ldap/ldap) emits the value as hexidecimal (base 16) array, with each byte separated by a backslash: `\1e\bc\ff\1e\a3\4a\9d\4f\a5\08\d4\d8\1f\1f\58\73`
+
+> - You can remove the backslashes (`1ebcff1ea34a9d4fa508d4d81f1f5873`) and parse it with [Golang like this](https://go.dev/play/p/9b8iDPuz0Nm). The snippets prints the base 10 representation of each value: `[30 188 255 30 163 74 157 79 165 8 212 216 31 31 88 115]`
+
+3.  Windows Powershell displays the value like this: `1effbc1e-4aa3-4f9d-a508-d4d81f1f5873`
+
+### Does `relaystate` need to be passed back to the client from the identity provider?
+
+Yes. If you're integrating Mattermost with a provider that doesn't already do so by default, ensure that `relaystate` is enabled. See the PingIdentity [SAML RelayState](https://support.pingidentity.com/s/article/SAML-RelayState-and-PingFederate#:~:text=RelayState%20is%20an%20optional%20parameter,the%20SAML%202.0%20bindings%20specification) documentation for details.
+
+### How can I troubleshoot the SAML logon process?
+
+The most useful tool that we've found for troubleshooting SAML connection issues is the [SAML Chrome Panel](https://chromewebstore.google.com/detail/paijfdbeoenhembfhkhllainmocckace?utm_source=item-share-cp) Chrome extension. We're not aware of similar tools for other browsers, but this tool justifies installing Chrome!

docs/main/administration-guide/onboard/sso-saml.mdx

@@ -0,0 +1,88 @@
+---
+title: "SAML Single Sign-On"
+---
+<PlanAvailability slug="all-commercial" />
+
+Single sign-on (SSO) is a way for users to log into multiple applications with a single user ID and password without having to re-enter their credentials. The SAML standard allows identity providers to pass credentials to service providers. Mattermost can be configured to act as a SAML 2.0 Service Provider.
+
+Mattermost can be configured to act as a SAML 2.0 Service Provider, and Mattermost officially supports Okta, OneLogin, and Microsoft ADFS as the identity providers (IDPs), please see links below for more details on how to configure SAML with these providers.
+
+In addition to the officially supported identity providers, you can also configure SAML for a custom IdP. For instance, customers have successfully set up miniOrange, Azure AD, DUO, PingFederate, Keycloak, and SimpleSAMLphp as custom IdPs. Because we do not test against these identity providers, it is important that you test new versions of Mattermost in a staging environment to confirm it will work with your identity provider. You can also set up MFA on top of your SAML provider for additional security.
+
+The SAML Single sign-on integration offers the following benefits:
+
+- **Single sign-on.** Users can log in to Mattermost with their SAML credentials.
+- **Centralized identity management.** Mattermost accounts automatically pull user attributes from SAML upon login, such as full name, email, and username.
+- **Automatic account provisioning.** Mattermost user accounts are automatically created the first time a user signs in with their SAML credentials on the Mattermost server.
+- **Sync groups to predefined roles in Mattermost.** Assign team and channel roles to groups via LDAP Group Sync.
+- **Compliance alignment with administrator management.** Manage Administrator access to Mattermost in the System Console using SAML attributes.
+
+<Important>
+
+\- SAML Single sign-on itself does not support periodic updates of user attributes nor automatic deprovisioning. However, SAML with AD/LDAP sync can be configured to support these use cases. - Account creation and updates is influenced by the attributes configured for identification.
+
+- If the email address is used as the unique identifier and it changes, Mattermost might interpret this as a new user. If an ID attribute is not set, or if it's set to use the email address, a new account may be created in Mattermost when the email address changes.
+- If an ID attribute that doesn't change, such as employeeID, is configured, then Mattermost can use this consistent ID to recognize and match the user account. This allows for updates to other attributes, such as email, without creating a new account. The user details are updated based on the non-changing ID attribute, ensuring continuity and correct user identification without duplicate accounts.
+- If configuring Mattermost to use the EU-Login system for authentication, please be aware that their <code>issuerURI</code> field is what Mattermost calls "Service Provider Identifier".
+- For more information about SAML, see [this article from Varonis](https://www.varonis.com/blog/what-is-saml/), and [this conceptual example from DUO](https://duo.com/blog/the-beer-drinkers-guide-to-saml).
+- See the [supported SAML encryption methods](/administration-guide/configure/authentication-configuration-settings#supported-saml-encryption-methods) in the authentication configuration settings documentation.
+
+</Important>
+
+## Using SAML attributes to apply roles
+
+You can use attributes to assign roles to specified users on login. To access the SAML attribute settings navigate to **System Console \> SAML 2.0**.
+
+### Username attribute
+
+(Optional) Enter a SAML assertion filter to use when searching for users.
+
+1.  Navigate to **System Console \> Authentication \> SAML 2.0** (or **System Console \> SAML** in versions prior to 5.12).
+2.  Complete the **Username Attribute** field.
+3.  Choose **Save**.
+
+When the user accesses the Mattermost URL, they log in with same username and password that they use for organizational logins.
+
+### Guest attribute
+
+When enabled, the `guest` attribute in Mattermost identifies external users whose SAML assertion is guest and who are invited to join your Mattermost server. These users will have the guest role applied immediately upon first login instead of the default member user role. This eliminates having to manually assign the role in the System Console.
+
+If a Mattermost guest user has the guest role removed in the SAML system, the synchronization processes will not automatically promote them to a member user role. This is done manually via **System Console \> User Management**. If a member user has the `guest` attribute added, the synchronization processes will automatically demote the member user to the guest role.
+
+1.  Enable Guest Access via **System Console \> SAML 2.0**.
+2.  Navigate to **System Console \> Authentication \> SAML 2.0**.
+3.  Complete the Guest Attribute field.
+4.  Choose **Save**.
+
+When a guest logs in for the first time they are presented with a default landing page until they are added to channels.
+
+See the [Guest accounts documentation](/administration-guide/onboard/guest-accounts) for more information about this feature.
+
+### Admin attribute
+
+(Optional) The attribute in the SAML Assertion for designating system admins. The users selected by the query will have access to your Mattermost server as system admins. By default, system admins have complete access to the Mattermost System Console.
+
+Existing members that are identified by this attribute will be promoted from member to system admin upon next login. The next login is based upon Session lengths set in **System Console \> Session Lengths**. It is recommended that users are manually demoted to members in **System Console \> User Management** to ensure access is restricted immediately.
+
+1.  Navigate to **System Console \> Authentication \> SAML 2.0**.
+2.  Set **Enable Admin Attribute** to `true`.
+3.  Complete the **Admin Attribute** field.
+4.  Choose **Save**.
+
+<Note>
+
+If the `admin` attribute is set to `false` the member's role as system admin is retained. However if the attribute is removed/changed, system admins that were promoted via the attribute will be demoted to members and will not retain access to the System Console. When this attribute is not in use, system admins can be manually promoted/demoted in **System Console \> User Management**.
+
+Aside from manually promoting users in **System Console \> User Management**, the Admin Attribute is the only way to designate system admins for SAML-authenticated users. The AD/LDAP [Admin Filter](/administration-guide/onboard/ad-ldap#admin-filter) doesn't apply to them, even when **Enable Synchronizing SAML Accounts With AD/LDAP** is enabled.
+
+</Note>
+
+## Configuration assistance
+
+We are open to providing assistance when configuring your custom IdP by answering Mattermost technical configuration questions and working with your IdP provider in support of resolving issues as they relate to Mattermost SAML configuration settings. However, we cannot guarantee your connection will work with Mattermost.
+
+For technical documentation on SAML, see [sso saml technical](/administration-guide/onboard/sso-saml-technical).
+
+To assist with the process of getting a user file for your custom IdP, see this [documentation](https://github.com/icelander/mattermost_generate_user_file).
+
+Please note that we may not be able to guarantee that your connection will work with Mattermost, however we will consider improvements to our feature as we are able. You can see more information on getting support [here](https://mattermost.com/support/) and submit requests for official support of a particular provider on our [feature idea portal](https://portal.productboard.com/mattermost/33-what-matters-to-you).

docs/main/administration-guide/onboard/user-provisioning-workflows.mdx

@@ -0,0 +1,39 @@
+---
+title: "Provisioning workflows"
+---
+<PlanAvailability slug="all-commercial" />
+
+This document provides an overview of user provisioning and deprovisioning workflows in Mattermost.
+
+There are currently 3 recommended user provisioning workflows in Mattermost:
+
+1.  **On demand:** If user accounts are not pre-provisioned using one of the methods described below, then a new user account will be provisioned when the user first logs in. When the user logs in, they are asked to select a public team to join (all users must belong to at least one team) and then they are added automatically to the Town Square channel. Mattermost also has a [default channel setting](/administration-guide/configure/experimental-configuration-settings#default-channels) that enables system admins to add everyone to additional channels specified by the organization.
+2.  **Pre-provisioned via bulk import:** Mattermost features a [bulk import tool](/administration-guide/onboard/bulk-loading-data) that can be used for pre-provisioning new users by adding them to teams and channels before their first login to Mattermost. This tool automates the creation of Teams, Channels, Users, and Posts (with file attachments). It can also be used to migrate users and content from an existing system.
+3.  **Mattermost API:** The Mattermost [RESTful API](https://api.mattermost.com) can be used to pre-provision new user accounts as well as add and remove them from teams and channels. This model is commonly used by enterprises that have central account provisioning applications.
+
+## Mattermost user identifier
+
+The user identifier used to uniquely identify users in Mattermost depends on the method of authentication:
+
+- **Email/password**: Email address or username. Created by the user or previously described account pre-provisioning process.
+- **AD/LDAP**: Configure a unique and unchanging ID Attribute from the AD/LDAP server to be used in Mattermost. If a user's ID Attribute changes, it will create a new Mattermost account unassociated with their old one.
+- **SAML 2.0**: Selected during configuration. You may use an Id Attribute instead of email to bind the user. We recommend choosing an ID that is unique and will not change over time.
+
+### User deprovisioning
+
+Users in Mattermost can be deactivated in the following ways:
+
+- **AD/LDAP Synchronization**: AD/LDAP users can be deactivated in Mattermost based on their status in the directory server via synchronization. Learn more in [AD/LDAP documentation](/administration-guide/onboard/ad-ldap#how-do-i-deactivate-users).
+- **System Console**: User management screen in **System Console \> Users** allows system admins to deactiveate users with email/password login. See the [Deactivate users](/administration-guide/configure/user-management-configuration-settings#deactivate-users) documentation for details.
+- **RESTful API** The Mattermost API can be used to deactivate users. See [API documentation to learn more](https://api.mattermost.com/#operation/DeleteUser).
+- **Command Line Interface**: You can use the Mattermost [mmctl user deactivate](/administration-guide/manage/mmctl-command-line-tool#mmctl-user-deactivate) command to deactivate users.
+
+Once deactivated, users still exist in the Mattermost database and their messages can still be viewed in Mattermost. You can use the [mmctl](/administration-guide/manage/mmctl-command-line-tool#mmctl-user-delete) tools to delete a user and all of their content.
+
+From Mattermost v10.10, when a user is deactivated, the account's [availability](/end-user-guide/preferences/set-your-status-availability#set-your-availability) is automatically set to offline.
+
+<Note>
+
+As long as the ID attribute selected via AD/LDAP or SAML 2.0 is a unique identifier, the user’s email address or name (along with other attributes) can be updated without breaking the user’s account.
+
+</Note>