diff --git a/extensions/sphinx_inline_tabs/directive.py b/extensions/sphinx_inline_tabs/directive.py index 1853c95ca3b..f95f75ab12c 100644 --- a/extensions/sphinx_inline_tabs/directive.py +++ b/extensions/sphinx_inline_tabs/directive.py @@ -122,9 +122,10 @@ def walk_parsed_nodes( if generated_tab_ids is None: generated_tab_ids = set() for parsed_node in parsed_nodes: + has_ids = True if hasattr(parsed_node, 'attributes') and parsed_node.attributes.get("ids") else False node_info: str = ( f"type(parsed_node)={type(parsed_node)}; " - f"has_ids={True if hasattr(parsed_node, 'attributes') and parsed_node.attributes["ids"] else False}; " + f"has_ids={has_ids}; " f"parent={parsed_node.parent!r}" ) logger.debug( @@ -133,11 +134,14 @@ def walk_parsed_nodes( if isinstance(parsed_node, TabContainer): tab_container_name: str = parsed_node.next_node(nodes.label).astext() + tab_ids = parsed_node.attributes.get("ids", []) + has_ids = True if tab_ids else False + first_id = tab_ids[0] if tab_ids else 'None' logger.debug( f"{LOG_PREFIX} walk_parsed_nodes({docname}|{tab_name}): [{level}/{tab_counter}] " f"TabContainer({tab_container_name}); node.tab_counter={parsed_node.tab_counter} " - f"is_parsed={parsed_node.is_parsed}; has_ids={True if parsed_node.attributes["ids"] else False}; " - f"first_id={parsed_node.attributes['ids'][0] if parsed_node.attributes['ids'] else 'None'}; " + f"is_parsed={parsed_node.is_parsed}; has_ids={has_ids}; " + f"first_id={first_id}; " f"increment tab_counter to {tab_counter + 1}" ) sub_tab_name: str = tab_name @@ -161,13 +165,16 @@ def walk_parsed_nodes( elif isinstance(parsed_node, nodes.section): section_title: str = parsed_node.next_node(nodes.title).astext() + section_ids = parsed_node.attributes.get("ids", []) + has_ids = True if section_ids else False + first_id = section_ids[0] if section_ids else 'None' logger.debug( f"{LOG_PREFIX} walk_parsed_nodes({docname}|{tab_name}): [{level}/{tab_counter}] section({section_title}); " - f"has_ids={True if parsed_node.attributes["ids"] else False}; " - f"first_id={parsed_node.attributes['ids'][0] if parsed_node.attributes['ids'] else 'None'}; " + f"has_ids={has_ids}; " + f"first_id={first_id}; " ) # If the node has at least one `id` attribute - if parsed_node.attributes["ids"]: + if section_ids: # Get the first `id` for the node node_id: str = parsed_node.attributes["ids"][0] # Create a new `id` value that includes the tab name, subsection level, and first node `id` diff --git a/source/administration-guide/manage/admin/abac-channel-access-rules.rst b/source/administration-guide/manage/admin/abac-channel-access-rules.rst index 09c79ce35cb..c2a76d2512a 100644 --- a/source/administration-guide/manage/admin/abac-channel-access-rules.rst +++ b/source/administration-guide/manage/admin/abac-channel-access-rules.rst @@ -4,30 +4,35 @@ Channel-specific access rules .. include:: ../../../_static/badges/entry-adv.rst :start-after: :nosearch: -Channel and Team Admins can self-manage access controls for their private channels directly through the Channel Settings modal, without requiring System Admin intervention. For organization-wide policies created by System Admins, see :doc:`System-wide attribute-based access policies `. +Channel and Team Admins can self-manage access controls for their channels directly through the Channel Settings modal, without requiring System Admin intervention. For organization-wide policies created by System Admins, see :doc:`System-wide attribute-based access policies `. -Each ABAC channel access policy has an explicit active state that determines whether the policy will automatically add users who meet the policy's criteria but are not yet channel members. When a policy is applied to a channel, the policy's rules are always enforced to remove members who no longer meet the required attribute rules, regardless of the active state. +From Mattermost v11.8, channel access rules can be applied to **both private and public channels**. The two channel types behave differently under ABAC: + +- **Private channels** are hard-gated. Non-matching members are removed during synchronization, and only matching users can be added or invited. +- **Public channels** are advisory. Non-matching members are *never* removed (anyone can still join a public channel by browsing or via a direct link). With auto-add enabled the policy still pulls matching users in; with auto-add disabled the channel surfaces under **Browse Channels > Recommended channels** for users whose attributes match. + +Each ABAC channel access policy has an explicit active state that determines whether the policy will automatically add users who meet the policy's criteria but are not yet channel members. For private channels, the policy's rules are always enforced to remove members who no longer meet the required attribute rules, regardless of the active state. For public channels, no member is ever removed by ABAC — the rules are advisory only. With channel access rules, Channel and Team Admins can: - Create channel-specific access rules using a simple interface. -- Rules are **additive** to any system policies (both must be satisfied). +- Use rules that are **additive** to any system policies. For private channels, both must be satisfied for adds and invites. For public channels, the combined rules affect auto-add and recommendations only, and don't block joins or remove members. - Automatic member synchronization with immediate feedback. -- Self-exclusion prevention to avoid locking yourself out. +- Self-exclusion prevention to avoid locking yourself out (private channels only). Prerequisites ------------- - :doc:`Attribute-Based Access Control (ABAC) ` must be enabled by a System Admin in **System Console > System Attributes > Attribute-Based Access**. - You need Channel Admin permissions and the ``manage_channel_access_rules`` permission. -- Channel access rules are available only for private channels. +- Channel access rules are available for private and public channels. Default channels (such as Town Square and Off-Topic), shared channels, and group-synced channels remain ineligible. Access Channel Settings ~~~~~~~~~~~~~~~~~~~~~~~~ -1. In a private channel where you have Channel Admin permissions, select the channel name at the top of the center pane. +1. In a private or public channel where you have Channel Admin permissions, select the channel name at the top of the center pane. 2. Select **Channel Settings** from the dropdown menu. -3. Navigate to the **Access Control** tab. This tab is only visible for private channels when you have the appropriate permissions and ABAC is enabled system-wide. +3. Navigate to the **Membership Policy** tab. This tab is only visible for eligible channels when you have the appropriate permissions and ABAC is enabled system-wide. The tab is hidden on default channels, shared channels, and group-synced channels. .. tip:: @@ -38,7 +43,7 @@ Configure access rules Channel access rules use the same simple interface as system policies, allowing you to create attribute-based conditions without complex syntax. -1. In the **Access Control** tab, you'll see any inherited system policies at the top in a blue information banner (if applicable). +1. In the **Membership Policy** tab, you'll see any inherited system policies at the top in a blue information banner (if applicable). 2. Use the **Add attribute** button to create new access conditions: - **Select attribute**: Choose from available user attributes @@ -58,10 +63,17 @@ Channel access rules use the same simple interface as system policies, allowing Auto-sync membership ~~~~~~~~~~~~~~~~~~~~ -The **Auto-add members based on access rules** toggle controls automatic membership management. This setting ensures that channel membership stays consistently aligned with the defined attribute rules, similar to how LDAP group channels work: +The **Auto-add members based on access rules** toggle controls automatic membership management. The behavior differs by channel type: + +- **Private channels (hard gate)**: Membership stays consistently aligned with the rules, similar to how LDAP group channels work. + + - **Enabled**: Users matching the rules are automatically added. If users temporarily lose attributes and later regain them, they will be automatically re-added. + - **Disabled**: Rules act as a gate (preventing unauthorized joins) but don't automatically add qualifying users. -- **Enabled**: Users matching the rules are automatically added to the channel. If users temporarily lose attributes and later regain them, they will be automatically re-added -- **Disabled**: Rules act as a gate (preventing unauthorized joins) but don't automatically add qualifying users +- **Public channels (advisory)**: ABAC never removes members — anyone can still join a public channel. + + - **Enabled**: Matching users are automatically added (a convenience, not a gate). + - **Disabled**: The channel appears under **Browse Channels > Recommended channels** for users whose attributes match, surfacing the channel without adding anyone. .. important:: @@ -69,22 +81,24 @@ The **Auto-add members based on access rules** toggle controls automatic members - If a system policy has auto-sync enabled, Channel and Team Admins cannot disable it at the channel level. - If a system policy has auto-sync disabled, Channel and Team Admins can choose to enable it for their channel. - When no rules are configured, this toggle is automatically disabled. - - Regardless of the auto-sync setting, users who no longer meet required attribute rules are always removed during synchronization. + - On **private** channels, users who no longer meet required attribute rules are always removed during synchronization regardless of the auto-sync setting. On **public** channels, no member is ever removed by ABAC. Validation and safety ~~~~~~~~~~~~~~~~~~~~~ Before saving changes, Mattermost validates your rules to prevent common issues: -- **Required fields**: All attribute selections and values must be completed -- **Self-exclusion prevention**: You cannot create rules that would remove yourself from the channel -- **Conflict detection**: Rules that create impossible conditions are identified +- **Required fields**: All attribute selections and values must be completed. +- **Self-exclusion prevention**: For private channels, you cannot save rules that would remove yourself from the channel. The check is skipped for public channels because they are advisory under ABAC and can't lock anyone out. +- **Conflict detection**: Rules that create impossible conditions are identified. When you save changes that affect membership, a confirmation dialog shows you: -- How many users will be added or removed -- Option to view the specific users affected -- Confirmation required before applying changes +- How many users will be added or removed. +- Option to view the specific users affected. +- Confirmation required before applying changes. + +Once a policy is attached to a channel, the channel cannot be converted between public and private until the policy is removed. The two modes have different semantics (advisory vs. hard gate), so a silent conversion would change what an existing policy actually does to its members. Policy inheritance -------------------- @@ -132,29 +146,39 @@ Visual indicators **Channel Members panel:** -- Information banner at the top explains that attribute-based access is enabled. +- Information banner at the top explains that attribute-based access is enabled. The message differs by channel type: private channels indicate that access is restricted by user attributes, while public channels indicate that member recommendations are based on user attributes. - Displays required attribute values as tags (e.g., "Engineering", "Confidential"). - Tooltip on hover shows the attribute name for each value. **Add Members modal:** - Similar information banner and attribute value display. -- Users who don't match the access criteria won't appear in search results. -- Only eligible users can be selected and added to the channel. +- On **private** channels, users who don't match the access criteria won't appear in search results — only eligible users can be added. +- On **public** channels, the full team list is shown and matching users are surfaced with a **Recommended** tag at the top of the list. Anyone can still be added because public-channel ABAC is advisory. + +**Browse Channels:** + +- A **Recommended channels** filter is available in the channel-type dropdown when ABAC is enabled. Selecting it lists the public channels whose policies the user matches — useful when auto-add is disabled and the channel is offered as a recommendation rather than auto-joined. Functional restrictions ~~~~~~~~~~~~~~~~~~~~~~~~ -When ABAC is enabled for a channel: +When ABAC is enabled for a **private** channel: - **Search limitations**: Users who don't match access criteria don't appear in member search results. - **Invitation restrictions**: Only users meeting attribute requirements can be added to the channel. - **Guest user exclusions**: Private channels with ABAC policies cannot have guest users invited. - **Automatic removal**: Users who lose required attributes are automatically removed during the next synchronization. +When ABAC is enabled for a **public** channel: + +- **Search results are unfiltered**: All eligible team members appear in the Add Members modal so admins can still invite anyone; matching users carry a **Recommended** tag. +- **Recommendations**: With auto-add disabled, the channel surfaces under **Browse Channels > Recommended channels** for matching users. +- **Auto-add (when enabled)**: Matching users are added automatically. **Members are never removed** by ABAC — users can always leave on their own, and joining freely is unaffected because the channel is public. + .. note:: - These restrictions apply across all Mattermost clients, including web, desktop, and mobile, to ensure consistent security enforcement. + These behaviors apply across all Mattermost clients, including web, desktop, and mobile, to ensure consistent enforcement. Troubleshooting and FAQs --------------------------- @@ -164,15 +188,15 @@ Common questions about attribute-based access control implementation and usage. Permission and access ~~~~~~~~~~~~~~~~~~~~~~ -Why can't I see the Access Control tab in Channel Settings? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Why can't I see the Membership Policy tab in Channel Settings? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The **Access Control** tab is only visible when all of these conditions are met: +The **Membership Policy** tab is only visible when all of these conditions are met: -- You have Channel Admin role or higher for the channel -- The channel is a private channel (not public, group message, or direct message) -- ABAC is enabled system-wide by a System Admin in **System Console > System Attributes > Attribute-Based Access** -- Your user role includes the ``manage_channel_access_rules`` permission +- You have Channel Admin role or higher for the channel. +- The channel is a private or public channel (not a default channel like Town Square or Off-Topic, group message, direct message, shared, or group-synced channel). +- ABAC is enabled system-wide by a System Admin in **System Console > System Attributes > Attribute-Based Access**. +- Your user role includes the ``manage_channel_access_rules`` permission. Can Channel and Team Admins override system policies? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -182,7 +206,14 @@ No. Channel rules are always **additive** to system policies. Users must satisfy What happens if I create rules that would exclude myself? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Mattermost prevents this with self-exclusion validation. If your rules would remove you from the channel, you'll see an error message and cannot save the changes until you adjust the rules or reset them. +For **private** channels, Mattermost prevents this with self-exclusion validation. If your rules would remove you from the channel, you'll see an error message and cannot save the changes until you adjust the rules or reset them. + +For **public** channels, the self-exclusion check is skipped — public-channel ABAC is advisory, the policy can't kick anyone out, and you can always re-join a public channel directly. This lets you author a policy intended for a different team (for example, a Sales admin configuring an Engineering recommendation) without being blocked. + +Can I convert a public channel to private (or vice versa) while a policy is attached? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +No. The two modes have different semantics — a public-channel policy is advisory while a private-channel policy is a hard gate that removes non-matching members. A silent conversion would change what the existing policy does to its members, so Mattermost requires you to remove the policy first, convert the channel, and re-attach the policy if you still want it. Rule configuration ~~~~~~~~~~~~~~~~~~~ diff --git a/source/administration-guide/manage/admin/abac-system-wide-policies.rst b/source/administration-guide/manage/admin/abac-system-wide-policies.rst index bd7aa811b5a..8da77896336 100644 --- a/source/administration-guide/manage/admin/abac-system-wide-policies.rst +++ b/source/administration-guide/manage/admin/abac-system-wide-policies.rst @@ -72,14 +72,23 @@ Manage rules You can apply changes to existing rules or remove rules at any time using either Simple Mode or Advanced Mode. Select **Save** to save your changes. -Assign policies to private channels -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Assign policies to channels +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Specify the private channel that your access control policy applies to by selecting **Add channels** to search for and select the channels you want. You can assign the policy to multiple channels at once, or you can `assign it to individual channels <#define-access-controls-per-channel>`__ later. Select **Save** to save your changes. +From Mattermost v11.8, system-wide policies can be assigned to **both private and public channels**. Select **Add channels** to search for and select the channels you want. You can assign the policy to multiple channels at once, or you can `assign it to individual channels <#define-access-controls-per-channel>`__ later. Select **Save** to save your changes. + +The two channel types behave differently under the same policy: + +- **Private channels** are hard-gated. The policy adds matching users (when auto-add is enabled), removes non-matching members during synchronization, and prevents non-matching users from being added or invited. +- **Public channels** are advisory. The policy never removes members and never blocks anyone from joining. With auto-add enabled it automatically adds matching users; with auto-add disabled the channel appears under **Browse Channels > Recommended channels** for matching users. + +Before saving, you'll be prompted to confirm the impact of the change so you can review how it affects each channel type. + +Default channels (such as Town Square and Off-Topic), shared channels, and group-synced channels remain ineligible — they are excluded from the channel selector. .. note:: - Private channels with attribute-based access control policies can't have guest users invited to them. Only users who match the defined attribute criteria can be added to ABAC-controlled channels, ensuring strict adherence to access control policies. + Private channels with attribute-based access control policies can't have guest users invited to them. Only users who match the defined attribute criteria can be added to ABAC-controlled private channels, ensuring strict adherence to access control policies. Public channels remain joinable by anyone regardless of the policy. Delete policies ~~~~~~~~~~~~~~~ @@ -89,12 +98,14 @@ To delete a policy, select the **Delete** button next to the policy you want to Define access controls per channel ---------------------------------- -You can assign an existing access control policy to a private channels for more granular control over channel membership. This is useful when you need to apply different rules for different channels. +You can assign an existing access control policy to a private or public channel for more granular control over channel membership. This is useful when you need to apply different rules for different channels. -1. In the System Console, go to **User Management > Channels** to select the private channel you want to configure, and select **Edit**. +1. In the System Console, go to **User Management > Channels** to select the private or public channel you want to configure, and select **Edit**. 2. In the **Channel Management** section, enable the **Enable attribute-based channel access** option. 3. Under **Access policy**, select **Link to a policy** to select an existing policy. +Once a policy is attached, the channel's privacy can no longer be flipped between public and private until the policy is removed — see :ref:`Channel-specific access rules `. + .. tip:: You can also assign ABAC rules to a channel directly from a channel's details page in the System Console under **Channel Management** by enabling the **Enable attribute-based channel access** option. Under **Access policy**, select **Link to a policy** to select an existing policy. diff --git a/source/administration-guide/manage/admin/attribute-based-access-control.rst b/source/administration-guide/manage/admin/attribute-based-access-control.rst index e188d2efbf1..58482a4bc7b 100644 --- a/source/administration-guide/manage/admin/attribute-based-access-control.rst +++ b/source/administration-guide/manage/admin/attribute-based-access-control.rst @@ -21,6 +21,13 @@ Attribute-based access control (ABAC) provides 2 levels of control: - **System-wide policies** (managed by System Admins): Centralized policies that can be applied across multiple channels in the System Console. See :doc:`System-wide attribute-based access policies `. - **Channel-specific rules** (managed by Channel Admins): Self-service access rules that Channel Admins can configure directly in Channel Settings for individual channels. See :doc:`Channel-specific access rules `. +From Mattermost v11.8, ABAC policies can be applied to **both private and public channels**, with deliberately different semantics for each: + +- **Private channels** are hard-gated by the policy. Non-matching members are removed during synchronization and only matching users can be added or invited. +- **Public channels** are advisory. Anyone can still join freely, no member is ever removed by ABAC, and the policy is used either to **auto-add** matching users (when enabled) or to **recommend** the channel under **Browse Channels > Recommended channels** (when auto-add is disabled). + +Default channels (Town Square, Off-Topic), shared channels, and group-synced channels remain ineligible. + Before you begin ------------------ diff --git a/source/end-user-guide/collaborate/manage-channel-members.rst b/source/end-user-guide/collaborate/manage-channel-members.rst index 58724e2dafd..9fc077178e3 100644 --- a/source/end-user-guide/collaborate/manage-channel-members.rst +++ b/source/end-user-guide/collaborate/manage-channel-members.rst @@ -9,7 +9,10 @@ Add members to a channel Any member of a channel can add other members to public or private channels, unless your system admin has restricted access to do so. -When a channel has :doc:`attribute-based access controls ` enabled, you'll see details about which user attributes are permitted access to the channel. Only users who meet the requirements appear in search results when adding members to that channel. +When a channel has :doc:`attribute-based access controls ` enabled, you'll see details about which user attributes are permitted access to the channel. Behavior differs by channel type: + +- **Private channels**: Only users who meet the requirements appear in search results when adding members, and only those users can be added. +- **Public channels**: All eligible team members appear in search results, and users who meet the recommended attributes are labeled **Recommended**. Anyone can still be added because public-channel access controls are advisory and never remove existing members. .. tab:: Web/Desktop