Skip to content

IAM - User types and actors

Purpose

BizOS serves two completely distinct audiences: the internal platform team that operates the multi-tenant infrastructure, and the customer teams that use BizOS to run their businesses. This specification defines the two user types, their storage boundaries, authentication realms, role models, and isolation rules so that platform security and tenant data boundaries remain absolute.

User classification

Characteristic Type 1: System and internal team users Type 2: Customer (tenant) users
Common name Operators, Platform staff, System administrators Tenant users, Workspace members, Customers
Primary purpose Operate, provision, monitor, and support the multi-tenant SaaS platform Run daily business workflows (CRM, sales, contracts, tasks, team collaboration)
Target application Admin portal (apps/admin) Tenant web app (apps/web)
Domain / URL pattern Reserved administrative domain (admin.<root-domain>) Per-tenant subdomain (<tenant>.<root-domain>)
Database location Shared database (bizos_dev) in admin_operators table Shared database (bizos_dev) in users table (scoped by tenant_id)
Backend module libs/api/admin (operator-access) libs/api/iam (sign-in, register, user-management)
Account creation Invite-only by an Owner; no self sign-up Sign-up flow (new tenant creation) or invited by a Tenant Admin
MFA requirement Mandatory TOTP MFA on all accounts Optional / configurable by tenant policy
Session lifecycle 30 minutes idle timeout, 12 hours absolute maximum 12 hours session cookie
Data visibility Platform-level operational metadata (tenant status, resource counts, error logs) Tenant business data (contacts, deals, contracts, documents) within their tenant only

Roles and permissions

Type 1: Platform operator roles (Cấp độ nền tảng)

Platform operator roles are fixed across the platform and govern operations on the control plane. They are managed through the admin portal (see Operator access and audit).

Role Role Key Responsibility Scope of authority
Super Admin super_admin Platform lead / CTO Full access: manage operator accounts and roles, delete tenants, restore and reset databases, configure platform secrets.
Admin admin DevOps, site reliability engineers, platform operations Operational tasks: suspend/reactivate tenants, retry provisioning/migrations, trigger on-demand backups, manage job queues.
Support support Technical support agents Diagnostic access: view tenant status, logs, provisioning runs, resend transactional emails, and view audit entries. No destructive actions.

Type 2: Tenant user roles (Cấp độ người dùng)

Tenant roles govern activities within a specific tenant workspace. They are scoped entirely within that tenant's database and have zero authority over the platform or other tenants.

Stored on the tenant users.role column. A legacy stored value of customer is read as user. After sign-in, each role opens the workspace menu in Customer portal.

Role Stored value Responsibility
Tenant Owner tenant_owner Tenant workspace owner (chủ shop / quản lý). Full control over tenant business workflows, billing, company settings, and team member management.
User user Daily business work: dashboard, CRM, contracts, tasks, and personal profile. Self-registration and member invites create this role.

Requirements

ID Priority Requirement
USR-01 Must The system enforces strict logical identity segregation between internal operator accounts and customer tenant accounts (ADR-0012).
USR-02 Must Operator credentials can never authenticate against any tenant application (<tenant>.<root-domain>), returning 401 Unauthorized.
USR-03 Must Tenant user credentials can never authenticate against the admin portal (admin.<root-domain>), returning 401 Unauthorized.
USR-04 Must An operator's identity and permissions are resolved exclusively from global operator tables, independent of tenant state.
USR-05 Must A customer user's identity and permissions are resolved exclusively from tenant users scoped by tenant_id for the incoming request subdomain.
USR-06 Must The API gateway / auth guard determines the expected user type based on the hostname and routing context before evaluating credentials.
USR-07 Must Operator sessions and tenant user sessions use distinct token namespaces and cookie names to prevent session smuggling across domains.
USR-08 Must System and internal team users have zero ambient access to customer business records (contacts, contracts, tasks). Viewing tenant records requires explicit tenant support elevation and full auditing.
USR-09 Must Internal operator account creation requires an email invite from an existing Owner; self-registration on admin.<root-domain> is blocked.
USR-10 Must Tenant user account creation occurs via onboarding registration (first admin) or via invitation from a Tenant Admin within that tenant.
USR-11 Must Deactivating an internal operator immediately revokes all active operator sessions on the control plane.
USR-12 Must Suspending a tenant immediately blocks all tenant users of that tenant from signing in or executing authenticated API requests.

Screens and user entry points

1. Internal team entry point (admin.<root-domain>)

  • Login screen: Prompts for operator email and password, followed by mandatory TOTP MFA step.
  • Account recovery / setup: Accepts invite token sent via email to set initial password and scan TOTP QR code.
  • Navigation context: Displays global operator dashboard, tenant list, health metrics, and activity log.

2. Customer tenant entry point (<tenant>.<root-domain>)

  • Login screen: Located at /sign-in. Accepts customer email and password. Shows tenant branding/name when configured.
  • Registration screen: Located at /register (for new workspace users where allowed) or onboarding provisioning URL.
  • Navigation context: Displays tenant business modules (CRM, contracts, tasks, tenant settings).

Business rules

  • Host routing rule:
  • admin.<root-domain> routes strictly to the internal admin portal and API endpoints under /api/admin/*.
  • <tenant>.<root-domain> routes strictly to tenant web application and API endpoints under /api/auth/* and tenant feature routes.
  • IP-based or unknown-host requests are rejected before authentication.
  • Identity isolation:
  • Even if an internal staff member and a customer share the exact same personal email address (e.g. staff@example.com), their records exist in separate databases with separate password hashes and separate session states.
  • Changing an operator password in the control plane has zero effect on tenant accounts, and vice versa.
  • Cross-tenant isolation:
  • A customer user in Tenant A (tenant-a.<root-domain>) has no record in Tenant B's database and cannot log into tenant-b.<root-domain>.
  • Audit segregation:
  • All operator activities are written to the control-plane activity log (operator_audit_log). A Super Admin can delete entries. Entries cannot be edited.
  • Tenant activities (e.g. customer user sign-in, record modifications) are logged to that tenant's audit trail within their tenant database.

Acceptance criteria

  • USR-07: Operator routes read only bizos_admin_session. A tenant bizos_session cookie alone cannot authenticate /api/admin/*. Tenant JWTs use realm: tenant; after exchange, operator JWTs use realm: operator.
  • USR-03 / USR-07: An operator-realm JWT is rejected by tenant currentUser / tenant APIs.
  • USR-02 / USR-04: A tenant-realm JWT (including tenant_owner / user) cannot authenticate the admin portal; exchange accepts only platform roles and issues an operator session while clearing tenant cookies.
  • USR-11: Deactivating an operator deletes their control-plane sessions so the next request is unauthorized.
  • USR-12: When a tenant is suspended, sign-in returns 403 with TENANT_SUSPENDED, and authenticated tenant API calls (including /api/auth/me) are forbidden with the same code.
  • USR-06: Host classification treats reserved / admin hosts as control-plane and tenant labels as tenant; on localhost, /api/admin stays control-plane and DEV_TENANT_SUBDOMAIN can bind workspace requests to a tenant.

Not yet implemented

  • Invite links opened on a tenant subdomain are not yet hard-redirected to admin.<root-domain> in the web apps (host routing for invites).
  • Pure admin_operators accounts that have no IAM users row still cannot use the unified customer sign-in; they use /api/admin/auth/sign-in only (intentional with IAM-17 for seeded platform roles that live in IAM).

Out of scope

  • Multi-tenant single sign-on (SSO) bridging operator accounts into tenant workspaces.
  • Delegated support impersonation (customer screen-sharing / support token granting).
  • Social logins (Google / GitHub OAuth) for operators or tenants.

Open questions

  • None. Both types of users and their boundaries are aligned with ADR-0005 and STACK.md.