Skip to content

User Onboarding Model (MVP -> Post-MVP)

Purpose

Define the product and control-plane onboarding model so the platform feels complete without waiting on MaaS or enterprise federation rollout.

This document separates:

  1. MVP onboarding path we can implement now
  2. Post-MVP expansion paths (tenant federation automation, multi-tenant switching)

Current Constraints

  1. Personal account signup/login exists and auto-bootstraps tenant/project context.
  2. Seeded bootstrap users still exist for local/dev bring-up.
  3. Tenant/project ownership and membership are now the authorization root.
  4. MaaS onboarding is explicitly deferred (A-MAAS-001).

MVP Onboarding Model (Implement Now)

Identity and Role Boundaries

  1. users.role=admin is platform-admin only (platform scope).
  2. Tenant/project access is controlled by memberships:
  3. tenant_memberships
  4. project_memberships
  5. Resource ownership is tenant/project-rooted; user id is attribution.
  6. Extended role taxonomy and lifecycle (platform ops, tenant/project role sets, custom roles) are defined in:
  7. doc/architecture/Role_and_Policy_Lifecycle_Model.md

User Creation and Access Flow

  1. Work account path (MVP behavior):
  2. uses platform OIDC login path backed by the shared realm setup.
  3. tenant federation discovery/config is not required for MVP runtime.
  4. tenant hints are advisory and server-validated.
  5. UI behavior: Continue with SSO path with optional work-email/tenant-hint input; no personal username/password fields in this branch.
  6. Personal account path:
  7. user signs up/signs in with personal credentials.
  8. personal sign-in must use public auth/session flows, not internal bootstrap endpoint POST /api/v1/auth/login.
  9. signup atomically creates personal tenant + default project + owner memberships.
  10. bootstrap role binding on success:
    • tenant role: tenant_owner
    • project role: project_owner
  11. UI behavior: personal username/password sign-in and sign-up controls; no SSO redirect in this branch.
  12. Platform admin can create tenant admin user using current admin path:
  13. POST /api/v1/admin/users for identity creation, then
  14. membership binding via scripts/ops/bind_tenant_admin_membership.sh (single controlled scripted operation, no ad-hoc SQL) until tenant-admin membership APIs land.
  15. script requirements: correlation_id input, explicit actor/target fields, and audit log write in the same operation path.
  16. Tenant admin manages tenant users and project memberships within tenant scope.
  17. API resolves user -> active tenant membership -> request-scoped project context.
  18. If project context is missing for project-owned operations:
  19. return deterministic 400 invalid_request with canonical envelope.

Failure and Deactivation Paths

  1. Personal signup bootstrap is transactionally atomic:
  2. any failure returns canonical error and no partial tenant/project/membership state is committed.
  3. If membership is revoked or account is deactivated mid-session:
  4. subsequent protected calls return canonical authz/auth errors,
  5. client clears local session and routes user back to sign-in.

UX Expectations (MVP)

  1. Login screen presents two account paths: Work account and Personal account.
  2. Authenticated user sees current tenant/project context in shell/header.
  3. First-run zero-balance user is routed to billing onboarding CTA (already defined in product UX docs).
  4. User-management surfaces clearly show actor scope (platform vs tenant/project) and deterministic membership/context errors.
  5. MVP-activated tenant roles in onboarding flows are:
  6. tenant_owner, tenant_admin, tenant_member.
  7. Defined-but-not-activated-by-default roles in onboarding UX are:
  8. tenant_billing_manager, tenant_billing_viewer, tenant_viewer.

Post-MVP Expansion (Not Blocking MVP)

  1. Enterprise SSO federation admin UX (ADR-010 baseline):
  2. per-tenant OIDC/SAML provider config,
  3. invite/pre-authorization gate before membership activation.
  4. Multi-tenant user context switching UX:
  5. remove MVP single-tenant uniqueness guard when enabled.
  6. guard location today: partial unique active-membership constraint ux_tenant_memberships_user_active on tenant_memberships(user_id) in doc/architecture/db_schema_v1.sql; removal means dropping/relaxing that constraint and updating membership selection UX.
  7. Self-service tenant-admin membership APIs/UI:
  8. replace internal runbook/SQL fallback.
  9. tracking anchor: this follow-up must be represented in doc/governance/Agent_Work_Queue.yaml before implementation kickoff; architectural dependency is doc/architecture/adrs/ADR-008-tenant-project-ownership-baseline.md.

Onboarding-Specific Contract Requirements

  1. Personal signup endpoint must be idempotent by key and safe to retry.
  2. Personal signup bootstrap must be atomic across user+tenant+project+membership creation.
  3. Work/personal onboarding failures must always return canonical error envelopes.
  4. Audit for onboarding mutations must include full authz context fields from role lifecycle baseline:
  5. correlation_id, actor_type, actor_id, platform_role, tenant_id, project_id, resource_name (when applicable), reason_code.

Out of Scope for This Sprint

  1. MaaS node onboarding integration.
  2. Full enterprise IdP admin UX.
  3. Service-account onboarding UX.

References

  1. doc/architecture/adrs/ADR-008-tenant-project-ownership-baseline.md
  2. doc/architecture/Tenant_Federation_SSO_Model.md
  3. doc/product/UX_Implementation_Spec.md
  4. doc/product/UX_Journeys.md
  5. doc/architecture/Role_and_Policy_Lifecycle_Model.md