User Management

Complete guide to managing user accounts, roles, permissions, and authentication in SysManage.

Overview

SysManage implements a comprehensive user management system with role-based access control (RBAC), secure authentication, and granular permissions. This system ensures that users have appropriate access to system resources while maintaining security and compliance requirements.

User Account Management

Creating User Accounts

New user accounts can be created through the web interface or API:

Web Interface

Navigate to Administration > Users
Click Create User
Fill in required information:
- Username (unique identifier)
- Email address
- Full name
- Initial password
- Role assignment
Configure account settings
Click Create

API Example

curl -X POST "https://your-server.example.com/api/v1/user" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "username": "john.doe",
       "email": "john.doe@company.com",
       "full_name": "John Doe",
       "password": "secure-password",
       "role": "operator",
       "is_active": true
     }'

Modifying User Accounts

Profile Updates

Personal Information: Users can update their own profile details
Password Changes: Users can change their passwords
Email Updates: Email changes may require verification
Profile Pictures: Upload and manage profile images

Administrative Updates

Role Changes: Administrators can modify user roles
Account Status: Enable, disable, or lock accounts
Permission Overrides: Grant specific permissions
Password Resets: Force password resets for security

Account Deactivation and Deletion

Account Deactivation

Recommended approach for temporarily disabling access:

Preserves user data and audit trails
Can be easily reactivated
Maintains referential integrity
Blocks all authentication attempts

Account Deletion

⚠️ Warning: Account deletion is permanent and may affect system data integrity. Consider deactivation instead.

When deletion is necessary:

Export user-related data if needed
Update ownership of resources
Document the deletion in audit logs
Verify no active sessions exist

Roles and Permissions

Built-in Roles

Administrator

Full system access and control
User management capabilities
System configuration access
Security settings management
Audit log access

Operator

Host and agent management
Package management operations
Report generation and viewing
Basic monitoring access
Limited configuration changes

Viewer

Read-only access to most features
Dashboard and report viewing
Host status monitoring
Basic system information access
No modification capabilities

Auditor

Specialized role for compliance
Full audit log access
Security report generation
User activity monitoring
Compliance report access

Permission Matrix

Feature	Administrator	Operator	Viewer	Auditor
User Management	✅ Full	❌ None	❌ None	👁️ View Only
Host Management	✅ Full	✅ Full	👁️ View Only	👁️ View Only
Package Management	✅ Full	✅ Full	👁️ View Only	👁️ View Only
System Configuration	✅ Full	⚠️ Limited	❌ None	👁️ View Only
Security Settings	✅ Full	❌ None	❌ None	👁️ View Only
Audit Logs	✅ Full	⚠️ Limited	❌ None	✅ Full
Reports	✅ Full	✅ Full	👁️ View Only	✅ Full

Custom Roles

Create custom roles for specific organizational needs:

Department-specific roles: IT, Security, Compliance teams
Project-based access: Temporary permissions for specific projects
Regional access: Geographic or organizational unit restrictions
Specialized functions: Backup operators, monitoring specialists

Creating Custom Roles

curl -X POST "https://your-server.example.com/api/v1/roles" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "backup-operator",
       "description": "Backup and recovery operations",
       "permissions": [
         "hosts.view",
         "reports.view",
         "reports.backup",
         "system.backup",
         "system.restore"
       ]
     }'

Authentication Methods

Local Authentication

Built-in username/password authentication with advanced security features:

Password Policies: Configurable complexity requirements
Account Lockouts: Protection against brute force attacks
Password Expiration: Automatic password aging
Password History: Prevention of password reuse

Password Policy Configuration

{
  "password_policy": {
    "min_length": 12,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_special_chars": true,
    "max_age_days": 90,
    "history_count": 12,
    "lockout_attempts": 5,
    "lockout_duration_minutes": 30
  }
}

Multi-Factor Authentication (MFA)

Phase 10.3 ships an OSS Multi-Factor Authentication implementation. MFA is opt-in by default, and a global "admin-required" toggle (with a configurable grace period) lets administrators force enrollment fleet-wide.

Supported MFA Methods

TOTP (Time-based OTP): Any RFC 6238 authenticator app — Google Authenticator, Authy, 1Password, Bitwarden, etc.
Backup codes: Single-use Argon2-hashed recovery codes (10 by default) issued at enrollment for when the user loses access to their authenticator.

Roadmap: SMS / email-code fallback, FIDO2/WebAuthn — tracked in the 10.3 follow-up tasks.

User Enrollment Flow

User opens Profile → Security Information and clicks Enable MFA.
Server generates a fresh TOTP secret (encrypted at rest with Fernet) and returns the otpauth:// provisioning URI plus the raw base32 secret.
User adds the account to their authenticator app (scan the URI with a QR generator, or paste the secret manually).
User enters the first 6-digit code their app shows; on success the server issues 10 single-use backup codes shown exactly once.
User saves the backup codes somewhere safe, ticks the acknowledgement, and is fully enrolled.

Login with MFA

User submits username + password as usual.
If they're enrolled, the server returns {mfa_required: true, pending_token: "..."} instead of a session token. The pending token is short-lived (5 minutes).
The login UI prompts for a verification code — either a current TOTP code or one of the backup codes (in XXXX-XXXX format, but the dash is optional).
The client posts pending-token + code to /api/auth/mfa/verify; on success it receives a normal session token.

Admin Settings (`/api/settings/mfa`)

issuer_name — string shown in authenticator apps (default SysManage).
totp_digits / totp_period_seconds — TOTP shape (default 6 digits, 30 s period).
backup_code_count — codes issued per enrollment / regeneration (default 10; 0 disables backup codes entirely).
admin_required — when true, users who pass the grace period without enrolling are blocked at login until they enrol.
grace_period_days — days from account creation during which a user can sign in without MFA even when admin_required is on (default 14).

Recovery

User-driven: sign in with a backup code, then re-enrol from the profile page (this rotates the secret and issues a fresh set of backup codes).
Admin-driven: delete the user's user_mfa_enrollment row directly (or via the Users admin page) — the user can sign in with their password and re-enrol on next login.

External Authentication

LDAP/Active Directory Integration

{
  "ldap_config": {
    "server": "ldap://corp.example.com:389",
    "base_dn": "dc=corp,dc=example,dc=com",
    "user_dn": "cn=sysmanage,ou=service,dc=corp,dc=example,dc=com",
    "user_filter": "(sAMAccountName={username})",
    "group_filter": "(member={user_dn})",
    "role_mapping": {
      "CN=SysManage-Admins,OU=Groups,DC=corp,DC=example,DC=com": "administrator",
      "CN=SysManage-Operators,OU=Groups,DC=corp,DC=example,DC=com": "operator"
    }
  }
}

SAML 2.0 Integration

Single Sign-On (SSO) with identity providers
Automatic user provisioning
Role mapping from SAML attributes
Just-in-time (JIT) account creation

OAuth 2.0 / OpenID Connect

Integration with modern identity providers
Google, Microsoft, GitHub authentication
Token-based authentication flow
Refresh token management

Session Management

Session Policies

Session Timeout: Automatic logout after inactivity
Concurrent Sessions: Limit number of active sessions
Session Monitoring: Track active user sessions
Force Logout: Administrative session termination

Session Configuration

{
  "session_config": {
    "timeout_minutes": 480,
    "max_concurrent_sessions": 3,
    "remember_me_days": 30,
    "secure_cookies": true,
    "same_site": "strict"
  }
}

Active Session Monitoring

Monitor and manage active user sessions:

View all active sessions
Session location and IP tracking
Device and browser information
Last activity timestamps
Administrative session termination

API Example: List User Sessions

curl -X GET "https://your-server.example.com/api/v1/users/sessions" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

Common User Management Workflows

New Employee Onboarding

Create user account with appropriate role
Configure initial permissions
Set up authentication method (local/SSO)
Enable MFA if required
Assign to relevant host groups
Provide initial training materials
Schedule permission review

Role Change Process

Submit role change request
Manager approval (if required)
Security team review
Update user role and permissions
Notify user of changes
Document change in audit log
Schedule follow-up review

Employee Offboarding

Disable user account immediately
Revoke all active sessions
Transfer resource ownership
Export user-related data
Update documentation
Archive account data
Schedule account deletion review

Security Incident Response

Identify compromised accounts
Immediately disable affected accounts
Force password resets
Revoke all active sessions
Review audit logs for activity
Implement additional security measures
Document incident and remediation

Security Best Practices

Account Security

Principle of Least Privilege: Grant minimum necessary permissions
Regular Access Reviews: Periodic audit of user permissions
Separation of Duties: Distribute administrative responsibilities
Account Monitoring: Monitor for unusual account activity
Privileged Account Management: Special handling for administrative accounts

Authentication Security

Strong Password Policies: Enforce complex password requirements
Multi-Factor Authentication: Require MFA for administrative access
Session Security: Implement secure session management
Login Monitoring: Track and alert on login anomalies
Regular Password Updates: Enforce periodic password changes

Compliance Considerations

Audit Trail: Maintain comprehensive user activity logs
Data Protection: Ensure compliance with privacy regulations
Access Certification: Regular attestation of user access
Segregation of Duties: Implement role-based controls
Documentation: Maintain current user management procedures

Troubleshooting User Issues

Login Problems

Account Locked: Check lockout status and unlock if appropriate
Password Expired: Force password reset or extend expiration
MFA Issues: Provide backup codes or reset MFA
Session Limits: Terminate old sessions or increase limits

Permission Issues

Access Denied: Review and adjust user permissions
Role Conflicts: Resolve conflicting role assignments
Resource Access: Check host group assignments
Feature Restrictions: Verify role-based feature access

Integration Issues

LDAP Connectivity: Test LDAP server connectivity
SAML Errors: Verify SAML configuration and certificates
Role Mapping: Check external group to role mappings
Synchronization: Verify user data synchronization