Enabling Laravel Jetstream’s Built‑In Two‑Factor Authentication

Why add 2FA with Jetstream?

Even with strong passwords, credential theft remains a common attack vector. Laravel Jetstream ships an optional two‑factor authentication (2FA) feature that uses time‑based one‑time passwords (TOTP). When enabled, it adds a verification step after the usual login form, significantly raising the bar for attackers who only have a username and password.

How Jetstream’s 2FA works

Jetstream does not reinvent the wheel; it relies on the laravel/totp package (or a compatible implementation) to generate and validate TOTP codes. When a user enables 2FA, Jetstream:

1. Generates a random secret key.
2. Stores an encrypted version of that secret in a new two_factor_secret column on the users table.
3. Creates a set of one‑time recovery codes, saved encrypted in two_factor_recovery_codes.
4. Shows a QR code that encodes the secret so the user can scan it with an authenticator app (Google Authenticator, Authy, etc.).
5. During login, after the password check, Jetstream prompts for the six‑digit code from the app and validates it against the stored secret.

The encryption ensures that even if the database is exposed, the secret cannot be read directly.

Enabling the feature

Assuming you already have a Laravel project with Jetstream installed (Livewire or Inertia stack), follow these steps:

1. Publish Jetstream’s configuration if you haven’t already:

php artisan vendor:publish --provider="Laravel\Jetstream\JetstreamServiceProvider"

1. Open config/jetstream.php and set the 2FA flag to true:

'features' => [
    'two_factor_authentication' => true,
    // other features…
],

1. Run the migration that adds the two columns:

php artisan migrate

After the migration, log in (or register) a test user, navigate to the profile page, and you’ll see a new “Two‑Factor Authentication” section. Click “Enable Two‑Factor Authentication”, scan the QR code with your authenticator app, enter the generated code, and Jetstream will confirm that 2FA is now active.

What the user experiences

Once 2FA is enabled, the login flow changes:

• User enters email and password as usual.
• If credentials are correct, Jetstream redirects to a second screen asking for the six‑digit TOTP code.
• After a valid code is submitted, the user is granted access.
• If the user loses access to their authenticator app, they can use one of the recovery codes shown only once during setup.

From a developer’s perspective, no changes to controllers or routes are required; Jetstream adds the necessary middleware automatically.

Trade‑offs and limitations

While the added security is valuable, consider these points before rolling out to all users:

• Time synchronization: TOTP relies on the server clock being in sync with UTC. If the host drifts, validation will fail and users may be locked out. Use NTP or a similar service to keep time accurate.
• Recovery codes are shown once: If a user does not download or store the codes, losing the authenticator app means permanent lockout unless an admin resets the secret.
• Existing accounts: Enabling 2FA after users have already registered does not force them to set it up immediately. They can still log in with just password until they visit their profile and enable 2FA. Plan a communication campaign or a forced‑reset flow if you need universal coverage.
• Extra step adds friction: Some users may find the additional code entry annoying, especially on mobile devices. Offering a “remember this device for 30 days” cookie (not provided out‑of‑the‑box by Jetstream) can mitigate this, but requires custom implementation.

Verification checklist

To confirm that 2FA is working as expected, perform the following:

1. Check the users table: the two_factor_secret column should contain an encrypted string, and two_factor_recovery_codes should hold a JSON‑encoded array after setup.
2. Log out, then log in with correct email and password. Verify that you are prompted for a TOTP code.
3. Enter an incorrect code; the login should fail with a validation error.
4. Enter a correct code from your authenticator app; you should be redirected to the intended dashboard.
5. Attempt to log in without completing the 2FA step (e.g., by directly accessing a protected route); you should be redirected to the 2FA code entry page.

If any of these checks fail, revisit the configuration, ensure migrations ran, and verify that the server time is synchronized.

Actionable next steps

If you decide Jetstream’s 2FA fits your project:

1. Enable the feature in config/jetstream.php.
2. Run the migration and test with a fresh user account.
3. Document the recovery‑code procedure for your support team.
4. Monitor server time drift and set up alerts if NTP deviates.
5. Consider a gradual rollout: enable 2FA for new registrations first, then prompt existing users via a banner or email.

By following these steps, you’ll add a strong layer of protection to your Laravel application while keeping the implementation straightforward and maintainable.