Users & Settings

coreX Platform includes a user management system with authentication, two-factor authentication (2FA), role-based access control, and theme customization.

For global options, feature flags, password policy, session settings, and backup/restore, see Settings.

Authentication

Admin User

On first startup, coreX Platform creates an admin user. The password is read from the ADMIN_PASSWORD environment variable. If unset, a random password is generated and printed to the logs.

Change the default password

If ADMIN_PASSWORD is not set, a random password is generated. Check the startup logs for the password and change it immediately after first login.

Login

  1. Navigate to the coreX Platform URL
  2. Enter username and password
  3. If 2FA is enabled, enter the TOTP code
  4. You receive a JWT token for API access

JWT Tokens

Authentication uses JWT tokens. Tokens are:

  • Issued on login
  • Included in API requests as Authorization: Bearer <token>
  • Refreshable via the refresh endpoint
  • Revocable (individual tokens can be revoked)

The token’s lifetime is controlled by the session_timeout_minutes setting (default 30 minutes). See Settings for session configuration.

Password Expiry

If the password_rotation_months setting is non-zero, passwords expire after the configured period. On login, the backend injects a pwd_exp claim into the JWT. A middleware blocks all non-auth API calls with 403 password_change_required until the user changes their password. The frontend shows a blocking modal — the user cannot navigate away until they set a new password that meets the current password policy.

See Settings for password policy configuration.

Two-Factor Authentication (2FA)

2FA uses TOTP (Time-based One-Time Password) compatible with authenticator apps (Google Authenticator, Authy, 1Password, etc.).

Enabling 2FA

  1. Navigate to System > Users and open your user profile
  2. Click Enable 2FA
  3. Scan the QR code with your authenticator app
  4. Enter the verification code to confirm
  5. Save the backup codes in a secure location

Disabling 2FA

  1. Open your user profile
  2. Click Disable 2FA
  3. Enter your password to confirm
Backup codes

When you enable 2FA, coreX Platform generates one-time backup codes. Store these securely — each can be used once if you lose access to your authenticator device.

User Management

User Fields

Each user has the following fields:

FieldRequiredDescription
UsernameYesUnique login identifier
PasswordYes (on create)Must meet the password policy (see Settings)
EmailNoUsed for SSL Labs scan registration and notifications
First nameNoUsed for SSL Labs scan registration
Last nameNoUsed for SSL Labs scan registration
OrganizationNoUsed for SSL Labs scan registration. Defaults to the first admin’s organization, or “coreX Platform” if unset
RoleYesAccess level (see below)

Roles

coreX Platform has three roles with different permission levels:

RoleDescription
adminFull access to all features and settings. Can manage users, configure HA, and change global options.
operatorCan create, edit, and delete resources (backends, listeners, WAF rules, security rules, certificates, etc.) but cannot manage users or change global settings.
viewerRead-only access. Can view all pages and data but cannot make changes.
Write permissions

The operator and admin roles have write permissions. Most mutating API endpoints (POST, PUT, DELETE) require write access and return 403 Forbidden for viewer users. Some sensitive operations (user management, HA config, global options) require admin specifically.

Creating Users

  1. Navigate to System > Users
  2. Click Add User
  3. Enter username, email, password, and optional name/organization fields
  4. Assign a role (admin, operator, or viewer)
  5. Save

The password must meet the current password policy (minimum length, character requirements). See Settings for policy configuration.

Managing Users

  • Edit — Change user details, role, or reset password
  • Last login — The Users table shows the last login time for each user (updated on each successful login)
  • Reset password — Admin can reset a user’s password (the new password must meet the policy)
  • Disable 2FA — Admin can reset 2FA for users who lost access to their authenticator device
  • Delete — Remove a user (cannot delete the last admin)

Themes

coreX Platform supports runtime theme switching via CSS variables. Users can also create custom themes.

Built-in Themes

6 built-in themes are available:

  • Slate Dark
  • Dracula
  • Tokyo Night
  • Catppuccin Mocha
  • Material Light
  • Catppuccin Latte

Custom Themes

  1. Navigate to Settings > Appearance
  2. Click Create Custom Theme
  3. Clone from a built-in theme or start from scratch
  4. Customize the 18 color variables (backgrounds, borders, text, semantic, status)
  5. Preview live as you edit
  6. Save with a custom name

Theme Persistence

The active theme is persisted to localStorage and applied on page load. Custom themes are also stored in localStorage.

Step-by-Step: Change the Admin Password

  1. Log in as admin
  2. Navigate to System > Users and open the admin user
  3. Click Change Password
  4. Enter the current password and new password
  5. Save

The new password must meet the current password policy.

Step-by-Step: Create a Read-Only User

  1. Navigate to System > Users
  2. Click Add User
  3. Username: viewer
  4. Email: viewer@example.com
  5. Password: a strong password meeting the policy
  6. Role: viewer
  7. Save

The user can now log in and view all pages but cannot make changes.

Step-by-Step: Create a Custom Theme

  1. Navigate to Settings > Appearance
  2. Click Create Custom Theme
  3. Select a built-in theme to clone from (e.g. Dracula)
  4. Name your theme (e.g. My Custom Dark)
  5. Adjust colors using the color pickers:
    • Background colors
    • Border colors
    • Text colors
    • Semantic colors (primary, secondary, accent)
    • Status colors (success, warning, error, info)
  6. Preview the changes live
  7. Click Save
  8. Select your custom theme from the theme picker

Verification

  1. Test login:

    curl -k -X POST https://localhost/api/v1/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"your-password"}'

    Expect a JWT token in the response.

  2. Test 2FA:

    • Enable 2FA on your account
    • Log out and log back in
    • Verify the TOTP code is required

  3. Test viewer role:

    • Log in as the viewer user
    • Attempt to create a backend
    • Expect a 403 Forbidden response

  4. Test operator role:

    • Log in as the operator user
    • Create a backend — should succeed
    • Attempt to access System > Users — should be restricted
    • Attempt to change global options — should be restricted

  5. Test theme switching:

    • Switch between built-in themes
    • Verify the UI updates immediately
    • Refresh the page and verify the theme persists

Next Steps

← Previous Audit & Snapshots Next → Settings