TenantAtlas/specs/063-entra-signin/spec.md

Feature Specification: 063 — Entra Sign-in (Tenant Panel) v1

Feature Branch: 063-entra-signin Created: 2026-01-26 Status: Draft (v1) Scope: Tenant Admin panel (/admin) sign-in only

Context / Goal

TenantAtlas needs a clean, enterprise-grade sign-in flow for the Tenant Admin panel (/admin) using Microsoft Entra ID (OIDC).

This feature MUST:

• provide Entra-only login UX on /admin/login
• upsert tenant users safely keyed by (entra_tenant_id, entra_object_id)
• route users after login based on tenant memberships
• keep pages DB-only at render time
• log safely (no tokens/claims dumps)

This feature intentionally does not change platform/operator access (/system) or break-glass behavior; those belong to Feature 064-auth-structure.

Clarifications

Session 2026-01-26

• Q: For a user belonging to multiple tenants, what should happen immediately after they sign in? → A: Redirect to a dedicated, full-screen "tenant chooser" page that lists all their memberships. The user must click one to proceed to the main dashboard.
• Q: If a user record exists in a disabled state (e.g., deleted_at is not null, or an is_active flag is false), and that user completes a valid Entra ID sign-in, what should happen? → A: Block the login. Redirect the user to the login page with a generic error message (e.g., "Your account is disabled. Please contact an administrator.").
• Q: What should be the maximum character length for the users.entra_tenant_id and users.entra_object_id columns in the database schema? → A: VARCHAR(36). Both Entra Tenant IDs and Object IDs are GUIDs, which have a standard fixed length of 36 characters.

---

Existing System Compatibility (important)

The repository already contains:

• A System Panel at /system using guard platform and platform_users (platform operator access).
• Break-glass recovery mechanics for platform operators (banner/middleware/routes).
• Tenant membership storage using a pivot table (tenant_user or equivalent) with role values via TenantRole enum.

Compatibility constraints for 063

• 063 MUST NOT modify /system panel, platform guards, platform users, or break-glass routes/UX.
• 063 MUST NOT refactor tenant RBAC data model or enforcement. It may only read memberships to decide where to redirect after login.
• 063 MUST NOT introduce Graph calls (or any outbound HTTP) during render/poll/hydration of /admin pages.

---

Non-Goals (explicit)

• No Platform Operator /system login implementation (already exists or handled elsewhere).
• No break-glass UX on /admin/login.
• No tenant RBAC redesign or role enforcement changes (assume memberships already exist).
• No Graph calls or remote work in login render/poll/hydration.
• No storing of Entra access/refresh tokens.
• No queue/worker dependence for login (login is synchronous request/response).

---

User Scenarios & Testing (mandatory)

User Story 1 — Entra-only login UI on /admin/login (Priority: P1)

A tenant user can only start Microsoft sign-in from /admin/login.

Acceptance Scenarios

1. Given I open /admin/login, then I see only “Sign in with Microsoft” and no email/password fields.
2. Given Entra config is missing/invalid, /admin/login still renders and shows a generic message (no secrets).

Independent Test

• Render /admin/login and assert no password inputs exist.

---

User Story 2 — OIDC callback upserts tenant identity safely (Priority: P1)

The callback upserts a tenant user using Entra claims.

Acceptance Scenarios

1. Given Entra callback includes tid and oid, when sign-in completes, then users is upserted keyed by:
   • entra_tenant_id = tid
   • entra_object_id = oid
2. Given sign-in succeeds, then the session is regenerated.
3. Given callback is missing tid or oid, then redirect to /admin/login with a generic error.
4. Given a user exists but is disabled (soft-deleted), when they complete a valid sign-in, then they are redirected to /admin/login with a generic error.

Independent Test

• Fake a callback payload and assert (tid, oid) uniqueness is enforced.

---

User Story 3 — Post-login routing is membership-based (Priority: P1)

After login, routing depends on Suite tenant memberships.

Acceptance Scenarios

1. Given I have 0 memberships, then redirect to /admin/no-access.
2. Given I have exactly 1 membership, then redirect into that tenant’s dashboard.
3. Given I have >1 memberships, then redirect to a dedicated, full-screen tenant chooser page.

Independent Test

• Seed memberships and assert each redirect path.

---

User Story 4 — Filament-native “No access” page (Priority: P2)

Users without memberships get a safe, Filament-native page.

Acceptance Scenarios

1. Given I have 0 memberships, /admin/no-access renders using Filament UI (no raw HTML pages).
2. The page does not leak internal details; it provides next steps (“Ask an admin to add you”).

---

Requirements (mandatory)

Functional Requirements

• FR-001: /admin/login MUST be Entra-only (no password login form).
• FR-002: Tenant user upsert MUST be keyed by (entra_tenant_id, entra_object_id) and MUST NOT store Entra access/refresh tokens.
• FR-003: Post-login routing MUST be based on memberships:
  • 0 → /admin/no-access
  • 1 → tenant dashboard
  • N → dedicated tenant chooser page
• FR-004: OIDC failures MUST be handled safely:
  • redirect to /admin/login with generic error
  • log stable reason_code + correlation_id
  • never log token/claims payloads
• FR-005: Logging MUST be privacy-safe:
  • success: minimal (user_id, tid, oid hash, timestamp, correlation_id)
  • failure: reason_code, correlation_id, minimal diagnostics
• FR-006: /admin/login and /admin/no-access MUST be DB-only at render time (no outbound HTTP).
• FR-007: 063 MUST NOT surface break-glass links or platform login UX on /admin/login.
• FR-008: Session separation MUST prevent implicit crossover:
  • a tenant session MUST NOT grant access to /system
  • a platform session MUST NOT grant access to /admin tenant membership routes (Implementation is via separate guards/panels; 063 only asserts behavior via tests.)
• FR-009: Login flow MUST NOT require queue workers; it must complete synchronously.
• FR-010: If a user record exists but is in a disabled or soft-deleted state, a successful Entra ID authentication MUST be blocked, and the user redirected to the login page with a generic error.

Non-Functional Requirements (NFR)

• NFR-01 (Security): Do not persist secrets/tokens. Sanitize all error output and logs.
• NFR-02 (Stability): Callback is idempotent; safe to retry without creating duplicates.
• NFR-03 (Performance): Callback returns within ~2s under normal conditions.
• NFR-04 (Maintainability): Minimal diff; do not refactor membership/RBAC models.

---

Data Model

Uses existing users table. Required columns:

• entra_tenant_id (string)
• entra_object_id (string)
• name (string)
• email (nullable)

Index

• Unique index on (entra_tenant_id, entra_object_id).

Optional (if already present / needed later):

• last_tenant_id (nullable FK to tenants.id) to optimize redirect for multi-membership users.

No new tables required.

Routes / UI Surfaces

• /admin/login — Filament login override (Entra-only CTA)
• /auth/entra/redirect — starts OIDC redirect (Socialite)
• /auth/entra/callback — handles callback, upsert, routing
• /admin/no-access — Filament page for 0-membership users
• /admin/choose-tenant — Filament page for N-membership users to select a tenant

---

OIDC Handling & Failure Semantics

Claims requirements

• tid (tenant id) MUST be present.
• oid (object id) MUST be present. If missing → fail safely.

Generic user-facing error

• “Authentication failed. Please try again.”

Server-side logging

Log event auth.entra.login with:

• success: boolean
• reason_code: string (on failure)
• user_id: (on success)
• entra_tenant_id: tid (or hashed)
• entra_object_id_hash: hash(oid)
• correlation_id: request id or session id
• timestamp

Reason code examples (stable)

• oidc_missing_claims
• oidc_invalid_state
• oidc_user_denied
• oidc_provider_unavailable
• oidc_user_upsert_failed
• user_disabled

---

Implementation Guardrails (hard)

• Do not implement a password login form for /admin.
• Do not call $this->form->fill() with default creds.
• Do not show break-glass link/button on /admin/login.
• Do not modify /system panel, platform guards, or break-glass logic.
• Do not refactor User::tenants() or membership schema; use a small resolver/service to decide redirect.
• Do not make outbound HTTP during render/poll/hydration of /admin pages.
• Do not store raw claims or tokens.

---

Acceptance Tests (required)

Feature tests (Pest)

1. AdminLoginIsEntraOnlyTest
   • GET /admin/login contains Microsoft CTA
   • asserts no password input / no local login form
2. EntraCallbackUpsertByTidOidTest
   • callback upserts user by (tid, oid) (unique)
   • session is regenerated
3. PostLoginRoutingByMembershipTest
   • 0 memberships → /admin/no-access
   • 1 membership → tenant dashboard
   • N memberships → chooser page
4. OidcFailureRedirectsSafelyTest
   • missing tid/oid → redirect /admin/login
   • logs contain reason_code + correlation_id
   • logs do not contain tokens/claims dumps
5. SessionSeparationSmokeTest
   • tenant session cannot access /system
   • platform session cannot access tenant membership routes without membership
6. DisabledUserLoginIsBlockedTest
   • Seed a disabled/soft-deleted user
   • Fake a successful OIDC callback for that user
   • Assert redirect to /admin/login
   • Assert log contains reason_code: user_disabled

Quality gate

• ./vendor/bin/sail php ./vendor/bin/pint --dirty
• ./vendor/bin/sail artisan test tests/Feature/Auth --stop-on-failure

---

Manual Verification Checklist

1. Open /admin/login - only Microsoft sign-in CTA visible
2. Complete Entra sign-in - user record exists with tid/oid
3. 0 memberships → /admin/no-access
4. 1 membership → tenant dashboard

5. 1 memberships → chooser page

6. Verify logs:
   • failures show reason_code + correlation_id
   • no tokens/claims in logs

---

Out of Scope / Follow-ups

• 064-auth-structure: /system operator login hardening, break-glass UX, panel separation governance.
• 062-tenant-rbac-v1: role enforcement audit + resource-by-resource authorization hardening.
• Advanced Entra topics (v2+): delegated flows, refresh token storage, certificate auth, conditional access UI.