ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
bc906639da
TenantAtlas/specs/064-auth-structure/spec.md
ahmido 210cf5ce8b feat: implement auth structure system panel (#77) 
Implements 064-auth-structure (Auth Structure v1.0):

Adds platform_users + PlatformUser identity (factory + seeder) for platform operators
Introduces platform auth guard/provider in auth.php
Adds a dedicated Filament v5 System panel at system using guard platform (custom login + dashboard)
Enforces strict cross-scope isolation between /admin and system (deny-as-404)
Adds platform capability gating (platform.access_system_panel, platform.use_break_glass) + gates in AuthServiceProvider
Implements audited break-glass mode (enter/exit/expire), banner via render hook, feature flag + TTL config
Removes legacy users.is_platform_superadmin runtime usage and adds an architecture test to prevent regressions
Updates tenant membership pivot usage where needed (tenant_memberships)
Testing:

vendor/bin/sail artisan test --compact tests/Feature/Auth (28 passed)
vendor/bin/sail bin pint --dirty
Notes:

Filament v5 / Livewire v4 compatible.
Panel providers registered in providers.php.
Destructive actions use ->action(...) + ->requiresConfirmation() where applicable.

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@MacBookPro.fritz.box>
Reviewed-on: #77
2026-01-27 21:49:18 +00:00

9.2 KiB
Raw Blame History

Feature Specification: Auth Structure v1.0: Panel & Identity Separation

Feature Branch: 064-auth-structure Created: Tuesday, January 27, 2026 Status: Draft Input: User description: "Spec 064 — Auth Structure v1.0 Panel & Identity Separation..."

User Scenarios & Testing (mandatory)

User Story 1 - Tenant Admin Access (Priority: P1)

A Tenant Administrator needs to securely access their organization's resources. They will log in to the /admin panel using their existing company credentials via Microsoft Entra ID (OIDC). The system must ensure they only see their tenant's data and have no access to platform-level controls.

Why this priority: This is the primary user flow for the application's customers. It must be secure, seamless, and strictly isolated from the platform operations.

Independent Test: Can be tested by attempting to log in with a valid Entra ID account, verifying successful access to /admin/t/{tenant}, and confirming that /system returns a 404 error. This delivers the core value of tenant administration.

Acceptance Scenarios:

  1. Given a user is not authenticated, When they navigate to /admin/login, Then they are presented only with a "Sign in with Microsoft" option.
  2. Given a valid Tenant Admin uses the Microsoft login, When they successfully authenticate, Then they are redirected to their tenant-specific dashboard within the /admin path.
  3. Given an authenticated Tenant Admin, When they attempt to access any /system/* URL, Then they receive a 404 Not Found response.

User Story 2 - Platform Operator Access (Priority: P1)

A Platform Operator needs to manage the overall application and perform system-level tasks. They will log in to the /system panel using a locally stored username and password. Their access is separate from any tenant's identity system.

Why this priority: This flow is critical for system maintenance, operations, and emergency recovery. It guarantees that platform administrators can always access the system, even if a tenant's Entra ID is unavailable.

Independent Test: Can be tested by logging in with a seeded platform_user account, verifying access to the /system dashboard, and confirming that tenant-scoped admin routes (/admin/t/*) return a 404 error.

Acceptance Scenarios:

  1. Given a user is not authenticated, When they navigate to /system/login, Then they are presented with an email and password login form.
  2. Given a valid Platform Operator provides correct credentials, When they log in, Then they are redirected to the /system dashboard.
  3. Given an authenticated Platform Operator, When they attempt to access a tenant-scoped URL like /admin/t/{tenant}/*, Then they receive a 404 Not Found response.

User Story 3 - Break-glass Emergency Recovery (Priority: P2)

A Platform Operator with the appropriate permissions needs to perform an emergency recovery action on a tenant's behalf. They must enter a temporary, audited "break-glass" mode from within the /system panel to gain the necessary (but limited and logged) privileges.

Why this priority: Provides a crucial, secure mechanism for disaster recovery and support, while ensuring such powerful access is explicitly enabled, temporary, and fully audited. It's a safety net, not a primary workflow.

Independent Test: Can be tested by enabling the feature flag, having a privileged Platform Operator start the break-glass session, verifying the persistent banner appears, performing a recovery action, and then exiting the mode. The audit log must reflect all state changes.

Acceptance Scenarios:

  1. Given the BREAK_GLASS_ENABLED flag is true and a Platform Operator has the platform.use_break_glass capability, When they initiate the "Enter break-glass mode" action, Then a persistent banner indicating "Recovery mode active" is displayed on all /system pages.
  2. Given a Platform Operator is in break-glass mode, When the configured TTL expires, Then the break-glass session is automatically terminated, the banner is removed, and an "expired" event is logged.
  3. Given a Platform Operator is in break-glass mode, When they click the "Exit break-glass" button, Then the session is immediately terminated, the banner is removed, and an "exit" event is logged.
  4. Given the BREAK_GLASS_ENABLED flag is false, Then no option to enter break-glass mode is visible in the UI.

Edge Cases

  • What happens if a user's session expires while in break-glass mode? The break-glass state should be cleared along with the regular session.
  • How does the system handle a login attempt for a platform_user whose account is marked as inactive? The login should fail with a generic "invalid credentials" message.
  • What if a backfill migration runs for a users.is_platform_superadmin who already has a platform_user account? It should idempotently add the capabilities without creating a duplicate user.

Requirements (mandatory)

Constitution alignment (required): This feature introduces significant changes to authentication and authorization.

  • Graph Calls: No new direct Graph calls are specified for this core auth structure, but the /admin panel relies on Entra OIDC (from feature 063).
  • Safety Gates: The "break-glass" feature is a critical safety gate itself. It is gated by a feature flag (BREAK_GLASS_ENABLED), requires explicit user action with confirmation, is time-limited (TTL), and produces a detailed audit trail. Tenant recovery actions within this mode are also explicitly audited.
  • Tenant Isolation: This is a primary goal. The spec enforces strict separation via different authentication scopes and routing rules that return 404 for cross-scope access attempts, preventing information leakage.
  • Run Observability: While auth handshakes don't create OperationRuns (OPS-EX-AUTH-001), security-relevant actions MUST create detailed AuditLog entries. This includes platform login attempts (success and failure) and break-glass lifecycle events (enter, exit, expire), including actor, action, outcome, and timestamp.
  • Badge Alignment: Not applicable.

Functional Requirements

  • FR-001: The system MUST provide two separate admin experiences: /admin for Tenants and /system for Platform Operators.
  • FR-002: The /admin experience MUST authenticate tenant admins via Microsoft Entra ID (OIDC).
  • FR-003: The /system experience MUST authenticate platform operators via locally managed credentials stored separately from tenant identities.
  • FR-004: The system MUST implement a "break-glass" mode for privileged platform users, which is disabled by default via a BREAK_GLASS_ENABLED environment variable.
  • FR-005: When active, break-glass mode MUST display a persistent banner on all /system pages and expire automatically after a configurable TTL. All state transitions (start, exit, expiry) MUST be audited.
  • FR-006: The users.is_platform_superadmin database column MUST be deprecated; no new code may use it for authorization checks.
  • FR-007: An authenticated tenant session attempting to access any /system/* route MUST receive a 404 Not Found response.
  • FR-008: An authenticated platform session attempting to access any tenant-scoped /admin/t/{tenant}/* route MUST receive a 404 Not Found response.
  • FR-009: The system MUST provide a capability-based authorization system for platform users (e.g., platform.access_system_panel, platform.use_break_glass).
  • FR-010: The login page at /admin/login MUST NOT contain password fields or links related to local auth or break-glass.
  • FR-011: All platform login attempts (success and failure) and break-glass lifecycle events MUST be recorded in an audit log.

Key Entities

  • PlatformUser: Represents a platform operator with local credentials. Attributes include name, email, hashed password, and a list of capabilities. It is distinct from the tenant user identity.
  • Break-glass Session: A temporary, elevated session state for a PlatformUser, not a database entity. It is managed via session state that tracks the expiry time, the initiating actor, and an operator-provided reason.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: 100% of authentication attempts to the /admin panel are routed through the Entra OIDC flow.
  • SC-002: 100% of authentication attempts to the /system panel are routed through the local platform_users provider.
  • SC-003: 0% of authenticated users from one panel can successfully access scoped resource pages in the other panel (verified by 404 responses).
  • SC-004: When break-glass mode is activated, a persistent visual indicator is present on 100% of /system pages until the session is terminated (manually or by TTL).
  • SC-005: All break-glass session activations, expirations, and manual exits are logged, with 100% of events recorded in the audit trail.
  • SC-006: Code coverage for the new authentication guards, middleware, and platform authorization gates is at or above 80%.
  • SC-006: Automated test coverage for the authentication separation and break-glass flows is at or above 80%.