Skip to main content

Two-factor authentication

Two-factor authentication (2FA) adds a second step to logging in to YAFFA: besides your password, you also need a short code generated by an authenticator app on your phone. This protects your account even if your password leaks.

2FA is optional and disabled by default. Each user decides if they want to use it, and turning it on does not change anything for other users of the instance. It works with any standard TOTP authenticator app. The codes are generated and verified locally, and no third-party service is involved.

note

Two-factor authentication is available since YAFFA 4.0. It is not available in the hosted sandbox.

Turn on 2FA​

You manage 2FA in your user settings.

  1. Open the two-factor authentication section, and select to enable it.
  2. Scan the QR code with your authenticator app.
  3. Enter the current 6-digit code shown by the app to confirm the setup.
  4. YAFFA shows your recovery codes. Save them in a safe place, for example in a password manager. They are displayed only once, and you have to confirm that you saved them.

Log in with 2FA​

After you enter your email address and password, YAFFA asks for the code from your authenticator app. If you cannot access the app, you can use a recovery code instead. Each recovery code works only once.

As a protection against guessing the code, login attempts are limited: after 6 attempts within a minute, further attempts are refused for a while, even with a correct code.

Recovery codes​

If you used up your recovery codes, or you suspect that someone saw them, you can generate a new set in your user settings. This requires your current password, and all previous codes become invalid.

Turn off 2FA​

You can turn 2FA off in your user settings. This also requires your current password.

If you lose your device and your recovery codes​

There is no way to bypass 2FA from the login page, and there is no support desk to contact, since you host YAFFA yourself. Whoever has access to the server can disable 2FA for a user with the following command, after which the user can log in with the password only, and set up 2FA again.

php artisan app:user:disable-2fa user@example.com

With the Docker setup, run it inside the application container.

docker compose exec app php artisan app:user:disable-2fa user@example.com

Good to know​

  • The 2FA secrets and recovery codes are stored encrypted, using the application key of your instance. Keep a copy of the key and back up your data, so a restored instance can still read them.
  • The name shown in the authenticator app is the name of the application. You can customize it with the optional OTP_TOTP_ISSUER setting in the .env file.
  • 2FA also protects the creation of API tokens, as they are created from the same, logged-in user settings.