Password Authentication

Password authentication uses the typical username and password to login a user. Password authentication also supports Signup, recaptcha, and Two-Factor Authentication features.

Basic Configuration link

1
2
3
4
5
6

auth:
  methods:
    password:
      enabled: true
      minLength: 5
      signup: false

Options link

With User Signup link

1
2
3
4
5
6

auth:
  methods:
    password:
      enabled: true
      minLength: 12
      signup: true

Set Admin Password link

If password authentication is enabled, FileBrowser creates a built-in admin password on first startup. The username defaults to admin.

If adminPassword is unset or left as admin (including when auth.methods.password.adminPassword is unset or admin), a random speakable bootstrap password is generated, logged once, and the admin account is flagged requirePasswordChange so login is blocked until a new password is set. The generated form is word-xxxxx-xx (a random word from a fixed list, a 5-character code, and a 2-character code) instead of a long hex string. v2.0+ uses this format.

Best practice - use an environment variable: link

1

export FILEBROWSER_ADMIN_PASSWORD="secure-password"

Config-based admin password link

1
2
3
4
5
6

auth:
  methods:
    password:
      enabled: true
      adminUsername: admin
      adminPassword: "choose-a-password"

Require password change (v2.0.0) link

Password-based users can be required to set a new password before any other login succeeds:

• User defaults: userDefaults.account.requirePasswordChange (also configurable under Settings → User management → User defaults).
• Per user: admins can toggle Require password change when editing a user.
• Bootstrap admin: when the initial admin password is generated (unset/admin config as above), requirePasswordChange is set automatically.

When requirePasswordChange is true, normal login returns a change-password flow in the UI. The API endpoint is POST /api/auth/password/change-required (current password in the X-Password header; new password in the JSON body). After a successful change, the flag is cleared.

Two-Factor Authentication (2FA) link

Two-Factor Authentication (2FA) adds an extra layer of security to password-based logins by requiring a time-based one-time password (TOTP) in addition to the username and password.

Benefits of Two-Factor Authentication link

• Enhanced Security: Even if a password is compromised, attackers cannot access the account without the 6-digit code
• Protection Against Phishing: 2FA codes are time-limited and cannot be reused
• Compliance: Meets security requirements for many organizations and regulations
• User Control: Users can enable or disable 2FA from their profile settings unless enforcedOtp is set under auth.methods.password.

How It Works link

1. Setup: User enables 2FA in their profile settings
2. QR Code: A QR code is displayed that can be scanned with authenticator apps (Google Authenticator, Authy, Microsoft Authenticator, etc.)
3. Verification: User enters a 6-digit code from their authenticator app to complete setup
4. Login: After entering username and password, users with 2FA enabled must enter the current 6-digit code from their authenticator app
5. Time-Based: Codes refresh every 30 seconds and are valid for 2 minutes

Configuration link

Generate TOTP Secret link

Before enabling 2FA, you must generate a secure encryption key for TOTP secrets. This key encrypts user TOTP secrets in the database.

Generate a secure random key using OpenSSL:

1

openssl rand -base64 32

Add the generated key to your configuration:

1
2

auth:
  totpSecret: "your-generated-key-here"  # Use environment variable for security

1

export FILEBROWSER_TOTP_SECRET="your-generated-key-here"

Enforce Two-Factor Authentication link

Require all password users to enable 2FA:

1
2
3
4
5

auth:
  methods:
    password:
      enabled: true
      enforcedOtp: true  # All password users must enable 2FA

When enforcedOtp: true:

• New password users must set up 2FA before they can log in
• Existing password users without 2FA cannot log in until they enable it
• Users are prompted to set up 2FA on their first login after enforcement is enabled

User Management link

Enable 2FA (User) link

Users can enable 2FA from their profile settings:

1. Go to Profile → Security
2. Click Enable 2FA or Generate New OTP
3. Scan the QR code with an authenticator app
4. Enter the 6-digit code to verify and complete setup

Admin Management link

Administrators can manage 2FA for any user:

1. Go to User Management
2. Edit the user
3. In the user edit dialog, toggle 2FA on or off
4. Click Generate New OTP to reset a user’s 2FA (useful if they lost their device)

Reset 2FA via CLI link

If a user loses access to their authenticator device, administrators can reset their password and 2FA using the CLI. See CLI password reset for details.

Next Steps link

• OIDC authentication
• Manage users
• CLI commands for user management