# Role-Based Access Control

## Overview

Role-Based Access Control (RBAC) implements a permission-to-role-to-user authorization model. Permissions define specific allowed actions on resources, roles bundle related permissions together, and users are assigned one or more roles. This model simplifies access management by allowing administrators to manage permissions at the role level rather than per-user.

The RBAC implementation follows the principle of least privilege, ensuring users only have access to what they need for their job function.

## Business Purpose

Organizations need granular access control that scales with team size:

- **Simplified Administration**: Instead of managing permissions per user, administrators assign roles
- **Consistency**: All users with the same role have identical permissions
- **Separation of Duties**: Different roles can have non-overlapping permissions to prevent fraud
- **Auditability**: Clear mapping from user to roles to permissions supports compliance reviews
- **Scalability**: Adding new users requires only role assignment, not permission configuration

## Process Flow

```mermaid
flowchart TD
    A[Define Permission] --> B[Permission Created]
    B --> C[Assign Permission to Role]
    C --> D[Role Has Permission]

    E[Create Role] --> F[Role Created]
    F --> C

    G[Assign Role to User] --> H{User Active?}
    H -->|No| I[Return Error: USER_NOT_ACTIVE]
    H -->|Yes| J[User Has Role]
    J --> K[User Inherits Role's Permissions]

    subgraph Permission Check
    L[Check User Permission] --> M[Get User's Roles]
    M --> N[Get Roles' Permissions]
    N --> O{Has Required Permission?}
    O -->|Yes| P[Access Granted]
    O -->|No| Q[Access Denied]
    end
```

## Scenario Patterns

- **Permission Definition**: Administrator defines `orders:read` and `orders:write` permissions. The format `resource:action` clearly identifies what resource and operation is controlled.
- **Role Creation**: Administrator creates "Sales Representative" role and assigns `orders:read` permission. Creates "Sales Manager" role with both `orders:read` and `orders:write` permissions.
- **User Role Assignment**: New sales hire is assigned "Sales Representative" role. User immediately inherits all permissions associated with that role.
- **Role Promotion**: Sales rep promoted to manager. Administrator assigns "Sales Manager" role. User can retain or lose previous role based on business policy.
- **Role Revocation**: User transfers to different department. Administrator revokes current role and assigns appropriate role for new position.
- **Idempotent Assignment**: Assigning the same role to a user twice does not create duplicate assignments or return an error. The operation is idempotent.
- **Inactive User Restriction**: Attempt to assign role to PENDING or INACTIVE user fails. Only ACTIVE users can receive role assignments.

## Test Cases

- Creating a permission with valid key format should succeed
- Permission key must follow `resource:action` format
- Duplicate permission keys should be rejected
- Creating a role with valid name should succeed
- Assigning permission to role should succeed
- Assigning same permission to role twice should be idempotent (no error)
- Revoking permission from role should remove the association
- Assigning role to ACTIVE user should succeed
- Assigning role to PENDING user should fail with USER_NOT_ACTIVE error
- Assigning role to INACTIVE user should fail with USER_NOT_ACTIVE error
- Assigning same role to user twice should be idempotent (no error)
- Revoking role from user should remove the user-role association
- Assigning role to non-existent user should fail with USER_NOT_FOUND error
- Assigning non-existent role to user should fail with ROLE_NOT_FOUND error
- Assigning non-existent permission to role should fail with PERMISSION_NOT_FOUND error

## Reference Links

- [NIST RBAC Model](https://csrc.nist.gov/projects/role-based-access-control)
- [Odoo Access Rights](https://www.odoo.com/documentation/19.0/applications/general/users/access_rights.html)
- [OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html)
