Change login passwords and add users for Basic Auth, TinyAuth, Authelia and Google OAuth
You set up a login method for your apps. Now you want to change a password, let another person in, or get back in after you lost your two-factor device. This guide shows how, one method at a time. It is for anyone who finished Choose a login method for your apps.
Overview
Section titled “Overview”Each method keeps its users in a different place. For most methods you edit a file in your Docker folder, then restart or recreate one container. Recreate needs a Basic, Plus or Pro license.
| Method | Where the users are | License to set it up |
|---|---|---|
| Basic HTTP Auth | secrets/basic_auth_credentials |
Plus or Pro (part of Traefik Preparation) |
| TinyAuth | appdata/tinyauth/users_file |
Pro |
| Authelia | appdata/authelia/users.yml |
Pro |
| Authentik | Authentik’s own admin interface | Pro |
| Google OAuth | secrets/oauth_secrets |
Pro |
All paths in this guide are inside your Docker folder, for example /home/USER/docker. Most of these files belong to root. The Authelia files belong to your user. Using sudo works for all of them.
Not sure which method an app uses? Open Security > Manage Auth (Pro). It lists each app with its current method. See Switch your apps to the new method.
Before you start
Section titled “Before you start”-
Open a terminal on the server.
-
Go to your Docker folder. Replace
YOUR_DOCKER_FOLDERwith its path:Terminal window cd YOUR_DOCKER_FOLDER -
Keep this terminal open. The commands below use paths that start from this folder.
Basic HTTP Auth
Section titled “Basic HTTP Auth”Traefik reads Basic HTTP Auth logins from secrets/basic_auth_credentials. The htpasswd tool comes with the packages Deployrr installs, so you can use it here. To see how this file is first made by hand, read UDMS part 18: Basic HTTP authentication secret (manual setup).
Change a password or add a user
Section titled “Change a password or add a user”-
Back up the file:
Terminal window sudo cp secrets/basic_auth_credentials secrets/basic_auth_credentials.bak -
Run this command. Replace
USERNAMEwith the user’s name. Use the existing name to change a password. Use a new name to add a user:Terminal window sudo htpasswd -B secrets/basic_auth_credentials USERNAME -
Type the password when asked. Type it again to confirm.
-
Recreate Traefik so it reads the file. Go to Tools > Stack Manager > Recreate. At
Select an app to recreate:, type the number oftraefikand press Enter. With the Deployrr bash aliases, you can run this instead:Terminal window dcrec traefik
Remove a user
Section titled “Remove a user”-
Back up the file, as shown above.
-
Run this command. Replace
USERNAMEwith the user’s name:Terminal window sudo htpasswd -D secrets/basic_auth_credentials USERNAME -
Recreate Traefik, as in the previous part.
If you changed the main user’s password
Section titled “If you changed the main user’s password”Deployrr also keeps the main user’s name and password in two files: secrets/basic_auth_username and secrets/basic_auth_password. If you run Traefik Preparation again, it builds the login file from these two files. Only that one user is kept. Users you added by hand are removed.
To keep your new password for a later Preparation run:
-
Open the password file:
Terminal window sudo nano secrets/basic_auth_password -
Edit the file so it holds only the new password.
-
Save with
Ctrl+O,Enter, then close withCtrl+X.
You can also use Tools > Secrets Editor with a Pro license. See Edit .env values and secrets.
TinyAuth
Section titled “TinyAuth”TinyAuth keeps one line per user in appdata/tinyauth/users_file. A line looks like one of these:
username:bcrypt-hashusername:bcrypt-hash:TOTPSECRETThe second form means the user has two-factor login. TOTPSECRET is the secret for the authenticator app.
Add a user or change a password
Section titled “Add a user or change a password”-
Back up the file:
Terminal window sudo cp appdata/tinyauth/users_file appdata/tinyauth/users_file.bak -
Run this command. Replace
USERNAMEwith the user’s name. Use a new name to add a user. Use an existing name to change that user’s password. Do not add-c:Terminal window sudo htpasswd -B appdata/tinyauth/users_file USERNAME -
Type the password when asked. Type it again to confirm.
-
Recreate TinyAuth so it reads the file. Go to Tools > Stack Manager > Recreate and type the number of
tinyauth. Or, with the bash aliases, rundcrec tinyauth.
When you change a password this way, htpasswd rewrites that user’s line without the :TOTPSECRET part. Two-factor is then off for that user. A new user also has no two-factor yet. Add it as shown in the next part.
Turn on two-factor for a user, or set up a new device
Section titled “Turn on two-factor for a user, or set up a new device”-
Show the user’s full line. Replace
USERNAMEwith the user’s name:Terminal window sudo grep '^USERNAME:' appdata/tinyauth/users_file -
Generate a secret. Replace
FULL_LINEwith the whole line from step 1. Keep the single quotes:Terminal window sudo docker run -t --rm ghcr.io/steveiliop56/tinyauth:v5 totp generate --user 'FULL_LINE'v5is the TinyAuth version Deployrr uses by default. If you pinned another version, use that one. -
Scan the QR code with the user’s authenticator app.
-
Copy the text after
secret=. -
Open the file:
Terminal window sudo nano appdata/tinyauth/users_file -
At the end of that user’s line, type a colon and then the secret. The line then looks like
username:bcrypt-hash:TOTPSECRET. -
Save with
Ctrl+O,Enter, then close withCtrl+X. -
Recreate TinyAuth, as in the previous part.
Lost the two-factor device
Section titled “Lost the two-factor device”You have two choices:
- Remove the colon and the secret from the end of the user’s line. The user can then log in with the password only. Recreate TinyAuth.
- Generate a new secret as shown above and put it on the line in place of the old one. Recreate TinyAuth.
Authelia
Section titled “Authelia”Authelia keeps users in appdata/authelia/users.yml. Each user is a block under users: with a name, display name, email, password hash and group. To understand how the file is built, read UDMS part 19: Authelia users (manual setup).
Make a password hash
Section titled “Make a password hash”Authelia stores a hash, not the password.
-
Run this command. Replace
NEWPASSWORDwith the password you want. Keep the single quotes:Terminal window sudo docker run --rm authelia/authelia:4.37.5 authelia hash-password 'NEWPASSWORD' -
Look for the line that starts with
Password hash:. -
Copy the text after
Password hash:. It starts with$argon2id$.
Change a password
Section titled “Change a password”-
Back up the file:
Terminal window sudo cp appdata/authelia/users.yml appdata/authelia/users.yml.bak -
Open the file:
Terminal window sudo nano appdata/authelia/users.yml -
Find the user’s
password:line. -
Replace the value with the new hash. Put it in single quotes.
-
Save with
Ctrl+O,Enter, then close withCtrl+X. -
Restart Authelia:
Terminal window sudo docker restart authelia
Add a user
Section titled “Add a user”-
Make a hash for the new user’s password, as shown above.
-
Back up the file, as in the previous part.
-
Open the file with
sudo nano appdata/authelia/users.yml. -
Copy an existing user block, including its name line.
-
Paste it below the last user.
-
Change the name,
displayname,emailandpasswordof the copy. -
Save with
Ctrl+O,Enter, then close withCtrl+X. -
Restart Authelia:
Terminal window sudo docker restart authelia
Register a new device or reset a password
Section titled “Register a new device or reset a password”Authelia asks for two-factor on your domain. It does not send email. It writes its messages to a file instead. To see this done, watch Authelia 2FA guide: registering a device with notifications.txt at 27:39 (manual Docker Compose setup; Deployrr does these steps for you).
-
Open the Authelia login page, for example
https://authelia.YOUR_DOMAIN. ReplaceYOUR_DOMAINwith your domain. -
Log in with the user’s password.
-
Choose the option to register a new device. For a forgotten password, choose the reset option on the login page.
-
Print the messages file:
Terminal window sudo cat appdata/authelia/notifications.txt -
Copy the code or link from the newest message.
-
Use it in the browser, on the same device you started on.
Too many failed logins
Section titled “Too many failed logins”Authelia blocks a user for 12 hours after 3 failed tries in 10 minutes. Wait for the block to end. These numbers are in the regulation part of appdata/authelia/configuration.yml.
Authentik
Section titled “Authentik”Authentik manages users in its own admin interface. Open https://authentik.YOUR_DOMAIN and log in as your admin. Replace YOUR_DOMAIN with your domain. Add users and change passwords there. Deployrr has no files to edit for this.
If you never created the admin account, open https://authentik.YOUR_DOMAIN/if/flow/initial-setup/.
Google OAuth
Section titled “Google OAuth”Google OAuth does not store passwords. People log in with their Google account. You control who may log in with a list of allowed accounts. Each allowed account is one whitelist=EMAIL line in secrets/oauth_secrets. To see an allowed account added by hand, watch Google OAuth with Traefik Forward Auth: allowed account in the secrets file at 11:24 (manual Docker Compose setup; the file is named oauth-secrets there).
Add an allowed account
Section titled “Add an allowed account”-
Back up the file:
Terminal window sudo cp secrets/oauth_secrets secrets/oauth_secrets.bak -
Open the file:
Terminal window sudo nano secrets/oauth_secrets -
Add a new line for the account. Replace
name@gmail.comwith the person’s Google address:whitelist=name@gmail.com -
Save with
Ctrl+O,Enter, then close withCtrl+X. -
Recreate the
oauthcontainer. Go to Tools > Stack Manager > Recreate. AtSelect an app to recreate:, type the number ofoauthand press Enter. See Stack Manager and Restart, Recreate or Reinstall an app after a change.
To remove an account, delete its whitelist= line and recreate oauth the same way. If a secrets/oauth_whitelist_N file holds that address, delete that file too (sudo rm secrets/oauth_whitelist_N, with the right number). Otherwise the account comes back the next time you run Security > Google OAuth.
Move your Basic Auth users to TinyAuth or Authelia
Section titled “Move your Basic Auth users to TinyAuth or Authelia”You can keep your Basic Auth users when you move to TinyAuth or Authelia. Their passwords stay the same. The hashes in secrets/basic_auth_credentials are bcrypt, and both tools accept them.
-
Show your Basic Auth users:
Terminal window sudo cat secrets/basic_auth_credentials -
Each line is
username:hash. The hash starts with$2y$. Keep this output open. -
Set up the new method first with Security > TinyAuth or Security > Authelia. Read the caution in TinyAuth or Authelia first. A rerun removes users, so do this before you copy anyone in.
-
Back up the new method’s file, as shown in its section.
Move users to TinyAuth
Section titled “Move users to TinyAuth”-
Open the file:
Terminal window sudo nano appdata/tinyauth/users_file -
Paste each Basic Auth line you want to keep on its own line. Do not change it. Skip the user you typed during setup, who is already there.
-
Save with
Ctrl+O,Enter, then close withCtrl+X. -
Recreate TinyAuth with Tools > Stack Manager > Recreate, or run
dcrec tinyauth.
Moved users have no two-factor. To add it, see Turn on two-factor for a user, or set up a new device.
Move users to Authelia
Section titled “Move users to Authelia”-
Open the file:
Terminal window sudo nano appdata/authelia/users.yml -
Add a block for each user below the last one. Use the text after the colon as the
passwordvalue, in single quotes. ReplaceUSERNAMEandEMAIL:USERNAME:disabled: falsedisplayname: USERNAMEemail: EMAILpassword: 'HASH_FROM_BASIC_AUTH'groups:- admins -
Save with
Ctrl+O,Enter, then close withCtrl+X. -
Restart Authelia:
Terminal window sudo docker restart authelia
Each user needs an email. Authelia uses it for password resets, and the messages go to notifications.txt. Keep the indent the same as the other users.
If a user cannot log in, make a new hash with Make a password hash. Put it in password: and restart Authelia. That user then has a new password.
Move your apps
Section titled “Move your apps”Use Security > Manage Auth (Pro) to switch apps to the new method. See Switch your apps to the new method.
Check it worked
Section titled “Check it worked”- Open a private browser window.
- Open an app that uses the method you changed, for example
https://APP.YOUR_DOMAIN. ReplaceAPPwith the app’s subdomain andYOUR_DOMAINwith your domain. - Log in as the new user, or with the new password.
- The app should open.
- If the method has two-factor, confirm the code works too.
If you are locked out
Section titled “If you are locked out”Put your backup file back, then recreate or restart the container. For example, for TinyAuth:
-
Restore the file:
Terminal window sudo cp appdata/tinyauth/users_file.bak appdata/tinyauth/users_file -
Recreate
tinyauthwith Tools > Stack Manager > Recreate, or rundcrec tinyauthwith the bash aliases.
For the other methods, use the matching backup and container:
| Method | Backup to restore | Container |
|---|---|---|
| Basic HTTP Auth | secrets/basic_auth_credentials.bak |
traefik (recreate) |
| Authelia | appdata/authelia/users.yml.bak |
authelia (restart) |
| Google OAuth | secrets/oauth_secrets.bak |
oauth (recreate) |
If the app still does not load, read the Traefik logs.
Next steps
Section titled “Next steps”- Move more apps to your login method with Manage Auth. See Choose a login method for your apps.
- Back up your Docker folder before bigger changes. See Back up and restore your Docker folder.

