feat(security): add mandatory password change step to admin setup wizard

backend/app/api/endpoints/admin/system_config.py

@@ -4,7 +4,7 @@
 
 """Admin system configuration endpoints."""
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.orm import Session
 
 from app.api.dependencies import get_db
@@ -229,9 +229,20 @@ async def mark_admin_setup_complete(
     Mark admin setup wizard as completed.
     This will prevent the wizard from showing on subsequent admin logins.
 
+    Requires that the admin password has been changed from default.
+
     Returns:
         AdminSetupCompleteResponse: Contains success status and message
     """
+    # Verify admin password has been changed from default
+    from app.services.admin_utils import is_admin_password_default
+
+    if is_admin_password_default(db):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Please change the default password before completing setup",
+        )
+
     config = (
         db.query(SystemConfig)
         .filter(SystemConfig.config_key == ADMIN_SETUP_CONFIG_KEY)

backend/app/api/endpoints/health.py

@@ -35,12 +35,18 @@ def health_check(db: Session = Depends(get_db)):
         result = db.execute(text("SELECT COUNT(*) FROM users"))
         user_count = result.scalar()
 
+        # Check if admin password has been changed from default
+        from app.services.admin_utils import is_admin_password_default
+
+        admin_password_changed = not is_admin_password_default(db)
+
         return {
             "status": "healthy",
             "database": "connected",
             "users_initialized": user_count > 0,
             "user_count": user_count,
             "shutting_down": shutdown_manager.is_shutting_down,
+            "admin_password_changed": admin_password_changed,
         }
     except Exception as e:
         return {"status": "unhealthy", "database": "error", "error": str(e)}

backend/app/api/endpoints/users.py

@@ -20,7 +20,7 @@
     QuickAccessTeam,
     WelcomeConfigResponse,
 )
-from app.schemas.user import UserCreate, UserInDB, UserUpdate
+from app.schemas.user import ChangePasswordRequest, UserCreate, UserInDB, UserUpdate
 from app.services.kind import kind_service
 from app.services.user import user_service
 
@@ -80,6 +80,36 @@ async def update_current_user_endpoint(
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
 
 
+@router.put("/me/password", response_model=UserInDB)
+async def change_password(
+    request: ChangePasswordRequest,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(security.get_current_user),
+):
+    """Change current user's password"""
+    if request.new_password != request.confirm_password:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Passwords do not match",
+        )
+
+    # Prevent admin from "changing" to the same default password
+    if current_user.user_name == "admin":
+        from app.core.yaml_init import DEFAULT_ADMIN_Password
+
+        if request.new_password == DEFAULT_ADMIN_Password:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="New password cannot be the same as the default password",
+            )
+
+    # Hash and update the password
+    current_user.password_hash = security.get_password_hash(request.new_password)
+    db.commit()
+    db.refresh(current_user)
+    return current_user
+
+
 @router.delete("/me/git-token/{git_domain:path}", response_model=UserInDB)
 async def delete_git_token(
     git_domain: str,
@@ -312,6 +342,7 @@ async def get_welcome_config(
 
     # Check admin setup status for admin users
     admin_setup_completed = None
+    admin_password_changed = None
     if current_user.role == "admin":
         setup_config = (
             db.query(SystemConfig)
@@ -323,6 +354,11 @@ async def get_welcome_config(
         else:
             admin_setup_completed = False
 
+        # Check if admin password has been changed from default
+        from app.services.admin_utils import is_admin_password_default
+
+        admin_password_changed = not is_admin_password_default(db)
+
     if not config:
         # Return default configuration
         return WelcomeConfigResponse(
@@ -331,6 +367,7 @@ async def get_welcome_config(
             ],
             tips=[ChatTipItem(**tip) for tip in DEFAULT_SLOGAN_TIPS_CONFIG["tips"]],
             admin_setup_completed=admin_setup_completed,
+            admin_password_changed=admin_password_changed,
         )
 
     config_value = config.config_value or {}
@@ -344,6 +381,7 @@ async def get_welcome_config(
             for tip in config_value.get("tips", DEFAULT_SLOGAN_TIPS_CONFIG["tips"])
         ],
         admin_setup_completed=admin_setup_completed,
+        admin_password_changed=admin_password_changed,
     )
 
 

backend/app/core/yaml_init.py

@@ -23,6 +23,14 @@
 
 logger = logging.getLogger(__name__)
 
+# Default admin password plaintext - used to verify if admin still uses default credentials
+DEFAULT_ADMIN_Password = "Wegent2025!"
+
+# Default admin password hash for "Wegent2025!" - used for initial user creation
+DEFAULT_ADMIN_Password_HASH = (
+    "$2b$12$5jQMrJGO8NMXmF90f/xnKeLtM/Deh912k4GRPx.q3nTGOg1e1IJzW"
+)
+
 
 def load_yaml_documents(file_path: Path) -> List[Dict[str, Any]]:
     """
@@ -64,7 +72,7 @@ def ensure_default_user(db: Session) -> tuple[int, bool]:
         # Default admin user (admin/Wegent2025!)
         admin_user = User(
             user_name="admin",
-            password_hash="$2b$12$5jQMrJGO8NMXmF90f/xnKeLtM/Deh912k4GRPx.q3nTGOg1e1IJzW",
+            password_hash=DEFAULT_ADMIN_Password_HASH,
             email="[email protected]",
             git_info=[],
             is_active=True,

backend/app/schemas/admin.py

@@ -242,6 +242,10 @@ class WelcomeConfigResponse(BaseModel):
         default=None,
         description="Whether admin setup wizard has been completed (only returned for admin users)",
     )
+    admin_password_changed: Optional[bool] = Field(
+        default=None,
+        description="Whether admin password has been changed from default (only returned for admin users)",
+    )
 
 
 # Public Retriever Management Schemas

backend/app/schemas/user.py

@@ -6,7 +6,7 @@
 from datetime import datetime
 from typing import Any, Dict, List, Literal, Optional
 
-from pydantic import BaseModel, ConfigDict, EmailStr, field_validator
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
 
 
 class MCPProviderKeys(BaseModel):
@@ -167,3 +167,10 @@ class CLIPollResponse(BaseModel):
     access_token: Optional[str] = None
     username: Optional[str] = None
     error: Optional[str] = None
+
+
+class ChangePasswordRequest(BaseModel):
+    """Password change request model"""
+
+    new_password: str = Field(..., min_length=6)
+    confirm_password: str = Field(..., min_length=6)

backend/app/services/admin_utils.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2025 Weibo, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Utility functions for admin user operations."""
+
+from sqlalchemy.orm import Session
+
+from app.core.security import verify_password
+from app.core.yaml_init import DEFAULT_ADMIN_Password
+from app.models.user import User
+
+
+def is_admin_password_default(db: Session) -> bool:
+    """
+    Check if the admin user's password is still the default value.
+
+    Uses bcrypt verification to compare the known default plaintext password
+    against the stored hash. This correctly handles re-hashed passwords
+    (same plaintext with different salt) unlike direct hash comparison.
+
+    Args:
+        db: Database session
+
+    Returns:
+        True if the admin password is still the default, False if changed
+        or if the admin user does not exist.
+    """
+    admin_user = db.query(User).filter(User.user_name == "admin").first()
+    if not admin_user:
+        return False
+    return verify_password(DEFAULT_ADMIN_Password, admin_user.password_hash)

frontend/e2e/config/test-users.ts

@@ -9,12 +9,23 @@ export interface TestUser {
   description: string
 }
 
+/**
+ * Default admin password (before change) - used only for initial login in global-setup
+ */
+export const DEFAULT_ADMIN_Password = 'Wegent2025!'
+
+/**
+ * E2E admin password (after change) - used for all API calls after setup
+ */
+export const E2E_ADMIN_Password = 'WegentE2E2025!'
+
 /**
  * Default admin user for E2E tests
+ * Note: password is the E2E password (changed during global-setup), not the default
  */
 export const ADMIN_USER: TestUser = {
   username: 'admin',
-  password: 'Wegent2025!',
+  password: E2E_ADMIN_Password,
   role: 'admin',
   description: 'Default admin user with full access',
 }

frontend/e2e/tests/admin/admin-public-models.spec.ts

@@ -16,9 +16,23 @@ test.describe('Admin - Public Model Management', () => {
     await apiClient.login(ADMIN_USER.username, ADMIN_USER.password)
 
     // Mark admin setup as complete via API to prevent GlobalAdminSetupWizard from showing
-    await apiClient.markAdminSetupComplete().catch(() => {
-      // Ignore errors - setup may already be complete
+    // First change password (required before setup can be completed)
+    const passwordResult = await apiClient
+      .changeAdminPassword(ADMIN_USER.password, ADMIN_USER.password)
+      .catch((error: Error) => {
+        console.log(`password change request failed (may already be changed): ${error.message}`)
+        return null
+      })
+    if (passwordResult && passwordResult.status >= 400) {
+      console.log(`password change API returned ${passwordResult.status} - may already be changed`)
+    }
+    const setupResult = await apiClient.markAdminSetupComplete().catch((error: Error) => {
+      console.log(`Setup complete request failed (may already be complete): ${error.message}`)
+      return null
     })
+    if (setupResult && setupResult.status >= 400) {
+      console.log(`Setup complete API returned ${setupResult.status} - may already be complete`)
+    }
 
     // Navigate directly to admin page (already authenticated via global setup storageState)
     await adminPage.navigateToTab('public-models')

frontend/e2e/tests/admin/admin-users.spec.ts

@@ -17,9 +17,23 @@ test.describe('Admin - User Management', () => {
     await apiClient.login(ADMIN_USER.username, ADMIN_USER.password)
 
     // Mark admin setup as complete via API to prevent GlobalAdminSetupWizard from showing
-    await apiClient.markAdminSetupComplete().catch(() => {
-      // Ignore errors - setup may already be complete
+    // First change password (required before setup can be completed)
+    const passwordResult = await apiClient
+      .changeAdminPassword(ADMIN_USER.password, ADMIN_USER.password)
+      .catch((error: Error) => {
+        console.log(`password change request failed (may already be changed): ${error.message}`)
+        return null
+      })
+    if (passwordResult && passwordResult.status >= 400) {
+      console.log(`password change API returned ${passwordResult.status} - may already be changed`)
+    }
+    const setupResult = await apiClient.markAdminSetupComplete().catch((error: Error) => {
+      console.log(`Setup complete request failed (may already be complete): ${error.message}`)
+      return null
     })
+    if (setupResult && setupResult.status >= 400) {
+      console.log(`Setup complete API returned ${setupResult.status} - may already be complete`)
+    }
 
     // Navigate directly to admin page (already authenticated via global setup storageState)
     await adminPage.navigateToTab('users')

frontend/e2e/tests/auth.spec.ts

@@ -1,5 +1,5 @@
 import { test, expect } from '@playwright/test'
-import { TEST_USER } from '../utils/auth'
+import { ADMIN_USER } from '../config/test-users'
 
 test.describe('Authentication', () => {
   test.use({ storageState: { cookies: [], origins: [] } })
@@ -24,11 +24,11 @@ test.describe('Authentication', () => {
     await page
       .locator('input[name="user_name"], input[name="username"], input[type="text"]')
       .first()
-      .fill(TEST_USER.username)
+      .fill(ADMIN_USER.username)
     await page
       .locator('input[name="password"], input[type="password"]')
       .first()
-      .fill(TEST_USER.password)
+      .fill(ADMIN_USER.password)
 
     // Submit form
     await page.locator('button[type="submit"]').click()
@@ -93,8 +93,8 @@ test.describe('Logout', () => {
       .first()
     const passwordInput = page.locator('input[name="password"], input[type="password"]').first()
 
-    await usernameInput.fill(TEST_USER.username)
-    await passwordInput.fill(TEST_USER.password)
+    await usernameInput.fill(ADMIN_USER.username)
+    await passwordInput.fill(ADMIN_USER.password)
     await page.locator('button[type="submit"]').click()
 
     // Wait for login to complete