Skip to content

BRD

Feature BRD: Admin: Effective Permissions View
Document Version: 1.0
Author: Senior Business Analyst
Date: 2025-09-10
Status: Draft for Review

1. Introduction

1.1. Feature Overview

This document specifies the business requirements for the Effective Permissions View. This is a read-only diagnostic feature that allows authorized administrators to inspect the complete, calculated set of permissions for any given user. It is not a page for making changes, but rather a tool for auditing, validating, and troubleshooting user access issues by providing a transparent view of the final permission set generated by the RBAC/GBAC model defined in ADR-0004 and the Access Control Model Foundation BRD.

1.2. Business Objectives

  • Accelerate Troubleshooting: To provide administrators with a definitive, at-a-glance tool to answer the question, "Why can (or can't) this user perform this action?", drastically reducing the time required to resolve access-related support tickets.
  • Enhance Security Auditing: To enable a simple, clear method for auditing the precise access rights of any individual user, ensuring compliance with internal security policies.
  • Validate Access Model Configuration: To allow administrators to confirm that the combination of a user's group memberships and assigned roles results in the intended set of permissions, helping to verify correct system configuration.

1.3. Scope

In Scope Out of Scope
A read-only page or modal accessible from the User Editing or User Listing page. The ability to modify a user's groups, roles, or permissions from this view.
Displaying the user's name and email for clear identification. A side-by-side comparison of permissions between two or more users.
A comprehensive list of all groups the user belongs to. A detailed log or history of how a user's permissions have changed over time.
A final, de-duplicated list of all "effective permissions" the user possesses. An explanation of which specific role granted each individual permission.

2. Business Requirements & Rules

2.1. Access Control

  • Rule 2.1.1: The ability to access the Effective Permissions View MUST be strictly controlled. An administrator MUST have the user:view:permissions permission in their effective permission set.
  • Rule 2.1.2: A "View Permissions" button or link MUST only be visible on the User Listing or User Edit page to administrators who possess the user:view:permissions permission.
  • Rule 2.1.3: Any user without this permission who attempts to access the view's URL directly MUST be redirected to an "Access Denied" page.

2.2. User Interface and Data Display

  • Rule 2.2.1 (User Identification): The view MUST prominently display the Full Name and Email Address of the user being inspected to avoid any ambiguity.
  • Rule 2.2.2 (Information Structure): The information MUST be presented in a clear, read-only format, logically separated into the following sections:
    • Group Memberships: A list of the names of all groups the user is a member of.
    • Inherited Roles: A unique list of the names of all roles the user inherits from their group memberships.
    • Effective Permissions: The final, comprehensive list of all unique permission strings the user possesses.
  • Rule 2.2.3 (Data Presentation): For readability, all lists (Groups, Roles, and Permissions) MUST be sorted alphabetically.

2.3. System Logic

  • Rule 2.3.1 (Permission Calculation): The "Effective Permissions" list MUST be calculated by the system using the exact logic defined in the "Access Control Model Foundation" BRD (Rule 2.4.1): it must be the unique union of all permissions from all roles associated with every group the user belongs to.
  • Rule 2.3.2 (Real-Time Data): The data displayed MUST be generated in real-time upon loading the view to ensure it reflects the user's current state, not a cached version.

3. User Scenarios

3.1. Scenario 1: Admin Troubleshoots a User's Access Issue

  • Persona: David, a System Administrator.
  • Action: A user, Bob, from the sales team, reports that he cannot access a newly launched "Q3 Sales Projections" report. David finds Bob on the user list and clicks "View Effective Permissions".
  • Expected System Behavior:
    1. The system calculates Bob's permissions in real-time.
    2. The view loads, showing Bob's name, email, his group ("Sales Analytics"), and his inherited role ("Report Viewer").
    3. David scans the alphabetized "Effective Permissions" list and sees report:view:sales but does not see the required report:view:sales_q3_projections permission.
    4. Outcome: David immediately knows the problem is not with Bob's account but with the "Report Viewer" role, which needs to be updated to include the new permission.

3.2. Scenario 2: Admin Verifies Access for a Manager

  • Persona: David, a System Administrator.
  • Action: Carol has been promoted to a marketing manager. David has placed her in two groups: "Marketing Department" and "Content Approvers." Before closing the ticket, he wants to verify her access. He navigates to Carol's profile and clicks "View Effective Permissions."
  • Expected System Behavior:
    1. The view loads and shows Carol's details.
    2. The "Group Memberships" list correctly shows both "Marketing Department" and "Content Approvers."
    3. The "Effective Permissions" list shows a combined set of permissions from both the "Manager" and "Publisher" roles, including campaign:approve and article:publish.
    4. Outcome: David confirms the configuration is correct and that Carol has the appropriate level of access for her new role.

3.3. Scenario 3: Unauthorized Attempt to View Permissions

  • Persona: A team lead with permission to view the user list (user:view:list) but not to inspect permissions.
  • Action: The team lead is looking at their team members in the user list.
  • Expected System Behavior:
    1. The "View Effective Permissions" button or link is not visible on any user row.
    2. If the team lead were to obtain and try to use the direct URL for the permissions view, the system would validate