Skip to content

Change login passwords and add users for Basic Auth, TinyAuth, Authelia and Google OAuth

GuideDeployrr v6.0+CurrentAuthenticationTraefik

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.

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.

  1. Open a terminal on the server.

  2. Go to your Docker folder. Replace YOUR_DOCKER_FOLDER with its path:

    Terminal window
    cd YOUR_DOCKER_FOLDER
  3. Keep this terminal open. The commands below use paths that start from this folder.

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).

  1. Back up the file:

    Terminal window
    sudo cp secrets/basic_auth_credentials secrets/basic_auth_credentials.bak
  2. Run this command. Replace USERNAME with 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
  3. Type the password when asked. Type it again to confirm.

  4. Recreate Traefik so it reads the file. Go to Tools > Stack Manager > Recreate. At Select an app to recreate:, type the number of traefik and press Enter. With the Deployrr bash aliases, you can run this instead:

    Terminal window
    dcrec traefik
  1. Back up the file, as shown above.

  2. Run this command. Replace USERNAME with the user’s name:

    Terminal window
    sudo htpasswd -D secrets/basic_auth_credentials USERNAME
  3. Recreate Traefik, as in the previous part.

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:

  1. Open the password file:

    Terminal window
    sudo nano secrets/basic_auth_password
  2. Edit the file so it holds only the new password.

  3. Save with Ctrl+O, Enter, then close with Ctrl+X.

You can also use Tools > Secrets Editor with a Pro license. See Edit .env values and secrets.

TinyAuth keeps one line per user in appdata/tinyauth/users_file. A line looks like one of these:

username:bcrypt-hash
username:bcrypt-hash:TOTPSECRET

The second form means the user has two-factor login. TOTPSECRET is the secret for the authenticator app.

  1. Back up the file:

    Terminal window
    sudo cp appdata/tinyauth/users_file appdata/tinyauth/users_file.bak
  2. Run this command. Replace USERNAME with 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
  3. Type the password when asked. Type it again to confirm.

  4. Recreate TinyAuth so it reads the file. Go to Tools > Stack Manager > Recreate and type the number of tinyauth. Or, with the bash aliases, run dcrec 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”
  1. Show the user’s full line. Replace USERNAME with the user’s name:

    Terminal window
    sudo grep '^USERNAME:' appdata/tinyauth/users_file
  2. Generate a secret. Replace FULL_LINE with 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'

    v5 is the TinyAuth version Deployrr uses by default. If you pinned another version, use that one.

  3. Scan the QR code with the user’s authenticator app.

  4. Copy the text after secret=.

  5. Open the file:

    Terminal window
    sudo nano appdata/tinyauth/users_file
  6. At the end of that user’s line, type a colon and then the secret. The line then looks like username:bcrypt-hash:TOTPSECRET.

  7. Save with Ctrl+O, Enter, then close with Ctrl+X.

  8. Recreate TinyAuth, as in the previous part.

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 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).

Authelia stores a hash, not the password.

  1. Run this command. Replace NEWPASSWORD with the password you want. Keep the single quotes:

    Terminal window
    sudo docker run --rm authelia/authelia:4.37.5 authelia hash-password 'NEWPASSWORD'
  2. Look for the line that starts with Password hash:.

  3. Copy the text after Password hash: . It starts with $argon2id$.

  1. Back up the file:

    Terminal window
    sudo cp appdata/authelia/users.yml appdata/authelia/users.yml.bak
  2. Open the file:

    Terminal window
    sudo nano appdata/authelia/users.yml
  3. Find the user’s password: line.

  4. Replace the value with the new hash. Put it in single quotes.

  5. Save with Ctrl+O, Enter, then close with Ctrl+X.

  6. Restart Authelia:

    Terminal window
    sudo docker restart authelia
  1. Make a hash for the new user’s password, as shown above.

  2. Back up the file, as in the previous part.

  3. Open the file with sudo nano appdata/authelia/users.yml.

  4. Copy an existing user block, including its name line.

  5. Paste it below the last user.

  6. Change the name, displayname, email and password of the copy.

  7. Save with Ctrl+O, Enter, then close with Ctrl+X.

  8. Restart Authelia:

    Terminal window
    sudo docker restart authelia

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).

  1. Open the Authelia login page, for example https://authelia.YOUR_DOMAIN. Replace YOUR_DOMAIN with your domain.

  2. Log in with the user’s password.

  3. Choose the option to register a new device. For a forgotten password, choose the reset option on the login page.

  4. Print the messages file:

    Terminal window
    sudo cat appdata/authelia/notifications.txt
  5. Copy the code or link from the newest message.

  6. Use it in the browser, on the same device you started on.

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 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 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).

  1. Back up the file:

    Terminal window
    sudo cp secrets/oauth_secrets secrets/oauth_secrets.bak
  2. Open the file:

    Terminal window
    sudo nano secrets/oauth_secrets
  3. Add a new line for the account. Replace name@gmail.com with the person’s Google address:

    whitelist=name@gmail.com
  4. Save with Ctrl+O, Enter, then close with Ctrl+X.

  5. Recreate the oauth container. Go to Tools > Stack Manager > Recreate. At Select an app to recreate:, type the number of oauth and 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.

  1. Show your Basic Auth users:

    Terminal window
    sudo cat secrets/basic_auth_credentials
  2. Each line is username:hash. The hash starts with $2y$. Keep this output open.

  3. 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.

  4. Back up the new method’s file, as shown in its section.

  1. Open the file:

    Terminal window
    sudo nano appdata/tinyauth/users_file
  2. 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.

  3. Save with Ctrl+O, Enter, then close with Ctrl+X.

  4. 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.

  1. Open the file:

    Terminal window
    sudo nano appdata/authelia/users.yml
  2. Add a block for each user below the last one. Use the text after the colon as the password value, in single quotes. Replace USERNAME and EMAIL:

    USERNAME:
    disabled: false
    displayname: USERNAME
    email: EMAIL
    password: 'HASH_FROM_BASIC_AUTH'
    groups:
    - admins
  3. Save with Ctrl+O, Enter, then close with Ctrl+X.

  4. 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.

Use Security > Manage Auth (Pro) to switch apps to the new method. See Switch your apps to the new method.

  1. Open a private browser window.
  2. Open an app that uses the method you changed, for example https://APP.YOUR_DOMAIN. Replace APP with the app’s subdomain and YOUR_DOMAIN with your domain.
  3. Log in as the new user, or with the new password.
  4. The app should open.
  5. If the method has two-factor, confirm the code works too.

Put your backup file back, then recreate or restart the container. For example, for TinyAuth:

  1. Restore the file:

    Terminal window
    sudo cp appdata/tinyauth/users_file.bak appdata/tinyauth/users_file
  2. Recreate tinyauth with Tools > Stack Manager > Recreate, or run dcrec tinyauth with 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.