> ## Documentation Index
> Fetch the complete documentation index at: https://forest-chore-open-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Two-Factor Authentication (2FA)

> Enable and enforce two-factor authentication to add an extra layer of security to user accounts

## Overview

Two-Factor Authentication (2FA) adds an additional security layer beyond username and password. Users must provide a second factor - typically a time-based one-time password (TOTP) from an authenticator app - to access Forest.

<Info>
  **Recommended for All Users**: 2FA significantly reduces the risk of unauthorized access, even if passwords are compromised.
</Info>

## Supported 2FA methods

### Authenticator apps (recommended)

Time-based One-Time Password (TOTP) apps generate 6-digit codes that change every 30 seconds:

<CardGroup cols={2}>
  <Card title="Google Authenticator" icon="google">
    Free app for iOS and Android
  </Card>

  <Card title="Microsoft Authenticator" icon="microsoft">
    Supports backup and cloud sync
  </Card>

  <Card title="Authy" icon="mobile">
    Multi-device support with encrypted backups
  </Card>

  <Card title="1Password" icon="key">
    Password manager with built-in TOTP
  </Card>

  <Card title="Bitwarden" icon="lock">
    Open-source with TOTP support
  </Card>

  <Card title="LastPass Authenticator" icon="shield">
    One-tap push notifications
  </Card>
</CardGroup>

### Backup codes

Recovery codes to use if you lose access to your authenticator app:

* Generated during 2FA setup
* One-time use only
* Store securely (password manager or printed copy)
* Can regenerate if needed

<Warning>
  **Save Your Backup Codes**: Without backup codes or access to your authenticator, you'll be locked out if your device is lost.
</Warning>

## Enabling 2FA (for users)

### Setup process

<Steps>
  <Step title="Access Account Settings">
    Click your profile picture > **Account Settings** > **Security**
  </Step>

  <Step title="Enable Two-Factor Authentication">
    Click **Enable 2FA** button
  </Step>

  <Step title="Scan QR Code">
    1. Open your authenticator app
    2. Tap "Add account" or "+" button
    3. Scan the QR code displayed in Forest

    **Or** enter the setup key manually if you can't scan
  </Step>

  <Step title="Verify Setup">
    Enter the 6-digit code from your authenticator app to confirm it's working correctly
  </Step>

  <Step title="Save Backup Codes">
    1. Download or copy your backup codes
    2. Store them securely (password manager recommended)
    3. Check the box to confirm you've saved them
  </Step>

  <Step title="2FA Enabled">
    You'll now be prompted for a code each time you log in
  </Step>
</Steps>

### Manual setup key

If you can't scan the QR code, use the manual setup key:

```
Setup Key: JBSWY3DPEHPK3PXP
Account: your-email@example.com
Type: Time-based
```

## Using 2FA to log in

### Login flow

<Steps>
  <Step title="Enter Credentials">
    Enter your email and password as usual
  </Step>

  <Step title="Enter 2FA Code">
    Open your authenticator app and enter the current 6-digit code
  </Step>

  <Step title="Remember Device (Optional)">
    Check "Trust this device for 30 days" to skip 2FA on this device
  </Step>

  <Step title="Access Granted">
    You're logged in to Forest
  </Step>
</Steps>

### Using backup codes

If you don't have access to your authenticator app:

<Steps>
  <Step title="Click 'Use Backup Code'">
    On the 2FA prompt, click the link to use a backup code
  </Step>

  <Step title="Enter Backup Code">
    Enter one of your saved backup codes (case-insensitive)
  </Step>

  <Step title="Code is Consumed">
    Each backup code can only be used once. Generate new ones if running low.
  </Step>
</Steps>

### Trusted devices

Mark devices as trusted to skip 2FA for 30 days:

* **Use Case**: Your primary work computer
* **Security**: A secure cookie identifies the device
* **Removal**: Go to Account Settings > Security > Trusted Devices to revoke

<Warning>
  **Public Computers**: Never mark public or shared computers as trusted.
</Warning>

## Enforcing 2FA (for admins)

Administrators can require 2FA for all users or specific roles.

### Project-wide enforcement

Require 2FA for everyone:

<Steps>
  <Step title="Navigate to Security Settings">
    Go to **Project Settings** > **Security** > **Authentication**
  </Step>

  <Step title="Enable 2FA Requirement">
    Toggle **Require Two-Factor Authentication** to ON
  </Step>

  <Step title="Set Grace Period">
    Choose how long users have to enable 2FA:

    * 24 hours (urgent)
    * 7 days (recommended)
    * 30 days (gradual rollout)
  </Step>

  <Step title="Notify Users">
    Forest automatically emails users about the requirement
  </Step>

  <Step title="Monitor Compliance">
    Track which users have enabled 2FA in **Project Settings** > **Teams** > **Users**
  </Step>
</Steps>

### Role-based enforcement

Require 2FA only for specific roles:

```javascript theme={null}
// Example: Require 2FA for Admins and Editors
{
  "roles": {
    "admin": {
      "require2FA": true
    },
    "editor": {
      "require2FA": true
    },
    "viewer": {
      "require2FA": false  // Optional for viewers
    }
  }
}
```

**Configuration**:

1. Go to **Project Settings** > **Roles**
2. Edit each role
3. Check **Require 2FA for this role**

### Exceptions

Allow specific users to bypass 2FA requirement:

* **Use Case**: Emergency access accounts, service accounts, external contractors
* **Configuration**: Edit user profile > **Security** > **Exempt from 2FA requirement**

<Info>
  **Best Practice**: Minimize exceptions. If a user truly needs access, they should enable 2FA.
</Info>

## Managing 2FA

### Regenerating backup codes

If you've used all your backup codes or lost them:

<Steps>
  <Step title="Access Security Settings">
    Go to **Account Settings** > **Security**
  </Step>

  <Step title="Regenerate Codes">
    Click **Regenerate Backup Codes**
  </Step>

  <Step title="Enter 2FA Code">
    Verify with current authenticator code
  </Step>

  <Step title="Save New Codes">
    Old codes are invalidated. Save the new ones securely.
  </Step>
</Steps>

### Resetting your own 2FA

If you need to switch authenticator apps or devices:

<Steps>
  <Step title="Disable 2FA">
    Go to **Account Settings** > **Security** > **Disable 2FA**
  </Step>

  <Step title="Verify Identity">
    Enter your current 2FA code or a backup code
  </Step>

  <Step title="Re-enable 2FA">
    Follow the setup process again with your new device/app
  </Step>
</Steps>

### Admin: resetting user's 2FA

If a user loses access to their authenticator and backup codes:

<Warning>
  **Security Risk**: Only reset 2FA after verifying the user's identity through alternate means (video call, ID verification, etc.).
</Warning>

<Steps>
  <Step title="Verify User Identity">
    Confirm the user's identity (don't rely solely on email, which could be compromised)
  </Step>

  <Step title="Navigate to User Management">
    Go to **Project Settings** > **Teams** > **Users**
  </Step>

  <Step title="Find User">
    Search for the user who needs 2FA reset
  </Step>

  <Step title="Reset 2FA">
    Click user menu (...) > **Reset Two-Factor Authentication**
  </Step>

  <Step title="Confirm Action">
    Confirm the reset. User must set up 2FA again at next login (if required).
  </Step>

  <Step title="Log the Action">
    This action is automatically logged in audit logs for security tracking
  </Step>
</Steps>

## 2FA + SSO

### How they work together

2FA and SSO can be used simultaneously for defense in depth:

<Tabs>
  <Tab title="IdP-Based 2FA (Recommended)">
    **MFA enforced at identity provider**

    * User authenticates with IdP (e.g., Okta, Azure AD)
    * IdP requires MFA (push notification, TOTP, etc.)
    * Forest trusts the IdP's authentication

    **Advantages**:

    * Centralized MFA management
    * One MFA prompt for all applications
    * Better user experience

    **Configuration**: Enable MFA in your IdP settings
  </Tab>

  <Tab title="Forest 2FA + SSO">
    **Additional 2FA layer in Forest**

    * User authenticates via SSO
    * Forest requires its own 2FA

    **Advantages**:

    * Extra layer of security
    * Works even if IdP MFA is disabled
    * Forest-specific second factor

    **Use Case**: Very high security environments, compliance requirements
  </Tab>

  <Tab title="SSO Only (No Forest 2FA)">
    **Rely entirely on IdP security**

    * User authenticates via SSO
    * No additional 2FA in Forest
    * IdP should enforce MFA

    **Advantages**:

    * Simplified user experience
    * Consistent with other applications

    **Requirement**: IdP must have strong MFA policies
  </Tab>
</Tabs>

### Recommended configuration

<CardGroup cols={2}>
  <Card title="For SSO Users" icon="building">
    Enforce MFA at the IdP level

    Disable Forest 2FA for SSO users to avoid double-prompting
  </Card>

  <Card title="For Password Users" icon="user">
    Require Forest 2FA

    These users don't benefit from IdP security
  </Card>
</CardGroup>

## Troubleshooting

### Code not working

<AccordionGroup>
  <Accordion title="Time Sync Issues">
    **Problem**: Authenticator app time is out of sync

    **Symptoms**: Code is always rejected, even when entered correctly

    **Solution**:

    1. Check your phone's time settings
    2. Enable automatic time/date
    3. Try the next code (they change every 30 seconds)

    **For Google Authenticator**:

    * Go to Settings > Time correction for codes > Sync now
  </Accordion>

  <Accordion title="Wrong Code Entered">
    **Problem**: Entering an old or incorrect code

    **Solution**:

    * Wait for the code to refresh in your app
    * Ensure you're using the correct account (if you have multiple)
    * Check for typos (0 vs O, 1 vs l)
  </Accordion>

  <Accordion title="Authenticator App Deleted">
    **Problem**: Removed app or factory reset phone without backing up

    **Solution**:

    * Use a backup code if you have one
    * Contact your admin for 2FA reset
    * Admin must verify your identity before resetting
  </Accordion>
</AccordionGroup>

### Can't scan QR code

**Solutions**:

1. **Use Manual Entry**: Copy the setup key and enter it manually in your authenticator app
2. **Try Different Device**: Use a tablet or another phone to scan
3. **Check Camera Permissions**: Ensure authenticator app has camera access
4. **Screenshot**: Take a screenshot (secure it afterwards) and scan from photos

### Lost backup codes

**If you still have authenticator access**:

1. Log in with your authenticator code
2. Regenerate new backup codes
3. Save them securely

**If you don't have authenticator or backup codes**:

1. Contact your administrator
2. Admin will verify your identity
3. Admin can reset your 2FA
4. Set up 2FA again immediately

### Can't log in after 2FA enforcement

**Problem**: 2FA was enforced but user hasn't set it up

**Solution**:

1. Users receive grace period to enable 2FA
2. During grace period, they're prompted to set up 2FA
3. After grace period, they must set up 2FA before accessing

**Admin Override**:

* Admin can temporarily exempt user from 2FA requirement
* User can then log in and set up 2FA properly