This PR implements a comprehensive TOTP (Time-based One-Time Password) 2FA authentication system for Open WebUI. The implementation adds an optional second authentication factor while maintaining full backward compatibility with existing users.
Documentation: Will update docs if requested by maintainers
Dependencies: Added qrcode dependency (documented in package.json)
Testing: Comprehensive testing completed (see summary above)
Code review: Self-reviewed for coding standards and best practices
Prefix: Using feat: prefix for new feature
Changelog Entry
Description
Implements TOTP 2FA authentication system providing optional two-factor authentication for enhanced security while maintaining backward compatibility.
Added
TOTP 2FA authentication system with RFC 6238 compliance
Database migration for TOTP fields (secret, enabled, backup_codes)
6 new API endpoints for TOTP lifecycle management:
POST /auth/totp/setup - Initialize TOTP setup
POST /auth/totp/enable - Enable 2FA with verification
POST /auth/totp/disable - Disable 2FA (requires password)
GET /auth/totp/backup-codes - Retrieve current backup codes
POST /auth/totp/regenerate-backup-codes - Generate new backup codes
POST /auth/signin/totp - Complete authentication with TOTP code
TOTP utility functions for secret generation, QR codes, and validation
Modular TotpSettings.svelte component for account management
QR code generation for authenticator app setup
Backup code system with single-use enforcement
Two-step authentication flow with temporary tokens
Frontend API integration for TOTP operations
qrcode dependency for QR code generation
Changed
Authentication flow now supports optional two-step process for 2FA users
Account settings UI enhanced with TOTP management section
User model extended with TOTP-related fields
Login page rewritten to handle 2FA authentication flow
Security
Password confirmation required for disabling 2FA
Temporary tokens with 5-minute expiration for setup process
Single-use hashed backup codes for account recovery
TOTP validation with ±30 second window tolerance
Secure secret generation using cryptographically secure methods
Protection against timing attacks with consistent response times
Additional Information
Backward Compatibility: Existing users are unaffected; 2FA is completely optional
Standards Compliance: Full RFC 6238 TOTP implementation
Authenticator Support: Compatible with Google Authenticator, Authy, Microsoft Authenticator, and other standard TOTP apps
Recovery Options: 10 single-use backup codes generated for account recovery
Mobile Friendly: Responsive design works on all device sizes
Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.
## 📋 Pull Request Information
**Original PR:** https://github.com/open-webui/open-webui/pull/16461
**Author:** [@jeremy-windsor](https://github.com/jeremy-windsor)
**Created:** 8/10/2025
**Status:** ❌ Closed
**Base:** `dev` ← **Head:** `feature/totp-2fa-integration`
---
### 📝 Commits (4)
- [`0cca3d3`](https://github.com/open-webui/open-webui/commit/0cca3d33084c5caa6ad26c797a57fe8fac84802b) feat: Add TOTP 2FA authentication system
- [`f40f9a8`](https://github.com/open-webui/open-webui/commit/f40f9a826fd7947d278476c4352990327346b3a9) fix: add missing @tiptap/suggestion dependency for build
- [`8d0451d`](https://github.com/open-webui/open-webui/commit/8d0451dd2729c21aadbe94e6c9dc725d3928ddb4) Update TOTP 2FA integration: added admin control
- [`bda05ba`](https://github.com/open-webui/open-webui/commit/bda05bac0d128255312a2241c368de286d51d6eb) Merge upstream/dev into feature/totp-2fa-integration
### 📊 Changes
**12 files changed** (+3935 additions, -6388 deletions)
<details>
<summary>View changed files</summary>
📝 `.gitignore` (+1 -0)
➕ `backend/open_webui/migrations/versions/e4f7b8c9d2a1_add_totp_fields_to_user_table.py` (+37 -0)
📝 `backend/open_webui/models/users.py` (+9 -1)
📝 `backend/open_webui/routers/auths.py` (+419 -4)
📝 `backend/open_webui/utils/auth.py` (+139 -0)
📝 `package-lock.json` (+1997 -5859)
📝 `package.json` (+2 -0)
📝 `src/lib/apis/auths/index.ts` (+230 -0)
📝 `src/lib/components/admin/Users/UserList/EditUserModal.svelte` (+59 -0)
📝 `src/lib/components/chat/Settings/Account.svelte` (+5 -0)
➕ `src/lib/components/chat/Settings/Account/TotpSettings.svelte` (+455 -0)
📝 `src/routes/auth/+page.svelte` (+582 -524)
</details>
### 📄 Description
# TOTP 2FA Authentication Integration
## Description
This PR implements a comprehensive TOTP (Time-based One-Time Password) 2FA authentication system for Open WebUI. The implementation adds an optional second authentication factor while maintaining full backward compatibility with existing users.
**Related Discussion:** https://github.com/open-webui/open-webui/discussions/16338
## Changes Summary
- Add database migration for TOTP fields (secret, enabled, backup_codes)
- Implement TOTP utilities for secret generation, QR codes, and validation
- Add 6 new API endpoints for TOTP setup, enable/disable, and authentication
- Rewrite authentication flow to support two-step login process
- Add comprehensive TOTP management UI in account settings
- Include backup code generation and single-use enforcement
- Add proper error handling and security validation
- Support for standard authenticator apps via RFC 6238 compliance
- Add qrcode dependency for QR code generation
**Migration file:** `e4f7b8c9d2a1_add_totp_fields_to_user_table.py`
## Testing Completed
✅ Login with/without 2FA enabled
✅ TOTP setup with QR code generation
✅ Backup code usage and regeneration
✅ Password-protected 2FA disable
✅ Token expiration handling
✅ Cross-browser compatibility
✅ Mobile responsiveness
## Pull Request Checklist
- [x] **Target branch:** Targeting the `dev` branch
- [x] **Description:** Comprehensive description provided above
- [x] **Changelog:** See changelog entry below
- [ ] **Documentation:** Will update docs if requested by maintainers
- [x] **Dependencies:** Added `qrcode` dependency (documented in package.json)
- [x] **Testing:** Comprehensive testing completed (see summary above)
- [x] **Code review:** Self-reviewed for coding standards and best practices
- [x] **Prefix:** Using `feat:` prefix for new feature
# Changelog Entry
## Description
Implements TOTP 2FA authentication system providing optional two-factor authentication for enhanced security while maintaining backward compatibility.
## Added
- TOTP 2FA authentication system with RFC 6238 compliance
- Database migration for TOTP fields (secret, enabled, backup_codes)
- 6 new API endpoints for TOTP lifecycle management:
- `POST /auth/totp/setup` - Initialize TOTP setup
- `POST /auth/totp/enable` - Enable 2FA with verification
- `POST /auth/totp/disable` - Disable 2FA (requires password)
- `GET /auth/totp/backup-codes` - Retrieve current backup codes
- `POST /auth/totp/regenerate-backup-codes` - Generate new backup codes
- `POST /auth/signin/totp` - Complete authentication with TOTP code
- TOTP utility functions for secret generation, QR codes, and validation
- Modular `TotpSettings.svelte` component for account management
- QR code generation for authenticator app setup
- Backup code system with single-use enforcement
- Two-step authentication flow with temporary tokens
- Frontend API integration for TOTP operations
- `qrcode` dependency for QR code generation
## Changed
- Authentication flow now supports optional two-step process for 2FA users
- Account settings UI enhanced with TOTP management section
- User model extended with TOTP-related fields
- Login page rewritten to handle 2FA authentication flow
## Security
- Password confirmation required for disabling 2FA
- Temporary tokens with 5-minute expiration for setup process
- Single-use hashed backup codes for account recovery
- TOTP validation with ±30 second window tolerance
- Secure secret generation using cryptographically secure methods
- Protection against timing attacks with consistent response times
---
## Additional Information
- **Backward Compatibility:** Existing users are unaffected; 2FA is completely optional
- **Standards Compliance:** Full RFC 6238 TOTP implementation
- **Authenticator Support:** Compatible with Google Authenticator, Authy, Microsoft Authenticator, and other standard TOTP apps
- **Recovery Options:** 10 single-use backup codes generated for account recovery
- **Mobile Friendly:** Responsive design works on all device sizes
## Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
---
<sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 Pull Request Information
Original PR: https://github.com/open-webui/open-webui/pull/16461
Author: @jeremy-windsor
Created: 8/10/2025
Status: ❌ Closed
Base:
dev← Head:feature/totp-2fa-integration📝 Commits (4)
0cca3d3feat: Add TOTP 2FA authentication systemf40f9a8fix: add missing @tiptap/suggestion dependency for build8d0451dUpdate TOTP 2FA integration: added admin controlbda05baMerge upstream/dev into feature/totp-2fa-integration📊 Changes
12 files changed (+3935 additions, -6388 deletions)
View changed files
📝
.gitignore(+1 -0)➕
backend/open_webui/migrations/versions/e4f7b8c9d2a1_add_totp_fields_to_user_table.py(+37 -0)📝
backend/open_webui/models/users.py(+9 -1)📝
backend/open_webui/routers/auths.py(+419 -4)📝
backend/open_webui/utils/auth.py(+139 -0)📝
package-lock.json(+1997 -5859)📝
package.json(+2 -0)📝
src/lib/apis/auths/index.ts(+230 -0)📝
src/lib/components/admin/Users/UserList/EditUserModal.svelte(+59 -0)📝
src/lib/components/chat/Settings/Account.svelte(+5 -0)➕
src/lib/components/chat/Settings/Account/TotpSettings.svelte(+455 -0)📝
src/routes/auth/+page.svelte(+582 -524)📄 Description
TOTP 2FA Authentication Integration
Description
This PR implements a comprehensive TOTP (Time-based One-Time Password) 2FA authentication system for Open WebUI. The implementation adds an optional second authentication factor while maintaining full backward compatibility with existing users.
Related Discussion: https://github.com/open-webui/open-webui/discussions/16338
Changes Summary
Migration file:
e4f7b8c9d2a1_add_totp_fields_to_user_table.pyTesting Completed
✅ Login with/without 2FA enabled
✅ TOTP setup with QR code generation
✅ Backup code usage and regeneration
✅ Password-protected 2FA disable
✅ Token expiration handling
✅ Cross-browser compatibility
✅ Mobile responsiveness
Pull Request Checklist
devbranchqrcodedependency (documented in package.json)feat:prefix for new featureChangelog Entry
Description
Implements TOTP 2FA authentication system providing optional two-factor authentication for enhanced security while maintaining backward compatibility.
Added
POST /auth/totp/setup- Initialize TOTP setupPOST /auth/totp/enable- Enable 2FA with verificationPOST /auth/totp/disable- Disable 2FA (requires password)GET /auth/totp/backup-codes- Retrieve current backup codesPOST /auth/totp/regenerate-backup-codes- Generate new backup codesPOST /auth/signin/totp- Complete authentication with TOTP codeTotpSettings.sveltecomponent for account managementqrcodedependency for QR code generationChanged
Security
Additional Information
Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.