two-factor-auth

Two Factor Authentication

Adds TOTP-based two-factor authentication on top of an existing auth system. Uses nimble_totp for code generation/verification and eqrcode for the QR code shown during enrollment. Extends the User schema with a has_two_factor_auth_setup flag, manages authenticator secrets through UserToken, and adds a setup/verify LiveView plus a router gate that can force every user to enroll.

When to use

• The app handles money or sensitive data and needs a second login factor.
• You want enrollment, QR display, and TOTP verification with ready-made UI.
• You need app-wide enforcement (require every user to enroll) or per-user opt-in.
• Don't reach for this if email confirmation alone is enough — that's require_confirmed_user.

Dependencies

• Requires: None — but it injects into the auth schema, UserToken, and UserAuth, so install authentication first.
• Recommended: None.

Install

mix saaskit.feature.install two_factor_auth

Pulls in {:eqrcode, "~> 0.2.1"} and {:nimble_totp, "~> 1.0.0"}, generates the 2FA controller and LiveView, injects the schema field, the Users context functions, the UserToken helpers, the router scope, and the UserAuth gate. No installer decisions — enforcement is a config flag (see Configuration).

What it generates

• lib/my_app_web/live/user_two_factor_live.ex — setup/verify LiveView. Shows a QR code on first enrollment, accepts a 6-digit code, sets has_two_factor_auth_setup.
• lib/my_app_web/controllers/user_two_factor_controller.ex — verifies the signed "2fa_confirmed" token and writes :confirmed_2fa_setup into the session.
• Extends lib/my_app/users.ex — generate_user_authenticator_token/1, get_authenticator_token_for_user/1, delete_user_authenticator_token/1, generate_timebased_challenge/1, generate_authenticator_url/1, verify_timebased_challenge/2.
• Extends lib/my_app/users/user_token.ex — build_authenticator_token/1 (a "authenticator"-context token holding the TOTP secret) and find_authenticator_token_query/1.
• Extends lib/my_app/users/user.ex — adds field :has_two_factor_auth_setup and includes it in @additional_attributes.
• Extends lib/my_app_web/user_auth.ex — adds the ensure_2fa_setup/1 gate into require_authenticated_user/2.
• Extends lib/my_app_web/router.ex — /users/two_factor (LiveView) and /users/two_factor/:token (controller confirm).
• Adds tests in test/my_app/users_test.exs and test/my_app_web/controllers/user_two_factor_controller_test.exs.