Authentication FAQ¶
Common questions and troubleshooting for DUMB's authentication system.
Choose the right login recovery path¶
A rejected password, an expired session and a complete lockout have different recovery paths. Use another active account where one is available before considering the manual reset procedure.
flowchart TD
Issue["What happens when you sign in?"] --> Password["Invalid credentials"]
Issue --> Disabled["Account is disabled"]
Issue --> Session["A previous session expired"]
Issue --> Lockout["No usable account remains"]
Password --> Check["Check username, password and case"]
Disabled --> Active["Ask an active account holder to review the user"]
Session --> Login["Sign in again and check system time if expiry repeats"]
Lockout --> Recovery["Follow the documented lockout recovery procedure"]
Setup and configuration¶
Do I need to enable authentication?¶
Enable authentication whenever other people or networks can reach DUMB. Every enabled account currently has operator permissions; an extra account is not a read-only role. Only leave authentication disabled in an intentionally trusted, isolated environment.
How do I create the first user account?¶
When DUMB starts with no users:
- Navigate to the DUMB frontend
- You'll be redirected to
/setup - Enter a username and password
- Click Create Account
Can I change my password?¶
Currently, password changes require:
- Creating a temporary second user
- Signing in as the temporary user
- Deleting the original user (users cannot delete their own current account)
- Recreating the original username with the new password
- Signing in as the recreated user and deleting the temporary account
How many users can I create?¶
There's no hard limit on the number of user accounts. Create as many as needed for your use case.
All enabled users currently have the same DUMB permissions. Creating another account does not create a read-only role.
Login issues¶
"Invalid credentials" error¶
- Check username - Usernames are case-sensitive
- Verify password - Passwords are also case-sensitive
- Account status - Check if the user is disabled in Settings
"User account is disabled" error¶
Another authenticated DUMB user has disabled your account. Contact an operator with an enabled account to re-enable it via Settings User Management.
Session expires too quickly¶
Access tokens expire after 60 minutes by default. Local refresh tokens default to 30 days; OIDC-backed DUMB refresh tokens last one day. If you're experiencing frequent logouts:
- Check if Remember Me was selected during login
- Without Remember Me, tokens are stored in session storage and cleared when the browser closes
- With Remember Me, tokens persist in local storage
Browser shows login page but I was logged in¶
- Your access token may have expired
- The frontend should automatically refresh - wait a moment
- If it persists, clear browser storage and log in again
- Check if authentication was recently disabled/re-enabled
Account management¶
How do I disable a user without deleting them?¶
- Go to Settings User Management
- Find the user
- Click the disable button
Disabled users cannot log in but their account remains for re-enabling later.
"Cannot disable the last active user" error¶
DUMB prevents disabling or deleting the last non-disabled user to avoid lockouts. To disable this user:
- Create another user account first
- Then disable the original user
How do I delete a user?¶
- Go to Settings User Management
- Find the user
- Click the delete button
- Confirm the deletion
Permanent action
Deleted users cannot be recovered. Create a new account if needed.
Lockout recovery¶
I forgot my password - how do I reset it?¶
DUMB has no self-service password reset. First try another enabled operator account or the identity provider's recovery tools. If local-account recovery is necessary:
- Restrict access to DUMB and stop its container.
- Back up the host-mounted
/config/users.jsonprivately, preserving the original users, signing secret, and OIDC settings. - In that file, set
"enabled": false. If the mode is OIDC-only, temporarily set"mode": "hybrid"so the temporary local account can sign in later; keep theoidcsettings intact. - Start the container. Authentication is temporarily disabled for anyone who can reach it.
- In Settings → User Management, create a temporary local user with a different username.
- Re-enable authentication and sign in as that temporary user.
- Delete the forgotten local account and recreate it with the desired username and a new password.
- Sign in as the recreated user, remove the temporary user, and restore the intended sign-in mode.
- Verify login before restoring wider network access. Retain or dispose of the private recovery copy according to your backup policy.
Disabling authentication alone does not change a password or remove existing accounts. Do not clear the user list or signing secret as a shortcut.
I deleted all users and can't log in¶
Follow the lockout recovery steps above to disable authentication, then create a new user.
The users.json file is corrupted¶
Stop DUMB and preserve the damaged file privately before attempting repair. Prefer restoring a known-good backup that retains users, the signing secret, and any OIDC configuration. If no usable backup exists, creating a fresh authentication configuration resets those identities and sessions; plan that recovery explicitly rather than overwriting the file blindly.
API and tokens¶
How long do tokens last?¶
| Token Type | Lifetime |
|---|---|
| Access Token | 60 minutes |
| Local refresh token | 30 days by default |
| OIDC-backed DUMB refresh token | 1 day |
How do I authenticate API requests?¶
Include the access token in the Authorization header:
How do I authenticate WebSocket connections?¶
Pass the token as a query parameter:
My API calls return 401 Unauthorized¶
- Verify the token is included in the Authorization header
- Check if the token has expired
- Ensure the format is
Bearer <token>(with space) - Try getting a new token via login
Security¶
Where are passwords stored?¶
Passwords are hashed using bcrypt and stored in /config/users.json. The original password is never stored.
Is the JWT secret secure?¶
DUMB generates a signing secret when needed and stores it in /config/users.json. Keep the complete file private; it also contains password hashes and may contain OIDC client credentials.
Can I use DUMB without HTTPS?¶
Yes, but authentication tokens will be transmitted in plain text. For production deployments exposed to the internet:
- Use a reverse proxy with HTTPS
- Or deploy behind a VPN
Should I disable authentication for local use?¶
For truly local/isolated environments (e.g., home lab with no internet exposure), disabling authentication simplifies access. However, if anyone on your network can reach DUMB, consider keeping authentication enabled.