2FAuth has been designed for personal use only, it is single user oriented.
You have to create a user account to use the app, and more than one user account cannot be created. None of the app's features can be used unless you have been authenticated with one of the following methods.
Authentication is done by submitting your credentials, an email and a password, to the 2FAuth login form. Nothing special here, it is a very common and well-known method.
This is the default authentication method.
2FAuth supports the W3C Web Authentication API aka WebAuthn (learn more). This means you can register a security device like a Yubikey, a Titan Security Key, or a facial recognition system like Apple FaceId and use it to log into 2FAuth.
This method is considered more secure, as it proves you are in fact you because you have to physically own the security device.
WebAuthn is available in 2FAuth as a complement or a replacement to the built-in login/password method. Consider using only WebAuthn to provide the highest protection to your 2FAuth instance.
The WebAuthn flow does not use login & password, but the creation of a user account with an email and a password remains mandatory.
Registering a security device
2FAuth offers to register a WebAuthn device right after submitting the user registration form or through its Settings > Webauthn section. Whatever you choose, the registration process will be the same and depends on the hardware you use (desktop, laptop or smartphone) and how your browser implements the WebAuthn flow.
A typical workflow would be:
- You click the Register a new device link in 2FAuth
- Your browser prompts you to grant the operation
- You put your finger on the key's touch button
- 2FAuth registers the key and offers you to rename it
You can register several security devices, there is no limitation in the number of devices.
Revoking a security device
You can revoke any registered security device through the Settings > Webauthn section.
Simply click the relevant Revoke button.
The revocation of a device is permanent and cannot be undone.
I lost my device
Don't worry, there is always a solution, depending on how you have configured 2FAuth's WebAuthn options.
If you have registered another device and still own it, just use this device to log in. Otherwise, you can recover your account by registering a new security device.
Click the Recover your account link of the 2FAuth's login form, this will send a link to your registered email address. Follow this link, you will be able to register a new device and revoke all existing ones.
Assuming you haven't lost your password too, switch the 2FAuth login form using the link Sign in using login & password and log in using your email address and password. It's that simple!
Don't forget to revoke the lost device in the Settings > Webauthn section.
Most authenticators and smartphones will ask the user to actively verify themselves to log in. For example, through a touch plus pin code, password entry, or biometric recognition (e.g., presenting a fingerprint). The intent is to distinguish one user from any other.
You can configure how the user verification step behave during the WebAuthn login flow with the
WEBAUTHN_USER_VERIFICATION env var:
|required||Will ALWAYS ask for user verification|
|preferred (default)||Will ask for user verification IF POSSIBLE|
|discouraged||Will NOT ask for user verification (for example, to minimize disruption to the user interaction flow)|
Personal Access Token
Use Personal Access Tokens (PAT) to authenticate requests sent to the 2FAuth REST API.
You can configure 2FAuth to let an HTTP proxy handle authentication. In this case, 2FAuth will consider you logged in as long as you are authenticated at proxy level. This is particularly useful if you want to deploy 2FAuth behind a service like Sandstorm or behind an Auth server like Authelia.
2FAuth will check for an HTTP header, named
REMOTE_USER by default, in every request from the proxy. (see RFC3875)
2FAuth only check for the header presence, nor its validity nor its content, so be sure your instance cannot be reached otherwise than through your auth proxy.
Enable the proxy guard
AUTHENTICATION_GUARD environment variable to
WebAuthn and Personal Access Token are not supported when using the
Customize the header name
You can customize the header name by setting the
AUTH_PROXY_HEADER_FOR_USER environment variable to match a specific proxy configuration. For example, if the proxy header is
2FAUTH-User, then set
You can configure 2FAuth to check for an additional header that contain the authenticated user email address. This header may or may not exist depending on the auth proxy configuration. The environment variable to set for that is
For now, 2FAuth does not use this information, but a future feature could use it to send you emails.