Skip to content

IAM - Roles and permissions

Purpose

BizOS organizes users into two primary groups: Operator (platform operations) and Customer (tenant business members). This specification defines the user group hierarchy, standardized roles within each group, cross-portal access permissions, and navigation/feature access control across both the Admin Portal and Customer Portal.

User Groups and Standardized Roles

Users are classified into two top-level groups:

┌────────────────────────────────────────────────────────┐
│                      BIZOS USERS                       │
└───────────────────────────┬────────────────────────────┘
                            │
            ┌───────────────┴───────────────┐
            ▼                               ▼
  ┌───────────────────┐           ┌───────────────────┐
  │  Operator Group   │           │  Customer Group   │
  └─────────┬─────────┘           └─────────┬─────────┘
            │                               │
     ┌──────┼──────┐                 ┌──────┴──────┐
     ▼      ▼      ▼                 ▼             ▼
Super Admin Admin Support       Tenant Owner      User

1. Group: Operator (operator)

The platform control-plane group responsible for infrastructure, provisioning, maintenance, tenant onboarding, and operational support. - Roles in group: - super_admin (Super Admin - Platform Lead / CTO) - admin (Admin - DevOps / Site Reliability Engineers) - support (Support - Customer Support / Technical Operations) - Portal Access: - Admin Portal (admin.<root-domain>): Allowed with full administrative functionality according to operator role. - Customer Portal (<tenant>.<root-domain>): Allowed with full functionality across all modules (ambient oversight, configuration, and tenant assistance).

2. Group: Customer (customer)

The tenant workspace group comprising customer organization members who use BizOS for daily business operations. - Roles in group: - tenant_owner (Tenant Owner - Organization Admin / Business Owner) - user (User - Standard Staff / Team Member) - Portal Access: - Admin Portal (admin.<root-domain>): BLOCKED. Customer accounts cannot access the admin portal (HTTP 401/403). - Customer Portal (<tenant>.<root-domain>): - tenant_owner: Full functionality across the entire Customer Portal, including WORKSPACE and BUSINESS MANAGEMENT. - user: Access to WORKSPACE only; BLOCKED from the BUSINESS MANAGEMENT section.

Portal Access Matrix

Group Role Key Admin Portal Access Customer Portal - WORKSPACE Customer Portal - BUSINESS MANAGEMENT
Operator super_admin ✓ Full Access ✓ Full Access ✓ Full Access
Operator admin ✓ Full Access ✓ Full Access ✓ Full Access
Operator support ✓ Read / Diagnostic Access ✓ Full Access ✓ Full Access
Customer tenant_owner ✗ Blocked (401/403) ✓ Full Access ✓ Full Access
Customer user ✗ Blocked (401/403) ✓ Full Access ✗ Blocked (Hidden & 403)

Customer Portal Functional Breakdown

The Customer Portal layout is divided into two distinct navigation and permission sections:

1. Section: WORKSPACE (Shop Work / Daily Operations)

  • Routes:
  • Dashboard (/)
  • Customers & Sales CRM (/crm)
  • Contracts & Orders (/contracts)
  • Tasks & Progress (/tasks)
  • Personal Profile (/profile)
  • Change Password (/change-password)
  • Allowed Roles: Both tenant_owner and user (as well as the Operator group).

2. Section: BUSINESS MANAGEMENT (Administration & Governance)

  • Routes:
  • Plans & Billing (/billing)
  • Staff & Members Management (/users)
  • Company Settings (/settings)
  • Activity Log (/activity-log)
  • Allowed Roles: tenant_owner (and the Operator group).
  • Blocked Roles: user (Navigation links are hidden; direct URL access redirects to / or returns HTTP 403; API endpoints return 403).

Detailed Feature Permission Matrix

Feature / Screen Route Operator Group (super_admin, admin, support) Tenant Owner (tenant_owner) User (user)
Admin Portal
Control Plane Dashboard / (Admin) ✓ ✗ Blocked ✗ Blocked
Tenant Registry & Quotas /tenants ✓ ✗ Blocked ✗ Blocked
Provisioning Monitor /provisioning ✓ ✗ Blocked ✗ Blocked
Backup, Restore & Reset /backups ✓ ✗ Blocked ✗ Blocked
System Health & Metrics /health ✓ ✗ Blocked ✗ Blocked
All Users Oversight /users (Admin) ✓ ✗ Blocked ✗ Blocked
Platform SMTP Settings /settings/smtp ✓ ✗ Blocked ✗ Blocked
Operator Management /operators ✓ (Super Admin only for edits) ✗ Blocked ✗ Blocked
Operator Activity Log /activity-log (Admin) ✓ ✗ Blocked ✗ Blocked
Customer Portal - WORKSPACE
Executive Dashboard / (Tenant) ✓ ✓ ✓
CRM (Directory, Pipeline, Activity, Products) /crm/* ✓ ✓ ✓
Contracts & Orders /contracts/* ✓ ✓ ✓
Tasks & Progress Board /tasks/* ✓ ✓ ✓
User Profile & Password Change /profile, /change-password ✓ ✓ ✓
Customer Portal - BUSINESS MANAGEMENT
Plans & Resource Meters /billing ✓ ✓ ✗ Blocked
Staff & Member Management /users ✓ ✓ ✗ Blocked
Company Legal Settings /settings ✓ ✓ ✗ Blocked
Tenant Activity Log /activity-log ✓ ✓ ✗ Blocked

Requirements

ID Priority Requirement
PRM-01 Must The system groups users into two top-level groups: operator (containing super_admin, admin, support) and customer (containing tenant_owner, user).
PRM-02 Must Users in the operator group can access both the Admin Portal and the Customer Portal with full functionality. From Admin, an authenticated operator can open a tenant Customer Portal via ambient SSO (POST /api/admin/auth/customer-bridge) without a prior customer-portal sign-in; the API issues a tenant-realm session cookie and returns a redirect URL.
PRM-03 Must Users in the customer group cannot authenticate against or access the Admin Portal (admin.<root-domain>), receiving HTTP 401 Unauthorized or HTTP 403 Forbidden.
PRM-04 Must A tenant_owner has full access to all features in the Customer Portal, including WORKSPACE and BUSINESS MANAGEMENT.
PRM-05 Must A user has access to the WORKSPACE section only (Dashboard, CRM, Contracts, Tasks, Profile). They are strictly blocked from the BUSINESS MANAGEMENT section (/billing, /users, /settings, /activity-log).
PRM-06 Must When a user navigates directly to any route in BUSINESS MANAGEMENT, the application redirects them to the workspace home (/) and displays an authorization warning notice.
PRM-07 Must Backend API endpoints backing the BUSINESS MANAGEMENT section (such as /api/users, /api/billing, /api/tenant/settings, /api/audit-logs) verify caller roles and reject requests from user with HTTP 403 Forbidden.
PRM-08 Must In the Customer Portal sidebar navigation, the BUSINESS MANAGEMENT menu group is rendered for tenant_owner and operators, but completely omitted from the DOM for users with the user role.
PRM-09 Must An operator accessing the Customer Portal can view and manage both WORKSPACE and BUSINESS MANAGEMENT without requiring separate customer credentials.
PRM-10 Must A tenant_owner cannot delete their own user account in the member management screen to prevent organization lockout.
PRM-11 Must The last active super_admin in the platform cannot be demoted, deactivated, or deleted.
PRM-12 Must Modifying a user's role or group takes effect immediately; active sessions are refreshed or terminated to reflect the updated permissions.
PRM-13 Must All authorization failures and permission-denied events (attempted cross-portal or unauthorized section access) are logged to the respective audit log.

Screens

1. Customer Portal Navigation (apps/web)

  • For tenant_owner and Operators:
  • Sidebar displays two navigation groups: WORKSPACE (Dashboard, Customers & CRM, Contracts & Orders, Tasks & Progress) and BUSINESS MANAGEMENT (Plans & Billing, Staff & Members, Company Settings, Activity Log). Published notices are opened from the header bell, not from a sidebar item.
  • For user:
  • Sidebar displays only WORKSPACE. The BUSINESS MANAGEMENT group header and all child items are completely hidden.

2. Admin Portal Navigation (apps/admin)

  • Available only to users in the operator group (super_admin, admin, support).
  • Customer users navigating to admin.<root-domain> are stopped at authentication with an "Unauthorized portal access" error.

Business rules

  1. Group Membership:
  2. Every user belongs to exactly one group (operator or customer) and possesses exactly one role within that group.
  3. First User Provisioning:
  4. The user who registers or onboards a new tenant is automatically granted the tenant_owner role in the customer group.
  5. Any member subsequently invited or created within that tenant workspace defaults to the user role unless elevated by a tenant_owner.
  6. Defense in Depth:
  7. Frontend navigation omission is a convenience filter. Server-side middleware and controller guards must enforce PRM-05 and PRM-07 independently of the client UI state.

Acceptance criteria

  • PRM-01: User group classification accurately resolves super_admin, admin, and support to operator, and tenant_owner and user to customer.
  • PRM-02: An authenticated operator user can open and perform actions in both portals (unified IAM login + operator session cookie; tenant session cookie kept after exchange). Ambient SSO: Admin customer-bridge issues a tenant-realm session without a prior customer login; tenant detail Open workspace uses that bridge.
  • PRM-03: Given a tenant_owner or user credential, when attempting to sign in to admin.<root-domain>, then access is denied with 401 or 403.
  • PRM-04: Given a signed-in tenant_owner, all routes under WORKSPACE and BUSINESS MANAGEMENT render and allow full action execution.
  • PRM-05: Given a signed-in user, navigating to /billing, /users, /settings, or /activity-log redirects to / with an authorization warning and does not load management data. The sidebar has no Notifications item.
  • PRM-06: Given a signed-in user, API calls to GET /api/users return HTTP 403 Forbidden.
  • PRM-07: Given a signed-in tenant_owner, API calls to GET /api/users return HTTP 200 OK with the member list.
  • PRM-08: In the customer portal DOM for a user session, no DOM element contains text or links for the BUSINESS MANAGEMENT menu group.
  • PRM-09: An operator opening a tenant Customer Portal via POST /api/admin/auth/customer-bridge gets a tenant-realm session even when no IAM users row existed yet (the API provisions a matching platform user). Tenant APIs also accept an operator-realm JWT when the request includes x-bizos-operator-access: 1, so BUSINESS MANAGEMENT such as GET /api/users works without a separate customer password.
  • PRM-10: When a tenant_owner calls DELETE /api/users/:selfId, then HTTP 400 Bad Request is returned.
  • PRM-11: The last active super_admin cannot be demoted, deactivated, or deleted.
  • PRM-12: Changing a workspace member's role (user / tenant_owner) via PATCH /api/users/:id persists the role and deletes that user's sessions so the next request is unauthorized until they sign in again. Changing an operator role ends their control-plane sessions and the next operator JWT request uses the stored role, not the role baked into the token.
  • PRM-13: A user calling BUSINESS MANAGEMENT APIs (GET /api/users, GET /api/iam/audit-log, unpublished notification catalog) receives HTTP 403 and a tenant Activity log row (recordType Quyền). A customer tenant session hitting the admin portal or POST /api/admin/auth/exchange is denied and writes unauthorized_portal_access on the operator audit log. An authenticated operator missing a permission writes permission_denied.

Not yet implemented

None.

Out of scope

  • Dynamic custom group creation by tenant administrators.
  • Sub-role permissions within user (e.g. Sales-only vs Support-only within customer portal).

Open questions

None.