Password Reset
MaestroHub provides two methods for resetting user passwords: a self-service flow via email and a break-glass CLI method for administrators. The available method depends on whether email services are configured in your deployment.
Self-Service Password Reset
When email is configured, users can reset their own passwords through the login page.
Prerequisites
SMTP must be configured in MaestroHub's platform settings for self-service password reset to be available. Without a working SMTP configuration, the Forgot your password? link will not appear on the login page. Contact your system administrator to set up email services if this option is missing.
How It Works
- User clicks Forgot your password? on the login page
- User enters their email address and submits the form
- System generates a secure reset token (valid for 30 minutes)
- Email is sent with a password reset link
- User clicks the link and enters a new password
- Password is updated and user can sign in
Security Features
- Token expiration: Reset tokens expire after 30 minutes
- Single use: Each token can only be used once
- Email enumeration prevention: The system returns the same success message whether or not the email exists, preventing attackers from discovering valid accounts
- Password validation: New passwords must meet the configured password requirements
Break-Glass Password Reset
When email is not configured, or in emergency situations, administrators can reset passwords directly using the Admin CLI tool. This requires server access.
Prerequisites
- Direct access to the server running MaestroHub
- Path to the
auth.dbdatabase file
Database Location
The auth.db file is located in the /data directory. By default, /data is located in the home directory (~/) of the operating system:
| OS | Default Path |
|---|---|
| Linux | ~/data/auth.db |
| macOS | ~/data/auth.db |
| Windows | %USERPROFILE%\data\auth.db |
Command Syntax
admin-cli user reset-password --database <path-to-auth.db> -e <email> [-p <password>]
Options
| Flag | Description |
|---|---|
--database | Path to the auth.db file (required) |
-e, --email | User's email address (required) |
-p, --password | New password (optional, defaults to TempPassword2024!) |
Examples
Reset password with default temporary password:
admin-cli user reset-password --database ~/data/auth.db -e user@example.com
Reset password with a custom password:
admin-cli user reset-password --database ~/data/auth.db -e user@example.com -p MySecurePassword123!
Post-Reset Actions
After using break-glass reset:
- Communicate the temporary password to the user through a secure channel
- Instruct the user to change their password immediately after signing in
- Document the reset action for audit purposes
Password Requirements
New passwords must meet the following criteria:
| Requirement | Default |
|---|---|
| Minimum length | 8 characters |
| Uppercase letter | Required |
| Lowercase letter | Required |
| Number | Required |
| Special character | Optional |
Users can view the current password requirements by clicking the info icon on the password field during reset.
Troubleshooting
"Email service is not available"
This message appears when email is not configured. Use the break-glass CLI method instead, or configure email services in the platform settings.
"Invalid or expired token"
Reset tokens expire after 30 minutes. Request a new password reset email and complete the process promptly.
"No user found with email"
The specified email address does not exist in the system. Verify the email address is correct. Note: this error only appears in the CLI; the web interface intentionally shows a generic message to prevent email enumeration.
User cannot sign in after reset
Verify that:
- The user account is in Active status (not Inactive or Deleted)
- The password meets all requirements
- The user is entering the correct email address