Multi-Factor Authentication (MFA)
Relevant source files
The following files were used as context for generating this wiki page:
Multi-Factor Authentication (MFA) in Casdoor is a security framework that requires users to provide two or more verification factors to gain access to their accounts. This system enhances security by adding layers of protection beyond traditional password-based authentication, supporting various methods including SMS, Email, TOTP (Time-based One-Time Password), RADIUS, and Push notifications.
Sources: object/mfa.go:34-40, web/src/auth/MfaSetupPage.js:24-29
System Architecture and Components
The MFA module is structured into backend logic handling validation and generation of secrets, and a frontend interface for setup and verification. The backend utilizes an interface-driven design (MfaInterface) to support extensible authentication types.
Key Data Structures
The core of the MFA configuration is defined by the MfaProps struct, which carries information about the enabled status, secret keys, and recovery options.
| Field | Type | Description |
|---|---|---|
Enabled | bool | Indicates if the MFA method is active for the user. |
IsPreferred | bool | Marks the method as the primary choice for the user. |
MfaType | string | The type of MFA (sms, email, app, radius, push). |
Secret | string | The shared secret or destination (phone/email). |
RecoveryCodes | []string | Backup codes used for account recovery. |
MfaRememberInHours | int | Duration for which the device is trusted. |
Sources: object/mfa.go:21-30, controllers/mfa.go:66-69
MFA Types
Casdoor supports five primary MFA types:
- SMS (
sms): Verification via phone text messages. - Email (
email): Verification via email codes. - TOTP (
app): Time-based tokens generated by apps like Google Authenticator. - RADIUS (
radius): Authentication against a RADIUS server. - Push (
push): Mobile push notification approval.
Sources: object/mfa.go:34-40
MFA Lifecycle and Data Flow
The MFA process consists of three main phases: Setup Initiation, Verification (during setup), and Enabling.
Setup Flow
During setup, the system initiates the process by generating required secrets (like a TOTP secret) and provides recovery codes.
Authentication Flow
When a user logs in with MFA enabled, the system checks the required MFA rules and prompts for the secondary factor if necessary.
Administrative Configuration
Organizations can define how MFA is applied to their users using rules. These rules determine if MFA is mandatory, suggested, or optional.
MFA Rules
Rules are configured per organization or user:
- Required: User must set up and use MFA to access the application.
- Prompted: User is encouraged to set up MFA but can skip.
- Optional: User can choose to enable MFA manually.
Sources: web/src/table/MfaTable.js:31-35, web/src/Setting.js:630-632
API Endpoints
The MFA functionality is exposed through several specific API endpoints.
| Endpoint | Method | Description |
|---|---|---|
/api/mfa/setup/initiate | POST | Starts the setup process for a specific MFA type. |
/api/mfa/setup/verify | POST | Validates the passcode during the setup phase. |
/api/mfa/setup/enable | POST | Finalizes and activates MFA for the user. |
/api/delete-mfa | POST | Disables all MFA methods for a user. |
/api/set-preferred-mfa | POST | Sets a specific method as the default. |
Sources: web/src/backend/MfaBackend.js:15-68, controllers/mfa.go:34-245
Recovery Logic
If a user loses access to their primary MFA device, they can use recovery codes generated during the setup process.
func MfaRecover(user *User, recoveryCode string) error {
hit := false
for _, code := range user.RecoveryCodes {
if code == recoveryCode {
hit = true
user.RecoveryCodes = util.DeleteVal(user.RecoveryCodes, code)
break
}
}
if !hit {
return fmt.Errorf("recovery code not found")
}
_, err := UpdateUser(user.GetId(), user, []string{"recovery_codes"}, false)
return err
}
The MfaRecover function checks the provided code against the stored list, removes it once used to ensure single-use security, and updates the user record.
Sources: object/mfa.go:55-80, web/src/auth/mfa/MfaAuthVerifyForm.js:52-67
Summary
The MFA module in Casdoor provides a comprehensive security layer through various authentication methods and flexible enforcement rules. By separating setup logic from authentication verification and providing robust recovery mechanisms, it ensures both account security and user accessibility. Administrative control via the MfaTable allows organizations to customize the security posture based on their specific requirements.
Sources: web/src/table/MfaTable.js:17-40, object/mfa.go:174-190