# Feature Specification: Managed Tenant Onboarding Wizard v1 **Feature Branch**: `069-managed-tenant-onboarding-wizard` **Created**: 2026-01-31 **Status**: Draft **Input**: User description: "Spec 069 — Managed Tenant Onboarding Wizard v1 (Single Front Door, DB-only render, enqueue-only runs, resumable onboarding session, RBAC-UX enforcement, remove legacy entry points)." ## Clarifications ### Session 2026-01-31 - Q: Do we need to store local app credentials (client_id/client_secret) for Managed Tenants in v1? → A: Conditional — Step 3 only when a config/driver says “credentials required”. - Q: When a user is a workspace member but lacks a capability and tries the action/server endpoint, what should the server return? → A: 403 Forbidden. - Q: For the legacy URL /admin/new (old managed tenant create entry), where should it redirect? → A: Redirect to “Choose workspace” (then start wizard from there). - Q: Who is allowed to resume an existing onboarding session for a Managed Tenant? → A: Any workspace member with `managed_tenants.create` (and tenant-scoped access). - Q: If a user starts the wizard again for the same workspace + tenant ID while an active onboarding session already exists, what should happen? → A: Auto-resume the existing active session. ## Terminology (Repository Mapping) - In this repository, the spec’s term **Workspace** maps to the existing **Tenant** concept (tenant-plane container + memberships). - Capability names shown in this spec (e.g. `managed_tenants.create`) are **conceptual** for stakeholders; implementation MUST map them onto the canonical capability registry and MUST NOT introduce new raw capability strings in feature code. ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Onboard a managed tenant end-to-end (Priority: P1) As a workspace Owner, I can onboard a new Managed Tenant through a consistent, guided wizard so onboarding is repeatable and results in a tenant that is ready to run verification/health operations. **Why this priority**: This is the primary business outcome: reliable onboarding and operational readiness. **Independent Test**: Can be fully tested by completing the wizard and observing that the system marks onboarding complete and allows runs to be started. **Acceptance Scenarios**: 1. **Given** a user is a workspace Owner and no Managed Tenant exists for the target tenant ID, **When** they start the wizard and complete the steps, **Then** a Managed Tenant record exists and onboarding is marked complete. 2. **Given** a user started onboarding and leaves mid-way, **When** they return, **Then** they can resume the wizard at the last completed step with their previously entered (non-secret) data. 3. **Given** a Managed Tenant already exists in the workspace with the same tenant ID, **When** the user enters that tenant ID, **Then** the wizard prevents creating a duplicate and guides the user to the existing tenant's onboarding/resume state. --- ### User Story 2 - Run verification checks without blocking page loads (Priority: P2) As an authorized operator, I can trigger verification/health operations for a Managed Tenant so the system checks permissions and connectivity without performing external calls during page rendering. **Why this priority**: Operational safety and predictability; the UI must remain responsive and all outbound work must be observable. **Independent Test**: Can be tested by loading wizard steps (no outbound activity on render) and then triggering a verification action that creates a run. **Acceptance Scenarios**: 1. **Given** a Managed Tenant is in onboarding, **When** the user clicks “Verify permissions”, **Then** a background run is queued and the page does not perform synchronous external calls. 2. **Given** the last verification run reported missing permissions, **When** the user visits the permissions step, **Then** they see the stored “Granted/Missing” status from the last run. --- ### User Story 3 - RBAC-UX enforcement and safe access semantics (Priority: P3) As a tenant-plane user, I can only see and interact with wizard and tenant actions I am entitled to, with deny-as-not-found for non-members and server-side enforcement for every action. **Why this priority**: Prevents information leakage across tenants/workspaces and ensures policy-compliant enforcement. **Independent Test**: Can be tested by attempting to access the wizard as a non-member, and as a member lacking specific capabilities. **Acceptance Scenarios**: 1. **Given** a user is not a member of the workspace scope, **When** they attempt to access the onboarding wizard or tenant pages, **Then** they receive a 404 response (deny-as-not-found). 2. **Given** a user is a member but lacks the relevant capability, **When** they view the wizard step, **Then** restricted actions are disabled with an explanatory tooltip and server-side attempts are rejected with 403. --- ### Edge Cases - Invalid tenant ID format entered (not a UUID/GUID). - Attempt to create a second Managed Tenant with the same tenant ID within the same workspace. - Two users start onboarding the same Managed Tenant concurrently. - A user loses membership/capabilities while an onboarding session is in progress. - Verification run fails (transient error) and surfaces a stored error code/status without breaking page rendering. - Credentials are required but not yet set; wizard shows “missing” state. - Credentials were set previously; wizard shows “set” state without revealing secret values. ## 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 (Forbidden) - 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. ### Assumptions & Dependencies - Depends on the existing workspace + managed tenant foundations from Spec 068 v2 (including canonical naming and tenant-plane routing). - The onboarding wizard lives in the tenant-plane admin area (not the platform/system area). - Credential capture is required only if the product uses local credentials for managed tenants; otherwise that step is skipped/hidden. - A single configuration/driver flag determines whether credentials are required for the current environment. - Permission/connection status displayed in the wizard is based on stored results from the latest completed verification run. ### Functional Requirements - **FR-001 (Single Front Door)**: The system MUST allow creation of a new Managed Tenant only via the onboarding wizard. - **FR-002 (Disable Legacy Entry Points)**: The system MUST remove or disable all previous “Add Tenant/Create” entry points and MUST redirect any legacy creation URLs to an onboarding-appropriate destination. - **FR-002a (Legacy /admin/new Redirect)**: Requests to `/admin/new` MUST NOT create a managed tenant and MUST redirect to the “Choose workspace” entry point. - **FR-003 (DB-only Render)**: Loading any wizard step MUST NOT trigger outbound HTTP calls; step pages MUST render exclusively from persisted data (including latest known run results). - **FR-004 (Wizard Steps)**: The wizard MUST provide 5 steps: (1) Welcome/Requirements, (2) Tenant Details, (3) App/Credentials Setup (when applicable), (4) Admin Consent & Permissions, (5) Verification / First Run. - **FR-005 (Tenant Details Validation)**: The wizard MUST require a tenant ID (UUID/GUID) and validate its format. - **FR-005a (Tenant Details Fields)**: The tenant details step MUST capture: display name, tenant ID (required), optional domain, and an environment label (dev/staging/prod/other). - **FR-006 (Uniqueness)**: The system MUST prevent duplicates by enforcing uniqueness of Managed Tenant by `(workspace, tenant ID)`. - **FR-007 (Onboarding State)**: The system MUST track onboarding state per Managed Tenant and set initial state to “onboarding” when created/updated via the wizard. - **FR-008 (Credentials - Optional Step)**: If the product requires local credentials for managed tenants, the wizard MUST support setting them as part of onboarding. If not required, the wizard MUST skip this step. - **FR-008b (Credentials Decision Rule)**: The wizard MUST decide whether to include the credentials step based on a single configuration/driver rule (no ad-hoc per-page checks). - **FR-008a (Credential Fields)**: When the credentials step is applicable, it MUST allow setting a client identifier and a client secret, and MAY allow optional labeling/notes without exposing secret values. - **FR-009 (Credentials Security)**: When credentials are used, the system MUST store secrets encrypted at rest and MUST never display secret values after they are saved; the UI MUST only show “secret set” vs “missing”. - **FR-010 (Credentials RBAC)**: Only users with “manage” capability for managed tenants MUST be allowed to set/rotate credentials. - **FR-011 (Runs Canonical / Enqueue-only)**: “Verify permissions”, “Check connection”, and optional “Run inventory sync” MUST enqueue background runs and MUST NOT perform external calls synchronously. - **FR-012 (Admin Consent & Permissions UX)**: The permissions step MUST show a required permissions list, MUST display “Granted/Missing” derived from the latest completed verification run, and MUST provide a link for administrators to grant consent. - **FR-013 (Resume / Session Persistence)**: The system MUST persist onboarding sessions and allow users to resume an in-progress onboarding flow; persisted session payload MUST exclude secrets. - **FR-014 (Session Dedupe)**: The system MUST ensure at most one active onboarding session exists per Managed Tenant and deduplicate accordingly. - **FR-014a (Session Dedupe Behavior)**: When a user attempts to start onboarding for a tenant with an existing active session, the system MUST reuse that session and route the user to resume it. - **FR-015 (Completion Criteria)**: The wizard MUST mark onboarding “complete” when the Managed Tenant exists, required credentials (if applicable) are present, and the permissions verification is successful. - **FR-016 (Resume Link)**: The Managed Tenant view MUST show a “Resume wizard” entry point when onboarding is not complete. - **FR-016a (Resume Authorization)**: Resuming an onboarding session MUST be allowed for any workspace member who has `managed_tenants.create` within that workspace scope. - **FR-017 (Capabilities v1)**: The system MUST support these minimum capabilities: managed_tenants.create (start wizard), managed_tenants.manage (credentials/edit), managed_tenants.view, operations.run (start verify/health/inventory runs). ### Key Entities *(include if feature involves data)* - **Workspace**: Customer/organization container; owns Managed Tenants; defines membership scope. - **Managed Tenant**: A Microsoft/Entra/Intune tenant managed within a workspace; identified by a tenant ID; includes onboarding state and metadata (display name, optional domain, environment label). - **Onboarding Session**: A resumable onboarding state container with: workspace, optional managed tenant reference, creator, status (draft/in progress/completed/abandoned), current step, non-secret payload, last error code, timestamps. - **Operation Run**: An observable, queued execution record for verification/health/sync actions initiated from the wizard. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Workspace Owners can complete onboarding for a new Managed Tenant in under 10 minutes (excluding time waiting for admin consent). - **SC-002**: 100% of wizard step page loads complete without initiating outbound HTTP calls (outbound activity occurs only when a user triggers a run action). - **SC-003**: Users can resume an in-progress wizard in 2 clicks or fewer from the Managed Tenant view. - **SC-004**: After onboarding completion, authorized users can start verification/health runs successfully for the tenant. - **SC-005**: Non-members receive deny-as-not-found behavior (404) for tenant-plane onboarding/managed tenant pages; members lacking capabilities are prevented from performing restricted actions.