Program Management User

• Program Management User
  • Overview
  • Data Structure
    • State Schema
    • User Types and Status
    • Authentication Methods
  • Core Functionality
    • User Management
    • Authentication & Login
    • Password Management
    • Approval Workflows
  • API Methods
    • User Management Methods
    • Authentication Methods
    • Password Management Methods
    • Status Management
  • Key Features

Overview

The ProgramManagementUser class manages administrative users who operate the loyalty program system. These users have role-based access to manage members, companies, tiers, and other system entities. The class handles user lifecycle, authentication, and permission management.

General Purpose:

• Administrative user management for program operators
• Role-based access control integration
• Multi-method authentication (email/password, OTP)
• User invitation and approval workflows
• Scoped access control (company-specific users)

Data Structure

State Schema

The ProgramManagementUser class maintains a singleton state with all users:

interface ProgramManagementUserState {
  private: {
    users: ProgramManagementUser[]
  }
}

User Types and Status

enum ProgramManagementUserType {
  INTERNAL = 'internal',    // Internal system administrators
  COMPANY = 'company'       // Company-scoped users
}

enum ProgramManagementUserStatus {
  PENDING = 'pending',      // Pending invitation acceptance
  ACTIVE = 'active',        // Active user
  INACTIVE = 'inactive'     // Deactivated user
}

Authentication Methods

enum ProgramManagementLoginMethod {
  SSO = 'sso',                    // Single Sign-On
  EMAIL_PASSWORD = 'email_password' // Email and password
}

Core Functionality

User Management

• User Creation: Create new administrative users with role assignment
• User Updates: Modify user profiles, roles, and company associations
• Status Management: Activate, deactivate, and manage user lifecycle
• Listing & Filtering: User search and filtering capabilities

Authentication & Login

• Multi-Method Auth: Support for SSO (SAML 2.0) and email/password authentication
• SSO Integration: Azure Active Directory and SAML-compliant identity providers
• Domain-based Discovery: Automatic authentication method detection based on email domain
• OTP Integration: Two-factor authentication via email OTP for email/password method
• Session Management: Login tracking and audit trails
• Token Generation: JWT token creation with user claims and permissions

Password Management

• Password Reset: Secure password reset via email tokens
• Invitation Flow: New user invitation with secure password setup
• Password Security: Hashed password storage and validation

Approval Workflows

• User Creation Approval: Optional approval workflow for new users
• General Approval: Integration with ApprovalManager for user operations
• Invitation Acceptance: Secure invitation token validation

API Methods

User Management Methods

• createUser (WRITE) - Create new administrative user

  • Triggers invitation email for password setup

• updateUser (WRITE) - Update existing user

• getUser (READ) - Retrieve specific user by ID

• listUsers (READ) - List and filter users

• updateUserStatus (WRITE) - Update user status

  • Change user status between PENDING, ACTIVE, and INACTIVE
  • Validates email uniqueness when activating users
  • Triggers workflow for status change approval

• getPermissions (READ) - Get permissions for logged-in user

  • Returns permissions grouped by class key based on user's roles

Authentication Methods

• discoverAuthMethod (STATIC) - Determine user's authentication method by email domain

  • Returns SSO login URL for configured domains
  • Supports email/password fallback for non-SSO domains

• singleSignOn (WRITE) - Process SAML authentication response

  • Validates SAML response from identity provider
  • Generates JWT token and redirects to web application
  • Supports Azure AD and other SAML 2.0 providers

• login (WRITE) - Email/password authentication

  • Traditional username/password authentication
  • Triggers OTP for additional security

• checkOtp (WRITE) - Validate OTP during login

• resendOtp (WRITE) - Resend OTP for authentication

Password Management Methods

• sendPasswordResetEmail (WRITE) - Initiate password reset

• resetPassword (WRITE) - Complete password reset

• acceptInvitation (WRITE) - Accept user invitation

  • Activates user account and sets password

Status Management

• approveUser (QUEUED_WRITE) - General user approval

• approveUserCreate (QUEUED_WRITE) - Approve user creation

Key Features

1. Singleton Architecture: Single instance (default) manages all program management users
2. Role Integration: Deep integration with RoleManager for permission-based access
3. Company Scoping: Company-type users restricted to their assigned company operations
4. SSO Authentication: Full SAML 2.0 support with Azure AD integration and domain-based discovery
5. Multi-Auth Support: Flexible authentication methods including SSO and email/password with OTP
6. Workflow Compatible: Extends WorkflowCompatibleStateManager for approval processes
7. Audit Trail: Login attempt tracking and comprehensive user activity logging
8. Security Features: Secure password handling, SAML validation, token-based operations, and OTP validation

Class Relations

The following diagram illustrates how ProgramManagementUser integrates with other system components: