Password Reset
Users reset a forgotten password by email; administrators reset it from the Users list, or from the command line when no one can sign in.
- Self-service
- Needs SMTP configured
- Reset link
- Valid for 30 minutes
- Administrator
- Users → Reset password
- Break-glass
- admin-cli
MaestroHub provides three ways to reset a user's password: a self-service flow by email, an administrator reset from the Users list, and a break-glass CLI method for when no administrator can sign in.
Administrator Reset from the Users List
An administrator holding the user:reset_password permission (Identity Administrator, Security Administrator, System Administrator) sets a new password for a user from Identity & Access → Users & Roles → Users: the user's row menu → Reset password, or the Password row of their edit form. It works whether or not email is configured. The user's sign-ins end: any session they have open expires within the access-token lifetime (15 minutes by default); their personal access tokens keep working. See Resetting a user's password for who sees the action and what it records.
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
Accounts that sign in with single sign-on
An account created by an identity provider (OIDC, SAML or LDAP) has no MaestroHub password, and self-service cannot create one. If its user asks for a reset, no reset link is sent. Instead, they get an email saying the account signs in with single sign-on, and that they should reset their password with their identity provider. The page shows the same message as for any other address.
To give such an account a MaestroHub password, an administrator sets one with Reset password on the Users list (see Administrator Reset from the Users List), through the admin API (POST /api/v1/admin/users/{id}/reset-password) or with the admin CLI. From then on, the user can change it like any other password. A local account that was later linked to an identity provider keeps its password and every reset option.
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 no administrator can sign in to reset a password from the Users list (for example, the only administrator has lost theirs), reset it directly with the Admin CLI tool. This requires server access.
Prerequisites
- Direct access to the server running MaestroHub
- The
admin-clitool, which ships in the release archive and the Docker image
Where the CLI finds the users
The CLI reads the users from the auth store (auth.db with the default SQLite engine). You don't name the file: tell the CLI about the installation and it finds the store the same way MaestroHub does.
--config <file>: theconfig.yamlyou start MaestroHub with.--data-dir <dir>: MaestroHub's data directory (storage.dataDir).
MaestroHub's data directory defaults to ./data, relative to the directory the server runs in, not to your home directory. Without either flag, the CLI uses ./data relative to the directory you run it in, so run it from the server's working directory or pass --data-dir. In Docker, run it inside the container, where the defaults match. See Where the CLI finds the stores.
To name the store yourself, pass -d / --database with its path or connection URL. It is optional.
Command Syntax
admin-cli [--config <config.yaml> | --data-dir <dir>] user reset-password -e <email> [-p <password>]
Options
| Flag | Description |
|---|---|
-e, --email | User's email address (required) |
-p, --password | New password (optional, defaults to TempPassword2024!) |
--config | MaestroHub's config.yaml (optional) |
--data-dir | MaestroHub's data directory (optional) |
-d, --database | Path or URL of the auth store, instead of --config / --data-dir (optional) |
-f, --force | Skip the confirmation prompt |
Examples
Reset password with default temporary password, for a binary install whose data directory is ~/maestrohub/data:
admin-cli --data-dir ~/maestrohub/data user reset-password -e user@example.com
Reset password with a custom password, using the server's configuration file:
admin-cli --config /etc/maestrohub/config.yaml user reset-password -e user@example.com -p 'MySecurePassword123!'
In Docker:
docker exec -it --user maestrohub <container> admin-cli user reset-password -e user@example.com
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, or when an email configuration is saved but cannot be loaded (the Admin Overview then shows Email is set up but can't send). Ask an administrator to reset the password from the Users list, or configure email services in the platform settings. If no administrator can sign in, use the break-glass CLI method.
"Invalid or expired token"
Reset tokens expire after 30 minutes. Request a new password reset email and complete the process promptly.
An account that signs in with single sign-on also sees this message when it opens a reset link sent before the upgrade: such links no longer set a password. See Accounts that sign in with single sign-on.
"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