Configure

Two-factor authentication🔗

A password can be guessed, reused on another website, or read out of a leaked database. A second factor is something an attacker does not have: the device in the user's hand, or a key they carry.

FileRun asks for a second factor when a user signs in, and again before any change that affects the security of an account.

Note

This page describes FileRun 2026.3.0 and newer. Earlier versions offered only the authenticator app.

The verification methods🔗

FileRun always asks for the strongest method the account has, in this order: passkey, then authenticator app, then e-mailed code, then the account password. A weaker method is never accepted in place of a stronger one. If it were, an attacker who reached a user's mailbox could work around a passkey.

Because an e-mailed code counts as a verification method, every account with an e-mail address is protected by more than its password alone. Only accounts without an e-mail address fall back to the password.

Passkeys🔗

A passkey is a key pair stored by the device or by the browser's password manager. The private half never leaves the device, so there is nothing to steal from FileRun and nothing to type into a fake sign-in page.

The user adds one from Account settings → Two-factor authentication → Passkeys, names it, and confirms with the device. Add one on every device used regularly.

Passkeys need FileRun to be served over HTTPS, and they are tied to the host name in the address bar. See What to know before changing the address.

Authenticator app🔗

FileRun follows the TOTP standard (RFC 6238), so any compatible app works. Common ones are Google Authenticator, Microsoft Authenticator, Authy, 1Password and Bitwarden.

The user opens Account settings → Two-factor authentication → Authenticator app, scans the QR code with the app, and types the six digit code once to confirm that the app is set up correctly. The codes change every 30 seconds and each one can be used only once.

E-mailed codes🔗

When an account has neither a passkey nor an authenticator app, FileRun e-mails a six digit code to confirm a security change. The code is valid for 10 minutes, and a new one cannot be requested until the previous one expires.

E-mailed codes are not used for signing in. They protect the changes described under Confirming a security change.

Recovery codes🔗

Recovery codes are the way back into an account whose passkey or authenticator app is gone. FileRun generates ten of them, each usable once.

They are shown only once, when they are generated, and the page offers to download, print or copy them. FileRun stores only their hashes, so a lost set cannot be shown again — it can only be replaced. Generating a new set invalidates the old one, and the account owner receives an e-mail each time a set is generated and each time a code is used.

Recovery codes work only for accounts that have a passkey or an authenticator app enrolled. They stand in for a lost second factor; an account that never had one has nothing to recover.

Signing in🔗

1. The user types the username and password as usual.
2. If the account has a passkey or an authenticator app enrolled, FileRun then asks for it.

An account with neither signs in with the password alone. Enrolling a second factor is what turns the second step on, which is why an administrator who wants it can require it.

Users who sign in through single sign-on are asked for their second factor after the remote sign-in, but only when Allow users to protect their accounts with two-factor authentication. is enabled under Users → Authentication in the control panel. Without that option, a second factor is never requested for accounts authenticated by the third-party system.

Confirming a security change🔗

Signing in is not the only moment that matters. Anyone who reaches an unattended, already signed-in browser could otherwise change the password and take the account over. FileRun therefore asks for the account's strongest verification method again before:

• changing the password,
• changing the e-mail address,
• adding or removing a passkey,
• setting up or resetting the authenticator app,
• generating recovery codes,
• opening the list of sessions,
• opening the connected apps, and creating a new set of credentials with Connect app,
• resetting a forgotten password.

One verification covers the next five minutes, so a user changing several settings is not asked repeatedly. The permission is tied to the browser and to the IP address it came from, and changing the password or the e-mail address consumes it, so those two always ask again.

Setting it up as a user🔗

Everything is in Account settings, reachable from the user menu:

• Two-factor authentication → Passkeys
• Two-factor authentication → Authenticator app
• Two-factor authentication → Recovery codes
• Sessions
• Connected apps

The recommended order is: add a passkey on each device, generate the recovery codes and store them somewhere safe, and then remove the authenticator app if one was set up. As long as an authenticator app stays enrolled, the account can be signed in to without a passkey, so the account is only as strong as the weaker of the two.

A user who is not allowed to change these settings does not see the section. That is the User can change authentication settings option on the Login tab of the user account.

Requiring a second factor🔗

An administrator can make a second factor mandatory in two places:

• For everyone — Require two-factor authentication, under Security → Sign-in policy in the control panel.
• For one account — Require user to use two-step verification, on the Login tab when adding or editing a user account. When the global option is on, this one is on for every account and cannot be turned off individually.

A user in that state cannot reach the file manager until a method is enrolled. FileRun shows a configuration page with Passkeys, Authenticator app and Recovery codes, and the Continue button works once at least one of the first two is set up. An e-mailed code does not satisfy the requirement.

The requirement applies only to accounts allowed to change their own authentication settings. It is checked every time the main interface is loaded, not only at sign-in, so turning the option on takes effect for users who are already signed in.

When a user loses the device🔗

In order, from the least disruptive:

1. A recovery code. On the verification page the user chooses to use a recovery code instead. Each code works once.
2. The authenticator app, when only the passkey is lost. If the account has both, FileRun accepts the authenticator app as recovery.
3. An administrator reset. Editing the user account, the Login tab has Reset all multifactor verification methods now. It deletes the account's passkeys and its authenticator app configuration, so the account signs in with its password alone and can enroll again.
4. The superuser, who has no administrator above them, is reset from the command line:

 1php cron/reset_superuser_2fa.php

See Command line tools.

Note

Resetting the password does not remove the second factor. This is deliberate: if a user's mailbox is compromised, the second factor is the last line of defence, and a password reset must not be able to strip it.

Sessions🔗

Account settings → Sessions lists the browsers currently signed in to the account, with the IP address and when each was last used. The current one is marked. A user who no longer recognises a session can end it there.

Signing out, resetting the password and recovering a forgotten password each end every session of that account.

Resetting a forgotten password🔗

When Enable the "Forgot password?" option is on, under Security → Passwords:

1. The user asks for a reset and receives a six digit code by e-mail, valid for 10 minutes. Only one request is accepted at a time.
2. If the account has a passkey or an authenticator app, FileRun asks for it as well. An e-mailed code is not accepted here, because the reset itself already started with an e-mail.
3. The user then sets a new password directly. No temporary password is sent.

Completing a reset ends every session of the account, revokes its OAuth2 authorizations and deletes every set of credentials it created with Connect app. The user has to reconnect their devices afterwards.

An account with no passkey and no authenticator app is reset with the e-mailed code alone.

WebDAV, the API, and the desktop and mobile apps🔗

Since FileRun 2026.3.0, no account can use its own username and password for WebDAV, the API, the desktop sync app or the mobile apps. This is not related to two-factor authentication: it applies to every account.

Those connections use an app password instead, which the user generates with Connect app in the FileRun interface. Each one can be named, and is listed and revocable under Connected apps.

Existing connections were carried over by the update to 2026.3.0, so users did not have to reconnect their devices. Third-party integrations that used OAuth2 do have to be authorized again.

See Accessing via WebDAV and the API.

What to know before changing the address🔗

A passkey is bound to the host name FileRun is served from. If the installation moves from files.example.com to another host name, the passkeys registered under the old one stop working, and the affected users need a recovery code or an administrator reset.

Passkeys also require HTTPS. On an installation served over plain HTTP the browser refuses to create them.

Setting Administrator contact information, under System → Settings in the control panel, is worth doing before requiring a second factor. It is shown on the verification page to a user who can no longer verify their identity, so they know whom to ask.