From 0623ad908f53268bc722d4c11896a901487a0799 Mon Sep 17 00:00:00 2001 From: Devin Binnie Date: Thu, 13 Aug 2026 13:09:22 -0400 Subject: [PATCH 01/11] Session attributes docs --- .../configure/system-attributes.rst | 1 + .../admin/abac-channel-access-rules.rst | 11 + .../admin/abac-system-wide-policies.rst | 6 + .../admin/attribute-based-access-control.rst | 3 + .../manage/admin/server-configuration.rst | 2 + .../manage/admin/session-attributes.rst | 403 ++++++++++++++++++ .../desktop/desktop-app-deployment.rst | 28 +- .../mobile/mobile-security-features.rst | 7 + .../customize-desktop-app-experience.rst | 2 + source/security-guide/mobile-security.rst | 7 + 10 files changed, 469 insertions(+), 1 deletion(-) create mode 100644 source/administration-guide/manage/admin/session-attributes.rst diff --git a/source/administration-guide/configure/system-attributes.rst b/source/administration-guide/configure/system-attributes.rst index 080043cdca0..e0c722fe492 100644 --- a/source/administration-guide/configure/system-attributes.rst +++ b/source/administration-guide/configure/system-attributes.rst @@ -12,4 +12,5 @@ You can define, manage, and enforce specific attributes, including: - **User attributes**: Display details such as job titles, departments, or other metadata, on user profiles that align with your organizational structures and workflows. Learn more about :doc:`managing user attributes `. API responses for user attributes return default visibility and sort order when those values are missing. - **Granular access controls based on user attributes**: Ensure users have access to only the resources and functionality relevant to their roles, bolstering security and compliance across the organization. Learn more about :doc:`managing access based on user attributes `. +- **Session attributes**: From Mattermost v11.11 (Enterprise Advanced), evaluate per-session device and network context - such as IP address, network interface type, VPN status, and MDM enrollment - in permission policies. Learn more about :doc:`managing session attributes `. - **Control user-managed attributes in attribute-based access control (ABAC)**: From Mattermost v10.11 (Enterprise Edition Advanced), user-managed attributes are excluded from ABAC rules by default to prevent unauthorized access. System admins can enable them with a configuration setting. Learn more about enabling user-managed attributes in ABAC rules in the :ref:`User Attributes documentation `. 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 5d873a9a1d1..526fe9c3d09 100644 --- a/source/administration-guide/manage/admin/abac-channel-access-rules.rst +++ b/source/administration-guide/manage/admin/abac-channel-access-rules.rst @@ -38,6 +38,10 @@ Access Channel Settings 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. +.. important:: + + **Changes aren't applied until you save the tab.** Editing rules in either the **Membership Policy** or **Permissions Policy** tab stages your changes locally - nothing reaches the channel until you select **Save** in the **Save Changes** panel at the bottom of the tab. Permission rules take one more step than membership rules: selecting **Add rule** or **Save rule** in the rule editor only commits the rule to the list, and you still need to save the tab afterwards. + Configure access rules ---------------------- @@ -126,6 +130,8 @@ From Mattermost v11.8.0, channel admins can define channel-level permission rule For system-wide permission policies that restrict file upload and download actions, see :ref:`Permission policies `. +From Mattermost v11.11, permission rules can also use any :doc:`session attributes ` a System Admin has enabled, letting you restrict file actions by device or network rather than by who the user is. Because a rule that references a session attribute denies anyone whose client doesn't report it - including everyone working in a web browser - review :ref:`platform availability ` and simulate the rule before saving it. + Simulate access ---------------- @@ -133,6 +139,11 @@ From Mattermost v11.8.0, admins can use **Simulate access** in Channel Settings - Simulation can evaluate draft rules before they're saved, so you can confirm the intended scope without affecting live channel access. - Some denied results may indicate that the decision came from another policy. In that case, Mattermost shows that access was denied by another policy without exposing policy details you aren't authorized to see. +- From Mattermost v11.11, a neutral **No recent session** result indicates that the rules reference :doc:`session attributes ` and the selected user has no cached session data to evaluate. + +.. note:: + + Detailed evaluation traces showing how each rule contributed to a decision are only available to System Admins. Channel Admins and Team Admins see the contributing rule expressions without the underlying trace. .. note:: 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 c5b22e53a93..8006ec05b09 100644 --- a/source/administration-guide/manage/admin/abac-system-wide-policies.rst +++ b/source/administration-guide/manage/admin/abac-system-wide-policies.rst @@ -14,6 +14,8 @@ Prerequisites From Mattermost v10.11, user-managed attributes are excluded from attribute-based access control (ABAC) rules by default for security reasons. This prevents access control policies from being circumvented by users editing their own profile attributes. To include user-managed attributes in ABAC rules, a system admin must explicitly enable the ``EnableUserManagedAttributes`` configuration setting. See the :ref:`user attribute ` documentation for details on enabling this feature. This configuration setting is available only in Enterprise Edition Advanced and is disabled by default. +From Mattermost v11.11, :doc:`session attributes ` describing the connection a user is on - such as their IP address, VPN status, and device posture - can be used in `permission policies`_. Each session attribute must be enabled in **System Console > System Attributes > Session Attributes** before a rule can reference it. + Define access control policies ------------------------------ @@ -85,6 +87,8 @@ From Mattermost v11.8.0, you can use **Simulate access** to preview allowed and Simulation can test draft policy changes before they affect live channel access or file permissions. Detailed rule and attribute information is shown only when the denial comes from the policy or scope you're editing; otherwise, Mattermost may show that access was denied by another policy. +From Mattermost v11.11, results can also show a neutral **No recent session** indicator. This appears when the contributing rules reference :doc:`session attributes ` (``user.session.*``) and the selected user has no cached session attributes to evaluate - usually because they haven't connected recently, or haven't connected from a client that reports those attributes. + .. note:: **Simulate access** and channel-level permission policies for file upload and file download are gated by the ``PermissionPolicies`` feature flag (``MM_FEATUREFLAGS_PERMISSIONPOLICIES``) and require a Mattermost Enterprise Advanced license. See the Mattermost developer documentation for details on `enabling feature flags in a self-hosted deployment `_. Mattermost Cloud customers can request this feature flag be enabled by contacting their Mattermost Account Manager or by `creating a support ticket `_. @@ -151,6 +155,8 @@ When a permission policy applies, users who don't match the configured attribute 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. +From Mattermost v11.11, permission policy rules can also evaluate :doc:`session attributes ` - for example, restricting file downloads to devices on a corporate IP range or to MDM-enrolled devices. Because a rule that references a session attribute denies any session that doesn't report it, review the platform availability of each attribute before applying it to a file action your users depend on. + Attribute value masking ----------------------- 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 1be0fa445ac..4737647d744 100644 --- a/source/administration-guide/manage/admin/attribute-based-access-control.rst +++ b/source/administration-guide/manage/admin/attribute-based-access-control.rst @@ -12,6 +12,7 @@ Attribute-Based Access Control /administration-guide/manage/admin/abac-system-wide-policies /administration-guide/manage/admin/abac-team-channel-policies /administration-guide/manage/admin/abac-channel-access-rules + /administration-guide/manage/admin/session-attributes From Mattermost v10.9, system admins in large or complex organizations who require Zero Trust Security when handling with sensitive information can prevent unauthorized access through attribute-based access controls. @@ -42,6 +43,8 @@ Once user attributes are defined, go to **System Console > System Attributes > A From Mattermost v10.11, user-managed attributes are excluded from attribute-based access control (ABAC) rules by default for security reasons. This prevents access control policies from being circumvented by users editing their own profile attributes. To include user-managed attributes in ABAC rules, a system admin must explicitly enable the ``EnableUserManagedAttributes`` configuration setting. See the :ref:`user attribute ` documentation for details on enabling this feature. This configuration setting is available only in Enterprise Edition Advanced and is disabled by default. +From Mattermost v11.11, permission policies can also evaluate :doc:`session attributes ` - per-session context such as the client's IP address, network interface type, VPN status, and device posture - alongside user attributes. Each session attribute must be enabled in **System Console > System Attributes > Session Attributes** before a rule can reference it. + Configure access policies -------------------------- diff --git a/source/administration-guide/manage/admin/server-configuration.rst b/source/administration-guide/manage/admin/server-configuration.rst index 458d8362498..eb71bd889ce 100644 --- a/source/administration-guide/manage/admin/server-configuration.rst +++ b/source/administration-guide/manage/admin/server-configuration.rst @@ -18,6 +18,7 @@ Whether you’re setting up email notifications, optimizing search capabilities, Install Mattermost Boards Install and manage plugins Manage user attributes + Manage session attributes Enable content flagging Environment variables Customize the server @@ -37,6 +38,7 @@ Whether you’re setting up email notifications, optimizing search capabilities, * :doc:`Install Mattermost Boards ` - Learn how to install and configure the Boards plugin for your Mattermost instance. * :doc:`Install and manage plugins ` - Learn how to install, enable, configure, update, and remove plugins for your Mattermost instance. * :doc:`Manage custom user attributes ` - Learn how to manage custom user attributes in user profiles in Mattermost. +* :doc:`Manage session attributes ` - Learn how to collect and use per-session device and network context in access control policies. * :doc:`Environment variables ` - Learn how to use environment variables for Mattermost configuration. * :doc:`Customize the server ` - Learn about customizing branding for Mattermost server. * :doc:`SMTP email setup ` - Learn how to set up SMTP email for Mattermost. diff --git a/source/administration-guide/manage/admin/session-attributes.rst b/source/administration-guide/manage/admin/session-attributes.rst new file mode 100644 index 00000000000..1b6829279ea --- /dev/null +++ b/source/administration-guide/manage/admin/session-attributes.rst @@ -0,0 +1,403 @@ +Session attributes +================== + +.. include:: ../../../_static/badges/ent-adv.rst + :start-after: :nosearch: + +From Mattermost v11.11, :ref:`permission policies ` can evaluate **session attributes** in addition to user attributes. Where a user attribute describes *who* someone is, a session attribute describes *how they're connecting right now* (eg. the network they're on, the client they're using, and the posture of the device in front of them). + +This lets you write policies such as "only allow file downloads from a corporate IP range" or "block uploads from jailbroken mobile devices" - conditions that can't be expressed with user attributes alone. + +Session attributes are referenced in policy expressions as ``user.session.``, for example ``user.session.vpn_active == "true"``. + +.. note:: + Session attributes can only restrict user actions covered by permission policies; they aren't available for use in membership policies. + +.. important:: + + Session attributes are collected per session and evaluated at request time. They aren't stored in the database, aren't included in compliance exports, and are discarded when the session is revoked or expires. See `How session attributes are collected <#how-session-attributes-are-collected>`__. + +Prerequisites +------------- + +- A Mattermost Enterprise Advanced license. +- :doc:`Attribute-based access control ` must be enabled in **System Console > System Attributes > Attribute-Based Access**. +- Client-reported attributes require Mattermost Desktop App v6.3 or later, or Mattermost mobile app v2.44 or later. Users connecting from a web browser, or an older Desktop or mobile app, can only report a subset of attributes. See `Platform availability <#platform-availability>`__. + +Enable and tune session attributes +---------------------------------- + +**Every session attribute is disabled by default**, to avoid collecting and evaluating attributes that aren't needed. Administrators must explicitly enable each attribute intended for use in a policy. + +1. In the System Console, go to **System Attributes > Session Attributes**. +2. Locate the attribute you want to use and select **More** |more-icon| to open its actions menu. +3. Select **Enable**. + +The attribute list shows the following for each attribute: + +- **Display Name** and **Name**: The label shown in the System Console, and the internal name you reference in policy expressions as ``user.session.``. Attributes marked **Server** are measured by the Mattermost server rather than reported by the client. +- **Type**: ``String``, ``Boolean``, or ``Enum``. Boolean and Enum attributes accept only a fixed set of values; see `Session attribute reference <#session-attribute-reference>`__. +- **Platform**: The clients that can report the attribute, with each platform marked *active* or *inactive*. +- **TTL** and **Grace**: How often clients re-report the attribute, and how long a reported value stays usable after its TTL elapses. +- **Status**: **Enabled** or **Disabled**. + +The attribute list itself is fixed - session attributes can't be renamed, deleted, or added, and their types and supported platforms can't be changed. + +.. note:: + + Disabling an attribute stops it from being collected and evaluated. Policies that reference a disabled attribute will deny access, because the attribute is no longer present on any session. Mattermost blocks you from *saving* a new policy that references a disabled attribute, but disabling an attribute that an existing policy already references does not invalidate that policy. + +TTL and grace period +~~~~~~~~~~~~~~~~~~~~ + +Each attribute has two timers that together control how fresh its value must be: + +- **TTL (time-to-live)**: How long a client waits before re-reporting the attribute. A short TTL keeps the value current at the cost of slightly larger requests; a long TTL reduces overhead but lets the value go stale. +- **Grace period**: How long after the TTL elapses Mattermost will still evaluate the last reported value. Once TTL + grace period has passed without a fresh report, the attribute is treated as absent and policies referencing it deny access. + +Defaults vary by attribute - see the `session attribute reference <#session-attribute-reference>`__. Presets of 30 seconds, 1 minute, 5 minutes, 1 hour, and 24 hours are available for both timers. + +The time-to-live and grace can be adjusted in the System Console, by selecting the attribute in the Session Attributes list and opening the **More** |more-icon| menu. + +.. tip:: + + Grace periods absorb brief network interruptions. If you set a grace period to a very low value, users on flaky connections may be intermittently denied access while their client catches up on reporting. + +How session attributes are collected +------------------------------------ + +Session attributes come from two sources: + +- **Server-derived attributes** are measured by the Mattermost server from the incoming request itself - the connection's IP address and the ``User-Agent`` header. +- **Client-reported attributes** are collected by the Desktop App or mobile app using native operating system APIs and sent to the server in an ``X-MM-Session-Attributes`` request header. + +Clients collect only what you've enabled. When a client connects, the server tells it which attributes apply to its platform and how often to refresh each one, and anything not on that list is never collected. The server ignores values it doesn't expect, such as a value for a disabled attribute or for an attribute that platform can't support. Reported values are held in the session's in-memory cache rather than written to the database, are shared across all nodes in a :doc:`high availability cluster `, and are discarded when the user logs out or the session is revoked or expires. + +Platform availability +~~~~~~~~~~~~~~~~~~~~~ + +Not every client can report every attribute. A user connecting from a **web browser** can't report device or network attributes such as ``os_platform``, ``vpn_active``, or ``client_ip_address``, because a browser has no access to the operating system APIs needed to measure them. Any policy that requires one of those attributes will **always deny browser users**, including users of the Mattermost web app in a browser tab. If your intent is to restrict access to managed desktop and mobile clients, this is the desired behavior. If your intent is to gate on posture *where it can be measured*, you'll need to write the policy so that browser sessions are handled deliberately rather than incidentally. + +The **Platform** column in **System Console > System Attributes > Session Attributes** shows the supported clients for each attribute. The `Session attribute reference <#session-attribute-reference>`__ below lists them as well. + +Native device and network collection is only implemented on Windows and macOS, so ``hardware_id``, ``client_ip_address``, ``client_fqdn``, ``network_interface_type``, ``vpn_active``, ``ssid``, and ``mdm_enrolled`` are absent on desktop sessions for other platforms. + +For mobile users, enabling ``ssid`` prompts mobile users for location access, because both iOS and Android put Wi-Fi network information behind that permission. Mattermost reads only the current network's name and doesn't collect device location, but a user who declines the prompt reports no SSID and is denied by any policy that requires it. See :ref:`Session attribute collection ` for what the mobile app declares and why. + +Session attribute reference +--------------------------- + +.. list-table:: + :widths: 18 30 14 26 12 + :header-rows: 1 + + * - Attribute + - Description + - Platforms + - How it's collected + - Default TTL / grace + * - ``ip_address`` + - The IP address the request arrived from, as measured by the server. + - Desktop, mobile, browser + - Read from the request connection. Honors ``ServiceSettings.TrustedProxyIPHeader`` when a reverse proxy is configured. + - 15s / 15s + * - ``user_agent_platform`` + - Hardware platform. One of ``Windows``, ``Macintosh``, ``Linux``, ``iPad``, ``iPhone``, ``iPod``, ``BlackBerry``, ``Windows Phone``, or ``Unknown``. + - Desktop, mobile, browser + - Parsed from the ``User-Agent`` header. + - 300s / 300s + * - ``user_agent_os`` + - Operating system. One of ``Windows``, ``Windows 10``, ``Windows 8.1``, ``Windows 8``, ``Windows 7``, ``Windows Vista``, ``Windows XP x64 Edition``, ``Windows XP``, ``Windows 2000``, ``Windows Phone``, ``Mac OS``, ``iOS``, ``Android``, ``Chrome OS``, ``Linux``, ``BlackBerry``, ``Kindle``, ``webOS``, or ``Unknown``. + - Desktop, mobile, browser + - Parsed from the ``User-Agent`` header. + - 300s / 300s + * - ``user_agent_browser_name`` + - Client name. One of ``Chrome``, ``Firefox``, ``Safari``, ``Edge``, ``Internet Explorer``, ``Opera``, ``Android``, ``BlackBerry``, ``Desktop App``, ``Mobile App``, ``mmctl``, or ``Unknown``. + - Desktop, mobile, browser + - Parsed from the ``User-Agent`` header. + - 300s / 300s + * - ``user_agent_browser_version`` + - Version of the browser or Mattermost client, such as ``130.0.6723``. + - Desktop, mobile, browser + - Parsed from the ``User-Agent`` header. + - 300s / 300s + * - ``client_ip_address`` + - The IP address of the device's own primary network interface, as the device sees it. Differs from ``ip_address`` when the user is behind NAT or a proxy. + - Desktop, mobile + - Read from the primary network interface using native OS APIs. IPv4 is used when available; the client falls back to IPv6 when no IPv4 address is present. + - 15s / 15s + * - ``network_interface_type`` + - Type of the device's primary network interface. One of ``wifi``, ``ethernet``, ``cellular``, ``vpn``, ``bluetooth``, or ``other``. + - Desktop, mobile + - macOS: ``SCNetworkInterface`` interface type. Windows: IP Helper adapter type. iOS: ``NWPathMonitor``. Android: ``NetworkCapabilities`` transport type. + - 15s / 15s + * - ``vpn_active`` + - Whether a VPN or tunnel interface is active on the device. ``true`` or ``false``. + - Desktop, mobile + - Detected by inspecting the device's network interfaces for known VPN and tunnel adapter types. See `VPN detection <#vpn-detection>`__ for accuracy limitations. + - 15s / 15s + * - ``ssid`` + - Name of the Wi-Fi network the device is connected to. Empty when the device isn't on Wi-Fi. + - Desktop, mobile + - Windows: WLAN API. iOS and Android: platform Wi-Fi APIs, which require the user to grant location access. Not collected on macOS or Linux desktop. + - 15s / 15s + * - ``mdm_enrolled`` + - Whether the device is enrolled in mobile device management. ``true`` or ``false``. + - Desktop, mobile + - Windows: presence of MDM enrollment registry entries. iOS: managed app configuration. Android: managed profile or managed app restrictions. Always reports ``false`` on macOS desktop, and isn't collected on Linux desktop. + - 60s / 60s + * - ``jailbreak_detected`` + - Whether the mobile device appears to be jailbroken or rooted. ``true`` or ``false``. + - Mobile + - Root and jailbreak heuristics provided by the mobile OS integration. + - 60s / 60s + * - ``os_platform`` + - The device's operating system family. One of ``macos``, ``windows``, ``linux``, ``ios``, or ``android``. + - Desktop, mobile + - Reported directly by the client using Electron or React Native APIs. + - 60s / 60s + * - ``os_version`` + - The device's operating system version, such as ``15.3.1`` or ``10.0.22631``. + - Desktop, mobile + - Reported directly by the client using Electron or React Native APIs. + - 60s / 60s + * - ``client_version`` + - The version of the Mattermost Desktop App or mobile app, such as ``6.3.0``. + - Desktop, mobile + - Reported directly by the client using Electron or React Native APIs. + - 60s / 60s + * - ``hardware_id`` + - A stable hardware identifier for the device. + - Desktop + - macOS: ``IOPlatformUUID``. Windows: SMBIOS system UUID. + - 300s / 300s + * - ``client_device_id`` + - A per-vendor, per-install device identifier for mobile devices. + - Mobile + - iOS: ``identifierForVendor``. Android: ``ANDROID_ID``. + - 300s / 300s + * - ``tls_device_id`` + - A device identity asserted by your reverse proxy, typically derived from a client TLS certificate. + - Desktop, browser + - Read from the ``X-Mattermost-Session-Attribute-Device-Id`` header, and only when ``TrustProxyDeviceIdentityHeader`` is enabled. Never accepted from a client in the header. + - 300s / 300s + * - ``server_fqdn`` + - The hostname of the Mattermost server the client is connected to. Useful when a client connects to multiple servers. + - Desktop, mobile + - Derived by the client from the configured server URL. + - 300s / 300s + * - ``client_fqdn`` + - The device's own fully qualified domain name. + - Desktop + - macOS: local hostname combined with the primary DNS search domain. Windows: ``GetComputerNameExW``. Not collected on Linux desktop. + - 300s / 300s + +.. important:: + + **All session attribute values are case-sensitive.** A rule written as ``user.session.ssid == "corp-wifi"`` will never match a device connected to a network named ``Corp-WiFi``. Values are compared exactly as the client reports them. This matters most for free-text attributes such as ``ssid`` and ``client_fqdn``. Attributes with a fixed set of values are offered in a dropdown in the simple policy editor, but you still type them by hand in the CEL editor. + +.. note:: + + Boolean attributes such as ``vpn_active``, ``mdm_enrolled``, and ``jailbreak_detected`` are reported as the **strings** ``"true"`` and ``"false"``, not as CEL booleans. Compare them as strings: ``user.session.mdm_enrolled == "true"``. + +IPv4 and IPv6 +~~~~~~~~~~~~~ + +``client_ip_address`` prefers IPv4. When the device's primary interface has no usable IPv4 address, the client reports its IPv6 address instead. Write CIDR rules to cover both cases if your network is dual-stack, otherwise a user whose interface falls back to IPv6 will be denied by an IPv4-only rule. ``ip_address`` reflects whatever address the connection actually arrived from, which may be IPv4 or IPv6 depending on your network and reverse proxy configuration. + +VPN detection +~~~~~~~~~~~~~ + +``vpn_active`` is determined by inspecting the **types of network interfaces present on the device**, not by inspecting network traffic. Mattermost looks for interfaces that the operating system reports as VPN or tunnel adapters - for example ``utun`` and ``ipsec`` interfaces on macOS and iOS, and adapters whose type or name identifies them as VPN or tunnel devices on Windows. + +Because detection is based on recognizing interface types, it has real limits: + +- **Split-tunnel VPNs** may be reported as active even when traffic to Mattermost isn't going through the tunnel, or not reported at all, depending on how the client provisions its interfaces. +- **Non-standard VPN implementations** that don't present a recognizable tunnel interface aren't detected. +- ``vpn_active`` tells you a tunnel interface exists, not that the Mattermost connection is using it. + +.. warning:: + + Don't treat ``vpn_active`` as proof that a user's traffic is traversing your corporate VPN. If you need to enforce that requests originate from your network, gate on ``ip_address`` with an ``inCIDR`` check against the address ranges your VPN concentrator or gateway presents. Use ``vpn_active`` as a supporting signal, not as the primary control. + +Use session attributes in permission policies +--------------------------------------------- + +Enabled session attributes appear in the attribute list in the policy editors for permission policies, alongside user attributes. In the simple attribute-and-operator editor, you select a session attribute and an operator the same way you would for a user attribute. Attributes with a fixed set of values, such as ``os_platform``, ``vpn_active``, and ``user_agent_browser_name``, present their values in a dropdown, so you can't mistype them. The `session attribute reference <#session-attribute-reference>`__ lists the valid values for each. + +In the Advanced Mode CEL editor, session attributes are referenced as ``user.session.`` and can be combined with user attributes and with each other using the usual CEL operators: + +.. code-block:: none + + user.session.mdm_enrolled == "true" || user.session.os_platform in ["macos", "windows"] + +Mattermost validates session attribute references when you save a policy. Saving fails if an expression references an attribute that doesn't exist, or one that exists but is currently disabled. + +IP range and version conditions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some conditions can't be expressed by comparing an attribute to a fixed value. Matching an IP address against a subnet, or checking that a client is at or above a minimum version, would otherwise mean listing every acceptable value one by one. Mattermost provides dedicated operators for both cases. In the simple editor they appear in the operator menu, but only after you select an attribute that supports them. In the CEL editor they're written as functions after the attribute they apply to, with the value you're comparing against in parentheses: + +.. code-block:: none + + user.session..("") + +.. list-table:: + :header-rows: 1 + :widths: 22 18 34 26 + + * - Operator + - CEL function + - What it checks + - Available on + * - **in IP range** + - ``inCIDR`` + - The IP address falls inside the given CIDR block, such as ``10.0.0.0/8``. + - ``ip_address``, ``client_ip_address`` + * - **version is** + - ``versionEQ`` + - The version is exactly the given version. + - ``os_version``, ``client_version``, ``user_agent_browser_version`` + * - **version is at least** + - ``versionGTE`` + - The version is equal to or newer than the given version. + - ``os_version``, ``client_version``, ``user_agent_browser_version`` + * - **version is greater than** + - ``versionGT`` + - The version is strictly newer than the given version. + - ``os_version``, ``client_version``, ``user_agent_browser_version`` + * - **version is at most** + - ``versionLTE`` + - The version is equal to or older than the given version. + - ``os_version``, ``client_version``, ``user_agent_browser_version`` + * - **version is less than** + - ``versionLT`` + - The version is strictly older than the given version. + - ``os_version``, ``client_version``, ``user_agent_browser_version`` + +These operators return true or false, so in the CEL editor you can combine them with each other and with ordinary comparisons using ``&&``, ``||``, ``!``, and parentheses. To allow a range of addresses, join several ``inCIDR`` checks with ``||``: + +.. code-block:: none + + user.session.ip_address.inCIDR("10.0.0.0/8") || user.session.ip_address.inCIDR("192.168.0.0/16") + +To require a managed desktop client on a corporate subnet running a supported version: + +.. code-block:: none + + user.session.mdm_enrolled == "true" && user.session.ip_address.inCIDR("10.0.0.0/8") && user.session.client_version.versionGTE("6.3.0") + +Keep the following in mind: + +- **Version comparisons follow semantic versioning**, so ``6.10.0`` is correctly treated as newer than ``6.9.0``. A leading ``v`` and shortened versions such as ``6.3`` are accepted. Pre-release versions such as ``6.3.0-rc1`` sort before the matching release. +- **IP family must match.** An IP range condition only matches when the address and the CIDR block are the same IP version. An IPv4-only rule denies a session that reported an IPv6 address, so cover both families on a dual-stack network. See `IPv4 and IPv6 <#ipv4-and-ipv6>`__. +- **An unparseable value denies access.** If the attribute doesn't hold a valid IP address or version, the condition can't produce a result and the user is denied rather than allowed. +- **Select Validate syntax** before saving in the CEL editor. Validation catches misspelled function names and malformed CIDR blocks or version strings. + +A missing attribute denies access +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + **If a policy references a session attribute that isn't present on the session, access is denied.** This applies whether the attribute was never reported, is disabled, isn't supported on the user's platform, or has gone stale past its TTL and grace period. + +This is deliberate. Evaluating an absent attribute as "no value" would turn a negative condition into an implicit allow: a rule written as ``user.session.jailbreak_detected != "true"`` would pass for every client that simply never reports the attribute, including one that omits it on purpose. Denying on absence means a posture check can't be bypassed by withholding the data it depends on. + +The practical consequence is that **a session attribute rule is also a client requirement**. Consider what a rule implies before saving it: + +- ``user.session.os_platform == "windows"`` denies every browser and mobile session, not just non-Windows desktops. +- ``user.session.vpn_active == "false"`` denies browser sessions, because they never report ``vpn_active`` at all. +- ``user.session.hardware_id != ""`` denies every mobile and browser session, and every Linux desktop session. + +Use **Simulate access** to check the outcome for real users on the clients they actually use before you save. See `Simulate access with session attributes <#simulate-access-with-session-attributes>`__. + +Simulate access with session attributes +--------------------------------------- + +:ref:`Simulate access ` evaluates draft policies against selected users before you save. When the rules contributing to an action reference ``user.session.*`` and the selected user has no cached session attributes, Mattermost shows a neutral **No recent session** indicator instead of an allow or deny result. + +**No recent session** means the simulation had no session data to evaluate, not that the user would be denied. It typically appears when the selected user hasn't connected recently enough for their attributes to still be within TTL and grace period, or has never connected from a client that reports the attributes your rules reference. + +To get a meaningful result, have the user connect from the client you're targeting, then re-run the simulation. + +Configuration settings +---------------------- + +Both settings are managed in **System Console > System Attributes > Attribute-Based Access** and are disabled by default. + +Trust proxy device identity header +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Populates the ``tls_device_id`` session attribute from the ``X-Mattermost-Session-Attribute-Device-Id`` request header, allowing a reverse proxy that performs mutual TLS to assert a device identity that the client itself can't forge. + +- ``config.json`` setting: ``".AccessControlSettings.TrustProxyDeviceIdentityHeader: false",`` with options ``true`` and ``false``. +- Environment variable: ``MM_ACCESSCONTROLSETTINGS_TRUSTPROXYDEVICEIDENTITYHEADER`` + +.. warning:: + + Only enable this setting when a reverse proxy you control terminates every connection to Mattermost **and** strips or overwrites ``X-Mattermost-Session-Attribute-Device-Id`` on inbound requests. If clients can reach the Mattermost server directly, or if your proxy passes the header through unmodified, any client can assert an arbitrary device identity and satisfy policies that gate on ``tls_device_id``. + +Enforce device ID consistency +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Revokes a session when the device identity reported on it changes mid-session. Mattermost compares the ``tls_device_id``, ``client_device_id``, and ``hardware_id`` attributes against the values previously cached for the session; if a value changes, the session is revoked and the user must log in again. Successful revocations are recorded in the audit log. + +- ``config.json`` setting: ``".AccessControlSettings.EnforceDeviceIDConsistency: false",`` with options ``true`` and ``false``. +- Environment variable: ``MM_ACCESSCONTROLSETTINGS_ENFORCEDEVICEIDCONSISTENCY`` + +When disabled, a changed device identity simply overwrites the cached value without revoking the session. + +This setting mitigates session token theft: a stolen token replayed from a different device reports a different device identifier and the session is terminated. Enable it once you've confirmed that the device identity attributes you rely on report stable values across your fleet, since an identifier that legitimately changes will log users out. + +Privacy considerations +---------------------- + +Session attribute collection is opt-in on the server, and default-on on the client. No attribute is collected unless a System Admin enables it, and clients only report the attributes the server asks for in the manifest. + +Desktop App users can stop their client from reporting attributes entirely by clearing **Settings > Advanced > Enable session attributes**. When disabled, the Desktop App stops sending the ``X-MM-Session-Attributes`` header, which means any policy that depends on a client-reported attribute will deny that user. While the setting is enabled, the Desktop App shows users a table of every attribute it can collect and the value it currently reports, so they can see exactly what's being sent. See :ref:`Session attribute collection ` for what the Desktop App collects and how to communicate this to your users. + +On mobile, enabling ``ssid`` may prompt users for location access. See :ref:`Session attribute collection ` for the permissions the mobile app declares. + +Reported values live only in the server's per-session cache. They aren't written to the database, aren't included in compliance exports, and are discarded when the session ends. + +Troubleshooting and FAQs +------------------------ + +Why is a user denied access when their attributes look correct? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Work through these in order: + +1. **Check the client.** Confirm the user is on a client that can report the attribute. Browser sessions can't report device or network attributes, and Linux desktop sessions report only ``os_platform``, ``os_version``, ``client_version``, and ``server_fqdn``. +2. **Check the attribute is enabled.** A disabled attribute is never collected, so any rule referencing it denies. Go to **System Console > System Attributes > Session Attributes** to confirm the status. +3. **Check value casing.** Values are case-sensitive, so a free-text value such as ``ssid`` must match exactly what the client reports. +4. **Check freshness.** If the attribute's TTL plus grace period has elapsed without a fresh report, it's treated as absent. Very short grace periods make this more likely on unstable connections. +5. **Check the user's Desktop App setting.** If the user has cleared **Settings > Advanced > Enable session attributes**, their client reports nothing. When the setting is enabled, the table beneath it shows the value the app currently reports for each attribute, which tells you whether the problem is on the client or the server. +6. **Check location permission for** ``ssid``. Mobile devices only report the Wi-Fi network name when the user has granted location access. + +Why does Simulate access show "No recent session"? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The selected user has no cached session attributes for the simulator to evaluate. Have them connect from the client you're targeting and re-run the simulation. This is a neutral result, not a denial. + +Can users spoof session attributes? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Client-reported attributes are self-attested by the client, so treat them as posture signals rather than as cryptographic proof. Mattermost limits the exposure in several ways: server-derived attributes such as ``ip_address`` and the ``user_agent_*`` values are measured from the request and can't be overridden by a client; ``tls_device_id`` is only ever accepted from a trusted proxy, never from a client; incoming values are validated against the schema and dropped when they're unknown, disabled, or not valid for the requesting platform; and `Enforce device ID consistency <#enforce-device-id-consistency>`__ terminates sessions whose device identity changes. + +For controls that must not be self-attested, prefer ``ip_address`` with ``inCIDR`` (measured by the server) or ``tls_device_id`` backed by mutual TLS at your proxy. + +Are session attributes collected for bots, personal access tokens, or integrations? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No. Collection is limited to interactive end-user sessions. Personal access token sessions, OAuth app sessions, local mode sessions, and remote cluster tokens don't correspond to a physical device with a security posture, so they can't report session attributes. Policies that reference session attributes will deny these callers. + +Do session attributes work in a high availability cluster? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes. Attribute updates are broadcast to all nodes so every node evaluates policies against the same view of a session, regardless of which node handled the request that reported the value. + +Can I add my own session attributes? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No. The set of session attributes is fixed and defined by Mattermost. You can enable, disable, and tune the TTL and grace period of the built-in attributes, but you can't add, rename, or remove attributes, or change their types or supported platforms. For organization-specific values, use :doc:`user attributes ` instead. diff --git a/source/deployment-guide/desktop/desktop-app-deployment.rst b/source/deployment-guide/desktop/desktop-app-deployment.rst index 00638e17f6a..a4e8388e19d 100644 --- a/source/deployment-guide/desktop/desktop-app-deployment.rst +++ b/source/deployment-guide/desktop/desktop-app-deployment.rst @@ -79,4 +79,30 @@ Error reports include: Error reporting is **enabled by default**. Users can disable it at any time by going to **Settings > Advanced > Send error reports to help improve the app**. Restart the app to apply the change. -Organizations with data handling policies should inform users about this feature and provide guidance on whether to disable it. For organizations building the Desktop app from source, error reporting can be disabled at build time by omitting the ``MM_DESKTOP_BUILD_SENTRYDSN`` environment variable. \ No newline at end of file +Organizations with data handling policies should inform users about this feature and provide guidance on whether to disable it. For organizations building the Desktop app from source, error reporting can be disabled at build time by omitting the ``MM_DESKTOP_BUILD_SENTRYDSN`` environment variable. + +Session attribute collection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +From Mattermost Desktop v6.3, the desktop app can report device and network context - such as hardware and network identifiers, VPN status, and MDM enrollment - to the servers it's connected to, for use in :doc:`attribute-based access control policies `. This is separate from error reporting and from anonymous usage data. See the :ref:`session attribute reference ` for every value that can be reported and how each one is measured, and :ref:`platform availability ` for the differences between macOS, Windows, and Linux. + +**When collection happens** + +Collection occurs according to a manifest sent by the server. The server specifies which attributes it wants (based on admin configuration), and the desktop app collects and sends them only as often as the server's configured time-to-live requires. + +**What is NOT sent** + +- Message content or user communications +- Credentials, passwords, or authentication tokens +- Browsing history, running processes, or installed applications +- Contents of network traffic. VPN status is determined by inspecting the *types* of network interfaces present on the device, not by inspecting traffic. + +**Privacy and user control** + +Session attribute reporting is **enabled by default**. Users can disable it at any time by clearing **Settings > Advanced > Enable session attributes**. While it's enabled, a read-only table beneath the setting shows each attribute the app can collect and the value it currently reports, so users can see exactly what's being sent, and admins have somewhere to look first when a user is unexpectedly denied access. + +.. important:: + + Disabling this setting stops the desktop app from reporting attributes, which means the user will be **denied access** to any channel, file upload, or file download governed by a policy that depends on a client-reported session attribute. Organizations that rely on session attributes for access control should inform users of this before rolling the policies out. + +Values reported by the desktop app are held only in the server's in-memory per-session cache. They aren't written to the database, aren't included in compliance exports, and are discarded when the session ends. \ No newline at end of file diff --git a/source/deployment-guide/mobile/mobile-security-features.rst b/source/deployment-guide/mobile/mobile-security-features.rst index f059bef229a..07b21b39403 100644 --- a/source/deployment-guide/mobile/mobile-security-features.rst +++ b/source/deployment-guide/mobile/mobile-security-features.rst @@ -20,6 +20,13 @@ See the :ref:`jailbreak/root protection configuration setting `. Collection is server-initiated and opt-in: the app reports only the attributes a System Admin has explicitly enabled, and only as often as each attribute's time-to-live requires. Message content, credentials, device location, and the contents of network traffic are never included, and reported values are never written to the database or included in compliance exports. + +Reading the Wi-Fi network name requires location access on both platforms, so enabling the ``ssid`` attribute prompts users for that permission. The app declares ``ACCESS_WIFI_STATE`` and ``ACCESS_FINE_LOCATION`` on Android and the ``com.apple.developer.networking.wifi-info`` entitlement on iOS, on both the main app and the share extension. A user who declines the prompt, or who isn't on Wi-Fi, reports no network name and is denied by any policy that requires it. + Biometric authentication ------------------------ diff --git a/source/end-user-guide/preferences/customize-desktop-app-experience.rst b/source/end-user-guide/preferences/customize-desktop-app-experience.rst index ea9441a3a43..39cda184137 100644 --- a/source/end-user-guide/preferences/customize-desktop-app-experience.rst +++ b/source/end-user-guide/preferences/customize-desktop-app-experience.rst @@ -53,6 +53,7 @@ You can customize your desktop app further with additional settings. Select the - **Logging level**: Adjust logging levels to isolate and troubleshoot issues. Increasing the log level increases disk space usage and can impact performance. - **Send anonymous usage data to your configured servers**: Send desktop app usage and performance data to your configured Mattermost servers set up to accept it. - **Send error reports to help improve the app**: From Mattermost Desktop v6.1.0, error reports and crash information are automatically sent to Sentry (a third-party error tracking service) to help identify and fix issues. This setting is enabled by default. Error reports include crash information, app version, and platform details (OS, architecture, memory stats), but no personally identifiable information (PII) is included. You can disable error reporting if preferred. Restart the desktop app to apply changes to this setting. + - **Enable session attributes**: From Mattermost Desktop v6.3, sends device and network information, such as your operating system version and VPN status, to your configured servers for use in permission policies. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it may make some channels or file attachments inaccessible if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. - **Use GPU hardware acceleration**: GPU hardware acceleration renders the desktop app interface more efficiently. If you encounter decreased stability, disable GPU hardware acceleration. Restart the desktop app to apply changes to this setting. .. tab:: Windows/Linux @@ -105,4 +106,5 @@ You can customize your desktop app further with additional settings. Select the - **Logging level**: Adjust logging levels to isolate and troubleshoot issues. Increasing the log level increases disk space usage and can impact performance. - **Send anonymous usage data to your configured servers**: Send desktop app usage and performance data to your configured Mattermost servers set up to accept it. - **Send error reports to help improve the app**: From Mattermost Desktop v6.1.0, error reports and crash information are automatically sent to Sentry (a third-party error tracking service) to help identify and fix issues. This setting is enabled by default. Error reports include crash information, app version, and platform details (OS, architecture, memory stats), but no personally identifiable information (PII) is included. You can disable error reporting if preferred. Restart the desktop app to apply changes to this setting. + - **Enable session attributes**: From Mattermost Desktop v6.3, sends device and network information, such as your operating system version and VPN status, to your configured servers for use in permission policies. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it may make some channels or file attachments inaccessible if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. - **Use GPU hardware acceleration**: GPU hardware acceleration renders the desktop app interface more efficiently. If you encounter decreased stability, disable GPU hardware acceleration. Restart the desktop app to apply changes to this setting. diff --git a/source/security-guide/mobile-security.rst b/source/security-guide/mobile-security.rst index 0a5a734d4d1..7492fc36d74 100644 --- a/source/security-guide/mobile-security.rst +++ b/source/security-guide/mobile-security.rst @@ -43,6 +43,13 @@ Jailbreaking or rooting a device disables many built-in security measures, makin By detecting such devices, Mattermost ensures that only secure, uncompromised devices can access sensitive data. When enabled by the system admin, this proactive measure ensures the underlying mobile platform operates reliably and performs the expected kernel and operating system security protections before sending any customer data to the Mattermost application, and minimizes risk in environments where personal device security cannot be guaranteed. Learn more about Mattermost :ref:`mobile jailbreak and root detection `. +Session attribute collection +---------------------------- + +Session attributes let the mobile app report the posture of the current connection - the device, the network it's on, and how it's managed - so administrators can require a specific posture before a user uploads or downloads a file. Reported values are held only in the server's in-memory session cache and are refreshed on a per-attribute interval that administrators control, so a device that falls out of compliance loses access once the data is considered stale. + +Reporting the Wi-Fi network name requires the user to grant location access, because both iOS and Android gate Wi-Fi information behind that permission. Learn more about Mattermost :ref:`mobile session attribute collection ` and how administrators :doc:`enable and use session attributes `. + Biometric authentication ------------------------ From e91825e3df9b9e9fef3a5e0a6f767f75d49ed587 Mon Sep 17 00:00:00 2001 From: Devin Binnie Date: Fri, 14 Aug 2026 12:03:56 -0400 Subject: [PATCH 02/11] CodeRabbit feedback --- .../admin/abac-channel-access-rules.rst | 6 ++++- .../manage/admin/session-attributes.rst | 25 +++++++++++-------- .../desktop/desktop-app-deployment.rst | 4 +-- .../mobile/mobile-security-features.rst | 2 +- .../customize-desktop-app-experience.rst | 4 +-- 5 files changed, 25 insertions(+), 16 deletions(-) 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 526fe9c3d09..a524ac0d6dc 100644 --- a/source/administration-guide/manage/admin/abac-channel-access-rules.rst +++ b/source/administration-guide/manage/admin/abac-channel-access-rules.rst @@ -130,7 +130,11 @@ From Mattermost v11.8.0, channel admins can define channel-level permission rule For system-wide permission policies that restrict file upload and download actions, see :ref:`Permission policies `. -From Mattermost v11.11, permission rules can also use any :doc:`session attributes ` a System Admin has enabled, letting you restrict file actions by device or network rather than by who the user is. Because a rule that references a session attribute denies anyone whose client doesn't report it - including everyone working in a web browser - review :ref:`platform availability ` and simulate the rule before saving it. +From Mattermost v11.11, permission rules can also use any :doc:`session attributes ` a System Admin has enabled, letting you restrict file actions by device or network rather than by who the user is. + +.. warning:: + + A rule that references a session attribute denies anyone whose client doesn't report it. Browsers report the IP address and user agent the server measures from the request, but never device attributes such as ``os_platform`` or ``vpn_active``, so a rule using one of those denies everyone working in a web browser. Review :ref:`platform availability ` and simulate the rule before saving it. Simulate access ---------------- diff --git a/source/administration-guide/manage/admin/session-attributes.rst b/source/administration-guide/manage/admin/session-attributes.rst index 1b6829279ea..85f19e66305 100644 --- a/source/administration-guide/manage/admin/session-attributes.rst +++ b/source/administration-guide/manage/admin/session-attributes.rst @@ -99,7 +99,7 @@ Session attribute reference * - ``ip_address`` - The IP address the request arrived from, as measured by the server. - Desktop, mobile, browser - - Read from the request connection. Honors ``ServiceSettings.TrustedProxyIPHeader`` when a reverse proxy is configured. + - Read from the request connection, or from ``ServiceSettings.TrustedProxyIPHeader`` when that setting is configured. See `Trusted proxy headers and inCIDR rules <#trusted-proxy-headers-and-incidr-rules>`__. - 15s / 15s * - ``user_agent_platform`` - Hardware platform. One of ``Windows``, ``Macintosh``, ``Linux``, ``iPad``, ``iPhone``, ``iPod``, ``BlackBerry``, ``Windows Phone``, or ``Unknown``. @@ -139,12 +139,12 @@ Session attribute reference * - ``ssid`` - Name of the Wi-Fi network the device is connected to. Empty when the device isn't on Wi-Fi. - Desktop, mobile - - Windows: WLAN API. iOS and Android: platform Wi-Fi APIs, which require the user to grant location access. Not collected on macOS or Linux desktop. + - Windows: WLAN API. iOS and Android: platform Wi-Fi APIs, which require the user to grant location access. Not collected on macOS desktop. - 15s / 15s * - ``mdm_enrolled`` - Whether the device is enrolled in mobile device management. ``true`` or ``false``. - Desktop, mobile - - Windows: presence of MDM enrollment registry entries. iOS: managed app configuration. Android: managed profile or managed app restrictions. Always reports ``false`` on macOS desktop, and isn't collected on Linux desktop. + - Windows: presence of MDM enrollment registry entries. iOS: managed app configuration. Android: managed profile or managed app restrictions. Always reports ``false`` on macOS desktop. - 60s / 60s * - ``jailbreak_detected`` - Whether the mobile device appears to be jailbroken or rooted. ``true`` or ``false``. @@ -189,7 +189,7 @@ Session attribute reference * - ``client_fqdn`` - The device's own fully qualified domain name. - Desktop - - macOS: local hostname combined with the primary DNS search domain. Windows: ``GetComputerNameExW``. Not collected on Linux desktop. + - macOS: local hostname combined with the primary DNS search domain. Windows: ``GetComputerNameExW``. - 300s / 300s .. important:: @@ -205,6 +205,11 @@ IPv4 and IPv6 ``client_ip_address`` prefers IPv4. When the device's primary interface has no usable IPv4 address, the client reports its IPv6 address instead. Write CIDR rules to cover both cases if your network is dual-stack, otherwise a user whose interface falls back to IPv6 will be denied by an IPv4-only rule. ``ip_address`` reflects whatever address the connection actually arrived from, which may be IPv4 or IPv6 depending on your network and reverse proxy configuration. +Trusted proxy headers and inCIDR rules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When ``ServiceSettings.TrustedProxyIPHeader`` is configured, Mattermost takes ``ip_address`` from that header instead of the connection. An ``inCIDR`` rule on ``ip_address`` is only trustworthy when clients can't reach the Mattermost server directly **and** your reverse proxy overwrites the header with the real client address on every inbound request. If the proxy appends to a client-supplied value, or a client can bypass the proxy, the address is attacker-controlled and any network rule built on it can be satisfied at will. + VPN detection ~~~~~~~~~~~~~ @@ -281,11 +286,11 @@ These operators return true or false, so in the CEL editor you can combine them user.session.ip_address.inCIDR("10.0.0.0/8") || user.session.ip_address.inCIDR("192.168.0.0/16") -To require a managed desktop client on a corporate subnet running a supported version: +To require a managed Windows desktop client on a corporate subnet running a supported version: .. code-block:: none - user.session.mdm_enrolled == "true" && user.session.ip_address.inCIDR("10.0.0.0/8") && user.session.client_version.versionGTE("6.3.0") + user.session.os_platform == "windows" && user.session.mdm_enrolled == "true" && user.session.ip_address.inCIDR("10.0.0.0/8") && user.session.client_version.versionGTE("6.3.0") Keep the following in mind: @@ -307,7 +312,7 @@ The practical consequence is that **a session attribute rule is also a client re - ``user.session.os_platform == "windows"`` denies every browser and mobile session, not just non-Windows desktops. - ``user.session.vpn_active == "false"`` denies browser sessions, because they never report ``vpn_active`` at all. -- ``user.session.hardware_id != ""`` denies every mobile and browser session, and every Linux desktop session. +- ``user.session.hardware_id != ""`` denies every mobile and browser session, and any desktop session on a platform without native collection. Use **Simulate access** to check the outcome for real users on the clients they actually use before you save. See `Simulate access with session attributes <#simulate-access-with-session-attributes>`__. @@ -368,7 +373,7 @@ Why is a user denied access when their attributes look correct? Work through these in order: -1. **Check the client.** Confirm the user is on a client that can report the attribute. Browser sessions can't report device or network attributes, and Linux desktop sessions report only ``os_platform``, ``os_version``, ``client_version``, and ``server_fqdn``. +1. **Check the client.** Confirm the user is on a client that can report the attribute, using the **Platforms** column in the `session attribute reference <#session-attribute-reference>`__. Server-derived attributes such as ``ip_address`` and the ``user_agent_*`` values are available on every client, including browsers; client-reported attributes need a Desktop or mobile app on a supported platform. 2. **Check the attribute is enabled.** A disabled attribute is never collected, so any rule referencing it denies. Go to **System Console > System Attributes > Session Attributes** to confirm the status. 3. **Check value casing.** Values are case-sensitive, so a free-text value such as ``ssid`` must match exactly what the client reports. 4. **Check freshness.** If the attribute's TTL plus grace period has elapsed without a fresh report, it's treated as absent. Very short grace periods make this more likely on unstable connections. @@ -383,9 +388,9 @@ The selected user has no cached session attributes for the simulator to evaluate Can users spoof session attributes? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Client-reported attributes are self-attested by the client, so treat them as posture signals rather than as cryptographic proof. Mattermost limits the exposure in several ways: server-derived attributes such as ``ip_address`` and the ``user_agent_*`` values are measured from the request and can't be overridden by a client; ``tls_device_id`` is only ever accepted from a trusted proxy, never from a client; incoming values are validated against the schema and dropped when they're unknown, disabled, or not valid for the requesting platform; and `Enforce device ID consistency <#enforce-device-id-consistency>`__ terminates sessions whose device identity changes. +Client-reported attributes are self-attested by the client, so treat them as posture signals rather than as cryptographic proof. Mattermost limits the exposure in several ways: server-derived attributes are measured from the request rather than accepted from the client; ``tls_device_id`` is only ever accepted from a trusted proxy, never from a client; incoming values are validated against the schema and dropped when they're unknown, disabled, or not valid for the requesting platform; and `Enforce device ID consistency <#enforce-device-id-consistency>`__ terminates sessions whose device identity changes. -For controls that must not be self-attested, prefer ``ip_address`` with ``inCIDR`` (measured by the server) or ``tls_device_id`` backed by mutual TLS at your proxy. +For controls that must not be self-attested, prefer ``ip_address`` with ``inCIDR`` or ``tls_device_id`` backed by mutual TLS at your proxy. Both depend on your proxy being correctly configured - see `Trusted proxy headers and inCIDR rules <#trusted-proxy-headers-and-incidr-rules>`__ and `Trust proxy device identity header <#trust-proxy-device-identity-header>`__. Are session attributes collected for bots, personal access tokens, or integrations? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/deployment-guide/desktop/desktop-app-deployment.rst b/source/deployment-guide/desktop/desktop-app-deployment.rst index a4e8388e19d..88383db03aa 100644 --- a/source/deployment-guide/desktop/desktop-app-deployment.rst +++ b/source/deployment-guide/desktop/desktop-app-deployment.rst @@ -84,7 +84,7 @@ Organizations with data handling policies should inform users about this feature Session attribute collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -From Mattermost Desktop v6.3, the desktop app can report device and network context - such as hardware and network identifiers, VPN status, and MDM enrollment - to the servers it's connected to, for use in :doc:`attribute-based access control policies `. This is separate from error reporting and from anonymous usage data. See the :ref:`session attribute reference ` for every value that can be reported and how each one is measured, and :ref:`platform availability ` for the differences between macOS, Windows, and Linux. +From Mattermost Desktop v6.3, the desktop app can report device and network context - such as hardware and network identifiers, VPN status, and MDM enrollment - to the servers it's connected to, for use in :doc:`attribute-based access control policies `. This is separate from error reporting and from anonymous usage data. See the :ref:`session attribute reference ` for every value that can be reported and how each one is measured, and :ref:`platform availability ` for the differences between platforms. **When collection happens** @@ -99,7 +99,7 @@ Collection occurs according to a manifest sent by the server. The server specifi **Privacy and user control** -Session attribute reporting is **enabled by default**. Users can disable it at any time by clearing **Settings > Advanced > Enable session attributes**. While it's enabled, a read-only table beneath the setting shows each attribute the app can collect and the value it currently reports, so users can see exactly what's being sent, and admins have somewhere to look first when a user is unexpectedly denied access. +Session attribute reporting is **enabled by default**. Users can disable it at any time by clearing **Settings > Advanced > Enable session attributes**. While it's enabled, a read-only table beneath the setting shows each attribute the app can collect on that device and the value it currently reports, which tells users what the app is capable of sending and gives admins somewhere to look first when a user is unexpectedly denied access. Only the attributes the server asks for are actually sent. .. important:: diff --git a/source/deployment-guide/mobile/mobile-security-features.rst b/source/deployment-guide/mobile/mobile-security-features.rst index 07b21b39403..42ba833780d 100644 --- a/source/deployment-guide/mobile/mobile-security-features.rst +++ b/source/deployment-guide/mobile/mobile-security-features.rst @@ -23,7 +23,7 @@ See the :ref:`jailbreak/root protection configuration setting `. Collection is server-initiated and opt-in: the app reports only the attributes a System Admin has explicitly enabled, and only as often as each attribute's time-to-live requires. Message content, credentials, device location, and the contents of network traffic are never included, and reported values are never written to the database or included in compliance exports. +From Mattermost mobile app v2.44, connected to Mattermost server v11.11 or later, the app can report device and network context - such as device identifiers, network interface type, VPN status, MDM enrollment, and jailbreak or root status - to its configured servers for use in :doc:`permission policies `. Collection is server-initiated and controlled entirely by the System Admin: the app reports only the attributes an admin has explicitly enabled, and only as often as each attribute's time-to-live requires. Message content, credentials, device location, and the contents of network traffic are never included, and reported values are never written to the database or included in compliance exports. Reading the Wi-Fi network name requires location access on both platforms, so enabling the ``ssid`` attribute prompts users for that permission. The app declares ``ACCESS_WIFI_STATE`` and ``ACCESS_FINE_LOCATION`` on Android and the ``com.apple.developer.networking.wifi-info`` entitlement on iOS, on both the main app and the share extension. A user who declines the prompt, or who isn't on Wi-Fi, reports no network name and is denied by any policy that requires it. diff --git a/source/end-user-guide/preferences/customize-desktop-app-experience.rst b/source/end-user-guide/preferences/customize-desktop-app-experience.rst index 39cda184137..501a5567484 100644 --- a/source/end-user-guide/preferences/customize-desktop-app-experience.rst +++ b/source/end-user-guide/preferences/customize-desktop-app-experience.rst @@ -53,7 +53,7 @@ You can customize your desktop app further with additional settings. Select the - **Logging level**: Adjust logging levels to isolate and troubleshoot issues. Increasing the log level increases disk space usage and can impact performance. - **Send anonymous usage data to your configured servers**: Send desktop app usage and performance data to your configured Mattermost servers set up to accept it. - **Send error reports to help improve the app**: From Mattermost Desktop v6.1.0, error reports and crash information are automatically sent to Sentry (a third-party error tracking service) to help identify and fix issues. This setting is enabled by default. Error reports include crash information, app version, and platform details (OS, architecture, memory stats), but no personally identifiable information (PII) is included. You can disable error reporting if preferred. Restart the desktop app to apply changes to this setting. - - **Enable session attributes**: From Mattermost Desktop v6.3, sends device and network information, such as your operating system version and VPN status, to your configured servers for use in permission policies. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it may make some channels or file attachments inaccessible if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. + - **Enable session attributes**: From Mattermost Desktop v6.3, sends device and network information, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it may make some channels or file attachments inaccessible if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. - **Use GPU hardware acceleration**: GPU hardware acceleration renders the desktop app interface more efficiently. If you encounter decreased stability, disable GPU hardware acceleration. Restart the desktop app to apply changes to this setting. .. tab:: Windows/Linux @@ -106,5 +106,5 @@ You can customize your desktop app further with additional settings. Select the - **Logging level**: Adjust logging levels to isolate and troubleshoot issues. Increasing the log level increases disk space usage and can impact performance. - **Send anonymous usage data to your configured servers**: Send desktop app usage and performance data to your configured Mattermost servers set up to accept it. - **Send error reports to help improve the app**: From Mattermost Desktop v6.1.0, error reports and crash information are automatically sent to Sentry (a third-party error tracking service) to help identify and fix issues. This setting is enabled by default. Error reports include crash information, app version, and platform details (OS, architecture, memory stats), but no personally identifiable information (PII) is included. You can disable error reporting if preferred. Restart the desktop app to apply changes to this setting. - - **Enable session attributes**: From Mattermost Desktop v6.3, sends device and network information, such as your operating system version and VPN status, to your configured servers for use in permission policies. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it may make some channels or file attachments inaccessible if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. + - **Enable session attributes**: From Mattermost Desktop v6.3, sends device and network information, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it may make some channels or file attachments inaccessible if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. - **Use GPU hardware acceleration**: GPU hardware acceleration renders the desktop app interface more efficiently. If you encounter decreased stability, disable GPU hardware acceleration. Restart the desktop app to apply changes to this setting. From 629a71d8e7fffa77492c4b24e771ce9f40d8d1f9 Mon Sep 17 00:00:00 2001 From: Devin Binnie <52460000+devinbinnie@users.noreply.github.com> Date: Fri, 14 Aug 2026 12:52:14 -0400 Subject: [PATCH 03/11] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- source/deployment-guide/mobile/mobile-security-features.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/deployment-guide/mobile/mobile-security-features.rst b/source/deployment-guide/mobile/mobile-security-features.rst index 42ba833780d..0252760d6e1 100644 --- a/source/deployment-guide/mobile/mobile-security-features.rst +++ b/source/deployment-guide/mobile/mobile-security-features.rst @@ -23,7 +23,7 @@ See the :ref:`jailbreak/root protection configuration setting `. Collection is server-initiated and controlled entirely by the System Admin: the app reports only the attributes an admin has explicitly enabled, and only as often as each attribute's time-to-live requires. Message content, credentials, device location, and the contents of network traffic are never included, and reported values are never written to the database or included in compliance exports. +From Mattermost mobile app v2.44 (when connected to Mattermost server v11.11 or later), the app can report device and network context - such as device identifiers, network interface type, VPN status, MDM enrollment, and jailbreak or root status - to its configured servers for use in :ref:`permission policies `. Collection is server-initiated and controlled entirely by the System Admin: the app reports only the attributes an admin has explicitly enabled, and only as often as each attribute's time-to-live requires. Message content, credentials, device location, and the contents of network traffic are never included, and reported values are never written to the database or included in compliance exports. Reading the Wi-Fi network name requires location access on both platforms, so enabling the ``ssid`` attribute prompts users for that permission. The app declares ``ACCESS_WIFI_STATE`` and ``ACCESS_FINE_LOCATION`` on Android and the ``com.apple.developer.networking.wifi-info`` entitlement on iOS, on both the main app and the share extension. A user who declines the prompt, or who isn't on Wi-Fi, reports no network name and is denied by any policy that requires it. From 180a74d68a08dfa255da26eadac6778984f81675 Mon Sep 17 00:00:00 2001 From: Devin Binnie <52460000+devinbinnie@users.noreply.github.com> Date: Fri, 14 Aug 2026 12:52:32 -0400 Subject: [PATCH 04/11] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- source/administration-guide/manage/admin/session-attributes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration-guide/manage/admin/session-attributes.rst b/source/administration-guide/manage/admin/session-attributes.rst index 85f19e66305..f7ab9bf9e83 100644 --- a/source/administration-guide/manage/admin/session-attributes.rst +++ b/source/administration-guide/manage/admin/session-attributes.rst @@ -4,7 +4,7 @@ Session attributes .. include:: ../../../_static/badges/ent-adv.rst :start-after: :nosearch: -From Mattermost v11.11, :ref:`permission policies ` can evaluate **session attributes** in addition to user attributes. Where a user attribute describes *who* someone is, a session attribute describes *how they're connecting right now* (eg. the network they're on, the client they're using, and the posture of the device in front of them). +From Mattermost v11.11, :ref:`permission policies ` can evaluate **session attributes** in addition to user attributes. Where a user attribute describes *who* someone is, a session attribute describes *how they're connecting right now* (e.g., the network they're on, the client they're using, and the posture of the device in front of them). This lets you write policies such as "only allow file downloads from a corporate IP range" or "block uploads from jailbroken mobile devices" - conditions that can't be expressed with user attributes alone. From 394cd6bf61925a9dcd4ab541b44d0d642316eb4e Mon Sep 17 00:00:00 2001 From: Devin Binnie <52460000+devinbinnie@users.noreply.github.com> Date: Fri, 14 Aug 2026 12:53:16 -0400 Subject: [PATCH 05/11] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- source/deployment-guide/desktop/desktop-app-deployment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/deployment-guide/desktop/desktop-app-deployment.rst b/source/deployment-guide/desktop/desktop-app-deployment.rst index 88383db03aa..ee625df21d3 100644 --- a/source/deployment-guide/desktop/desktop-app-deployment.rst +++ b/source/deployment-guide/desktop/desktop-app-deployment.rst @@ -84,7 +84,7 @@ Organizations with data handling policies should inform users about this feature Session attribute collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -From Mattermost Desktop v6.3, the desktop app can report device and network context - such as hardware and network identifiers, VPN status, and MDM enrollment - to the servers it's connected to, for use in :doc:`attribute-based access control policies `. This is separate from error reporting and from anonymous usage data. See the :ref:`session attribute reference ` for every value that can be reported and how each one is measured, and :ref:`platform availability ` for the differences between platforms. +From Mattermost Desktop v6.3, the desktop app can report device and network context - such as hardware and network identifiers, VPN status, and MDM enrollment - to the servers it's connected to, for use in :ref:`permission policies `. This is separate from error reporting and from anonymous usage data. See the :doc:`session attributes ` documentation for every value that can be reported and how each one is measured, and :ref:`platform availability ` for the differences between platforms. **When collection happens** From ac67b2c94965f16bececf39349854d0d1c6a8446 Mon Sep 17 00:00:00 2001 From: Devin Binnie <52460000+devinbinnie@users.noreply.github.com> Date: Fri, 14 Aug 2026 12:54:32 -0400 Subject: [PATCH 06/11] Update source/administration-guide/manage/admin/session-attributes.rst Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- source/administration-guide/manage/admin/session-attributes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration-guide/manage/admin/session-attributes.rst b/source/administration-guide/manage/admin/session-attributes.rst index f7ab9bf9e83..58df5355dd0 100644 --- a/source/administration-guide/manage/admin/session-attributes.rst +++ b/source/administration-guide/manage/admin/session-attributes.rst @@ -80,7 +80,7 @@ Not every client can report every attribute. A user connecting from a **web brow The **Platform** column in **System Console > System Attributes > Session Attributes** shows the supported clients for each attribute. The `Session attribute reference <#session-attribute-reference>`__ below lists them as well. -Native device and network collection is only implemented on Windows and macOS, so ``hardware_id``, ``client_ip_address``, ``client_fqdn``, ``network_interface_type``, ``vpn_active``, ``ssid``, and ``mdm_enrolled`` are absent on desktop sessions for other platforms. +For desktop sessions, native device and network collection is implemented only on Windows and macOS. These attributes are absent on desktop sessions for other platforms; mobile clients use the native APIs listed in the reference table. For mobile users, enabling ``ssid`` prompts mobile users for location access, because both iOS and Android put Wi-Fi network information behind that permission. Mattermost reads only the current network's name and doesn't collect device location, but a user who declines the prompt reports no SSID and is denied by any policy that requires it. See :ref:`Session attribute collection ` for what the mobile app declares and why. From d522071a621ddcca70e2b5e734448d40bde71377 Mon Sep 17 00:00:00 2001 From: Devin Binnie <52460000+devinbinnie@users.noreply.github.com> Date: Fri, 14 Aug 2026 12:54:49 -0400 Subject: [PATCH 07/11] Update source/security-guide/mobile-security.rst Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- source/security-guide/mobile-security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security-guide/mobile-security.rst b/source/security-guide/mobile-security.rst index 7492fc36d74..79f339bcc26 100644 --- a/source/security-guide/mobile-security.rst +++ b/source/security-guide/mobile-security.rst @@ -46,7 +46,7 @@ By detecting such devices, Mattermost ensures that only secure, uncompromised de Session attribute collection ---------------------------- -Session attributes let the mobile app report the posture of the current connection - the device, the network it's on, and how it's managed - so administrators can require a specific posture before a user uploads or downloads a file. Reported values are held only in the server's in-memory session cache and are refreshed on a per-attribute interval that administrators control, so a device that falls out of compliance loses access once the data is considered stale. +Session attributes let the mobile app report the posture of the current connection - the device, the network it's on, and how it's managed - so administrators can require a specific posture before a user uploads or downloads a file. Reported values are held only in the server's in-memory session cache and are refreshed on a per-attribute interval that administrators control. After the TTL expires, Mattermost can continue to evaluate the last value during the grace period. If no fresh report arrives before TTL plus grace period, the attribute is treated as absent and policies that require it deny access. Reporting the Wi-Fi network name requires the user to grant location access, because both iOS and Android gate Wi-Fi information behind that permission. Learn more about Mattermost :ref:`mobile session attribute collection ` and how administrators :doc:`enable and use session attributes `. From 7e19174af12630406f335aa71e880f060589cbc5 Mon Sep 17 00:00:00 2001 From: Devin Binnie Date: Fri, 14 Aug 2026 13:00:04 -0400 Subject: [PATCH 08/11] PR feedback --- .../manage/admin/abac-channel-access-rules.rst | 2 +- .../manage/admin/abac-system-wide-policies.rst | 4 ++-- source/deployment-guide/desktop/desktop-app-deployment.rst | 2 +- .../preferences/customize-desktop-app-experience.rst | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) 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 a524ac0d6dc..72b5a447380 100644 --- a/source/administration-guide/manage/admin/abac-channel-access-rules.rst +++ b/source/administration-guide/manage/admin/abac-channel-access-rules.rst @@ -134,7 +134,7 @@ From Mattermost v11.11, permission rules can also use any :doc:`session attribut .. warning:: - A rule that references a session attribute denies anyone whose client doesn't report it. Browsers report the IP address and user agent the server measures from the request, but never device attributes such as ``os_platform`` or ``vpn_active``, so a rule using one of those denies everyone working in a web browser. Review :ref:`platform availability ` and simulate the rule before saving it. + A rule that references a session attribute denies any session that doesn't have it. The server measures ``ip_address`` and the ``user_agent_*`` values from every request, but device attributes such as ``os_platform`` and ``vpn_active`` are reported only by the Desktop and mobile apps, so a rule using one of those denies everyone working in a web browser. Review :ref:`platform availability ` and simulate the rule before saving it. Simulate access ---------------- 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 8006ec05b09..9ee33d89587 100644 --- a/source/administration-guide/manage/admin/abac-system-wide-policies.rst +++ b/source/administration-guide/manage/admin/abac-system-wide-policies.rst @@ -130,7 +130,7 @@ You can assign an existing access control policy to a private or public channel 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 `. +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:: @@ -155,7 +155,7 @@ When a permission policy applies, users who don't match the configured attribute 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. -From Mattermost v11.11, permission policy rules can also evaluate :doc:`session attributes ` - for example, restricting file downloads to devices on a corporate IP range or to MDM-enrolled devices. Because a rule that references a session attribute denies any session that doesn't report it, review the platform availability of each attribute before applying it to a file action your users depend on. +From Mattermost v11.11, permission policy rules can also evaluate :doc:`session attributes ` - for example, restricting file downloads to devices on a corporate IP range or to MDM-enrolled devices. Because a rule that references a session attribute denies any session that doesn't report it, review the platform availability of each attribute before applying it to a file action your users depend on. Client-reported attributes such as ``mdm_enrolled`` are self-attested posture signals rather than proof; for stronger assurance, gate on server-measured values instead - ``ip_address`` with an IP range check, or ``tls_device_id`` asserted by your reverse proxy. Attribute value masking ----------------------- diff --git a/source/deployment-guide/desktop/desktop-app-deployment.rst b/source/deployment-guide/desktop/desktop-app-deployment.rst index ee625df21d3..328e4b44e3e 100644 --- a/source/deployment-guide/desktop/desktop-app-deployment.rst +++ b/source/deployment-guide/desktop/desktop-app-deployment.rst @@ -103,6 +103,6 @@ Session attribute reporting is **enabled by default**. Users can disable it at a .. important:: - Disabling this setting stops the desktop app from reporting attributes, which means the user will be **denied access** to any channel, file upload, or file download governed by a policy that depends on a client-reported session attribute. Organizations that rely on session attributes for access control should inform users of this before rolling the policies out. + Disabling this setting stops the desktop app from reporting attributes, which means the user will be **denied** any file upload or file download governed by a policy that depends on a client-reported session attribute. Organizations that rely on session attributes for access control should inform users of this before rolling the policies out. Values reported by the desktop app are held only in the server's in-memory per-session cache. They aren't written to the database, aren't included in compliance exports, and are discarded when the session ends. \ No newline at end of file diff --git a/source/end-user-guide/preferences/customize-desktop-app-experience.rst b/source/end-user-guide/preferences/customize-desktop-app-experience.rst index 501a5567484..b6e060d26aa 100644 --- a/source/end-user-guide/preferences/customize-desktop-app-experience.rst +++ b/source/end-user-guide/preferences/customize-desktop-app-experience.rst @@ -53,7 +53,7 @@ You can customize your desktop app further with additional settings. Select the - **Logging level**: Adjust logging levels to isolate and troubleshoot issues. Increasing the log level increases disk space usage and can impact performance. - **Send anonymous usage data to your configured servers**: Send desktop app usage and performance data to your configured Mattermost servers set up to accept it. - **Send error reports to help improve the app**: From Mattermost Desktop v6.1.0, error reports and crash information are automatically sent to Sentry (a third-party error tracking service) to help identify and fix issues. This setting is enabled by default. Error reports include crash information, app version, and platform details (OS, architecture, memory stats), but no personally identifiable information (PII) is included. You can disable error reporting if preferred. Restart the desktop app to apply changes to this setting. - - **Enable session attributes**: From Mattermost Desktop v6.3, sends device and network information, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it may make some channels or file attachments inaccessible if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. + - **Enable session attributes**: From Mattermost Desktop v6.3, sends the device and network information available on your platform, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it can stop you from uploading or downloading file attachments if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. - **Use GPU hardware acceleration**: GPU hardware acceleration renders the desktop app interface more efficiently. If you encounter decreased stability, disable GPU hardware acceleration. Restart the desktop app to apply changes to this setting. .. tab:: Windows/Linux @@ -106,5 +106,5 @@ You can customize your desktop app further with additional settings. Select the - **Logging level**: Adjust logging levels to isolate and troubleshoot issues. Increasing the log level increases disk space usage and can impact performance. - **Send anonymous usage data to your configured servers**: Send desktop app usage and performance data to your configured Mattermost servers set up to accept it. - **Send error reports to help improve the app**: From Mattermost Desktop v6.1.0, error reports and crash information are automatically sent to Sentry (a third-party error tracking service) to help identify and fix issues. This setting is enabled by default. Error reports include crash information, app version, and platform details (OS, architecture, memory stats), but no personally identifiable information (PII) is included. You can disable error reporting if preferred. Restart the desktop app to apply changes to this setting. - - **Enable session attributes**: From Mattermost Desktop v6.3, sends device and network information, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it may make some channels or file attachments inaccessible if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. + - **Enable session attributes**: From Mattermost Desktop v6.3, sends the device and network information available on your platform, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it can stop you from uploading or downloading file attachments if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. - **Use GPU hardware acceleration**: GPU hardware acceleration renders the desktop app interface more efficiently. If you encounter decreased stability, disable GPU hardware acceleration. Restart the desktop app to apply changes to this setting. From 8d1f34e517bb7e0c1795fde842c96b67e318c3ce Mon Sep 17 00:00:00 2001 From: Devin Binnie Date: Fri, 14 Aug 2026 16:05:47 -0400 Subject: [PATCH 09/11] PR feedback --- .../manage/admin/session-attributes.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/source/administration-guide/manage/admin/session-attributes.rst b/source/administration-guide/manage/admin/session-attributes.rst index 58df5355dd0..e0c66a2c64c 100644 --- a/source/administration-guide/manage/admin/session-attributes.rst +++ b/source/administration-guide/manage/admin/session-attributes.rst @@ -52,9 +52,11 @@ TTL and grace period Each attribute has two timers that together control how fresh its value must be: -- **TTL (time-to-live)**: How long a client waits before re-reporting the attribute. A short TTL keeps the value current at the cost of slightly larger requests; a long TTL reduces overhead but lets the value go stale. +- **TTL (time-to-live)**: For a client-reported attribute, how long the client waits before reporting it again. A short TTL keeps the value current at the cost of slightly larger requests; a long TTL reduces overhead but lets the value go stale. - **Grace period**: How long after the TTL elapses Mattermost will still evaluate the last reported value. Once TTL + grace period has passed without a fresh report, the attribute is treated as absent and policies referencing it deny access. +Clients never report server-derived attributes, so these timers don't govern their freshness. Mattermost measures ``ip_address`` and the ``user_agent_*`` values from each incoming request, which keeps them current for as long as the session is making requests. + Defaults vary by attribute - see the `session attribute reference <#session-attribute-reference>`__. Presets of 30 seconds, 1 minute, 5 minutes, 1 hour, and 24 hours are available for both timers. The time-to-live and grace can be adjusted in the System Console, by selecting the attribute in the Session Attributes list and opening the **More** |more-icon| menu. @@ -179,7 +181,7 @@ Session attribute reference * - ``tls_device_id`` - A device identity asserted by your reverse proxy, typically derived from a client TLS certificate. - Desktop, browser - - Read from the ``X-Mattermost-Session-Attribute-Device-Id`` header, and only when ``TrustProxyDeviceIdentityHeader`` is enabled. Never accepted from a client in the header. + - Read from the ``X-Mattermost-Session-Attribute-Device-Id`` header, and only when ``TrustProxyDeviceIdentityHeader`` is enabled. Any caller that can set that header can set this value, so it's only trustworthy when clients can't bypass your proxy - see `Trust proxy device identity header <#trust-proxy-device-identity-header>`__. - 300s / 300s * - ``server_fqdn`` - The hostname of the Mattermost server the client is connected to. Useful when a client connects to multiple servers. @@ -335,7 +337,7 @@ Trust proxy device identity header Populates the ``tls_device_id`` session attribute from the ``X-Mattermost-Session-Attribute-Device-Id`` request header, allowing a reverse proxy that performs mutual TLS to assert a device identity that the client itself can't forge. -- ``config.json`` setting: ``".AccessControlSettings.TrustProxyDeviceIdentityHeader: false",`` with options ``true`` and ``false``. +- ``config.json`` setting: ``"AccessControlSettings.TrustProxyDeviceIdentityHeader": false`` with options ``true`` and ``false``. - Environment variable: ``MM_ACCESSCONTROLSETTINGS_TRUSTPROXYDEVICEIDENTITYHEADER`` .. warning:: @@ -345,14 +347,14 @@ Populates the ``tls_device_id`` session attribute from the ``X-Mattermost-Sessio Enforce device ID consistency ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Revokes a session when the device identity reported on it changes mid-session. Mattermost compares the ``tls_device_id``, ``client_device_id``, and ``hardware_id`` attributes against the values previously cached for the session; if a value changes, the session is revoked and the user must log in again. Successful revocations are recorded in the audit log. +Revokes a session when the device identity reported on it changes mid-session. Mattermost compares the ``tls_device_id``, ``client_device_id``, and ``hardware_id`` attributes against the values previously cached for the session. When one of them was already cached and then arrives with a different value, the session is revoked, the user must log in again, and the revocation is recorded in the audit log. -- ``config.json`` setting: ``".AccessControlSettings.EnforceDeviceIDConsistency: false",`` with options ``true`` and ``false``. +- ``config.json`` setting: ``"AccessControlSettings.EnforceDeviceIDConsistency": false`` with options ``true`` and ``false``. - Environment variable: ``MM_ACCESSCONTROLSETTINGS_ENFORCEDEVICEIDCONSISTENCY`` When disabled, a changed device identity simply overwrites the cached value without revoking the session. -This setting mitigates session token theft: a stolen token replayed from a different device reports a different device identifier and the session is terminated. Enable it once you've confirmed that the device identity attributes you rely on report stable values across your fleet, since an identifier that legitimately changes will log users out. +This setting mitigates session token theft: a stolen token replayed from a device that reports a different identifier has its session revoked. Detection depends on there being a usable signal to compare, so a replay that reports no device identifier at all, or one on a session that never cached one, isn't revoked. ``tls_device_id`` is only present when `Trust proxy device identity header <#trust-proxy-device-identity-header>`__ is enabled, and the other two identifiers depend on `platform availability <#platform-availability>`__. Enable this setting once you've confirmed that the device identity attributes you rely on report stable values across your fleet, since an identifier that legitimately changes will log users out. Privacy considerations ---------------------- @@ -395,7 +397,7 @@ For controls that must not be self-attested, prefer ``ip_address`` with ``inCIDR Are session attributes collected for bots, personal access tokens, or integrations? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -No. Collection is limited to interactive end-user sessions. Personal access token sessions, OAuth app sessions, local mode sessions, and remote cluster tokens don't correspond to a physical device with a security posture, so they can't report session attributes. Policies that reference session attributes will deny these callers. +No. Collection is limited to interactive end-user sessions. Personal access token sessions, OAuth app sessions, local mode sessions, and remote cluster tokens don't correspond to a physical device with a security posture, so Mattermost collects nothing for them - not even the server-derived attributes it measures from ordinary requests. Policies that reference session attributes will deny these callers. Do session attributes work in a high availability cluster? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 6a3a66609c67f6cb7df90194b0de7cf1c4cbcb40 Mon Sep 17 00:00:00 2001 From: Devin Binnie Date: Mon, 17 Aug 2026 09:36:46 -0400 Subject: [PATCH 10/11] PR feedback --- .../administration-guide/manage/admin/session-attributes.rst | 4 ++-- source/deployment-guide/desktop/desktop-app-deployment.rst | 2 +- .../preferences/customize-desktop-app-experience.rst | 4 ++-- source/security-guide/mobile-security.rst | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/administration-guide/manage/admin/session-attributes.rst b/source/administration-guide/manage/admin/session-attributes.rst index e0c66a2c64c..b07f76fc779 100644 --- a/source/administration-guide/manage/admin/session-attributes.rst +++ b/source/administration-guide/manage/admin/session-attributes.rst @@ -99,7 +99,7 @@ Session attribute reference - How it's collected - Default TTL / grace * - ``ip_address`` - - The IP address the request arrived from, as measured by the server. + - The IP address the request arrived from, as measured by the server, such as ``203.0.113.42``. - Desktop, mobile, browser - Read from the request connection, or from ``ServiceSettings.TrustedProxyIPHeader`` when that setting is configured. See `Trusted proxy headers and inCIDR rules <#trusted-proxy-headers-and-incidr-rules>`__. - 15s / 15s @@ -124,7 +124,7 @@ Session attribute reference - Parsed from the ``User-Agent`` header. - 300s / 300s * - ``client_ip_address`` - - The IP address of the device's own primary network interface, as the device sees it. Differs from ``ip_address`` when the user is behind NAT or a proxy. + - The IP address of the device's own primary network interface, as the device sees it, such as ``10.0.12.34``. Differs from ``ip_address`` when the user is behind NAT or a proxy. - Desktop, mobile - Read from the primary network interface using native OS APIs. IPv4 is used when available; the client falls back to IPv6 when no IPv4 address is present. - 15s / 15s diff --git a/source/deployment-guide/desktop/desktop-app-deployment.rst b/source/deployment-guide/desktop/desktop-app-deployment.rst index 328e4b44e3e..960ca8b064f 100644 --- a/source/deployment-guide/desktop/desktop-app-deployment.rst +++ b/source/deployment-guide/desktop/desktop-app-deployment.rst @@ -103,6 +103,6 @@ Session attribute reporting is **enabled by default**. Users can disable it at a .. important:: - Disabling this setting stops the desktop app from reporting attributes, which means the user will be **denied** any file upload or file download governed by a policy that depends on a client-reported session attribute. Organizations that rely on session attributes for access control should inform users of this before rolling the policies out. + Disabling this setting stops the desktop app from reporting attributes, which means the user will be **denied** any permission, like file upload or file download, governed by a policy that depends on a client-reported session attribute. Organizations that rely on session attributes for access control should inform users of this before rolling the policies out. Values reported by the desktop app are held only in the server's in-memory per-session cache. They aren't written to the database, aren't included in compliance exports, and are discarded when the session ends. \ No newline at end of file diff --git a/source/end-user-guide/preferences/customize-desktop-app-experience.rst b/source/end-user-guide/preferences/customize-desktop-app-experience.rst index b6e060d26aa..0d178790cdb 100644 --- a/source/end-user-guide/preferences/customize-desktop-app-experience.rst +++ b/source/end-user-guide/preferences/customize-desktop-app-experience.rst @@ -53,7 +53,7 @@ You can customize your desktop app further with additional settings. Select the - **Logging level**: Adjust logging levels to isolate and troubleshoot issues. Increasing the log level increases disk space usage and can impact performance. - **Send anonymous usage data to your configured servers**: Send desktop app usage and performance data to your configured Mattermost servers set up to accept it. - **Send error reports to help improve the app**: From Mattermost Desktop v6.1.0, error reports and crash information are automatically sent to Sentry (a third-party error tracking service) to help identify and fix issues. This setting is enabled by default. Error reports include crash information, app version, and platform details (OS, architecture, memory stats), but no personally identifiable information (PII) is included. You can disable error reporting if preferred. Restart the desktop app to apply changes to this setting. - - **Enable session attributes**: From Mattermost Desktop v6.3, sends the device and network information available on your platform, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it can stop you from uploading or downloading file attachments if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. + - **Enable session attributes**: From Mattermost Desktop v6.3, sends the device and network information available on your platform, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it can block actions your organization controls with these values, like uploading or downloading file attachments. See :ref:`Session attribute collection ` for details on what's collected. - **Use GPU hardware acceleration**: GPU hardware acceleration renders the desktop app interface more efficiently. If you encounter decreased stability, disable GPU hardware acceleration. Restart the desktop app to apply changes to this setting. .. tab:: Windows/Linux @@ -106,5 +106,5 @@ You can customize your desktop app further with additional settings. Select the - **Logging level**: Adjust logging levels to isolate and troubleshoot issues. Increasing the log level increases disk space usage and can impact performance. - **Send anonymous usage data to your configured servers**: Send desktop app usage and performance data to your configured Mattermost servers set up to accept it. - **Send error reports to help improve the app**: From Mattermost Desktop v6.1.0, error reports and crash information are automatically sent to Sentry (a third-party error tracking service) to help identify and fix issues. This setting is enabled by default. Error reports include crash information, app version, and platform details (OS, architecture, memory stats), but no personally identifiable information (PII) is included. You can disable error reporting if preferred. Restart the desktop app to apply changes to this setting. - - **Enable session attributes**: From Mattermost Desktop v6.3, sends the device and network information available on your platform, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it can stop you from uploading or downloading file attachments if your organization uses these values to control access. See :ref:`Session attribute collection ` for details on what's collected. + - **Enable session attributes**: From Mattermost Desktop v6.3, sends the device and network information available on your platform, such as your operating system version and VPN status, to your configured servers for use in permission policies. Each server decides which of these attributes it asks for. This setting is enabled by default, and while it's enabled, a table below it shows the value currently reported for each attribute. Disabling it can block actions your organization controls with these values, like uploading or downloading file attachments. See :ref:`Session attribute collection ` for details on what's collected. - **Use GPU hardware acceleration**: GPU hardware acceleration renders the desktop app interface more efficiently. If you encounter decreased stability, disable GPU hardware acceleration. Restart the desktop app to apply changes to this setting. diff --git a/source/security-guide/mobile-security.rst b/source/security-guide/mobile-security.rst index 79f339bcc26..3f96e4f5b1f 100644 --- a/source/security-guide/mobile-security.rst +++ b/source/security-guide/mobile-security.rst @@ -46,7 +46,7 @@ By detecting such devices, Mattermost ensures that only secure, uncompromised de Session attribute collection ---------------------------- -Session attributes let the mobile app report the posture of the current connection - the device, the network it's on, and how it's managed - so administrators can require a specific posture before a user uploads or downloads a file. Reported values are held only in the server's in-memory session cache and are refreshed on a per-attribute interval that administrators control. After the TTL expires, Mattermost can continue to evaluate the last value during the grace period. If no fresh report arrives before TTL plus grace period, the attribute is treated as absent and policies that require it deny access. +Session attributes let the mobile app report the posture of the current connection - the device, the network it's on, and how it's managed - so administrators can require a specific posture before a user performs a controlled action, like uploading or downloading a file. Reported values are held only in the server's in-memory session cache and are refreshed on a per-attribute interval that administrators control. After the TTL expires, Mattermost can continue to evaluate the last value during the grace period. If no fresh report arrives before TTL plus grace period, the attribute is treated as absent and policies that require it deny access. Reporting the Wi-Fi network name requires the user to grant location access, because both iOS and Android gate Wi-Fi information behind that permission. Learn more about Mattermost :ref:`mobile session attribute collection ` and how administrators :doc:`enable and use session attributes `. From 1d92b1b9e0c14acb736f7efc04c8581b3e894e36 Mon Sep 17 00:00:00 2001 From: Devin Binnie Date: Wed, 2 Sep 2026 12:24:18 -0400 Subject: [PATCH 11/11] Include callout for version number checks --- source/administration-guide/manage/admin/session-attributes.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/administration-guide/manage/admin/session-attributes.rst b/source/administration-guide/manage/admin/session-attributes.rst index b07f76fc779..c586436ff7d 100644 --- a/source/administration-guide/manage/admin/session-attributes.rst +++ b/source/administration-guide/manage/admin/session-attributes.rst @@ -297,6 +297,7 @@ To require a managed Windows desktop client on a corporate subnet running a supp Keep the following in mind: - **Version comparisons follow semantic versioning**, so ``6.10.0`` is correctly treated as newer than ``6.9.0``. A leading ``v`` and shortened versions such as ``6.3`` are accepted. Pre-release versions such as ``6.3.0-rc1`` sort before the matching release. +- **Avoid exact-matching** ``client_version``. Client versions may include a build number, and different clients can format it differently, so a rule such as ``client_version == "2.44.0+807"`` can match one client but deny another that reports the same release as ``2.44.0+6000807``. Use a version operator such as **version is at least**, or compare against a shortened version such as ``2.44``, so the build number doesn't have to match. - **IP family must match.** An IP range condition only matches when the address and the CIDR block are the same IP version. An IPv4-only rule denies a session that reported an IPv6 address, so cover both families on a dual-stack network. See `IPv4 and IPv6 <#ipv4-and-ipv6>`__. - **An unparseable value denies access.** If the attribute doesn't hold a valid IP address or version, the condition can't produce a result and the user is denied rather than allowed. - **Select Validate syntax** before saving in the CEL editor. Validation catches misspelled function names and malformed CIDR blocks or version strings.