TenantAtlas/specs/068-workspace-foundation-v1/spec.md

Feature Specification: Workspace Foundation & Managed Tenant Onboarding Unification (v1)

Feature Branch: 068-workspace-foundation-v1
Created: 2026-01-31
Status: Draft
Input: Consolidate Managed Tenant onboarding and routing into a single admin “front door”, remove tenant-in-tenant patterns, and standardize RBAC UX semantics for Managed Tenant flows.

Clarifications

Session 2026-01-31

• Q: Should tenant_managed_tenants.open be a separate capability? → A: No. “Open” is allowed whenever tenant_managed_tenants.view is allowed.
• Q: What is the canonical destination for “Open” (for an active managed tenant) in v1? → A: A stable tenantless landing page in the admin area (e.g. /admin/managed-tenants/current) that shows the selected managed tenant, with the selection stored in session.
• Q: Where should the “current managed tenant” selection be stored in v1? → A: Session-only.
• Q: What should be the canonical onboarding URL/path in v1? → A: /admin/managed-tenants/onboarding.
• Q: For archived/deactivated tenants, should “View” always be allowed for viewers? → A: Yes. Archived tenants remain viewable for users with tenant_managed_tenants.view.

User Scenarios & Testing (mandatory)

User Story 1 - Add managed tenant via single front door (Priority: P1)

As an admin user, I can add a new managed tenant through one clearly labeled entry point (“Add managed tenant”), so there is no ambiguity about where onboarding begins.

Why this priority: This removes the current confusion and is the prerequisite for a future wizard-based onboarding experience.

Independent Test: Can be fully tested by verifying only one visible “Add managed tenant” entry exists, and legacy direct URLs redirect to the canonical onboarding screen.

Acceptance Scenarios:

1. Given I can access the admin panel, When I look for a way to add a managed tenant, Then there is exactly one visible entry point labeled “Add managed tenant”.
2. Given I open a legacy onboarding URL directly (e.g., the previously used “/admin/new”), When the page loads, Then I am redirected to the canonical onboarding screen.

---

User Story 2 - Manage tenants without tenant-in-tenant navigation (Priority: P2)

As an admin user, I can list, view, and manage managed tenants in a tenantless admin area, so the system does not require an already-selected tenant context to manage tenants.

Why this priority: Eliminates tenant-in-tenant logic and removes a large source of inconsistent access/404 semantics.

Independent Test: Can be fully tested by verifying there is a tenantless managed-tenant listing and that links/routes do not require any “current tenant” parameter.

Acceptance Scenarios:

1. Given I have access to the admin panel, When I navigate to the managed tenants list, Then the list loads without requiring a pre-selected tenant context.
2. Given I open any managed-tenant detail screen via URL, When the page loads, Then the URL does not include a “current tenant” path prefix.

---

User Story 3 - Open an active tenant context and handle archived tenants safely (Priority: P3)

As an admin user, I can “Open” a managed tenant to work within its context, and if a managed tenant is archived/deactivated I get a clear status screen instead of a broken experience.

Why this priority: Prevents confusing 404s and ensures consistent, safe operations as tenants change lifecycle state.

Independent Test: Can be fully tested by verifying “Open” is deterministic for active tenants, and for archived tenants it shows a status screen with only allowed actions.

Acceptance Scenarios:

1. Given a managed tenant is active and I am allowed to open it, When I click “Open”, Then I land on a stable tenantless screen that clearly indicates which managed tenant is selected.
2. Given a managed tenant is archived/deactivated, When I click “Open”, Then I see a status screen explaining the tenant is archived (not a 404).
3. Given a managed tenant is archived/deactivated and I do not have permission to restore or force delete it, When I view the status screen, Then those actions are not executable.

---

Edge Cases

• Attempting to access managed-tenant screens as a non-member of the tenant-plane scope.
• Attempting to execute a mutation (create/edit/archive/restore/delete) without the necessary capability.
• A managed tenant transitions to archived/deactivated while a user has an open browser tab.
• Legacy deep links to the old tenant-scoped managed-tenant routes.
• A user opens the admin panel with no “current managed tenant” selected yet.

Requirements (mandatory)

Constitution alignment (required): If this feature introduces any Microsoft Graph calls, any write/change behavior, or any long-running/queued/scheduled work, the spec MUST describe contract registry updates, safety gates (preview/confirmation/audit), tenant isolation, run observability (OperationRun type/identity/visibility), and tests. If security-relevant DB-only actions intentionally skip OperationRun, the spec MUST describe AuditLog entries.

Constitution alignment (RBAC-UX): If this feature introduces or changes authorization behavior, the spec MUST:

• state which authorization plane(s) are involved (tenant /admin/t/{tenant} vs platform /system),
• ensure any cross-plane access is deny-as-not-found (404),
• explicitly define 404 vs 403 semantics:
  • non-member / not entitled to tenant scope → 404 (deny-as-not-found)
  • member but missing capability → 403
• describe how authorization is enforced server-side (Gates/Policies) for every mutation/operation-start/credential change,
• reference the canonical capability registry (no raw capability strings; no role-string checks in feature code),
• ensure global search is tenant-scoped and non-member-safe (no hints; inaccessible results treated as 404 semantics),
• ensure destructive-like actions require confirmation (->requiresConfirmation()),
• include at least one positive and one negative authorization test, and note any RBAC regression tests added/updated.

Constitution alignment (OPS-EX-AUTH-001): OIDC/SAML login handshakes may perform synchronous outbound HTTP (e.g., token exchange) on /auth/* endpoints without an OperationRun. This MUST NOT be used for Monitoring/Operations pages.

Constitution alignment (BADGE-001): If this feature changes status-like badges (status/outcome/severity/risk/availability/boolean), the spec MUST describe how badge semantics stay centralized (no ad-hoc mappings) and which tests cover any new/changed values.

Functional Requirements

Scope, Definitions, Non-goals

• FR-001 (Scope / Plane): The feature MUST apply only to the admin tenant-plane area and MUST NOT change platform/system-plane behavior.
• FR-002 (Terminology): The UI MUST use the term “Managed tenant” (or an equivalent unambiguous label) in places where “Tenant” could be confused with a workspace or platform tenant concept.
• FR-003 (Non-goals enforced): This version MUST NOT introduce a wizard/stepper onboarding UI, a new workspace membership model, or a provider/credentials architecture refactor.

Single Front Door

• FR-004 (Canonical onboarding entry): The system MUST provide exactly one visible UI entry point to start managed-tenant onboarding (“Add managed tenant”), leading to a canonical onboarding screen.
• FR-004a (Canonical onboarding path): The canonical onboarding screen MUST be reachable at /admin/managed-tenants/onboarding.
• FR-005 (Legacy entry points): Legacy onboarding entry points MUST be removed from navigation/buttons, or MUST redirect to the canonical onboarding screen.
• FR-006 (Direct URL behavior): Direct requests to the legacy onboarding URL (previously used “/admin/new”) MUST redirect to the canonical onboarding screen.

Tenantless Managed Tenants Area (No tenant-in-tenant)

• FR-007 (Tenantless routes): Listing, viewing, and editing managed tenants MUST be available without requiring a “current tenant” context in the URL.
• FR-008 (No tenant-in-tenant): Managed-tenant management MUST NOT appear under a tenant-scoped URL structure (e.g., MUST NOT require “/t/{currentTenant}/…” style path segments).

“Open” vs “Switch” semantics

• FR-009 (Open semantics): “Open” on a managed tenant MUST mean “enter this managed tenant’s context within the admin area”, not “switch workspaces”.
• FR-010 (Deterministic destination): “Open” MUST take the user to a stable, deterministic destination that clearly indicates the selected managed tenant.
• FR-011 (No tenant-in-tenant link generation): Links used for “Open” MUST NOT rely on a tenant-scoped routing prefix.
• FR-011a (Open authorization): “Open” MUST be authorized by tenant_managed_tenants.view in v1 (no separate “open” capability).
• FR-011b (Open destination): In v1, “Open” MUST navigate to a stable tenantless destination in the admin area (e.g. /admin/managed-tenants/current), using a session-based “current managed tenant” selection.
• FR-011c (Selection storage): In v1, the “current managed tenant” selection MUST be stored in server-side session (no required DB persistence).

Archived / Deactivated Managed Tenants UX

• FR-012 (Archived view access): Archived/deactivated managed tenants MUST remain viewable (read-only) for users authorized by tenant_managed_tenants.view.
• FR-012a (No 404 for viewers): Archived/deactivated managed tenants MUST NOT present a “not found” experience solely due to being archived/deactivated when the user is authorized to view managed tenants.
• FR-013 (Archived open behavior): “Open” on an archived/deactivated managed tenant MUST NOT result in a “not found” experience; it MUST show a dedicated status screen explaining the tenant is archived/deactivated.
• FR-014 (Archived actions): The archived/deactivated status screen MUST present only actions that are allowed for the current user (e.g., restore, force delete), and MUST prevent execution when not allowed.

RBAC UX and Enforcement

• FR-015 (404 vs 403 semantics): Authorization behavior MUST follow these rules:
  • Non-member / not entitled to tenant-plane scope → treated as “not found” in user experience.
  • Member but missing capability → forbidden (action visible but disabled where appropriate; execution prevented).
• FR-016 (Consistent UI affordances): In managed-tenant flows, actions MUST consistently follow these UX rules:
  • Non-member: action not shown and not executable.
  • Member without capability: action visible but disabled with an explanatory tooltip; not executable.
  • Member with capability: action enabled.
• FR-017 (Server-side defense-in-depth): All mutations and operation-start actions in the managed-tenant area MUST be rejected server-side when the user lacks authorization.

Capabilities (Canonical)

• FR-018 (Capability registry): Managed-tenant functionality MUST be controlled via canonical capabilities (no ad-hoc permission checks).
• FR-019 (Minimal capabilities set): The system MUST define, at minimum, the following capabilities (names are canonical):
  • tenant_managed_tenants.view
  • tenant_managed_tenants.create
  • tenant_managed_tenants.manage
  • tenant_managed_tenants.archive
  • tenant_managed_tenants.restore
  • tenant_managed_tenants.force_delete
• FR-020 (Default role mapping): Default role-to-capability mapping MUST align with:
  • Owner/Manager: all managed-tenant capabilities.
  • Operator: view (includes “Open”) and tenant-context operations where permitted; not create/manage/archive/force delete.
  • Readonly: view only.

Backwards Compatibility

• FR-021 (Redirect compatibility): Legacy managed-tenant entry points and legacy deep links MUST redirect to the new tenantless managed-tenant area when reachable.
• FR-022 (No data loss): The feature MUST NOT delete or irreversibly modify existing managed-tenant data.

Acceptance Criteria Summary

• Exactly one visible “Add managed tenant” entry exists in the admin UI.
• Direct requests to the legacy onboarding URL redirect to the canonical onboarding screen.
• Managed-tenant management is available without any “current tenant” path prefix.
• “Open” leads to a stable tenant-context destination for active managed tenants.
• “Open” for archived/deactivated managed tenants shows a dedicated status screen (not “not found”).
• Authorization outcomes match the defined 404-vs-403 semantics and actions are never executable without the required capability.
• The canonical managed-tenant capabilities exist and role mapping matches the default expectations.
• No managed-tenant data is deleted or irreversibly changed by this feature.

Assumptions & Dependencies

• A managed tenant entity already exists with a lifecycle indicator (active vs archived/deactivated) that can be used to drive UX decisions.
• The admin interface can represent a “current managed tenant” selection (even if it is not persisted long-term in v1).
• In v1, the selection is session-only (not stored in the database).
• A canonical capability registry exists (or can be extended) to hold the managed-tenant capabilities.
• Legacy deep links may exist in bookmarks and documentation and therefore must remain reachable via redirects.

Key Entities (include if feature involves data)

• Workspace (v1 minimal): An organizational container in the admin interface used to structure managed-tenant management. In v1 it is a routing/UI concept and does not introduce a new membership model.
• Managed Tenant: A Microsoft Entra/Intune tenant managed by the product, including identity, consent/connection state, and lifecycle state (active vs archived/deactivated).
• Tenant Context (admin): The “current selection” of a managed tenant that determines what data/actions the admin interface displays.
• Capability: A permission unit used to allow/deny actions and UI affordances for managed-tenant flows.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001 (Single entry point): 100% of visible “add managed tenant” journeys originate from the single canonical entry point (no second visible onboarding CTA in the admin UI).
• SC-002 (No tenant-in-tenant): 0 managed-tenant CRUD routes require a “current tenant” path prefix.
• SC-003 (Archived UX): 100% of attempts to “Open” an archived/deactivated managed tenant result in a defined status screen (never a “not found” experience for authorized viewers).
• SC-004 (RBAC semantics): For managed-tenant flows, authorization outcomes are consistent and testable: non-members receive “not found” experience, members without capability are blocked from execution.
• SC-005 (Task completion): A user with the appropriate capability can start managed-tenant onboarding and reach the onboarding screen successfully on the first attempt in under 30 seconds.