# Authentication

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.

# Built-in

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.

# WebAuthn

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.

image by Arun (dribbble.com/nullpointone)

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.

# User verification

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:

In your .env file:
WEBAUTHN_USER_VERIFICATION=preferred

Supported value	Behavior
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.

How to authenticate API requests

../../api/#authentication

# Authentication proxy

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

Set the AUTHENTICATION_GUARD environment variable to reverse-proxy-guard.

In your .env file:
AUTHENTICATION_GUARD=reverse-proxy-guard

WebAuthn and Personal Access Token are not supported when using the reverse-proxy-guard

# 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 AUTH_PROXY_HEADER_FOR_USER to HTTP_2FAUTH_USER.

# Additional header

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

For now, 2FAuth does not use this information, but a future feature could use it to send you emails.