UX Spec: Permission Policies for File Access Control
Resources
Overview
This feature introduces Attribute-Based Permission Control into Mattermost, enabling administrators to define granular permission policies that override the legacy Role-Based Access Control (RBAC) system based on user attributes. This is another step toward a full Zero Trust access model within Mattermost, where authorization decisions are made dynamically per-request based on who the user is, what device they are on, and what attributes they carry.
For the MVP, permission policies will be scoped to File Access Controls, allowing admins to govern three specific permissions: View Files, Upload Files, and Download Files. These policies evaluate user attributes against defined conditions and grant or deny access accordingly, superseding the legacy RBAC system when applicable.
Problem Statement
Organizations dealing with sensitive information,particularly in defense, government, and regulated industries, require access controls that go beyond static role assignments. The current RBAC system in Mattermost assigns file access permissions uniformly based on system roles (All Members, Channel Admins, Team Admins, System Admins). This does not account for dynamic attributes such as security clearance level, rank, device posture, or program assignment.
Without attribute-based controls, administrators cannot enforce policies like “only users with a Managed device and a rank below Major can download files” without resorting to manual processes or external tooling, creating security risks and operational overhead.
Goals
Enable admins to create permission policies that control file access based on user attributes.
Introduce an ABAC layer that is evaluated before the legacy RBAC system, with RBAC serving as the fallback.
Add View Files, Upload Files, and Download Files as manageable permissions in both the new ABAC system and the legacy RBAC System Scheme.
Provide clear admin-facing indicators when ABAC policies override RBAC settings.
Scope
Permission Policies management page in System Console.
Policy creation/editing with attribute-based conditions (Simple and Advanced/CEL modes).
File Access permissions: View Files, Upload Files, Download Files.
Policy scope: Entire workspace (and specific teams?)
Role targeting: All Members, Channel Admins, Team Admins, System Admins.
Integration with legacy RBAC System Scheme (new file permissions + ABAC override indicators).
End-user experience for denied file actions (hidden UI elements or generic errors).
High-Level Architecture
Attribute-Based Permission/Access Control
The system introduces a Policy Engine powered by CEL (Common Expression Language) that sits between user authentication and resource access. When a user performs an action (e.g., downloading a file), the Policy Decision Point (PDP) evaluates all applicable permission policies against the user’s attributes and session data.
Decision Chain
The authorization decision flow follows a clearly defined evaluation order. This is critical for admins to understand the mental model of how access is determined.
Multi-Policy Conflict Resolution: Strict Intersection
When multiple permission policies apply to the same action, we use a Strict Intersection (Logical AND) as the Policy Combining Algorithm. The user must satisfy the positive conditions of ALL applicable policies to be granted access. If they fail even one policy’s constraints, access is denied.
This is a deliberate, security-first design decision that rejects the standard commercial default.
Why NOT Permit Overrides (Logical OR)
Many commercial access control systems (e.g., Okta, AWS IAM Allow statements) default to a Permit Overrides or Logical OR model, where satisfying any single policy grants access. This is an INFOSEC failure mode for sensitive environments.
Example of the OR failure
Admin A creates Policy 1 requiring Rank > Major. Admin B creates Policy 2 requiring Location == USA. Under Logical OR, a Private in Texas can download sensitive files because they satisfy Policy 2, even though they fail the rank requirement. This constitutes a data spillage incident because the system unioned two distinct security perimeters.
The Strict Intersection Model
In a Zero Trust Architecture (NIST 800-207), multiple constraints represent Defense-in-Depth, not a menu of options. When the PDP detects multiple policies governing the same action, it evaluates them as a strict intersection: Evaluate(Policy 1) AND Evaluate(Policy 2) must both equal TRUE.
Example: File Download with Two Policies
User | Policy 1: Rank > Major | Policy 2: Location == USA | Result |
|---|---|---|---|
Colonel in London | PASS | FAIL | DENIED |
Corporal in Texas | FAIL | PASS | DENIED |
Major in Washington D.C. | PASS | PASS | GRANTED |
Industry Alignment
NIST SP 800-162 (Guide to ABAC): Recommends combining algorithms that favor denial for environments with high-confidentiality requirements.
Zero Trust Principle: Aligns with “never trust, always verify.” Applying more policies to a resource always tightens the security perimeter, never accidentally loosens it.
Admin Guidance in Docs: Expressing OR Logic
If an administrator genuinely wants a user to satisfy either of two conditions (e.g., download files by being either a Major OR located in the USA), they must express that OR logic explicitly within a single policy using the CEL editor that supports OR conditions.
Single policy CEL example: (user.rank > "Major") || (user.location == "USA")
The system forces administrators to explicitly declare OR logic inside a single policy boundary, rather than letting the backend engine implicitly combine decoupled policies. This eliminates ambiguity and ensures every OR condition is a deliberate, auditable decision by a single policy author.
Recommendation
This admin guidance should be surfaced in the Permission Policies documentation and in contextual help within the System Console. When multiple policies exist for the same permission, a help tooltip should explain: “Multiple policies controlling the same permission are evaluated as a strict intersection. A user must satisfy ALL applicable policies. To allow access based on any one of several conditions, combine those conditions within a single policy using OR logic.”
Supporting Functionality
Before detailing the core Permission Policies UI, several supporting capabilities must be in place for the MVP to function as intended.
File Permissions in Legacy RBAC
[VERIFY] The tech spec does not currently plan to add file-level permissions to the RBAC System Scheme and has no RBAC fallback for file operations. This section describes the required design; engineering alignment is needed before implementation. The RBAC permission scheme fallback is the agreed approach when no ABAC policy matches a request, replacing the tech spec’s current default-allow behavior.
The MVP introduces a new “Manage Files” permission group into the existing System Scheme under Legacy RBAC. This ensures file access controls are available even without ABAC policies and provides the fallback layer when no ABAC policy applies.
These permissions appear under a new “Manage Files” parent row in the System Scheme permission table, nested as child toggles for View files, Upload files, and Download files.
ABAC Override Indicator
When one or more ABAC Permission Policies govern file access permissions, each file permission row in the System Scheme must display a “Permission Policy applicable” badge. This badge communicates to the admin that the RBAC toggle for that permission is not the final authority and ABAC policies take precedence when applicable.
Badge behavior: The badge appears when at least one Permission Policy exists that includes the corresponding file permission. The badge is shown on the parent “Manage files” row as well as each individual child permission row (View files, Upload files, Download files).
Tooltip on badge hover: “One or more Permission Policies control this permission. The RBAC setting below only applies when no Permission Policy matches the user.”
RBAC toggles remain editable: Admins can still modify RBAC toggles for file permissions. These toggles serve as the fallback when no ABAC policy matches an access request or resource.
Permission Policies List
The Permission Policies page is the central management surface for all ABAC permission policies in the system. Admins access it via System Console → User Management → Permission Policies.
Policy Detail Page
The Policy Detail page is where admins create and edit permission policies. It is divided into four main sections, each addressing a key dimension of the policy: who it targets, what conditions must be met, what permissions are modified, and where it applies.
Information Banner
An informational banner is displayed at the top of the policy form to explain how ABAC interacts with the legacy system. The copy must accurately reflect the decision chain.
Who This Policy Applies To
This section defines the target audience for the policy using two dimensions: the system role and user attribute conditions. Both must be satisfied for the policy to match a user (AND relationship between role selection and attribute conditions).
The selected role acts as a pre-filter. The policy will only be evaluated for users who hold the selected role. Attribute conditions are then applied as an additional filter within that role group.
[VERIFY] The tech spec currently defaults all policies to system_user and defers role selection to a post-MVP release. This conflicts with NIST 800-53 AC-6(5), AC-5, CMMC AC.3.017, and DoD ZTRA v2.0 PAM requirements, which require explicitly scoped policies for privileged roles. Role selection targeting at minimum system_user and system_admin can be considered for the MVP. Channel Admin and Team Admin targeting should also be validated against the backend system role model, as these map to existing RBAC permission sets.
User Attribute Requirements
Attribute conditions define what attribute values a user must carry for the policy to match them. This section supports two configuration modes: Simple and Advanced.
What Permissions Are Modified
This section defines which permissions the policy controls and whether they are granted or denied when the policy conditions are met.
Interaction Details
Adding permissions: “+ Add permission” button below the table opens a permission picker. For the MVP, only File Access permissions are available.
Toggling: Each permission has an individual checkbox. Checked = granted when policy matches. Unchecked = denied when policy matches.
Removing: Individual permissions or the entire File Access group can be removed via the red delete icon. Removing all permissions effectively deactivates the policy (it still exists but controls nothing).
[VERIFY] The tech spec suggests having allow-type rules only. Denial occurs implicitly when no matching rule grants access for a given action. Explicit deny-type policies are deferred to a future phase. This will mean that the checkbox for each permission may not make sense since adding the permission but unchecking it will be perceived as “denying” permission to be consistent with the current RBAC model.
Where This Policy Applies [to-be-validated]
This section controls the scope of the policy or where in the workspace the policy is enforced.
When “Specific channels and teams” is selected, tabs for channel and team pickers appear allowing the admin to search and select one or more items. Selected items are shown as removable chips/tags.
Saving a Policy
When saving a new policy or editing an existing one, a confirmation dialog must be presented before changes are applied.
Validation Before Save
Policy name is required and non-empty.
At least one attribute condition must be configured.
In Advanced mode, the CEL expression must pass syntax validation.
If any validation fails, the save button is disabled and inline errors are shown on the relevant fields.
Deleting a Policy
A policy can be deleted from the Policy Detail page or from the Actions menu on the Permission Policies list.
Delete Behavior
There are no prerequisites for deletion (unlike Access Policies, which require channels to be unassigned first). A Permission Policy can be deleted at any time.
A confirmation dialog is required before deletion.
Enforcement Timing
Policy changes take effect per-request via the system’s caching layer, which propagates updates automatically after saving. No session invalidation or server restart is required. Caching strategy and invalidation details are defined in the tech spec.
End-User Experience
When a permission policy denies a user access to a file action, the system must communicate this clearly without revealing policy details that could constitute an operational security risk.
Design Principle
In classified and high-security environments, revealing why access was denied (e.g., “your clearance is too low” or “your device is not managed”) can leak sensitive organizational structure and policy logic. The end-user experience follows a “minimum disclosure” principle:
Primary approach: Hide UI elements for actions the user cannot perform.
Fallback approach: If hiding is not technically feasible, show a generic “You do not have permission to perform this action” error on interaction.
Partial Permission Scenarios
A user may have mixed file permissions based on policy configuration. For example:
Can view but not download: File preview is visible, but the download button is hidden (or disabled with generic error on click).
Can upload but not view/download: Upload button is visible in the composer. Uploaded files appear with a generic file icon but no preview. Other users' files are hidden.
Cannot upload but can view/download: Upload button is hidden from the composer. Existing files in channels are viewable and downloadable
Generic Error Message
When the fallback error approach is used, the error message must be generic and must not reference:
The specific policy that denied access.
The attribute(s) that caused the denial.
The existence of ABAC policies in general.
Error Copy
Toast/inline error: “You do not have permission to perform this action.”
Additional context (optional): “Contact your system administrator if you believe this is an error.”
Audit Logging
For compliance with DoD IL4+ requirements and general security best practices, all policy-related events and access decisions must be logged.
Admin Guardrails & Edge Cases
Self-Lockout
An admin can create a policy that restricts their own file access. For example, a System Admin creating a policy targeting “All Members” with attribute conditions they satisfy will have their own file access modified by that policy.
Design decision: No warning or hard block is implemented for self-lockout in the MVP. The “Test matching users” feature allows admins to see if they are in the matching set before saving, which provides sufficient visibility.
No Matching Users
If the configured attribute conditions match zero users, the policy can still be saved. This is intentional since the policy may be created proactively for future users who will match the conditions once their attributes are provisioned.
Policy with No Permissions
If all permissions are removed from a policy, the policy persists but has no effect. To completely remove a policy, delete it from the Policy Detail page or via the Actions menu on the Permission Policies list.
Licensing
Permission Policies is a part of the Enterprise Advanced SKU.
Non-Licensed Experience
For workspaces on any other pricing tier (Free, Professional, Enterprise), the Permission Policies page in the System Console should display an upsell placeholder.
The “Permission Policy applicable” badges in the RBAC System Scheme should not appear for non-licensed workspaces, as no ABAC policies can exist.
Future Phases
The following capabilities are explicitly deferred from the MVP and planned for future iterations:
Policy enable/disable toggle for cleaner deactivation without deletion.
Additional permissions beyond file access (Teams, Channels, Webhooks, Plugins, Integrations & Customizations, Custom Groups).
Dynamically applying policies to channels/teams based on resource attributes.
Manually selecting specific channels within a policy.
Environmental and session attributes (MDM device posture, client type, network location).
API endpoints for policy CRUD operations.
AI-assisted rule creation in the CEL editor.
Policy versioning and rollback.
Policy simulation/dry-run mode that previews effective permissions across the user base.
Need-to-know attribute/value masking in policy configurations.
Delegated Granular Administration role for managing ABAC policies
Open Questions
Do we want to support “Deny” type policies? Detailed arguments here - ABAC Vision: Complexity with "Deny" type permission policies
Answered in tech spec: The current implementation uses allow-type rules only. Denial occurs implicitly when no matching rule grants access for a given action. Explicit deny-type policies are deferred to a future phase.
Attribute caching strategy: per-session vs. per-request? What is the acceptable staleness window for high-security deployments?