Skip to content

BRD

Feature BRD: Access Control Model Foundation (RBAC/GBAC)
Document Version: 1.1
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 foundational Access Control Model, which will serve as the security cornerstone for the entire enterprise console application. This feature is not a user-facing interface but rather a set of core business rules and data structures that define how permissions are granted, inherited, and evaluated.

  • For detailed user interaction flows, see the Use Case document.
  • For the quality assurance and validation strategy, see the Test Plan.

The model implements a hybrid strategy combining Role-Based Access Control (RBAC) and Group-Based Access Control (GBAC). This structure is intentionally designed to mirror our organization's operational hierarchy, ensuring that access management is both logical and scalable. It establishes the fundamental logic that will govern every user's ability to interact with any part of the application, now and in the future. This model is formally documented in the ADR for Strict, Group-Based Access Control.

1.2. Business Objectives

The implementation of this specific access control model is critical to achieving the following strategic goals:

  • Enforce the Principle of Least Privilege: To ensure users have access only to the information and functions essential for their job responsibilities, thereby minimizing security risks and potential for data misuse.
  • Simplify and Standardize Permission Management: To move away from error-prone, individual-based permission assignments. By managing access through a structured hierarchy, administrators can grant or revoke permissions for entire teams or job functions with a single action, drastically reducing administrative overhead.
  • Enhance Auditability and Compliance: To create a clear, transparent, and easily auditable trail of access rights. This model allows us to answer precisely "Who has access to what, and why?" which is a non-negotiable requirement for internal security audits and regulatory compliance.
  • Promote Scalability: To build a security framework that can grow with the company. As new departments are formed or new roles are created, the model can accommodate these changes without requiring a fundamental redesign of the access control system.

1.3. Scope

In Scope Out of Scope
The definition of the core data entities: Users, Groups, Roles, and Permissions. The User Interface (UI) for creating, reading, updating, and deleting Users, Groups, or Roles. (This will be defined in separate feature BRDs).
The establishment of the strict, non-negotiable hierarchical relationship and inheritance path between these entities. The definition of the specific, granular permissions themselves (e.g., user:create, report:view:sales). This document only defines the framework for how those permissions will be contained and assigned.
The business logic governing how a user's "effective permissions" are calculated from their group and role assignments. The user authentication (login) process, which is handled by Google IdP.
The absolute prohibition of assigning permissions or roles directly to users, ensuring the model's integrity. The workflow for a user to "Request Access" after being denied.

2. Business Requirements & Rules

This section defines the immutable rules that constitute the access control model. These rules must be enforced at the application and data layers to ensure system integrity.

2.1. Core Model Definition

  • Rule 2.1.1: The system MUST implement a hybrid access control model that leverages both Group-Based Access Control (GBAC) for user organization and Role-Based Access Control (RBAC) for permission aggregation.

2.2. Entity Definitions and Cardinality

  • Rule 2.2.1 (User): A User is a singular entity representing an individual operator authenticated by the system.
  • Rule 2.2.2 (Group): A Group is a logical container for Users, designed to reflect the company's organizational structure (e.g., "Marketing Department," "NY Sales Team").
    • A User can belong to one or more Groups.
    • A Group can contain one or more Users.
  • Rule 2.2.3 (Role): A Role is a collection of specific permissions, designed to represent a job function or a set of responsibilities (e.g., "System Administrator," "Content Editor").
    • A Group can be assigned one or more Roles.
    • A Role can be assigned to one or more Groups.
  • Rule 2.2.4 (Permission): A Permission is the most granular, atomic unit of authorization. It represents a single, indivisible right to perform a specific action within the system (e.g., user:delete, dashboard:view_kpi).
    • A Role can contain one or more Permissions.
    • A Permission can be included in one or more Roles.

2.3. The Hierarchy and Inheritance of Access

  • Rule 2.3.1 (Strict Inheritance Path): The system MUST enforce a strict, one-way inheritance path for permissions. The flow of rights is exclusively as follows:
    1. Permissions are collected into Roles.
    2. Roles are assigned to Groups.
    3. Users are placed into Groups.
      A user's access is determined solely by this chain.
  • Rule 2.3.2 (CRITICAL - Prohibition of Direct Assignment): To maintain the integrity and auditability of the model, the system MUST programmatically prevent the following direct assignments under any circumstance:
    • A Permission cannot be assigned directly to a User.
    • A Permission cannot be assigned directly to a Group.
    • A Role cannot be assigned directly to a User.
      This is the most critical business rule in this document. All access rights must flow through the complete hierarchy.

2.4. Effective Permission Calculation Logic

  • Rule 2.4.1 (Union of Permissions): A user's total set of "effective permissions" is the unique union (i.e., a combined list with no duplicates) of all permissions granted by all roles associated with every group to which that user belongs.
  • Rule 2.4.2 (Additive Model - No "Deny"): The permission model is purely additive. Access is granted by the presence of a specific permission in the user's effective permission set. Access is denied by its absence. The system MUST NOT implement any concept of an explicit "deny" rule that overrides an "allow" rule.

3. System Behavior and Logic Flows

This section describes the expected system behavior based on the rules defined above. This serves as a guide for development and a basis for QA test cases.

3.1. System Flow: Permission Check on Action

  • Description: For every protected action a user attempts to perform, the system must execute a real-time permission check against their calculated effective permissions before allowing the action to proceed.
  • System Logic Flow:
    1. Trigger: A user initiates a protected action (e.g., clicks a "Create New User" button).
    2. Identification: The system identifies the specific permission string required for that action (e.g., user:create).
    3. Data Retrieval (User -> Groups): The system retrieves the list of all Group IDs the user is a member of.
    4. Data Retrieval (Groups -> Roles): The system retrieves the list of all Role IDs assigned to those groups.
    5. Data Retrieval (Roles -> Permissions): The system compiles a complete, unique list of all Permission strings contained within all of those roles. This final list constitutes the user's "effective permissions" for this session.
    6. Evaluation & Decision:
      • Success Case: If the required permission string (user:create) exists in the user's effective permissions list, the system allows the action to proceed.
      • Failure Case: If the required permission string does not exist in the user's effective permissions list, the system MUST block the action and immediately trigger the standard "Unauthorized Access" handling procedure.

4. User Scenarios

This section provides practical examples of how the access control model will function for different users and situations.

4.1. Scenario 1: Successful Access (Standard Case)

  • Persona: Alice, a junior content writer.
  • Setup:
    • Alice is a member of the "Marketing Content Creators" Group.
    • The "Marketing Content Creators" Group is assigned the "Content Editor" Role.
    • The "Content Editor" Role contains the permissions: article:create, article:edit, and asset:upload.
  • Action: Alice logs in and navigates to the articles section. She clicks the "Create New Article" button.
  • Expected System Behavior:
    1. The system identifies that the action requires the article:create permission.
    2. The system calculates Alice's effective permissions by following the chain: Alice -> "Marketing Content Creators" Group -> "Content Editor" Role -> [article:create, article:edit, asset:upload].
    3. The system finds article:create in her effective permissions list.
    4. Outcome: Alice is successfully directed to the new article creation page.

4.2. Scenario 2: Denied Access (Insufficient Permissions)

  • Persona: Bob, a sales analyst.
  • Setup:
    • Bob is a member of the "Sales Analytics" Group.
    • The "Sales Analytics" Group is assigned the "Report Viewer" Role.
    • The "Report Viewer" Role contains the permissions: report:view:sales, dashboard:view.
  • Action: Bob is viewing a sales report and sees a link to the user management page. He clicks the link to try and view the list of system users.
  • Expected System Behavior:
    1. The system identifies that viewing the user list requires the user:view:list permission.
    2. The system calculates Bob's effective permissions: Bob -> "Sales Analytics" Group -> "Report Viewer" Role -> [report:view:sales, dashboard:view].
    3. The system does not find user:view:list in his effective permissions list.
    4. Outcome: The system blocks the navigation and displays a standard "Access Denied" message. The user interface should ideally have hidden this link from Bob in the first place based on his permissions.

4.3. Scenario 3: Complex Access (Union of Permissions from Multiple Groups)

  • Persona: Carol, a marketing manager.
  • Setup:
    • Carol is a member of two groups:
      1. "Marketing Department" Group, which has the "Manager" Role. The "Manager" Role contains permissions like report:view:marketing and campaign:approve.
      2. "Content Approvers" Group, which has the "Publisher" Role. The "Publisher" Role contains permissions like article:publish and article:delete.
  • Action: Alice (from Scenario 1) has finished writing an article and has submitted it for approval. Carol now needs to publish it. She navigates to the article and clicks "Publish".
  • Expected System Behavior:
    1. The system identifies that the action requires the article:publish permission.
    2. The system calculates Carol's effective permissions by taking the union of all permissions from all her roles:
      • From "Manager" Role: [report:view:marketing, campaign:approve]
      • From "Publisher" Role: [article:publish, article:delete]
      • Carol's Effective Permissions: [report:view:marketing, campaign:approve, article:publish, article:delete]
    3. The system finds article:publish in her combined effective permissions list.
    4. Outcome: The system successfully publishes the article and confirms the action to Carol.