MM-68992 - add attribute value masking documentation

source/administration-guide/manage/admin/abac-channel-access-rules.rst

@@ -71,6 +71,10 @@ The **Auto-add members based on access rules** toggle controls automatic members
   - 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.
 
+.. note::
+
+  If a policy rule references attribute values from a ``shared_only`` or ``source_only`` attribute that you don't personally hold, those values appear as ``--------`` and the row is read-only. Test and Delete actions are also disabled for those rows. See :ref:`Attribute value masking <administration-guide/manage/admin/abac-system-wide-policies:attribute value masking>` for details.
+
 Validation and safety
 ~~~~~~~~~~~~~~~~~~~~~
 

source/administration-guide/manage/admin/abac-system-wide-policies.rst

@@ -116,4 +116,23 @@ Permission policies can be used to restrict the following actions based on user
 
 When a permission policy applies, users who don't match the configured attribute values can't perform the restricted action. Users may see file attachments as unavailable or redacted in messages they would otherwise have access to. See :ref:`Restricted file attachments <end-user-guide/collaborate/share-files-in-messages:restricted file attachments>` for the end-user-facing behavior.
 
-Permission policies follow the same unique-name requirement as access policies: each parent permission policy must have a unique name, and Mattermost surfaces a user-friendly error if a duplicate name is entered.
+Permission policies follow the same unique-name requirement as access policies: each parent permission policy must have a unique name, and Mattermost surfaces a user-friendly error if a duplicate name is entered.
+
+Attribute value masking
+-----------------------
+
+From Mattermost v11.8, when a policy references attribute values that the editing admin doesn't personally hold, those values are hidden in the policy editor. This prevents admins from reading or copying sensitive attribute values they're not authorized to see, while still allowing the policy to enforce access control normally.
+
+Masking only applies to attributes configured with a ``shared_only`` or ``source_only`` access mode. Attributes with a ``public`` access mode are always visible to all admins. See :ref:`Attribute access modes <administration-guide/manage/admin/user-attributes:attribute access modes>` for details on how each mode controls value visibility.
+
+**What you'll see:**
+
+- Masked values appear as ``--------`` in the rule editor instead of the raw value.
+- Rows containing masked values are **read-only** and cannot be modified.
+- **Test rule** and **Delete** actions are disabled for rules that contain masked values.
+
+**Enforcement is unaffected:** masking applies to the editing UI only. The underlying rules continue to control channel access and permissions as configured.
+
+**To edit a masked rule**, ask the policy owner or another System Admin who holds the relevant attribute values to make the change.
+
+This behavior applies to both the table editor and the CEL editor, and also to Team Admin and Channel Admin policy editors in Team Settings and Channel Settings. Requires Enterprise Advanced license and the ``AttributeValueMasking`` feature flag.

source/administration-guide/manage/admin/user-attributes.rst

@@ -134,6 +134,19 @@ Manage attributes
 
 In cases where multiple system admins manage system attributes, refresh your web browser instance to see real-time updates to system attributes made by other admins.
 
+Attribute access modes
+-----------------------
+
+Each user attribute has an **access mode** that controls who can see its values when those values appear in access control policies. The access mode is set per attribute and determines whether an admin editing a policy can see the raw attribute values referenced in its rules.
+
+Access modes are not configurable through the System Console. They can only be set programmatically by a Mattermost plugin using the `Property Fields API <https://api.mattermost.com/#tag/properties>`_. Attributes created by system admins through the System Console always use the ``public`` access mode. A plugin that needs to restrict attribute visibility must create the field with ``protected: true`` and set the desired ``access_mode`` — this is typically done by plugins that sync sensitive attributes from an external identity source and need to control which admins can read those values.
+
+- **Public** (default): The attribute value is visible to all admins editing policies that reference it. No masking is applied.
+- **Shared only**: The attribute value is only visible to admins who personally hold that same value. Admins who don't hold the value see it masked (``--------``) in the policy editor.
+- **Source only**: The attribute value is only visible to the system source that set it (for example, the identity provider). All admins see it masked in the policy editor regardless of their own attribute values.
+
+Masking in the policy editor only applies to attributes with ``shared_only`` or ``source_only`` access mode. See :ref:`Attribute value masking <administration-guide/manage/admin/abac-system-wide-policies:attribute value masking>` for the editor behavior when masked values are present.
+
 Sync attributes with your identity provider
 --------------------------------------------