Skip to content

Merchant Admin Foundation & Security Manual

Module: M00 Foundation & Access Control

Product: ebosAi AMP
Classification: Internal — Confidential
Version: 2.0

1. Authentication Architecture

Tenant administrators (admin role) and managers (manager role) access the Merchant Admin Panel via two secure pathways:

sequenceDiagram
    autonumber
    actor Admin as Merchant Administrator
    participant Browser as Admin UI (/admin/*)
    participant BFF as Backend Auth Service
    participant SSO as EBOS Marketplace SSO
    participant DB as Neon Database

    alt Standard Path: Marketplace SSO
        Admin->>Browser: Click "Sign in with EBOS SSO"
        Browser->>SSO: Authenticate Admin Credentials
        SSO-->>Browser: Return Marketplace JWT Token
        Browser->>BFF: POST /api/v1/auth/exchange {token}
        BFF->>DB: Upsert User by sso_uid & Bind tenant_id
        BFF-->>Browser: Set httpOnly amp_admin_token Cookie
        Browser-->>Admin: Redirect to /admin/dashboard
    else Fallback Path: Emergency TempOTP
        Admin->>Browser: Visit /login & Enter Work Email
        Browser->>BFF: POST /api/v1/auth/tempotp/request
        BFF-->>Admin: Dispatch 6-Digit Code via SMTP (10m expiry)
        Admin->>Browser: Submit Code at /verify
        Browser->>BFF: POST /api/v1/auth/tempotp/verify
        BFF-->>Browser: Set httpOnly amp_admin_token Cookie
        Browser-->>Admin: Redirect to /admin/dashboard
    end

Key Security Standards:

  • Zero Stored Passwords: No user passwords exist in the local database.
  • httpOnly Cookie Protection: All administrative tokens are stored in httpOnly, Secure, SameSite=Strict cookies, preventing client-side script inspection.
  • Session Timeout: Administrative sessions automatically expire after 24 hours of inactivity.

2. Multi-Tenancy Data Scoping (tenant_id)

All database entities across the platform are strictly isolated by tenant_id UUID foreign keys: - The TenantContextMiddleware extracts the tenant scope directly from the authenticated JWT claims on every incoming request. - Database service queries automatically bind WHERE tenant_id = :tenant_id. - Zero Cross-Tenant Leakage: Administrators have absolute visibility within their own organization, but cannot access data belonging to other tenants.

3. Two-Level Tenant Security Architecture

The platform enforces two distinct layers of access governance: 1. Level 1 — Subscription Plan Gating: Routes and features are constrained by the company's active subscription tier (plan_1, plan_2, plan_3). 2. Level 2 — Granular User Role & Menu Overrides: Company Admins can customize individual internal user permissions and selectively enable/disable specific navigation routes.