Identity & Access Management (IAM)

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

---

Overview

The IAM domain defines authentication and authorization mechanisms for both human users (portal access) and SmartPOS devices (terminal operations). It implements a hierarchical role-based access control (RBAC) system for users and a secure OAuth2 private_key_jwt flow for device authentication. This dual-identity architecture ensures secure access control across the entire platform while maintaining operational flexibility and auditability.

Table of Contents

• Human Identity (Portal Users)
• Device Identity (SmartPOS Terminals)

---

Human Identity (Portal Users)

Purpose: Authentication and authorization for web portal users with hierarchical role-based access control using contract-first, ID-based login.

See also: Login ID Convention — ID format, tenant scoping, area entity, and provisioning flow details.

User Roles (Hierarchical)

Tier	Role	ID Format	Auth Method	Scope
L0	System Operator	SYS-{4an}	ID + pwd + MFA	Platform
L1	PSP Admin	PSP-{6an}	ID + pwd + MFA	Platform
L2	Merchant Admin	MCH-{8an}	ID + pwd + MFA	All stores under contract
L3	Area Manager	ARA-{MCH 8}-{3an}	ID + pwd + MFA	Assigned area (store group)
L4	Store Manager	STR-{MCH 8}-{3an}	ID + pwd + MFA (recommended)	Single store
L5	Staff Leader	SLR-{STR 3}-{3an}	6-digit PIN	Single store
L6	Store Staff	STF-{STR 3}-{3an}	6-digit PIN	Single store

Tenant hierarchy:

Platform (L0, L1)
 └── Merchant (L2)           ← contract boundary
      └── Area (L3)          ← store-group boundary
           └── Store (L4)    ← location boundary
                └── Staff (L5, L6)

Authentication Flow

L0–L4: Login ID + Password → MFA Challenge
    → MFA Verification (SMS/Email/TOTP) → Issue JWT (15-min TTL)
    → JWT Claims: {user_id, role, merchant_id, store_id, psp_id, area_id}

L5–L6: Login ID + 6-digit PIN → Issue JWT (session-scoped)
    → Max 5 failed attempts → lockout (L4 resets)

Key Features

• ID-based login (not email-based) — IDs are immutable, server-generated, alphanumeric
• Multi-factor authentication (MFA) for L0–L4
• PIN-based authentication for store staff (L5–L6)
• JWT-based session management
• Admin impersonation with audit trail
• Role-based permissions enforcement
• Session timeout and refresh tokens

API Endpoints

• POST /auth/user/login - ID/password authentication
• POST /auth/user/pin-login - PIN-based staff authentication
• POST /auth/user/mfa/send - Send MFA code (SMS/Email)
• POST /auth/user/mfa/verify - Verify MFA code and issue token
• POST /auth/admin/impersonate - Admin impersonation
• GET /jwks/human - Public keys for JWT validation

---

Device Identity (SmartPOS Terminals)

Purpose: Secure authentication for SmartPOS devices using OAuth2 private_key_jwt flow.

Device Lifecycle States

1. Unprovisioned - Factory state with serial number only
2. Pending Activation - Activation code generated, awaiting binding
3. Active - Fully provisioned, can authenticate
4. Suspended - Temporarily disabled by admin
5. Decommissioned - Permanently retired

Device Provisioning Flow

Device Boot → Generate EC P-256 Keypair (Android Keystore)
    → POST /device/provision/generateActivationCode
    → Display Activation Code
    → Staff Enters Code in Portal
    → POST /device/provision/activate (bind to store)
    → Device Polls /device/provision/activationStatus
    → Receive: {device_id, client_id, merchant_id, store_id}
    → Device Can Now Authenticate

Device Authentication (OAuth2 private_key_jwt)

Device Signs JWT with Private Key:
    {iss: client_id, sub: client_id, aud: /auth/device/token, exp: now+60s}
    → POST /auth/device/token {client_id, client_assertion}
    → Portal Validates Signature with Public Key
    → Issue Device Access Token (60-120 sec TTL)
    → JWT Claims: {device_id, device_sn, merchant_id, store_id, scope}

Security Features

• Private key stored in Android Keystore (non-exportable)
• Short-lived tokens (60-120 seconds)
• Public key cryptography (EC P-256)
• Activation code expiry (24 hours)
• Rate limiting on provisioning endpoints

API Endpoints

• POST /device/provision/generateActivationCode - Start provisioning
• POST /device/provision/activate - Bind device to store
• GET /device/provision/activationStatus - Poll activation status
• POST /auth/device/token - OAuth2 token request
• GET /jwks/device - Public keys for device JWT validation

---

See Also

Related Domains:

• Device Management - Device provisioning and lifecycle management
• Merchant Hierarchy - Permission scoping and organizational structure

Technical Implementation:

• Security Architecture - Authentication patterns and cryptographic specifications
• Database Architecture - IAM data model and schema design

API Reference:

• API Endpoints - Complete API specification for authentication endpoints

---

Navigation: ↑ Back to Domain Catalog | Next: Device Management →