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

YAML 
1
2
3
4
5
6

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

Options

OptionDefaultDescription
enabledtrueEnable password authentication
minLength5Minimum password length
signupfalseAllow user self-registration
enforcedOtpfalseRequire all password users to enable Two-Factor Authentication

With User Signup

YAML 
1
2
3
4
5
6

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

With reCAPTCHA

YAML 
1
2
3
4
5
6
7
8

auth:
  methods:
    password:
      enabled: true
      signup: true
      recaptcha:
        key: "your-site-key"
        secret: "your-secret"  # Use environment variable

Set Admin Password

If password authentication is enabled, by default filebrowser will create a default admin user. This admin user is uniquely able to have the password set by the config. This happens automatically on startup if you specify an admin password via environment variable or config file.

Best practice - use environment variable:

BASH 
1

export FILEBROWSER_ADMIN_PASSWORD="secure-password"

Config based admin password

TEXT 
1
2
3

auth:
  adminUsername: admin
  adminPassword: admin # if set it will get reset on startup.

Two-Factor Authentication (2FA)

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

  • 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 enforceOtp is configured in the server config.

How It Works

  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

Generate TOTP Secret

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:

BASH 
1

openssl rand -base64 32

Add the generated key to your configuration:

YAML 
1
2

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

Enforce Two-Factor Authentication

Require all password users to enable 2FA:

YAML 
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

Enable 2FA (User)

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

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

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