[PR #16461] [CLOSED] feat: Add TOTP 2FA authentication system #39773

New Issue

GiteaMirror · 2026-04-25T12:13:40-05:00

GiteaMirror commented

2026-04-25 12:13:40 -05:00

📋 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)

0cca3d3 feat: Add TOTP 2FA authentication system
f40f9a8 fix: add missing @tiptap/suggestion dependency for build
8d0451d Update TOTP 2FA integration: added admin control
bda05ba Merge 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

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

Target branch: Targeting the dev branch
Description: Comprehensive description provided above
Changelog: See changelog entry below
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>

GiteaMirror added the pull-request label 2026-04-25 12:13:40 -05:00

GiteaMirror closed this issue

2026-04-25 12:13:41 -05:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/open-webui#39773