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 role-based access control.

User Roles (Hierarchical)

1. System Operator (SYSTEM_OP)

   • Full system access
   • Manage all PSPs, merchants, stores
   • System configuration and monitoring
   • Can impersonate any lower role

2. PSP Admin (PSP_ADMIN)

   • Manage merchants within their PSP
   • View aggregated reports across merchants
   • Configure PSP-level settings
   • Can impersonate merchant/store roles

3. Merchant Admin (MERCHANT_ADMIN)

   • Manage stores within their merchant
   • User management for merchant scope
   • Financial reporting and analytics
   • Configure payment methods
   • Can impersonate store manager

4. Store Manager (STORE_MANAGER)

   • Manage devices for their store
   • View store-level reports
   • Activate/deactivate terminals
   • Staff management for store

5. Staff (STAFF)

   • View-only access to reports
   • Process refunds (with approval)
   • Customer service operations

Authentication Flow

User Login → Email/Password → MFA Challenge (Optional)
    → MFA Verification (SMS/Email/TOTP) → Issue JWT (15-min TTL)
    → JWT Claims: {user_id, role, merchant_id, store_id, psp_id}

Key Features

• Multi-factor authentication (MFA) support
• JWT-based session management
• Admin impersonation with audit trail
• Role-based permissions enforcement
• Session timeout and refresh tokens

API Endpoints

• POST /auth/user/login - Email/password 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 →