Use Case 005: Administrator User Management

Overview

Property	Value
Use Case ID	UC-005
Use Case Name	Administrator User Management
Module	Identity Management - Administrator Users
Priority	High
Status	Implemented
Version	1.0
Last Updated	January 30, 2026

Description

This use case describes the comprehensive management of administrator users who have privileged access to the Riptide Application Manager system itself. Administrators can create, update, and deactivate other admin accounts, manage roles and permissions, enforce password policies, and maintain security through audit logging. The system includes automatic creation of a default administrator account on first startup and implements strict security controls including password complexity requirements, multi-factor authentication support, and comprehensive activity auditing. This differs from trial user management (UC-001) as admin users are stored in the Configuration database and have system-level privileges.

Actors

Actor	Description	Role
Super Administrator	System admin with full privileges including user management	Primary
Administrator	System admin with role-based permissions	Primary
System	Application Manager platform	Supporting
Audit Service	Logging and monitoring service for security events	Supporting
Email Service	SMTP or AWS SES for sending notifications	Supporting

Preconditions

Application Manager is running and accessible
Configuration database is operational and initialized
Default admin account (admin/Admin@2026!) exists (created on first startup)
Super administrator is authenticated and has user management permissions
Email service is configured for notifications (optional but recommended)
Audit logging is enabled and operational

Postconditions

Success Postconditions

New administrator user record created/updated in Configuration database
Password hash stored securely using bcrypt or equivalent
Admin role assignments applied correctly
Account status reflects current state (Active/Inactive/Locked)
Welcome or notification email sent to administrator
All changes logged in audit trail with actor, timestamp, and details
Administrator can authenticate using credentials
Changes reflected immediately in authorization decisions

Failure Postconditions

No admin record created/modified if validation fails
Error message logged with security context
Failed attempt recorded in audit log
Original state maintained if transaction fails
Administrator notified of access denial if applicable

Triggers

Super administrator accesses admin user management interface
Administrator creation/update form submitted
API client calls admin user management endpoints
Scheduled password expiration notification
Failed login attempts trigger account lockout
System startup with empty admin user table

Basic Flow (Happy Path)

sequenceDiagram actor SuperAdmin as Super Administrator participant Web as Web Admin UI participant API as Application Manager API participant DB as Configuration Database participant Audit as Audit Service participant Email as Email Service SuperAdmin->>Web: Navigate to Admin Users page Web->>API: GET /api/v1/admin-users API->>DB: Query all admin users DB->>API: Return admin user list API->>Web: Return paginated admin users Web->>SuperAdmin: Display admin user list SuperAdmin->>Web: Click "Create New Administrator" Web->>SuperAdmin: Display admin creation form SuperAdmin->>Web: Submit form (username, email, name, role) Web->>API: POST /api/v1/admin-users API->>API: Validate input data API->>DB: Check username uniqueness DB->>API: Username available API->>API: Generate secure temporary password API->>API: Hash password (bcrypt, cost=12) API->>API: Set RequirePasswordChange=true API->>DB: Create admin user record DB->>API: Admin created successfully API->>Audit: Log admin creation event Audit->>Audit: Store: Actor, Action, Target, Timestamp API->>Email: Send welcome email with temp password Email->>SuperAdmin: Confirmation email Email->>NewAdmin: Welcome email with credentials API->>Web: 201 Created (admin details) Web->>SuperAdmin: Show success message Note over SuperAdmin,Web: New admin can now login NewAdmin->>Web: Login with temporary password Web->>API: POST /api/v1/auth/login API->>DB: Validate credentials DB->>API: Credentials valid, RequirePasswordChange=true API->>Web: Redirect to password change Web->>NewAdmin: Force password change screen NewAdmin->>Web: Submit new password Web->>API: POST /api/v1/auth/change-password API->>API: Validate password complexity API->>API: Hash new password API->>DB: Update password, set RequirePasswordChange=false API->>Audit: Log password change event API->>Web: Password changed successfully Web->>NewAdmin: Redirect to dashboard

Detailed Steps

Administrator Accesses Management Interface
- Super administrator logs into Application Manager
- Navigates to Admin Users section
- System displays list of existing administrators
- List includes: username, full name, email, roles, status, last login
Administrator Initiates User Creation
- Clicks "Create New Administrator" button
- System displays admin creation form with fields:
  - Username (required, unique, 3-50 characters)
  - Full Name (required, 2-100 characters)
  - Email Address (required, unique, valid format)
  - Role(s) (required, multi-select)
  - Initial Status (default: Active)
  - Send Welcome Email (checkbox, default: true)
  - Notes (optional, admin comments)
Administrator Provides Information
- Enters required and optional fields
- Selects one or more roles from available options
- Reviews and submits form
System Validates Input
- Check all required fields present
- Validate username format (alphanumeric, underscore, dash)
- Verify username uniqueness in Configuration database
- Validate email format (RFC 5322)
- Verify email uniqueness
- Validate selected roles exist and are valid
- Check creating user has permission to assign selected roles
System Creates Administrator Account
- Generate unique admin user ID (GUID)
- Generate secure temporary password (16 characters, mixed case, numbers, symbols)
- Hash password using bcrypt with cost factor 12
- Set IsActive = true
- Set RequirePasswordChange = true
- Set PasswordExpiresAt = CreatedAt + 90 days (configurable)
- Set AccountLockedUntil = null
- Set FailedLoginAttempts = 0
- Store creation timestamp and creating admin ID
- Initialize MFA settings (enabled but not configured)
System Assigns Roles
- For each selected role:
  - Create AdminUserRole record
  - Link admin user ID to role ID
  - Set AssignedAt timestamp
  - Set AssignedBy to creating admin's ID
System Records Audit Trail
- Create audit log entry:
  - Action: "AdminUserCreated"
  - Actor: Creating administrator ID and username
  - Target: New administrator ID and username
  - Details: JSON with roles, email, status
  - Timestamp: Current UTC time
  - IP Address: Request IP
  - User Agent: Request user agent
System Sends Welcome Email
- Compose email with:
  - Welcome message
  - Username
  - Temporary password
  - Application Manager login URL
  - Password change requirement notice
  - Password expiration policy (90 days)
  - MFA setup instructions
  - Support contact information
- Send via configured email provider
- Log email delivery attempt
System Returns Success Response
- Return 201 Created status
- Include sanitized admin details (no password)
- Provide next steps for new administrator
New Administrator First Login
- New admin navigates to login page
- Enters username and temporary password
- System validates credentials
- System detects RequirePasswordChange = true
- System redirects to mandatory password change screen
Administrator Changes Password
- System displays password change form
- Administrator enters new password (twice for confirmation)
- System validates password meets complexity requirements
- System ensures new password differs from temporary password
- System updates password hash and sets RequirePasswordChange = false
- System logs password change in audit trail
- Administrator is redirected to dashboard
Administrator Accesses System
- Administrator can now use full system features
- System enforces role-based access control
- All actions are logged in audit trail

Alternative Flows

Alt Flow 1: Updating Existing Administrator

sequenceDiagram actor SuperAdmin as Super Administrator participant Web as Web Admin UI participant API as Application Manager API participant DB as Configuration Database participant Audit as Audit Service participant Email as Email Service SuperAdmin->>Web: Select admin user to edit Web->>API: GET /api/v1/admin-users/{id} API->>DB: Query admin user details DB->>API: Return admin user data API->>Web: Return admin details Web->>SuperAdmin: Display edit form (pre-filled) SuperAdmin->>Web: Update fields (name, email, roles) Web->>API: PUT /api/v1/admin-users/{id} API->>API: Validate changes API->>DB: Check email uniqueness (if changed) DB->>API: Email available or unchanged API->>DB: Update admin user record DB->>API: Update successful API->>DB: Update role assignments (add/remove) DB->>API: Roles updated API->>Audit: Log admin update event Audit->>Audit: Record all field changes API->>Email: Send notification (if email changed) Email->>Admin: Your account has been updated API->>Web: 200 OK (updated details) Web->>SuperAdmin: Show success message

Steps:

Super administrator selects existing admin from list
System loads current admin details into edit form
Administrator modifies fields (name, email, roles, status, notes)
System validates changes
System updates record in database
System updates role assignments (adds new roles, removes deselected roles)
System logs all changes in audit trail with before/after values
If email changed, system sends notification to old and new addresses
System returns success confirmation

Business Rules:

Cannot change own roles (prevents privilege escalation)
Cannot deactivate self (prevents admin lockout)
Cannot remove last super administrator role from system
Email changes require re-verification (optional)

Alt Flow 2: Password Reset (Administrator-Initiated)

sequenceDiagram actor SuperAdmin as Super Administrator participant Web as Web Admin UI participant API as Application Manager API participant DB as Configuration Database participant Audit as Audit Service participant Email as Email Service SuperAdmin->>Web: Select admin, click "Reset Password" Web->>SuperAdmin: Confirm password reset SuperAdmin->>Web: Confirm action Web->>API: POST /api/v1/admin-users/{id}/reset-password API->>API: Generate new temporary password API->>API: Hash password (bcrypt) API->>DB: Update password hash API->>DB: Set RequirePasswordChange=true API->>DB: Increment PasswordResetCount DB->>API: Update successful API->>Audit: Log password reset event Audit->>Audit: Record: Actor, Target, Reason, Timestamp API->>Email: Send password reset email Email->>Admin: Your password has been reset API->>Web: 200 OK (confirmation) Web->>SuperAdmin: Display new temp password (one-time)

Steps:

Super administrator selects admin user
Clicks "Reset Password" action
System prompts for confirmation with reason (optional)
System generates new secure temporary password
System hashes password and updates database
System sets RequirePasswordChange = true
System increments PasswordResetCount counter
System logs password reset in audit trail with actor and reason
System sends email to administrator
System displays temporary password to super admin (shown only once)
Administrator must change password on next login

sequenceDiagram actor Admin as Administrator participant Web as Web Login participant API as Auth API participant DB as Configuration Database participant Audit as Audit Service participant Email as Email Service loop Failed Login Attempts Admin->>Web: Login with incorrect password Web->>API: POST /api/v1/auth/login API->>DB: Validate credentials DB->>API: Invalid password API->>DB: Increment FailedLoginAttempts API->>Audit: Log failed login attempt alt Attempts < 5 API->>Web: 401 Unauthorized Web->>Admin: "Invalid credentials. X attempts remaining." else Attempts >= 5 API->>DB: Set AccountLockedUntil = Now + 30 minutes API->>Audit: Log account lockout event API->>Email: Send lockout notification Email->>Admin: Your account has been locked API->>Web: 403 Forbidden Web->>Admin: "Account locked due to failed attempts. Try again in 30 minutes." end end Note over Admin: Wait 30 minutes or contact super admin Admin->>Web: Login after lockout period Web->>API: POST /api/v1/auth/login API->>DB: Check AccountLockedUntil DB->>API: Lockout expired API->>DB: Reset FailedLoginAttempts=0 API->>DB: Validate credentials DB->>API: Credentials valid API->>Web: 200 OK (session token) Web->>Admin: Login successful

Steps:

Administrator attempts login with incorrect password
System validates credentials (fail)
System increments FailedLoginAttempts counter
System logs failed attempt in audit trail with IP and user agent
If attempts < 5:
- Return 401 Unauthorized
- Display remaining attempts to user
If attempts >= 5:
- Set AccountLockedUntil = CurrentTime + 30 minutes
- Return 403 Forbidden
- Log account lockout event
- Send lockout notification email to administrator
- Display lockout message with duration
Administrator must wait for lockout period to expire OR contact super admin for manual unlock
After lockout expires, next successful login resets counter

Manual Unlock by Super Admin:

Super administrator accesses locked admin user
Clicks "Unlock Account" button
System sets AccountLockedUntil = null
System resets FailedLoginAttempts = 0
System logs manual unlock in audit trail
System sends notification to administrator
Administrator can login immediately

Alt Flow 4: Deactivating Administrator Account

sequenceDiagram actor SuperAdmin as Super Administrator participant Web as Web Admin UI participant API as Application Manager API participant DB as Configuration Database participant Audit as Audit Service participant SessionStore as Session Store participant Email as Email Service SuperAdmin->>Web: Select admin, click "Deactivate" Web->>SuperAdmin: Confirm deactivation (reason required) SuperAdmin->>Web: Provide reason, confirm Web->>API: PUT /api/v1/admin-users/{id}/deactivate API->>API: Validate not deactivating self API->>API: Validate not last super admin API->>DB: Update IsActive=false API->>DB: Set DeactivatedAt=now API->>DB: Set DeactivatedBy=actor ID API->>DB: Store DeactivationReason DB->>API: Update successful API->>SessionStore: Revoke all active sessions SessionStore->>API: Sessions revoked API->>Audit: Log account deactivation Audit->>Audit: Store: Actor, Target, Reason, Timestamp API->>Email: Send deactivation notice Email->>Admin: Your account has been deactivated API->>Web: 200 OK (confirmation) Web->>SuperAdmin: "Account deactivated successfully"

Steps:

Super administrator selects admin user to deactivate
Clicks "Deactivate Account" button
System displays confirmation dialog with reason field (required)
Administrator provides deactivation reason
System validates:
- Actor is not attempting to deactivate own account
- Not deactivating the last super administrator
System updates admin record:
- Set IsActive = false
- Set DeactivatedAt = CurrentTime
- Set DeactivatedBy = ActorAdminId
- Store deactivation reason in Notes or separate field
System revokes all active sessions for deactivated administrator
System logs deactivation in audit trail
System sends notification email to deactivated administrator
System returns success confirmation
Deactivated administrator cannot login (authentication fails)
Deactivated administrator still visible in admin list (filtered by status)

Reactivation Process:

Super administrator can reactivate by clicking "Reactivate Account"
System sets IsActive = true
System clears deactivation fields
System logs reactivation event
System sends reactivation email
Administrator can login with existing credentials

Alt Flow 5: Bulk Operations

flowchart TD A[Super admin selects multiple admins] --> B{Select bulk action} B -->|Deactivate| C[Confirm bulk deactivation] B -->|Change roles| D[Select new roles to apply] B -->|Send email| E[Compose bulk email] B -->|Export data| F[Generate CSV export] C --> C1[Validate each admin] C1 --> C2{All validations pass?} C2 -->|Yes| C3[Execute deactivations] C2 -->|No| C4[Report errors, skip invalid] C3 --> G[Log all changes] C4 --> G D --> D1[Validate role assignments] D1 --> D2[Apply roles to all selected] D2 --> G E --> E1[Send to all selected admins] E1 --> G F --> F1[Generate export with selected fields] F1 --> H[Download CSV file] G --> I[Display success summary] I --> J[Show: X successful, Y failed]

Supported Bulk Operations:

Bulk Deactivate: Deactivate multiple administrators at once
Bulk Role Assignment: Add or remove roles from multiple administrators
Bulk Email: Send notification to selected administrators
Bulk Export: Export selected admin data to CSV
Bulk Password Expiration: Force password change for multiple admins

Business Rules:

Maximum 50 administrators per bulk operation
Cannot bulk deactivate self
Must maintain at least one active super administrator
All bulk operations logged individually in audit trail
Failed operations reported with reasons
Partial success allowed (continues on per-admin errors)

Alt Flow 6: Default Admin Account Creation on First Startup

sequenceDiagram participant System as System Startup participant DB as Configuration Database participant Audit as Audit Service participant Log as Application Log System->>DB: Check if any admin users exist DB->>System: Count = 0 (no admins) System->>System: Generate default admin credentials Note over System: Username: admin<br/>Password: Admin@2026! System->>System: Hash password (bcrypt) System->>System: Create default super admin roles System->>DB: Create default admin user System->>DB: Assign SuperAdministrator role DB->>System: Admin created successfully System->>Audit: Log default admin creation System->>Log: Log credentials to application log Note over Log: IMPORTANT: Change default password immediately! System->>System: Continue startup process

Steps:

Application Manager starts up
During initialization, system checks Configuration database for admin users
If count of admin users = 0:
- Generate default admin account:
  - Username: admin
  - Password: Admin@2026!
  - Full Name: "Default Administrator"
  - Email: admin@localhost (must be changed)
  - Role: SuperAdministrator
  - RequirePasswordChange = true
  - IsActive = true
- Hash password using bcrypt
- Create admin user record in database
- Assign SuperAdministrator role
- Log creation in audit trail
- Log credentials to application log with security warning
- Display warning in console: "DEFAULT ADMIN CREATED - CHANGE PASSWORD IMMEDIATELY"
System continues normal startup
Admin user can login with default credentials
System forces password change on first login

Security Warning:

╔═══════════════════════════════════════════════════════════════╗
║ WARNING: DEFAULT ADMINISTRATOR ACCOUNT CREATED                ║
║                                                               ║
║ Username: admin                                               ║
║ Password: Admin@2026!                                         ║
║                                                               ║
║ CHANGE THIS PASSWORD IMMEDIATELY FOR SECURITY!                ║
╚═══════════════════════════════════════════════════════════════╝

Alt Flow 7: Role-Based Access Control Changes

Scenario: Administrator roles determine what actions they can perform. Changing roles affects permissions.

Steps:

Super administrator updates admin user's roles
System validates new role assignments
System removes old role assignments
System creates new role assignments
System logs role changes in audit trail
If administrator has active sessions:
- Option A: Revoke sessions, force re-login (strict)
- Option B: Apply changes on next token refresh (graceful)
- Option C: Notify administrator of pending changes
System sends notification email about role changes
Administrator's permissions reflect new roles

Available Roles:

SuperAdministrator: Full system access, can manage all admins
ApplicationAdministrator: Manage applications and configurations
UserAdministrator: Manage trial users only
ReportingAdministrator: Access to reports and analytics
AuditorAdministrator: Read-only access to audit logs and monitoring
SupportAdministrator: Limited access for support operations

Business Rules

Rule ID	Description	Enforcement
BR-001	Admin usernames must be unique in Configuration database	Database unique constraint + API validation
BR-002	Admin email addresses must be unique	Database unique constraint + API validation
BR-003	Password must meet complexity: 12+ chars, uppercase, lowercase, number, special	API validation on create/change
BR-004	Password hashes use bcrypt with cost factor 12 minimum	Password hashing implementation
BR-005	Passwords expire after 90 days (configurable)	Authentication service + periodic check
BR-006	Account locks after 5 failed login attempts for 30 minutes	Authentication service
BR-007	Cannot deactivate own account	API business logic validation
BR-008	Cannot remove last SuperAdministrator role from system	API business logic validation
BR-009	New admins must change temporary password on first login	Authentication service
BR-010	All admin operations logged in audit trail	AOP interceptor/middleware
BR-011	Default admin account (admin/Admin@2026!) created if no admins exist	Application startup initialization
BR-012	MFA required for SuperAdministrator role (configurable)	Authentication service
BR-013	Admin sessions expire after 12 hours of inactivity	Session management service
BR-014	Password history: cannot reuse last 5 passwords	Password change validation
BR-015	Username format: 3-50 chars, alphanumeric, underscore, dash	API validation

Data Requirements

Important: AdminUser is stored in the Configuration database and is separate from the Identity user hierarchy (User → TrialUser/ApplicationUser). AdminUsers manage the Application Manager itself, while Identity users use the managed applications.

For Identity user types (TrialUser, ApplicationUser), see UC-001 Data Requirements section.

Admin User Record (Configuration Database)

{
  "Id": "uuid-v4",
  "Username": "string (required, unique, 3-50 chars)",
  "PasswordHash": "string (required, bcrypt)",
  "PasswordSalt": "string (optional, if using salt)",
  "FullName": "string (required, 2-100 chars)",
  "Email": "string (required, unique, valid format)",
  "IsActive": "boolean (default: true)",
  "RequirePasswordChange": "boolean (default: true)",
  "PasswordSetAt": "datetime (UTC)",
  "PasswordExpiresAt": "datetime (UTC)",
  "AccountLockedUntil": "datetime (UTC, nullable)",
  "FailedLoginAttempts": "integer (default: 0)",
  "LastLoginAt": "datetime (UTC, nullable)",
  "LastLoginIp": "string (nullable)",
  "LoginCount": "integer (default: 0)",
  "CreatedAt": "datetime (UTC)",
  "CreatedBy": "uuid-v4 (nullable for system-created)",
  "UpdatedAt": "datetime (UTC)",
  "UpdatedBy": "uuid-v4 (nullable)",
  "DeactivatedAt": "datetime (UTC, nullable)",
  "DeactivatedBy": "uuid-v4 (nullable)",
  "DeactivationReason": "string (nullable)",
  "MfaEnabled": "boolean (default: true)",
  "MfaSecret": "string (encrypted, nullable)",
  "MfaVerifiedAt": "datetime (UTC, nullable)",
  "PasswordResetCount": "integer (default: 0)",
  "LastPasswordResetAt": "datetime (UTC, nullable)",
  "Notes": "string (nullable, admin comments)"
}

Admin User Role Assignment

{
  "Id": "uuid-v4",
  "AdminUserId": "uuid-v4 (foreign key)",
  "RoleId": "uuid-v4 (foreign key)",
  "RoleName": "string (denormalized for queries)",
  "AssignedAt": "datetime (UTC)",
  "AssignedBy": "uuid-v4 (admin who assigned)"
}

Role Definition

{
  "Id": "uuid-v4",
  "RoleName": "string (unique)",
  "DisplayName": "string",
  "Description": "string",
  "Permissions": "array of strings (permission identifiers)",
  "IsSystemRole": "boolean (cannot be deleted)",
  "CreatedAt": "datetime (UTC)",
  "UpdatedAt": "datetime (UTC)"
}

Password History (for password reuse prevention)

{
  "Id": "uuid-v4",
  "AdminUserId": "uuid-v4 (foreign key)",
  "PasswordHash": "string (bcrypt)",
  "SetAt": "datetime (UTC)"
}

Audit Log Entry

{
  "Id": "uuid-v4",
  "Timestamp": "datetime (UTC)",
  "Action": "string (AdminUserCreated, AdminUserUpdated, etc.)",
  "ActorId": "uuid-v4 (admin who performed action)",
  "ActorUsername": "string",
  "TargetId": "uuid-v4 (affected admin user)",
  "TargetUsername": "string",
  "Details": "json (before/after values, additional context)",
  "IpAddress": "string",
  "UserAgent": "string",
  "Severity": "string (Info, Warning, Critical)"
}

Email Templates

Welcome Email (New Admin):
- Subject: "Welcome to Riptide Application Manager - Administrator Access"
- Body includes: username, temporary password, login URL, password change requirement, MFA setup, support contact
Password Reset Email:
- Subject: "Your Administrator Password Has Been Reset"
- Body includes: notification of reset, temporary password (or link), who initiated reset, support contact
Account Locked Email:
- Subject: "Your Administrator Account Has Been Locked"
- Body includes: lockout reason, duration, unlock time, support contact for manual unlock
Account Deactivated Email:
- Subject: "Your Administrator Account Has Been Deactivated"
- Body includes: deactivation reason, who deactivated, support contact
Role Changed Email:
- Subject: "Your Administrator Roles Have Been Updated"
- Body includes: new roles, old roles, effective immediately, support contact
Password Expiration Warning:
- Subject: "Your Administrator Password Expires Soon"
- Body includes: expiration date (sent at 14, 7, 3, 1 days before), password change instructions

User Interface

Admin User List Page

┌─────────────────────────────────────────────────────────────────────────┐
│  Administrator Users                                    [+ Create New]   │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                          │
│  Filters: [Status ▼] [Role ▼] [Search username or email...]         │
│                                                                          │
│  ☐ Select All    Bulk Actions: [Deactivate ▼]                          │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │ ☐  Username      Full Name         Email            Roles  Status │ │
│  ├────────────────────────────────────────────────────────────────────┤ │
│  │ ☐  admin         Default Admin     admin@localhost  SA     🟢     │ │
│  │                  Last Login: 2026-01-30 09:15 AM             [Edit]│ │
│  │                                                                     │ │
│  │ ☐  jsmith        John Smith        john@example.com AA,UA  🟢     │ │
│  │                  Last Login: 2026-01-29 03:42 PM             [Edit]│ │
│  │                                                                     │ │
│  │ ☐  mjones        Mary Jones        mary@example.com RA     🔴     │ │
│  │                  Deactivated: 2026-01-25                     [Edit]│ │
│  │                  Reason: Left organization                          │ │
│  │                                                                     │ │
│  │ ☐  bwilson       Bob Wilson        bob@example.com  SA     🔒     │ │
│  │                  Locked: Failed login attempts               [Edit]│ │
│  │                  Unlocks: 2026-01-30 10:30 AM                      │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
│  Showing 4 of 4 administrators                      « 1 »               │
│                                                                          │
│  Legend: SA=Super Admin, AA=App Admin, UA=User Admin, RA=Reporting     │
│          🟢=Active, 🔴=Inactive, 🔒=Locked                             │
└─────────────────────────────────────────────────────────────────────────┘

Create Administrator Form

┌─────────────────────────────────────────────────────────────────────────┐
│  Create New Administrator                                [Cancel] [Save] │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                          │
│  Basic Information                                                       │
│  ─────────────────                                                       │
│                                                                          │
│  Username *                                                              │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ jdoe                                                              │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│  3-50 characters, letters, numbers, underscore, dash                     │
│                                                                          │
│  Full Name *                                                             │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Jane Doe                                                          │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  Email Address *                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ jane.doe@example.com                                              │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  Roles and Permissions *                                                 │
│  ─────────────────────────                                               │
│                                                                          │
│  ☐ Super Administrator (Full system access)                             │
│  ☑ Application Administrator (Manage applications)                      │
│  ☑ User Administrator (Manage trial users)                              │
│  ☐ Reporting Administrator (Access reports)                             │
│  ☐ Auditor Administrator (View audit logs)                              │
│  ☐ Support Administrator (Support operations)                           │
│                                                                          │
│  Account Settings                                                        │
│  ────────────────                                                        │
│                                                                          │
│  ☑ Account Active (user can login immediately)                          │
│  ☑ Require password change on first login                               │
│  ☑ Enable multi-factor authentication                                   │
│  ☑ Send welcome email with credentials                                  │
│                                                                          │
│  Password expires in: [90 ▼] days (0 = never expires)                   │
│                                                                          │
│  Notes (optional)                                                        │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Application administrator for Fee Manager and Value Manager       │  │
│  │                                                                   │  │
│  │                                                                   │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  * Required fields                                                       │
│                                                                          │
│                                              [Cancel]  [Create Account]  │
└─────────────────────────────────────────────────────────────────────────┘

Edit Administrator Form

┌─────────────────────────────────────────────────────────────────────────┐
│  Edit Administrator: jsmith                          [Cancel] [Save]     │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                          │
│  [Account Details] [Security] [Activity Log] [Sessions]                 │
│                                                                          │
│  Basic Information                                                       │
│  ─────────────────                                                       │
│                                                                          │
│  Username: jsmith (cannot be changed)                                    │
│                                                                          │
│  Full Name *                                                             │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ John Smith                                                        │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  Email Address *                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ john.smith@example.com                                            │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  Roles and Permissions *                                                 │
│  ─────────────────────────                                               │
│                                                                          │
│  ☐ Super Administrator                                                   │
│  ☑ Application Administrator                                             │
│  ☑ User Administrator                                                    │
│  ☐ Reporting Administrator                                               │
│  ☐ Auditor Administrator                                                 │
│  ☐ Support Administrator                                                 │
│                                                                          │
│  Account Status                                                          │
│  ──────────────                                                          │
│                                                                          │
│  Status: 🟢 Active        [Deactivate Account]                          │
│  Created: 2025-11-15 by admin                                            │
│  Last Updated: 2026-01-20 by admin                                       │
│  Last Login: 2026-01-29 03:42 PM from 192.168.1.100                     │
│  Login Count: 247                                                        │
│                                                                          │
│  Password Management                                                     │
│  ──────────────────────                                                  │
│                                                                          │
│  Password set: 2025-12-01                                                │
│  Password expires: 2026-03-01 (30 days remaining)                        │
│                                                                          │
│  [Reset Password]  [Force Password Change]  [Extend Expiration]         │
│                                                                          │
│  Security Settings                                                       │
│  ─────────────────                                                       │
│                                                                          │
│  ☑ Multi-factor authentication enabled                                  │
│     MFA configured: 2025-11-16                                           │
│     [Reset MFA]                                                          │
│                                                                          │
│  Failed login attempts: 0                                                │
│  Account locked: No                                                      │
│                                                                          │
│  Notes                                                                   │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Primary admin for Fee Manager application                        │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│                                              [Cancel]  [Save Changes]    │
└─────────────────────────────────────────────────────────────────────────┘

Admin Activity Log Tab

┌─────────────────────────────────────────────────────────────────────────┐
│  Activity Log: jsmith                                                    │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                          │
│  Filter: [Last 30 days ▼] [All actions ▼]              [Export CSV]     │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │ Timestamp           Action                 Details            IP   │ │
│  ├────────────────────────────────────────────────────────────────────┤ │
│  │ 2026-01-30 09:15 AM Login successful       Session created    .100 │ │
│  │ 2026-01-29 03:42 PM Login successful       Session created    .100 │ │
│  │ 2026-01-29 03:41 PM Failed login attempt   Invalid password   .100 │ │
│  │ 2026-01-28 10:22 AM Updated trial user     user@example.com   .100 │ │
│  │ 2026-01-28 09:15 AM Login successful       Session created    .100 │ │
│  │ 2026-01-27 02:33 PM Created trial user     test@example.com   .100 │ │
│  │ 2026-01-27 02:10 PM Login successful       Session created    .50  │ │
│  │ 2026-01-26 04:55 PM Password changed       Self-initiated     .100 │ │
│  │ 2026-01-26 04:50 PM Login successful       Session created    .100 │ │
│  │ 2026-01-25 11:30 AM Roles updated           Added: Reporting   .100 │ │
│  │                     By: admin                                       │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
│  Showing 10 of 247 events                       « 1 2 3 ... 25 »        │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│  🔒 Password Change Required                                            │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                                                          │
│  Welcome, jdoe! You must change your temporary password before          │
│  accessing the system.                                                   │
│                                                                          │
│  Current Password (temporary)                                            │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ ••••••••••••••••                                                  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  New Password *                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ ••••••••••••••••                                                  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  Password Strength: ▓▓▓▓▓▓▓▓░░░░ Strong                                │
│                                                                          │
│  Confirm New Password *                                                  │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ ••••••••••••••••                                                  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  Password Requirements:                                                  │
│  ✅ At least 12 characters                                              │
│  ✅ Contains uppercase letter                                           │
│  ✅ Contains lowercase letter                                           │
│  ✅ Contains number                                                      │
│  ✅ Contains special character (!@#$%^&*...)                            │
│  ✅ Different from temporary password                                   │
│                                                                          │
│  ℹ️ Your password will expire in 90 days                                │
│                                                                          │
│                                          [Change Password and Continue]  │
└─────────────────────────────────────────────────────────────────────────┘

API Endpoints

List Admin Users

Endpoint: GET /api/v1/admin-users

Authentication: Admin session token (requires UserAdministrator or SuperAdministrator role)

Query Parameters:

page (integer, default: 1)
pageSize (integer, default: 20, max: 100)
status (string: "active", "inactive", "locked", "all", default: "all")
role (string: role name filter, optional)
search (string: search in username, name, email)
sortBy (string: "username", "fullName", "lastLogin", "createdAt", default: "username")
sortOrder (string: "asc", "desc", default: "asc")

Success Response: 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "jsmith",
      "fullName": "John Smith",
      "email": "john.smith@example.com",
      "isActive": true,
      "roles": [
        {
          "id": "role-id-1",
          "roleName": "ApplicationAdministrator",
          "displayName": "Application Administrator"
        }
      ],
      "lastLoginAt": "2026-01-29T15:42:00Z",
      "loginCount": 247,
      "accountLocked": false,
      "passwordExpiresAt": "2026-03-01T00:00:00Z",
      "mfaEnabled": true,
      "createdAt": "2025-11-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 4,
    "totalPages": 1
  }
}

Error Responses:

401 Unauthorized - Invalid or missing authentication
403 Forbidden - Insufficient permissions

Create Admin User

Endpoint: POST /api/v1/admin-users

Authentication: Admin session token (requires SuperAdministrator role)

Request Body:

{
  "username": "jdoe",
  "fullName": "Jane Doe",
  "email": "jane.doe@example.com",
  "roleIds": [
    "role-id-app-admin",
    "role-id-user-admin"
  ],
  "isActive": true,
  "requirePasswordChange": true,
  "enableMfa": true,
  "passwordExpirationDays": 90,
  "sendWelcomeEmail": true,
  "notes": "Application administrator for Fee Manager"
}

Success Response: 201 Created

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "username": "jdoe",
  "fullName": "Jane Doe",
  "email": "jane.doe@example.com",
  "isActive": true,
  "requirePasswordChange": true,
  "roles": [
    {
      "id": "role-id-app-admin",
      "roleName": "ApplicationAdministrator",
      "displayName": "Application Administrator"
    }
  ],
  "temporaryPassword": "TempPass123!@#$%",
  "passwordExpiresAt": "2026-04-30T00:00:00Z",
  "mfaEnabled": true,
  "createdAt": "2026-01-30T10:30:00Z",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Administrator created successfully. Welcome email sent."
}

Error Responses:

400 Bad Request - Validation error

{
  "error": "ValidationError",
  "message": "One or more validation errors occurred",
  "errors": {
    "username": ["Username must be 3-50 characters"],
    "email": ["Email address is already in use"],
    "roleIds": ["At least one role must be assigned"]
  }
}

403 Forbidden - Insufficient permissions

{
  "error": "Forbidden",
  "message": "Only Super Administrators can create admin users"
}

409 Conflict - Duplicate username/email

{
  "error": "DuplicateUsername",
  "message": "Username 'jdoe' is already in use"
}

Get Admin User by ID

Endpoint: GET /api/v1/admin-users/{id}

Authentication: Admin session token

Success Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "jsmith",
  "fullName": "John Smith",
  "email": "john.smith@example.com",
  "isActive": true,
  "requirePasswordChange": false,
  "roles": [
    {
      "id": "role-id-1",
      "roleName": "ApplicationAdministrator",
      "displayName": "Application Administrator",
      "assignedAt": "2025-11-15T10:00:00Z",
      "assignedBy": "admin-id"
    }
  ],
  "passwordSetAt": "2025-12-01T00:00:00Z",
  "passwordExpiresAt": "2026-03-01T00:00:00Z",
  "accountLockedUntil": null,
  "failedLoginAttempts": 0,
  "lastLoginAt": "2026-01-29T15:42:00Z",
  "lastLoginIp": "192.168.1.100",
  "loginCount": 247,
  "mfaEnabled": true,
  "mfaVerifiedAt": "2025-11-16T09:00:00Z",
  "createdAt": "2025-11-15T10:00:00Z",
  "createdBy": "admin-id",
  "updatedAt": "2026-01-20T14:30:00Z",
  "updatedBy": "admin-id",
  "notes": "Primary admin for Fee Manager"
}

Error Responses:

404 Not Found - Admin user not found

Update Admin User

Endpoint: PUT /api/v1/admin-users/{id}

Authentication: Admin session token (requires SuperAdministrator role)

Request Body:

{
  "fullName": "John Smith Jr.",
  "email": "john.smith.jr@example.com",
  "roleIds": [
    "role-id-app-admin",
    "role-id-reporting-admin"
  ],
  "isActive": true,
  "passwordExpirationDays": 90,
  "enableMfa": true,
  "notes": "Updated contact email"
}

Success Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "jsmith",
  "fullName": "John Smith Jr.",
  "email": "john.smith.jr@example.com",
  "isActive": true,
  "roles": [
    {
      "id": "role-id-app-admin",
      "roleName": "ApplicationAdministrator",
      "displayName": "Application Administrator"
    },
    {
      "id": "role-id-reporting-admin",
      "roleName": "ReportingAdministrator",
      "displayName": "Reporting Administrator"
    }
  ],
  "updatedAt": "2026-01-30T10:45:00Z",
  "updatedBy": "660e8400-e29b-41d4-a716-446655440001",
  "message": "Administrator updated successfully. Notification email sent."
}

Error Responses:

400 Bad Request - Validation error
403 Forbidden - Cannot modify own roles or insufficient permissions
404 Not Found - Admin user not found
409 Conflict - Email already in use

Deactivate Admin User

Endpoint: PUT /api/v1/admin-users/{id}/deactivate

Authentication: Admin session token (requires SuperAdministrator role)

Request Body:

{
  "reason": "Employee left organization",
  "revokeActiveSessions": true
}

Success Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "jsmith",
  "isActive": false,
  "deactivatedAt": "2026-01-30T10:50:00Z",
  "deactivatedBy": "660e8400-e29b-41d4-a716-446655440001",
  "deactivationReason": "Employee left organization",
  "activeSessionsRevoked": 2,
  "message": "Administrator deactivated successfully"
}

Error Responses:

400 Bad Request - Cannot deactivate self
403 Forbidden - Cannot deactivate last super administrator
404 Not Found - Admin user not found

Reactivate Admin User

Endpoint: PUT /api/v1/admin-users/{id}/reactivate

Authentication: Admin session token (requires SuperAdministrator role)

Request Body:

{
  "resetPassword": true,
  "sendWelcomeEmail": true
}

Success Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "jsmith",
  "isActive": true,
  "reactivatedAt": "2026-02-15T09:00:00Z",
  "reactivatedBy": "660e8400-e29b-41d4-a716-446655440001",
  "requirePasswordChange": true,
  "temporaryPassword": "NewTemp456!@#",
  "message": "Administrator reactivated successfully"
}

Reset Password

Endpoint: POST /api/v1/admin-users/{id}/reset-password

Authentication: Admin session token (requires SuperAdministrator role)

Request Body:

{
  "reason": "Forgot password",
  "sendEmail": true
}

Success Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "jsmith",
  "temporaryPassword": "ResetPass789!@#$",
  "requirePasswordChange": true,
  "passwordResetAt": "2026-01-30T11:00:00Z",
  "passwordResetBy": "660e8400-e29b-41d4-a716-446655440001",
  "message": "Password reset successfully. Email sent to user."
}

Unlock Account

Endpoint: POST /api/v1/admin-users/{id}/unlock

Authentication: Admin session token (requires SuperAdministrator role)

Request Body:

{
  "reason": "False positive - legitimate access attempts"
}

Success Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "jsmith",
  "accountLocked": false,
  "accountLockedUntil": null,
  "failedLoginAttempts": 0,
  "unlockedAt": "2026-01-30T11:05:00Z",
  "unlockedBy": "660e8400-e29b-41d4-a716-446655440001",
  "message": "Account unlocked successfully"
}

Get Admin Activity Log

Endpoint: GET /api/v1/admin-users/{id}/activity

Authentication: Admin session token

Query Parameters:

page (integer, default: 1)
pageSize (integer, default: 50, max: 200)
startDate (ISO 8601 date, optional)
endDate (ISO 8601 date, optional)
actionType (string: filter by action type, optional)

Success Response: 200 OK

{
  "adminUserId": "550e8400-e29b-41d4-a716-446655440000",
  "username": "jsmith",
  "data": [
    {
      "id": "audit-id-1",
      "timestamp": "2026-01-30T09:15:00Z",
      "action": "LoginSuccessful",
      "details": {
        "sessionId": "session-123",
        "ipAddress": "192.168.1.100",
        "userAgent": "Mozilla/5.0..."
      },
      "severity": "Info"
    },
    {
      "id": "audit-id-2",
      "timestamp": "2026-01-29T15:42:00Z",
      "action": "TrialUserUpdated",
      "details": {
        "targetUserId": "trial-user-id",
        "targetEmail": "user@example.com",
        "changedFields": ["companyName", "notes"]
      },
      "severity": "Info"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 247,
    "totalPages": 5
  }
}

Get Active Sessions

Endpoint: GET /api/v1/admin-users/{id}/sessions

Authentication: Admin session token

Success Response: 200 OK

{
  "adminUserId": "550e8400-e29b-41d4-a716-446655440000",
  "username": "jsmith",
  "sessions": [
    {
      "id": "session-123",
      "createdAt": "2026-01-30T09:15:00Z",
      "lastActivityAt": "2026-01-30T11:30:00Z",
      "expiresAt": "2026-01-30T21:15:00Z",
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "isCurrentSession": true
    },
    {
      "id": "session-124",
      "createdAt": "2026-01-30T08:00:00Z",
      "lastActivityAt": "2026-01-30T10:00:00Z",
      "expiresAt": "2026-01-30T20:00:00Z",
      "ipAddress": "192.168.1.50",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X)",
      "isCurrentSession": false
    }
  ],
  "totalActiveSessions": 2
}

Revoke Session

Endpoint: DELETE /api/v1/admin-users/{id}/sessions/{sessionId}

Authentication: Admin session token (SuperAdministrator or session owner)

Success Response: 200 OK

{
  "sessionId": "session-124",
  "revokedAt": "2026-01-30T11:35:00Z",
  "revokedBy": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Session revoked successfully"
}

Bulk Operations

Endpoint: POST /api/v1/admin-users/bulk

Authentication: Admin session token (requires SuperAdministrator role)

Request Body:

{
  "operation": "deactivate",
  "adminUserIds": [
    "admin-id-1",
    "admin-id-2",
    "admin-id-3"
  ],
  "parameters": {
    "reason": "Organizational restructuring",
    "revokeActiveSessions": true
  }
}

Success Response: 200 OK

{
  "operation": "deactivate",
  "totalRequested": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "adminUserId": "admin-id-1",
      "success": true,
      "message": "Deactivated successfully"
    },
    {
      "adminUserId": "admin-id-2",
      "success": true,
      "message": "Deactivated successfully"
    },
    {
      "adminUserId": "admin-id-3",
      "success": false,
      "error": "Cannot deactivate last super administrator"
    }
  ],
  "completedAt": "2026-01-30T11:40:00Z"
}

Supported Operations:

deactivate - Deactivate multiple accounts
assign-role - Add role to multiple accounts
remove-role - Remove role from multiple accounts
reset-password - Reset passwords for multiple accounts
unlock - Unlock multiple accounts
extend-password-expiration - Extend password expiration

Performance Requirements

Metric	Target	Critical Threshold
Admin user creation	< 1 second	< 3 seconds
Admin user list query	< 500ms	< 2 seconds
Password validation	< 100ms	< 500ms
Role assignment update	< 500ms	< 2 seconds
Audit log query (50 records)	< 1 second	< 3 seconds
Concurrent admin operations	20/second	10/second
Bulk operation (50 users)	< 10 seconds	< 30 seconds
Session validation	< 50ms	< 200ms

Security Considerations

Password Security

Hashing Algorithm: bcrypt with cost factor 12 (minimum)
Complexity Requirements:
- Minimum 12 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number
- At least one special character (!@#$%^&*()_+-=[]|;:,.<>?)
Password History: Cannot reuse last 5 passwords
Expiration: Passwords expire after 90 days (configurable)
Temporary Passwords: Auto-generated, 16 characters, must be changed on first login
No Plain Text Storage: Passwords never logged or stored unencrypted

Authentication Security

Account Lockout: Lock account after 5 failed login attempts for 30 minutes
Session Management:
- Sessions expire after 12 hours of inactivity
- Maximum 5 concurrent sessions per admin
- Secure session tokens (cryptographically random, 64 characters)
- Session revocation on password change or deactivation
Multi-Factor Authentication:
- Required for SuperAdministrator role
- Time-based one-time passwords (TOTP)
- Backup codes provided during MFA setup

Access Control

Role-Based Access Control (RBAC):
- Principle of least privilege
- Roles define specific permissions
- Multiple roles can be assigned to one admin
- Cannot escalate own privileges
Separation of Duties:
- Cannot deactivate own account
- Cannot remove own roles
- Cannot be the sole approver for sensitive operations
Super Administrator Protection:
- System must always have at least one active SuperAdministrator
- Cannot remove last SuperAdministrator role

Audit and Monitoring

Comprehensive Audit Logging:
- All admin operations logged (create, update, delete, login, logout)
- Logs include: actor, action, target, timestamp, IP, user agent, before/after values
- Logs stored in tamper-evident manner
- Logs retained for minimum 1 year
Security Monitoring:
- Alert on multiple failed login attempts
- Alert on account lockouts
- Alert on privilege escalations
- Alert on bulk operations
- Alert on after-hours admin activity (configurable)
Audit Log Protection:
- Audit logs cannot be modified by admins
- Read-only access via AuditorAdministrator role
- Exported logs digitally signed for integrity

Data Protection

Sensitive Data:
- Passwords: bcrypt hashed, never reversible
- MFA secrets: encrypted at rest
- Session tokens: secure random, not guessable
- Personal data (email, name): stored with encryption support
Database Security:
- Admin users stored in Configuration database
- Separate from trial users (Identity database)
- Database connections use TLS
- Principle of least privilege for database accounts

Email Security

Email Notifications:
- Use TLS for SMTP connections
- Do not include passwords in email subject lines
- Include security best practices in welcome emails
- Include support contact for suspicious activity
Anti-Phishing:
- Emails signed with DKIM
- Include official company branding
- Link to official login page only
- Warn users never to share passwords

API Security

Authentication: All admin endpoints require valid session token
Authorization: Role-based permissions enforced on every request
Rate Limiting:
- 100 requests per minute per admin user
- 1000 requests per minute per IP
Input Validation: All inputs validated and sanitized
HTTPS Only: All API traffic over TLS 1.2+
CORS: Strict CORS policy for web UI

Testing Scenarios

Test Case 1: Create Admin User Successfully

Given: Authenticated SuperAdministrator
When: Admin submits valid new user form
Then: User created, email sent, 201 response returned
Verify: Database record exists, password hashed, roles assigned, audit log entry created

Test Case 2: Username Uniqueness Enforcement

Given: Username "jsmith" already exists
When: Admin attempts to create user with same username
Then: 409 Conflict returned
Verify: No duplicate user created, clear error message

Test Case 3: Password Complexity Validation

Given: New admin user
When: User sets password not meeting complexity requirements
Then: 400 Bad Request returned with specific requirements failed
Verify: Password not updated, user still requires password change

Test Case 4: Account Lockout After Failed Logins

Given: Active admin user
When: User fails login 5 times in succession
Then: Account locked for 30 minutes
Verify: AccountLockedUntil set, 403 returned, lockout email sent, audit log entries

Test Case 5: Cannot Deactivate Self

Given: Authenticated admin user
When: Admin attempts to deactivate own account
Then: 400 Bad Request returned
Verify: Account remains active, error message clear

Test Case 6: Cannot Remove Last Super Administrator

Given: Only one SuperAdministrator exists
When: Attempt to remove SuperAdministrator role or deactivate
Then: 403 Forbidden returned
Verify: Role remains, account active, system protection maintained

Test Case 7: Password Expiration Enforcement

Given: Admin user with expired password
When: User attempts to login
Then: Redirect to password change screen
Verify: Cannot access system until password changed

Test Case 8: Default Admin Creation on First Startup

Given: Empty Configuration database (no admin users)
When: Application Manager starts
Then: Default admin account created (admin/Admin@2026!)
Verify: Admin can login, RequirePasswordChange=true, SuperAdministrator role assigned, logged in console and audit trail

Test Case 9: Audit Trail Completeness

Given: Admin performs various operations
When: Operations include create, update, deactivate, password reset
Then: All operations logged in audit trail
Verify: Each log entry has actor, action, target, timestamp, IP, details

Test Case 10: MFA Required for Super Admin

Given: New SuperAdministrator created
When: Admin completes password change
Then: Redirected to MFA setup
Verify: Cannot access system until MFA configured

Test Case 11: Bulk Deactivate with Partial Failure

Given: Admin selects 10 users for bulk deactivation
When: 2 users cannot be deactivated (self, last super admin)
Then: 8 deactivated successfully, 2 skipped with reasons
Verify: Partial success, clear reporting, individual audit logs

Test Case 12: Session Revocation on Password Change

Given: Admin with 3 active sessions changes password
When: Password change completes
Then: All sessions except current one revoked
Verify: User must re-authenticate on other devices

Monitoring and Analytics

Key Metrics to Track

Admin User Metrics:
- Total active administrators
- Administrators by role distribution
- New administrators created (per week/month)
- Deactivated administrators (per week/month)
- Average admin tenure
Security Metrics:
- Failed login attempts (per admin, per day)
- Account lockouts (per day/week)
- Password resets (per week/month)
- MFA adoption rate
- Average password age
- Expired passwords not yet changed
Activity Metrics:
- Admin login frequency
- Most active administrators (by operation count)
- Operations by type distribution
- Peak admin activity hours
- Average session duration
Audit Metrics:
- Audit log growth rate
- High-severity audit events
- Privilege escalation attempts
- Bulk operations performed

Alerts

Critical Alerts:

No SuperAdministrator accounts active
Multiple failed login attempts from single IP (> 10 in 5 minutes)
Account lockout rate > 5% of active admins in 1 hour
Unauthorized privilege escalation attempt
Bulk deactivation > 10 accounts at once
After-hours admin activity from unusual location

Warning Alerts:

Password expiration rate > 20% of admins
MFA not configured for SuperAdministrator
Admin user not logged in for 90 days (inactive account)
Default admin password not changed within 24 hours of deployment
Email delivery failure for admin notifications
Audit log storage approaching capacity

Informational Alerts:

New administrator created
Administrator roles changed
Bulk operation completed
Weekly admin activity summary

Dashboards

Security Dashboard:

Failed login attempts (time series chart)
Locked accounts (count)
MFA adoption rate (percentage)
Password expiration warnings (count)
Recent high-severity audit events (list)

Admin Management Dashboard:

Total administrators by role (pie chart)
Admin creation/deactivation trends (time series)
Most active admins (top 10 list)
Login frequency heatmap
Password age distribution (histogram)

Audit Dashboard:

Recent admin operations (activity feed)
Operations by type (bar chart)
Admin activity timeline
Privilege changes log
Export/reporting tools

UC-001: Trial User Self-Registration and Access
UC-002: Trial User Login and Session Management
UC-003: Administrator Authentication and Authorization
UC-004: Role and Permission Management
UC-006: Audit Logging and Compliance Reporting
UC-007: Multi-Factor Authentication Setup
UC-008: Admin Password Reset and Recovery
UC-009: System Configuration Management
UC-010: Application Registration and Management

Notes and Assumptions

Database Separation: Admin users stored in Configuration database, separate from trial users (Identity database) for security and operational isolation
Default Account Security: Default admin account (admin/Admin@2026!) is a necessary bootstrap mechanism but must be changed immediately after first login
SuperAdministrator Requirement: System must always have at least one active SuperAdministrator; this is a hard constraint enforced by business logic
Password Policy Configurability: Password complexity, expiration, and lockout settings are configurable via system settings but have secure defaults
MFA Implementation: MFA uses TOTP (Time-based One-Time Password) standard compatible with Google Authenticator, Authy, etc.
Audit Log Retention: Audit logs retained for minimum 1 year for compliance; retention period configurable
Email Dependency: Email service highly recommended but system can function without it (admin must communicate credentials manually)
Session Management: Sessions are stateful (stored in database or Redis) for revocation capability and tracking
No Self-Service Password Reset: Admin password resets require another SuperAdministrator (no self-service via email link) for enhanced security
Bulk Operation Limits: Bulk operations limited to 50 users per request to prevent performance issues and accidental mass changes
Role Hierarchy: Roles are flat (no inheritance), permissions are explicitly assigned to each role
First-Time Setup: On fresh installation with empty database, system creates default admin automatically

Revision History

Version	Date	Author	Changes
1.0	2026-01-30	System Analyst	Initial use case documentation for administrator user management

Document Owner: Platform Architecture Team
Stakeholders: Security Team, Platform Engineering, Operations, Compliance
Review Cycle: Quarterly or as needed for security/compliance changes
Classification: Internal Use Only - Contains Security Information

Use Case 005: Administrator User Management

Overview

Description

Actors

Preconditions

Postconditions

Success Postconditions

Failure Postconditions

Triggers

Basic Flow (Happy Path)

Detailed Steps

Alternative Flows

Alt Flow 1: Updating Existing Administrator

Alt Flow 2: Password Reset (Administrator-Initiated)

Alt Flow 3: Account Lockout After Failed Login Attempts

Alt Flow 4: Deactivating Administrator Account

Alt Flow 5: Bulk Operations

Alt Flow 6: Default Admin Account Creation on First Startup

Alt Flow 7: Role-Based Access Control Changes

Business Rules

Data Requirements

Admin User Record (Configuration Database)

Admin User Role Assignment

Role Definition

Password History (for password reuse prevention)

Audit Log Entry

Email Templates

User Interface

Admin User List Page

Create Administrator Form

Edit Administrator Form

Admin Activity Log Tab

Password Change Screen (Forced First Login)

API Endpoints

List Admin Users

Create Admin User

Get Admin User by ID

Update Admin User

Deactivate Admin User

Reactivate Admin User

Reset Password

Unlock Account

Get Admin Activity Log

Get Active Sessions

Revoke Session

Bulk Operations

Performance Requirements

Security Considerations

Password Security

Authentication Security

Access Control

Audit and Monitoring

Data Protection

Email Security

API Security

Testing Scenarios

Test Case 1: Create Admin User Successfully

Test Case 2: Username Uniqueness Enforcement

Test Case 3: Password Complexity Validation

Test Case 4: Account Lockout After Failed Logins

Test Case 5: Cannot Deactivate Self

Test Case 6: Cannot Remove Last Super Administrator

Test Case 7: Password Expiration Enforcement

Test Case 8: Default Admin Creation on First Startup

Test Case 9: Audit Trail Completeness

Test Case 10: MFA Required for Super Admin

Test Case 11: Bulk Deactivate with Partial Failure

Test Case 12: Session Revocation on Password Change

Monitoring and Analytics

Key Metrics to Track

Alerts

Dashboards

Related Use Cases

Notes and Assumptions

Revision History