3b1dd98f52
This commit introduces a comprehensive Role-Based Access Control (RBAC) system for TenantAtlas. - Implements authentication via Microsoft Entra ID (OIDC). - Manages authorization on a per-Suite-Tenant basis using a table. - Follows a capabilities-first approach, using Gates and Policies. - Includes a break-glass mechanism for platform superadmins. - Adds policies for bootstrapping tenants and managing admin responsibilities.
104 lines
4.0 KiB
Markdown
104 lines
4.0 KiB
Markdown
# Implementation Plan: Tenant RBAC v1
|
|
|
|
**Branch**: `062-tenant-rbac-v1` | **Date**: 2026-01-25 | **Spec**: [specs/062-tenant-rbac-v1/spec.md](specs/062-tenant-rbac-v1/spec.md)
|
|
**Input**: Feature specification from `specs/062-tenant-rbac-v1/spec.md`
|
|
|
|
## Summary
|
|
|
|
This feature introduces a comprehensive Role-Based Access Control (RBAC) system for TenantAtlas. It leverages Microsoft Entra ID for authentication and manages authorization on a per-Suite-Tenant basis. The core of this feature is the `tenant_memberships` table, which will be the source of truth for authorization. The implementation will follow a capabilities-first approach, where permissions are checked using Gates and Policies rather than direct role comparisons.
|
|
|
|
### Clarifications
|
|
- No Entra user credentials are stored; only the dedicated break-glass platform superadmin may have local credentials.
|
|
- All access control decisions must be auditable.
|
|
- Non-member access to tenant-scoped routes (including direct `/t/{tenant}` URLs) MUST be deny-as-not-found (404).
|
|
- A canonical capability registry (e.g., `app/Support/Auth/Capabilities.php` or an enum) will be the source of truth. Role → capability mapping MUST reference only registry entries; tests must fail if unknown capabilities are used.
|
|
- Audit action_ids will be standardized:
|
|
- `tenant_membership.add`
|
|
- `tenant_membership.role_change`
|
|
- `tenant_membership.remove`
|
|
- `tenant_membership.bootstrap_assign`
|
|
- `tenant_membership.bootstrap_recover`
|
|
- `tenant_role_mapping.create`
|
|
- `tenant_role_mapping.update`
|
|
- `tenant_role_mapping.delete`
|
|
- The system MUST prevent removing or demoting the last remaining `owner` membership for a Suite Tenant.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: PHP 8.4
|
|
**Primary Dependencies**: Laravel 12, Filament v5, Livewire v4
|
|
**Storage**: PostgreSQL
|
|
**Testing**: Pest
|
|
**Target Platform**: Web
|
|
**Project Type**: Web Application
|
|
**Performance Goals**:
|
|
- User login and tenant selection should be completed in under 3 seconds.
|
|
- Membership changes should be reflected in under 2 seconds.
|
|
- Audit log entries should be created in under 1 second.
|
|
**Constraints**:
|
|
- No Entra user credentials are stored; only the dedicated break-glass platform superadmin may have local credentials.
|
|
- All access control decisions must be auditable.
|
|
**Scale/Scope**:
|
|
- The system should be designed to handle up to 1,000 tenants and 10,000 users.
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- **Inventory-first**: Not directly applicable.
|
|
- **Read/write separation**: **PASS**.
|
|
- **Graph contract path**: **PASS**.
|
|
- **Deterministic capabilities**: **PASS**.
|
|
- **Tenant isolation**: **PASS**.
|
|
- **Run observability**: **PASS**.
|
|
- **Automation**: **PASS**.
|
|
- **Data minimization**: **PASS**.
|
|
- **Badge semantics (BADGE-001)**: Not applicable.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/062-tenant-rbac-v1/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0 output
|
|
├── data-model.md # Phase 1 output
|
|
├── quickstart.md # Phase 1 output
|
|
├── contracts/ # Phase 1 output
|
|
└── tasks.md # Phase 2 output
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
app/
|
|
├── Models/
|
|
│ ├── User.php
|
|
│ ├── Tenant.php
|
|
│ ├── TenantMembership.php
|
|
│ └── TenantRoleMapping.php
|
|
├── Policies/
|
|
│ └── TenantMembershipPolicy.php
|
|
├── Providers/
|
|
│ └── AuthServiceProvider.php
|
|
└── Support/
|
|
└── Auth/
|
|
└── Capabilities.php
|
|
database/
|
|
└── migrations/
|
|
├── XXXX_XX_XX_XXXXXX_create_tenant_memberships_table.php
|
|
└── XXXX_XX_XX_XXXXXX_create_tenant_role_mappings_table.php
|
|
routes/
|
|
└── web.php
|
|
tests/
|
|
└── Feature/
|
|
└── TenantRBAC.php
|
|
```
|
|
|
|
**Structure Decision**: The project is a standard Laravel application. New files will be created in the appropriate directories.
|
|
|
|
## Complexity Tracking
|
|
|
|
No violations to the constitution.
|