> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fentufsm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Two-Factor Authentication (2FA)

> Securing Fentu FSM accounts with a second authentication factor

## Overview

Two-factor authentication (2FA) adds a second verification step after a user enters their password. Even if a password is compromised, an attacker cannot access the account without also having the second factor.

<Note>
  2FA can be enforced organization-wide by an administrator or enabled voluntarily by individual users. When enforced, users must set up 2FA before they can access Fentu FSM.
</Note>

## Supported Second Factors

| Method                       | How It Works                                                                                        | Recommended For                           |
| ---------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| **Authenticator App (TOTP)** | Time-based one-time code generated by an app (Google Authenticator, Microsoft Authenticator, Authy) | All users — most secure option            |
| **Email OTP**                | One-time code sent to the user's registered email address                                           | Users without a smartphone                |
| **SMS OTP**                  | One-time code sent via text message                                                                 | Fallback option when email is unavailable |

<Tip>
  Authenticator apps are strongly recommended over SMS or email. Codes are generated offline and are not vulnerable to SIM-swapping or email account compromise.
</Tip>

***

## Enforcing 2FA Organization-Wide

Administrators can require all users to set up 2FA before accessing Fentu FSM:

<Steps>
  <Step title="Open Security Settings">
    Navigate to **Administration > Settings > Security**
  </Step>

  <Step title="Enable 2FA Enforcement">
    Toggle **"Require Two-Factor Authentication"** on
  </Step>

  <Step title="Set Grace Period">
    Optionally set a grace period (e.g., 7 days) during which existing users can still log in without 2FA while they set it up
  </Step>

  <Step title="Save">
    Click **Save**. New login attempts will prompt users to enrol in 2FA before accessing any page
  </Step>
</Steps>

<Warning>
  Enforcing 2FA immediately (with no grace period) will block all users who have not yet set up a second factor. Communicate the change to your users before enabling enforcement, or set a grace period.
</Warning>

***

## Setting Up 2FA (Per User)

Users can set up 2FA from their own profile, or be prompted automatically when enforcement is active.

### Using an Authenticator App (TOTP)

<Steps>
  <Step title="Open Profile Settings">
    Click your avatar in the top-right corner and go to **Profile > Security**
  </Step>

  <Step title="Click Enable Two-Factor Authentication">
    Select **Authenticator App** as the method
  </Step>

  <Step title="Scan the QR Code">
    Open your authenticator app (Google Authenticator, Microsoft Authenticator, or Authy) and scan the QR code displayed on screen
  </Step>

  <Step title="Enter the Verification Code">
    Type the 6-digit code shown in your authenticator app to confirm the setup
  </Step>

  <Step title="Save Recovery Codes">
    Download or copy the **recovery codes** shown. Store them in a secure location. These are used if you lose access to your authenticator device
  </Step>

  <Step title="Done">
    2FA is now active. You will be prompted for a code on every login
  </Step>
</Steps>

### Using Email OTP

<Steps>
  <Step title="Open Profile Settings">
    Go to **Profile > Security > Enable Two-Factor Authentication**
  </Step>

  <Step title="Select Email">
    Choose **Email** as your second factor method
  </Step>

  <Step title="Confirm Your Email Address">
    Verify the email address shown is correct. A test code is sent immediately
  </Step>

  <Step title="Enter the Test Code">
    Enter the code from the email to confirm setup
  </Step>

  <Step title="Done">
    On future logins, a code will be emailed to you after you enter your password
  </Step>
</Steps>

***

## Logging In with 2FA

Once 2FA is active, the login flow has an additional step:

<Steps>
  <Step title="Enter Email and Password">
    Log in as normal on the Fentu FSM login page
  </Step>

  <Step title="Second Factor Prompt">
    After password verification, a prompt appears asking for your second factor code
  </Step>

  <Step title="Enter the Code">
    Open your authenticator app (or check your email/SMS) and enter the current 6-digit code
  </Step>

  <Step title="Access Granted">
    If the code is correct and has not expired, you are logged in
  </Step>
</Steps>

<Info>
  TOTP codes are valid for 30 seconds. If a code is rejected, wait for the next code to generate and try again. Ensure your device clock is accurate — TOTP codes depend on time synchronisation.
</Info>

***

## Recovery Codes

Recovery codes are one-time-use backup codes generated when 2FA is first set up. Use them if you lose access to your authenticator device or email.

### Using a Recovery Code

1. On the 2FA prompt, click **"Use a recovery code instead"**
2. Enter one of your saved recovery codes
3. You are logged in — the used code is invalidated immediately
4. After logging in, go to **Profile > Security** and re-enrol a new second factor or generate new recovery codes

<Warning>
  Each recovery code can only be used once. If you run out of recovery codes and lose your second factor device, you will need an administrator to reset your 2FA. Store your recovery codes securely (password manager, printed copy in a safe).
</Warning>

### Regenerating Recovery Codes

If you suspect your recovery codes are compromised:

1. Go to **Profile > Security**
2. Click **"Regenerate Recovery Codes"**
3. Save the new codes — the previous set is immediately invalidated

***

## Resetting 2FA for a User (Admin)

If a user loses access to their second factor and does not have recovery codes, an administrator can reset their 2FA:

<Steps>
  <Step title="Open User Management">
    Go to **Administration > Users**
  </Step>

  <Step title="Find the User">
    Search for the user by name or email
  </Step>

  <Step title="Open User Record">
    Click the user to open their detail view
  </Step>

  <Step title="Reset 2FA">
    Click **"Reset Two-Factor Authentication"** and confirm
  </Step>

  <Step title="Notify the User">
    Inform the user that their 2FA has been reset. They will be prompted to set up a new second factor on their next login
  </Step>
</Steps>

<Note>
  Only administrators with the **User Management** permission can reset another user's 2FA. All resets are recorded in the audit log.
</Note>

***

## 2FA and SSO

When SSO is enabled, the identity provider handles the authentication flow — including any MFA requirements configured in the IdP. In this case:

| Scenario                 | 2FA Handling                                                                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **SSO only**             | MFA is managed entirely by your identity provider (Entra ID, Okta, etc.). Fentu FSM 2FA is bypassed                              |
| **SSO + Fentu 2FA**      | Users complete IdP MFA, then are prompted for a Fentu 2FA code as well. Not recommended — configure MFA at the IdP level instead |
| **Local login (no SSO)** | Fentu FSM 2FA applies in full                                                                                                    |

<Tip>
  If you use SSO, configure and enforce MFA at the identity provider level rather than in Fentu FSM. This ensures a consistent and centrally managed security policy.
</Tip>

***

## Troubleshooting 2FA

| Symptom                                | Likely Cause                                    | Resolution                                                          |
| -------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
| "Invalid code" on correct-looking code | Device clock is out of sync                     | Sync your device time settings (Settings > Date & Time > Automatic) |
| Code rejected immediately after setup  | QR code scanned incorrectly                     | Delete the entry from your authenticator app and re-scan            |
| No email OTP received                  | Email in spam folder, or wrong email on account | Check spam; verify email address in Profile settings                |
| Locked out, no recovery codes          | Lost device and no codes saved                  | Contact your Fentu FSM administrator to reset 2FA                   |
| 2FA prompt does not appear             | 2FA not yet enforced or user exempt             | Check Security settings; verify user is not in the exempt list      |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Single Sign-On (SSO)" icon="arrow-right-to-bracket" href="/api-reference/sso">
    Authenticate users through your organization's identity provider
  </Card>

  <Card title="User Management" icon="users" href="/administration/users/user-management">
    Manage user accounts, roles, and security settings
  </Card>
</CardGroup>