October 30, 2025

Two-Factor Authentication (Admin Guide)

Configure organization-wide two-factor authentication settings and requirements.

Overview

As an organization administrator, you can enable two-factor authentication (2FA) for your organization and optionally require all users to set it up. This guide covers configuration and management of organization-wide 2FA settings.

Enabling Two-Factor Authentication

Prerequisites

  • You must have administrative access to organization settings
  • Typically requires Site Admin or Enterprise Admin role

Configuration Steps

  1. Navigate to Organization Settings

    • Go to your Company Profile
    • Select the Settings or Overview tab

  2. Locate Two-Factor Authentication Settings

    • Find the Security or Two-Factor Authentication section

  3. Enable 2FA

    • Toggle Enable Two-Factor Authentication to ON
    • This makes 2FA available as an option for all users in your organization

  4. Require 2FA (Optional)

    • Toggle Require Two-Factor Authentication to ON
    • When enabled, all users must set up 2FA to access the application
    • Users without 2FA will be redirected to the setup page upon login

  5. Save Changes

    • Click Save to apply the settings
    • The change will be logged in the organization audit trail

Configuration Options

Enable Two-Factor Authentication

Purpose: Makes 2FA available for users in your organization

When enabled:

  • Users can enable 2FA from their Account Settings
  • 2FA is optional - users choose whether to use it
  • Recommended for all organizations for enhanced security

When disabled:

  • No users can enable or use 2FA
  • Existing 2FA configurations remain but are inactive

Require Two-Factor Authentication

Purpose: Mandates that all users must enable 2FA

When enabled:

  • All users are required to set up 2FA
  • Users without 2FA are redirected to the setup page upon login
  • Users cannot access the application until 2FA is configured
  • Users cannot disable their own 2FA
  • Recommended for organizations handling sensitive data or subject to compliance requirements

When disabled:

  • 2FA remains available but is optional
  • Users can choose to enable or disable 2FA at their discretion

User Experience When 2FA is Required

When you enable "Require Two-Factor Authentication":

  1. Existing Users:

    • Upon next login, users without 2FA are automatically redirected to the setup page
    • They must complete 2FA setup before accessing the application
    • A warning message explains: "Your organization requires two-factor authentication. Please set it up to continue."

  2. New Users:

    • Follow the same flow - redirected to 2FA setup upon first login
    • Must complete setup before accessing any application features

  3. Pages Accessible During Setup:

    • Users can only access:
      • Two-Factor Setup page
      • Account Settings page
      • Logout functionality
    • All other pages redirect to the setup page

Managing Users with 2FA

Viewing 2FA Status

Via Audit Logs:

  1. Navigate to Company Profile → Audit tab
  2. Filter for events:
    • com.alaigned.auth.2fa.enabled - User enabled 2FA
    • com.alaigned.auth.2fa.disabled - User disabled 2FA
    • com.alaigned.auth.2fa.verify.success - Successful 2FA login
    • com.alaigned.auth.2fa.verify.failed - Failed 2FA attempt

Helping Users with 2FA Issues

User Lost Access to Authenticator

If a user loses their phone or authenticator app:

  1. If they have backup codes: User can log in with a backup code
  2. If no backup codes available:
    • Currently, you must disable 2FA for the user (contact support for assistance)
    • User can then log in and re-enable 2FA with their new device

Future Enhancement: Admin interface to reset user 2FA will be added in a future release.

User Cannot Complete Setup

Common issues and solutions:

  1. QR code won't scan: User should try manual entry using the secret key
  2. Verification code rejected: Check that user's device time is accurate (automatic time sync)
  3. Lost backup codes during setup: User must restart setup (refresh the page)

Compliance and Security

Audit Trail

All 2FA-related events are automatically logged:

Organization Events:

  • com.alaigned.organization.2fa.settings_changed - Admin changed 2FA settings
    • Includes which settings were changed (enabled, required)

User Events:

  • com.alaigned.auth.2fa.enabled - User completed 2FA setup
  • com.alaigned.auth.2fa.disabled - User disabled 2FA (when not required)
  • com.alaigned.auth.2fa.verify.success - Successful 2FA verification
  • com.alaigned.auth.2fa.verify.failed - Failed verification attempt
  • com.alaigned.auth.2fa.backup_codes.regenerated - User regenerated backup codes

All events include:

  • User ID and email
  • IP address
  • User agent (browser/device)
  • Timestamp
  • Method (TOTP or backup code, when applicable)

Monitoring Failed Attempts

Watch for patterns in failed 2FA attempts:

  1. Multiple failed attempts from same user: May indicate compromised password
  2. Failed attempts from unusual locations: Potential unauthorized access attempt
  3. Many failed attempts across users: Possible coordinated attack

These patterns can be identified by filtering audit logs for com.alaigned.auth.2fa.verify.failed events.

Rollout Strategy

When implementing required 2FA for your organization:

  1. Phase 1: Enable (Optional)

    • Enable 2FA but don't require it
    • Communicate to users that 2FA is available
    • Allow time for early adopters to test

  2. Phase 2: Communicate

    • Announce to all users that 2FA will be required
    • Provide at least 2 weeks notice
    • Share the user guide: Two-Factor Authentication
    • Host Q&A sessions for users who need help

  3. Phase 3: Require

    • Enable "Require Two-Factor Authentication"
    • Monitor audit logs for setup completions and issues
    • Provide support for users having difficulties

Communication Template

Subject: Two-Factor Authentication Required - Action Required

Dear Team,

To enhance the security of our organization's data, we will be requiring
two-factor authentication (2FA) for all users starting [DATE].

What this means:
- You'll need an authenticator app on your smartphone
- After entering your password, you'll enter a 6-digit code from your app
- This protects your account even if your password is compromised

Action Required:
1. Install an authenticator app (Google Authenticator, Microsoft Authenticator,
   or Authy)
2. Set up 2FA in your Account Settings before [DATE]
3. Save your backup codes in a secure location

Resources:
- Setup Guide: [link to two-factor-authentication guide]
- Supported Apps: Google Authenticator, Microsoft Authenticator, Authy,
  1Password, Bitwarden
- Support: Contact [support contact] if you need assistance

Starting [DATE], you'll be prompted to set up 2FA when you log in if you
haven't already done so.

Thank you for helping us keep our organization secure.

Best Practices

  1. Plan the rollout: Give users adequate notice before requiring 2FA
  2. Provide resources: Share the user guide and be available for questions
  3. Monitor adoption: Use audit logs to track which users have enabled 2FA
  4. Regular reminders: Remind users to keep their backup codes safe
  5. Security review: Periodically review failed 2FA attempts for security threats
  6. Documentation: Keep users informed about 2FA policies and procedures

Disabling Organization 2FA

To disable 2FA for your organization:

  1. Navigate to Organization Settings
  2. Toggle Require Two-Factor Authentication to OFF (if enabled)
  3. Toggle Enable Two-Factor Authentication to OFF
  4. Save changes

Important:

  • Disabling "Enable 2FA" affects all users
  • Users who have 2FA enabled will no longer be prompted for codes
  • Their 2FA configurations remain stored but inactive
  • Re-enabling organization 2FA will reactivate existing user 2FA setups

Frequently Asked Questions

Q: Can I require 2FA for specific roles only? A: Not currently. 2FA is organization-wide (all or none). Role-based 2FA requirements may be added in a future release.

Q: What happens if I disable required 2FA after users have set it up? A: Users keep their 2FA configurations but can now disable it themselves. They won't be required to use it for login.

Q: Can I see which users have 2FA enabled? A: You can view 2FA setup events in the audit logs. A dedicated user management view showing 2FA status is planned for a future release.

Q: What if a user is locked out due to lost authenticator? A: Contact support to reset their 2FA. They'll need to set it up again after reset. A self-service admin interface for this is planned.

Q: Are backup codes secure? A: Yes, backup codes are hashed using SHA-256 before storage, similar to passwords. They cannot be reversed or viewed by anyone, including administrators.