Security Settings

Security settings let users protect their account with password changes, email updates, MFA enrollment, and OAuth account linking. These controls are built on Better Auth and appear at /settings/security. Password and email options only show for users with credential authentication - OAuth-only users see just MFA and connected accounts.

Security settings are the user-facing controls for authentication credentials (password, email), multi-factor authentication (TOTP), and identity provider connections (OAuth).

• Location: apps/web/app/[locale]/(internal)/settings/security/page.tsx
• Route: /settings/security

These settings are only available to users who signed up with email and password (credential authentication). Users who signed up exclusively via OAuth providers will not see the password or email update options.

Update Password

Users can change their account password from this section. The form requires entering the current password for verification, followed by the new password and a confirmation.

Update Email

Users can update the email address associated with their account. For security, email changes require verification.

When a new email is submitted, a verification link is sent to both the new email address and the current email address. The user must click the link in both emails to confirm the change - this prevents unauthorized email takeover.

Two-Factor Authentication (MFA/2FA)

Users can enable two-factor authentication for additional account security. When enabled, users must enter a time-based one-time password (TOTP) from an authenticator app when signing in.

Note: MFA is only enforced for users signing in with email/password. Users signing in with OAuth providers are not required to have MFA enabled.

The setup process involves:

1. Verifying identity with current password
2. Scanning a QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.)
3. Entering a code from the app to confirm setup
4. Saving backup codes for account recovery

Once enabled, MFA can be disabled from this same section if needed.

Connected OAuth Accounts

Users can link multiple OAuth providers to their account, allowing them to sign in with any connected provider.

Available actions:

• Link a new provider - Connect additional OAuth accounts (Google, GitHub, etc.)
• Unlink a provider - Remove a connected OAuth account (only allowed if the user has a password or another OAuth provider linked)

This is useful for users who want flexibility in how they sign in, or who want to consolidate multiple authentication methods into a single account.

Common Pitfalls

• MFA backup codes not stored securely by users: Users lose access if they lose their authenticator device and didn't save backup codes. Consider showing backup codes prominently and requiring confirmation they were saved.
• Email change requires both old and new email access: If users no longer have access to their old email, they're stuck. Have a support process for this edge case.
• OAuth unlinking when it's the only auth method: Users can't unlink their last OAuth provider without a password. The UI prevents this, but test the edge case where password was never set.
• MFA not enforced for OAuth sign-ins: MFA is only required for email/password authentication. If you need MFA for all users, disable OAuth or implement custom checks.
• Password changes don't invalidate other sessions: By default, changing password doesn't sign out other devices. Implement session revocation if your security requirements demand it.

Next: Preferences →