fix: Address code review feedback and add SSO documentation

- Remove duplicate route registration - Fix return type for OAuth callback handler - Add OAuth SSO configuration documentation - Add security comments for OAuth query parameters Co-authored-by: samanhappy <2755122+samanhappy@users.noreply.github.com>
feat: Add OAuth 2.0 / OIDC SSO login support
2025-12-31 20:00:00 -05:00 · 2025-12-31 15:16:19 +00:00 · 2025-12-31 15:08:10 +00:00 · 2025-12-31 14:51:49 +00:00
22 changed files with 1716 additions and 1326 deletions
--- a/docs/configuration/oauth-sso.mdx
+++ b/docs/configuration/oauth-sso.mdx
@@ -0,0 +1,218 @@
+---
+title: OAuth SSO Configuration
+description: Configure OAuth 2.0 / OIDC Single Sign-On for MCPHub
+---
+
+# OAuth SSO Configuration
+
+MCPHub supports OAuth 2.0 / OIDC Single Sign-On (SSO) for enterprise authentication, allowing users to log in using their existing identity provider accounts (Google, Microsoft, GitHub, or custom OIDC providers).
+
+## Overview
+
+SSO support allows:
+- Login via major providers (Google, Microsoft, GitHub)
+- Custom OIDC provider integration
+- Auto-provisioning of new users from OAuth profiles
+- Role mapping from provider claims/groups
+- Hybrid auth (both SSO and local username/password)
+
+## Configuration
+
+Add the `oauthSSO` section to your `mcp_settings.json` under `systemConfig`:
+
+```json
+{
+  "systemConfig": {
+    "oauthSSO": {
+      "enabled": true,
+      "allowLocalAuth": true,
+      "callbackBaseUrl": "https://your-mcphub-domain.com",
+      "providers": [
+        {
+          "id": "google",
+          "name": "Google",
+          "type": "google",
+          "clientId": "your-google-client-id",
+          "clientSecret": "your-google-client-secret"
+        },
+        {
+          "id": "github",
+          "name": "GitHub",
+          "type": "github",
+          "clientId": "your-github-client-id",
+          "clientSecret": "your-github-client-secret"
+        },
+        {
+          "id": "microsoft",
+          "name": "Microsoft",
+          "type": "microsoft",
+          "clientId": "your-microsoft-client-id",
+          "clientSecret": "your-microsoft-client-secret"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Provider Configuration
+
+### Google
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing one
+3. Navigate to "APIs & Services" → "Credentials"
+4. Create OAuth 2.0 Client ID (Web application)
+5. Add authorized redirect URI: `https://your-domain/api/auth/sso/google/callback`
+6. Copy Client ID and Client Secret
+
+```json
+{
+  "id": "google",
+  "name": "Google",
+  "type": "google",
+  "clientId": "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
+  "clientSecret": "YOUR_GOOGLE_CLIENT_SECRET"
+}
+```
+
+### GitHub
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Click "New OAuth App"
+3. Set Authorization callback URL: `https://your-domain/api/auth/sso/github/callback`
+4. Copy Client ID and generate Client Secret
+
+```json
+{
+  "id": "github",
+  "name": "GitHub",
+  "type": "github",
+  "clientId": "YOUR_GITHUB_CLIENT_ID",
+  "clientSecret": "YOUR_GITHUB_CLIENT_SECRET"
+}
+```
+
+### Microsoft (Azure AD)
+
+1. Go to [Azure Portal](https://portal.azure.com/) → Azure Active Directory
+2. Navigate to "App registrations" → "New registration"
+3. Add redirect URI: `https://your-domain/api/auth/sso/microsoft/callback`
+4. Under "Certificates & secrets", create a new client secret
+5. Copy Application (client) ID and client secret value
+
+```json
+{
+  "id": "microsoft",
+  "name": "Microsoft",
+  "type": "microsoft",
+  "clientId": "YOUR_AZURE_CLIENT_ID",
+  "clientSecret": "YOUR_AZURE_CLIENT_SECRET"
+}
+```
+
+### Custom OIDC Provider
+
+For other OIDC-compatible identity providers:
+
+```json
+{
+  "id": "custom-idp",
+  "name": "Corporate SSO",
+  "type": "oidc",
+  "issuerUrl": "https://idp.example.com",
+  "authorizationUrl": "https://idp.example.com/oauth2/authorize",
+  "tokenUrl": "https://idp.example.com/oauth2/token",
+  "userInfoUrl": "https://idp.example.com/oauth2/userinfo",
+  "clientId": "YOUR_CLIENT_ID",
+  "clientSecret": "YOUR_CLIENT_SECRET",
+  "scopes": ["openid", "email", "profile"],
+  "attributeMapping": {
+    "username": "preferred_username",
+    "email": "email",
+    "name": "name"
+  }
+}
+```
+
+## Role Mapping
+
+Configure automatic admin role assignment based on provider claims:
+
+```json
+{
+  "id": "google",
+  "name": "Google",
+  "type": "google",
+  "clientId": "...",
+  "clientSecret": "...",
+  "roleMapping": {
+    "adminClaim": "groups",
+    "adminValues": ["mcphub-admins", "engineering-leads"],
+    "defaultIsAdmin": false
+  }
+}
+```
+
+This configuration:
+- Checks the `groups` claim in the user's profile
+- Grants admin access if any value matches `mcphub-admins` or `engineering-leads`
+- Non-matching users get regular (non-admin) access
+
+## Configuration Options
+
+### Global Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable/disable SSO globally |
+| `allowLocalAuth` | boolean | `true` | Allow local username/password auth alongside SSO |
+| `callbackBaseUrl` | string | auto-detected | Base URL for OAuth callbacks |
+
+### Provider Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `id` | string | Yes | Unique identifier for the provider |
+| `name` | string | Yes | Display name shown on login page |
+| `type` | string | Yes | Provider type: `google`, `github`, `microsoft`, or `oidc` |
+| `clientId` | string | Yes | OAuth client ID from the provider |
+| `clientSecret` | string | Yes | OAuth client secret from the provider |
+| `enabled` | boolean | No | Enable/disable this specific provider (default: true) |
+| `scopes` | string[] | No | OAuth scopes to request |
+| `autoProvision` | boolean | No | Auto-create users on first SSO login (default: true) |
+| `allowLinking` | boolean | No | Allow existing users to link their accounts (default: true) |
+
+### Custom OIDC Options (type: "oidc")
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `issuerUrl` | string | No | OIDC issuer URL for discovery |
+| `authorizationUrl` | string | Yes | OAuth authorization endpoint |
+| `tokenUrl` | string | Yes | OAuth token endpoint |
+| `userInfoUrl` | string | Yes | OIDC userinfo endpoint |
+| `attributeMapping` | object | No | Map provider claims to user attributes |
+
+## Security Notes
+
+1. **PKCE Support**: MCPHub uses PKCE (Proof Key for Code Exchange) for all providers except GitHub (which doesn't support it)
+2. **State Parameter**: A cryptographically random state is generated for each login to prevent CSRF attacks
+3. **Token Storage**: OAuth tokens from providers are not stored; only MCPHub's JWT is issued after successful authentication
+4. **Rate Limiting**: Consider implementing rate limiting at infrastructure level (reverse proxy) for SSO endpoints
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"OAuth provider not found"**: Check that the provider is enabled and configured correctly
+2. **"Invalid or expired OAuth state"**: The login attempt took too long (>10 minutes) or was a replay attack
+3. **"Could not determine username"**: The provider didn't return expected user attributes; check `attributeMapping`
+4. **"User account not found and auto-provisioning is disabled"**: Set `autoProvision: true` or pre-create the user
+
+### Debug Mode
+
+Enable debug logging by setting the `DEBUG` environment variable:
+
+```bash
+DEBUG=oauth* node dist/index.js
+```
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -8,7 +8,7 @@ import { SettingsProvider } from './contexts/SettingsContext';
 import MainLayout from './layouts/MainLayout';
 import ProtectedRoute from './components/ProtectedRoute';
 import LoginPage from './pages/LoginPage';
-import OAuthCallbackPage from './pages/OAuthCallbackPage';
+import SSOCallbackPage from './pages/SSOCallbackPage';
 import DashboardPage from './pages/Dashboard';
 import ServersPage from './pages/ServersPage';
 import GroupsPage from './pages/GroupsPage';
@@ -36,7 +36,7 @@ function App() {
                <Routes>
                  {/* 公共路由 */}
                  <Route path="/login" element={<LoginPage />} />
-                  <Route path="/oauth-callback" element={<OAuthCallbackPage />} />
+                  <Route path="/sso-callback" element={<SSOCallbackPage />} />

                  {/* 受保护的路由，使用 MainLayout 作为布局容器 */}
                  <Route element={<ProtectedRoute />}>
--- a/frontend/src/pages/LoginPage.tsx
+++ b/frontend/src/pages/LoginPage.tsx
@@ -2,11 +2,11 @@ import React, { useState, useMemo, useCallback, useEffect } from 'react';
 import { useLocation, useNavigate } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
 import { useAuth } from '../contexts/AuthContext';
-import { getToken, getOAuthSsoConfig, initiateOAuthSsoLogin } from '../services/authService';
+import { getToken, getSSOConfig, initiateSSOLogin } from '../services/authService';
 import ThemeSwitch from '@/components/ui/ThemeSwitch';
 import LanguageSwitch from '@/components/ui/LanguageSwitch';
 import DefaultPasswordWarningModal from '@/components/ui/DefaultPasswordWarningModal';
-import { OAuthSsoConfig, OAuthSsoProvider } from '../types';
+import { SSOProvider } from '../types';

 const sanitizeReturnUrl = (value: string | null): string | null => {
  if (!value) {
@@ -30,7 +30,7 @@ const sanitizeReturnUrl = (value: string | null): string | null => {
  }
 };

-// Provider icon component
+// Provider icons (SVG)
 const ProviderIcon: React.FC<{ type: string; className?: string }> = ({ type, className = 'w-5 h-5' }) => {
  switch (type) {
    case 'google':
@@ -42,27 +42,27 @@ const ProviderIcon: React.FC<{ type: string; className?: string }> = ({ type, cl
          <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" fill="#EA4335"/>
        </svg>
      );
-    case 'microsoft':
-      return (
-        <svg className={className} viewBox="0 0 24 24" fill="currentColor">
-          <path d="M11.4 11.4H2V2h9.4v9.4z" fill="#F25022"/>
-          <path d="M22 11.4h-9.4V2H22v9.4z" fill="#7FBA00"/>
-          <path d="M11.4 22H2v-9.4h9.4V22z" fill="#00A4EF"/>
-          <path d="M22 22h-9.4v-9.4H22V22z" fill="#FFB900"/>
-        </svg>
-      );
    case 'github':
      return (
        <svg className={className} viewBox="0 0 24 24" fill="currentColor">
-          <path fillRule="evenodd" clipRule="evenodd" d="M12 2C6.477 2 2 6.477 2 12c0 4.42 2.865 8.17 6.839 9.49.5.092.682-.217.682-.482 0-.237-.009-.866-.013-1.7-2.782.604-3.369-1.34-3.369-1.34-.454-1.156-1.11-1.464-1.11-1.464-.908-.62.069-.608.069-.608 1.003.07 1.531 1.03 1.531 1.03.892 1.529 2.341 1.087 2.91.831.092-.646.35-1.086.636-1.336-2.22-.253-4.555-1.11-4.555-4.943 0-1.091.39-1.984 1.029-2.683-.103-.253-.446-1.27.098-2.647 0 0 .84-.269 2.75 1.025A9.578 9.578 0 0112 6.836c.85.004 1.705.115 2.504.337 1.909-1.294 2.747-1.025 2.747-1.025.546 1.377.203 2.394.1 2.647.64.699 1.028 1.592 1.028 2.683 0 3.842-2.339 4.687-4.566 4.935.359.309.678.919.678 1.852 0 1.336-.012 2.415-.012 2.743 0 .267.18.579.688.481C19.137 20.167 22 16.418 22 12c0-5.523-4.477-10-10-10z"/>
+          <path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0024 12c0-6.63-5.37-12-12-12z"/>
+        </svg>
+      );
+    case 'microsoft':
+      return (
+        <svg className={className} viewBox="0 0 24 24" fill="currentColor">
+          <path fill="#F25022" d="M1 1h10v10H1z"/>
+          <path fill="#00A4EF" d="M1 13h10v10H1z"/>
+          <path fill="#7FBA00" d="M13 1h10v10H13z"/>
+          <path fill="#FFB900" d="M13 13h10v10H13z"/>
        </svg>
      );
    default:
+      // Generic OAuth/OIDC icon
      return (
        <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-          <path d="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4"/>
-          <polyline points="10 17 15 12 10 7"/>
-          <line x1="15" y1="12" x2="3" y2="12"/>
+          <circle cx="12" cy="12" r="10"/>
+          <path d="M12 6v6l4 2"/>
        </svg>
      );
  }
@@ -75,7 +75,9 @@ const LoginPage: React.FC = () => {
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  const [showDefaultPasswordWarning, setShowDefaultPasswordWarning] = useState(false);
-  const [ssoConfig, setSsoConfig] = useState<OAuthSsoConfig | null>(null);
+  const [ssoProviders, setSsoProviders] = useState<SSOProvider[]>([]);
+  const [ssoEnabled, setSsoEnabled] = useState(false);
+  const [allowLocalAuth, setAllowLocalAuth] = useState(true);
  const { login } = useAuth();
  const location = useLocation();
  const navigate = useNavigate();
@@ -84,23 +86,15 @@ const LoginPage: React.FC = () => {
    return sanitizeReturnUrl(params.get('returnUrl'));
  }, [location.search]);

-  // Check for OAuth error in URL params
+  // Load SSO configuration on mount
  useEffect(() => {
-    const params = new URLSearchParams(location.search);
-    const oauthError = params.get('error');
-    const oauthMessage = params.get('message');
-    if (oauthError === 'oauth_failed' && oauthMessage) {
-      setError(oauthMessage);
-    }
-  }, [location.search]);
-
-  // Load OAuth SSO configuration
-  useEffect(() => {
-    const loadSsoConfig = async () => {
-      const config = await getOAuthSsoConfig();
-      setSsoConfig(config);
+    const loadSSOConfig = async () => {
+      const config = await getSSOConfig();
+      setSsoEnabled(config.enabled);
+      setSsoProviders(config.providers);
+      setAllowLocalAuth(config.allowLocalAuth);
    };
-    loadSsoConfig();
+    loadSSOConfig();
  }, []);

  const isServerUnavailableError = useCallback((message?: string) => {
@@ -196,8 +190,8 @@ const LoginPage: React.FC = () => {
    }
  };

-  const handleSsoLogin = (provider: OAuthSsoProvider) => {
-    initiateOAuthSsoLogin(provider.id, returnUrl || undefined);
+  const handleSSOLogin = (providerId: string) => {
+    initiateSSOLogin(providerId, returnUrl || undefined);
  };

  const handleCloseWarning = () => {
@@ -205,9 +199,6 @@ const LoginPage: React.FC = () => {
    redirectAfterLogin();
  };

-  const showLocalAuth = !ssoConfig?.enabled || ssoConfig.localAuthAllowed;
-  const showSsoProviders = ssoConfig?.enabled && ssoConfig.providers.length > 0;
-
  return (
    <div className="relative min-h-screen w-full overflow-hidden bg-gray-50 dark:bg-gray-950">
      {/* Top-right controls */}
@@ -260,39 +251,39 @@ const LoginPage: React.FC = () => {
            <div className="absolute -top-24 right-12 h-40 w-40 -translate-y-6 rounded-full bg-indigo-500/30 blur-3xl" />
            <div className="absolute -bottom-24 -left-12 h-40 w-40 translate-y-6 rounded-full bg-cyan-500/20 blur-3xl" />

-            {/* SSO Providers */}
-            {showSsoProviders && (
-              <div className="mt-4 space-y-3">
-                {ssoConfig.providers.map((provider) => (
+            {/* SSO Buttons */}
+            {ssoEnabled && ssoProviders.length > 0 && (
+              <div className="space-y-3 mb-6">
+                {ssoProviders.map((provider) => (
                  <button
                    key={provider.id}
                    type="button"
-                    onClick={() => handleSsoLogin(provider)}
-                    className="group relative flex w-full items-center justify-center gap-3 rounded-md border border-gray-300/60 bg-white/80 px-4 py-3 text-sm font-medium text-gray-700 shadow-sm transition-all hover:bg-gray-50 hover:shadow focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 dark:border-gray-600/60 dark:bg-gray-800/80 dark:text-gray-200 dark:hover:bg-gray-700/80"
+                    onClick={() => handleSSOLogin(provider.id)}
+                    className="sso-button group relative flex w-full items-center justify-center gap-3 rounded-md border border-gray-300/60 bg-white/80 px-4 py-2.5 text-sm font-medium text-gray-700 shadow-sm transition-all hover:bg-gray-50 hover:border-gray-400/60 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 dark:border-gray-600/60 dark:bg-gray-800/80 dark:text-gray-200 dark:hover:bg-gray-700/80"
                  >
-                    <ProviderIcon type={provider.icon || provider.type} />
-                    <span>{provider.buttonText || t('oauthSso.signInWith', { provider: provider.name })}</span>
+                    <ProviderIcon type={provider.type} />
+                    <span>{t('auth.continueWith', { provider: provider.name })}</span>
                  </button>
                ))}
+                
+                {/* Divider - only show if local auth is also allowed */}
+                {allowLocalAuth && (
+                  <div className="relative my-4">
+                    <div className="absolute inset-0 flex items-center">
+                      <div className="w-full border-t border-gray-300/60 dark:border-gray-600/60" />
+                    </div>
+                    <div className="relative flex justify-center text-sm">
+                      <span className="px-2 bg-white/60 text-gray-500 dark:bg-gray-900/60 dark:text-gray-400">
+                        {t('auth.orContinueWith')}
+                      </span>
+                    </div>
+                  </div>
+                )}
              </div>
            )}

-            {/* Divider between SSO and local auth */}
-            {showSsoProviders && showLocalAuth && (
-              <div className="relative my-6">
-                <div className="absolute inset-0 flex items-center">
-                  <div className="w-full border-t border-gray-300/60 dark:border-gray-600/60" />
-                </div>
-                <div className="relative flex justify-center text-sm">
-                  <span className="bg-white/60 px-4 text-gray-500 dark:bg-gray-900/60 dark:text-gray-400">
-                    {t('oauthSso.orContinueWith')}
-                  </span>
-                </div>
-              </div>
-            )}
-
-            {/* Local auth form */}
-            {showLocalAuth && (
+            {/* Local auth form - only show if allowed */}
+            {allowLocalAuth && (
              <form className="mt-4 space-y-4" onSubmit={handleSubmit}>
                <div className="space-y-4">
                  <div>
@@ -347,10 +338,10 @@ const LoginPage: React.FC = () => {
              </form>
            )}

-            {/* Error display for SSO-only mode */}
-            {!showLocalAuth && error && (
-              <div className="mt-4 error-box rounded border border-red-500/20 bg-red-500/10 p-2 text-center text-sm text-red-600 dark:text-red-400">
-                {error}
+            {/* Show message if only SSO is available and no providers configured */}
+            {!allowLocalAuth && ssoProviders.length === 0 && (
+              <div className="text-center text-gray-500 dark:text-gray-400">
+                {t('auth.noLoginMethodsAvailable')}
              </div>
            )}
          </div>
--- a/frontend/src/pages/OAuthCallbackPage.tsx
+++ b/frontend/src/pages/OAuthCallbackPage.tsx
@@ -1,42 +0,0 @@
-import React, { useEffect } from 'react';
-import { useNavigate, useSearchParams } from 'react-router-dom';
-import { setToken } from '../services/authService';
-
-/**
- * OAuth Callback Page
- * 
- * This page handles the callback from OAuth SSO providers.
- * It receives the JWT token as a query parameter, stores it, and redirects to the app.
- */
-const OAuthCallbackPage: React.FC = () => {
-  const navigate = useNavigate();
-  const [searchParams] = useSearchParams();
-
-  useEffect(() => {
-    const token = searchParams.get('token');
-    const returnUrl = searchParams.get('returnUrl') || '/';
-
-    if (token) {
-      // Store the token
-      setToken(token);
-      
-      // Redirect to the return URL
-      navigate(returnUrl, { replace: true });
-    } else {
-      // No token - redirect to login with error
-      navigate('/login?error=oauth_failed&message=No+token+received', { replace: true });
-    }
-  }, [searchParams, navigate]);
-
-  // Show loading state while processing
-  return (
-    <div className="min-h-screen flex items-center justify-center bg-gray-50 dark:bg-gray-950">
-      <div className="text-center">
-        <div className="animate-spin rounded-full h-12 w-12 border-t-2 border-b-2 border-indigo-500 mx-auto"></div>
-        <p className="mt-4 text-gray-600 dark:text-gray-400">Completing authentication...</p>
-      </div>
-    </div>
-  );
-};
-
-export default OAuthCallbackPage;
--- a/frontend/src/pages/SSOCallbackPage.tsx
+++ b/frontend/src/pages/SSOCallbackPage.tsx
@@ -0,0 +1,108 @@
+import React, { useEffect, useState } from 'react';
+import { useNavigate, useLocation } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { handleSSOToken, getCurrentUser } from '../services/authService';
+import { useAuth } from '../contexts/AuthContext';
+
+/**
+ * SSO Callback Page
+ * Handles the redirect from OAuth SSO callback, extracts token, and redirects to destination
+ */
+const SSOCallbackPage: React.FC = () => {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { auth } = useAuth();
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const handleCallback = async () => {
+      const params = new URLSearchParams(location.search);
+      const token = params.get('token');
+      const returnUrl = params.get('returnUrl') || '/';
+      const errorParam = params.get('error');
+
+      // Handle OAuth errors
+      if (errorParam) {
+        setError(errorParam);
+        setTimeout(() => {
+          navigate('/login');
+        }, 3000);
+        return;
+      }
+
+      // Handle successful SSO login
+      if (token) {
+        try {
+          // Store the token
+          handleSSOToken(token);
+
+          // Verify the token by fetching current user
+          const response = await getCurrentUser();
+          if (response.success) {
+            // Redirect to the return URL or dashboard
+            if (returnUrl.startsWith('/oauth/authorize')) {
+              // For OAuth authorize flow, pass the token
+              const url = new URL(returnUrl, window.location.origin);
+              url.searchParams.set('token', token);
+              window.location.assign(`${url.pathname}${url.search}`);
+            } else {
+              navigate(returnUrl);
+            }
+          } else {
+            setError(t('auth.ssoTokenInvalid'));
+            setTimeout(() => {
+              navigate('/login');
+            }, 3000);
+          }
+        } catch (err) {
+          console.error('SSO callback error:', err);
+          setError(t('auth.ssoCallbackError'));
+          setTimeout(() => {
+            navigate('/login');
+          }, 3000);
+        }
+      } else {
+        // No token provided
+        setError(t('auth.ssoNoToken'));
+        setTimeout(() => {
+          navigate('/login');
+        }, 3000);
+      }
+    };
+
+    // Only handle callback if not already authenticated
+    if (!auth.isAuthenticated) {
+      handleCallback();
+    } else {
+      // Already authenticated, redirect to home
+      navigate('/');
+    }
+  }, [location.search, navigate, auth.isAuthenticated, t]);
+
+  return (
+    <div className="relative min-h-screen w-full overflow-hidden bg-gray-50 dark:bg-gray-950 flex items-center justify-center">
+      <div className="text-center">
+        {error ? (
+          <div className="space-y-4">
+            <div className="text-red-600 dark:text-red-400 text-lg font-medium">
+              {error}
+            </div>
+            <p className="text-gray-500 dark:text-gray-400 text-sm">
+              {t('auth.redirectingToLogin')}
+            </p>
+          </div>
+        ) : (
+          <div className="space-y-4">
+            <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-indigo-600 mx-auto"></div>
+            <p className="text-gray-600 dark:text-gray-300 text-lg">
+              {t('auth.ssoProcessing')}
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default SSOCallbackPage;
--- a/frontend/src/services/authService.ts
+++ b/frontend/src/services/authService.ts
@@ -3,7 +3,7 @@ import {
  LoginCredentials,
  RegisterCredentials,
  ChangePasswordCredentials,
-  OAuthSsoConfig,
+  SSOConfig,
 } from '../types';
 import { apiPost, apiGet } from '../utils/fetchInterceptor';
 import { getToken, setToken, removeToken } from '../utils/interceptors';
@@ -11,6 +11,35 @@ import { getToken, setToken, removeToken } from '../utils/interceptors';
 // Export token management functions
 export { getToken, setToken, removeToken };

+// Get SSO configuration
+export const getSSOConfig = async (): Promise<SSOConfig> => {
+  try {
+    const response = await apiGet<{ success: boolean; data: SSOConfig }>('/auth/sso/config');
+    if (response.success && response.data) {
+      return response.data;
+    }
+    return { enabled: false, providers: [], allowLocalAuth: true };
+  } catch (error) {
+    console.error('Get SSO config error:', error);
+    return { enabled: false, providers: [], allowLocalAuth: true };
+  }
+};
+
+// Initiate SSO login (redirects to provider)
+export const initiateSSOLogin = (providerId: string, returnUrl?: string): void => {
+  const basePath = import.meta.env.VITE_API_BASE_PATH || '';
+  let url = `${basePath}/api/auth/sso/${providerId}`;
+  if (returnUrl) {
+    url += `?returnUrl=${encodeURIComponent(returnUrl)}`;
+  }
+  window.location.href = url;
+};
+
+// Handle SSO callback token (called from SSO callback page)
+export const handleSSOToken = (token: string): void => {
+  setToken(token);
+};
+
 // Login user
 export const login = async (credentials: LoginCredentials): Promise<AuthResponse> => {
  try {
@@ -106,30 +135,6 @@ export const changePassword = async (
  }
 };

-// Get OAuth SSO configuration
-export const getOAuthSsoConfig = async (): Promise<OAuthSsoConfig | null> => {
-  try {
-    const response = await apiGet<{ success: boolean; data: OAuthSsoConfig }>('/auth/sso/config');
-    if (response.success && response.data) {
-      return response.data;
-    }
-    return null;
-  } catch (error) {
-    console.error('Get OAuth SSO config error:', error);
-    return null;
-  }
-};
-
-// Initiate OAuth SSO login (redirects to provider)
-export const initiateOAuthSsoLogin = (providerId: string, returnUrl?: string): void => {
-  const basePath = import.meta.env.VITE_BASE_PATH || '';
-  let url = `${basePath}/api/auth/sso/${providerId}`;
-  if (returnUrl) {
-    url += `?returnUrl=${encodeURIComponent(returnUrl)}`;
-  }
-  window.location.href = url;
-};
-
 // Logout user
 export const logout = (): void => {
  removeToken();
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -329,6 +329,19 @@ export interface IUser {
  permissions?: string[];
 }

+// OAuth SSO types
+export interface SSOProvider {
+  id: string;
+  name: string;
+  type: string;
+}
+
+export interface SSOConfig {
+  enabled: boolean;
+  providers: SSOProvider[];
+  allowLocalAuth: boolean;
+}
+
 // User management types
 export interface User {
  username: string;
@@ -381,21 +394,6 @@ export interface AuthResponse {
  isUsingDefaultPassword?: boolean;
 }

-// OAuth SSO types
-export interface OAuthSsoProvider {
-  id: string;
-  name: string;
-  type: string;
-  icon?: string;
-  buttonText?: string;
-}
-
-export interface OAuthSsoConfig {
-  enabled: boolean;
-  providers: OAuthSsoProvider[];
-  localAuthAllowed: boolean;
-}
-
 // Official Registry types (from registry.modelcontextprotocol.io)
 export interface RegistryVariable {
  choices?: string[];
--- a/locales/en.json
+++ b/locales/en.json
@@ -79,7 +79,15 @@
    "passwordRequireLetter": "Password must contain at least one letter",
    "passwordRequireNumber": "Password must contain at least one number",
    "passwordRequireSpecial": "Password must contain at least one special character",
-    "passwordStrengthHint": "Password must be at least 8 characters and contain letters, numbers, and special characters"
+    "passwordStrengthHint": "Password must be at least 8 characters and contain letters, numbers, and special characters",
+    "continueWith": "Continue with {{provider}}",
+    "orContinueWith": "or continue with",
+    "noLoginMethodsAvailable": "No login methods available. Please contact your administrator.",
+    "ssoProcessing": "Processing login...",
+    "ssoTokenInvalid": "Authentication failed. Please try again.",
+    "ssoCallbackError": "An error occurred during authentication.",
+    "ssoNoToken": "No authentication token received.",
+    "redirectingToLogin": "Redirecting to login page..."
  },
  "server": {
    "addServer": "Add Server",
@@ -840,25 +848,5 @@
    "internalError": "Internal Error",
    "internalErrorMessage": "An unexpected error occurred while processing the OAuth callback.",
    "closeWindow": "Close Window"
-  },
-  "oauthSso": {
-    "errors": {
-      "providerIdRequired": "Provider ID is required",
-      "providerNotFound": "OAuth provider not found",
-      "missingState": "Missing OAuth state parameter",
-      "missingCode": "Missing authorization code",
-      "invalidState": "Invalid or expired OAuth state",
-      "authFailed": "OAuth authentication failed",
-      "userNotProvisioned": "User not found and auto-provisioning is disabled"
-    },
-    "signInWith": "Sign in with {{provider}}",
-    "orContinueWith": "Or continue with",
-    "continueWithProvider": "Continue with {{provider}}",
-    "loginWithSso": "Login with SSO",
-    "providers": {
-      "google": "Google",
-      "microsoft": "Microsoft",
-      "github": "GitHub"
-    }
  }
 }
--- a/locales/zh.json
+++ b/locales/zh.json
@@ -79,7 +79,15 @@
    "passwordRequireLetter": "密码必须包含至少一个字母",
    "passwordRequireNumber": "密码必须包含至少一个数字",
    "passwordRequireSpecial": "密码必须包含至少一个特殊字符",
-    "passwordStrengthHint": "密码必须至少 8 个字符，且包含字母、数字和特殊字符"
+    "passwordStrengthHint": "密码必须至少 8 个字符，且包含字母、数字和特殊字符",
+    "continueWith": "使用 {{provider}} 登录",
+    "orContinueWith": "或使用账号登录",
+    "noLoginMethodsAvailable": "没有可用的登录方式，请联系管理员。",
+    "ssoProcessing": "正在处理登录...",
+    "ssoTokenInvalid": "认证失败，请重试。",
+    "ssoCallbackError": "认证过程中发生错误。",
+    "ssoNoToken": "未收到认证令牌。",
+    "redirectingToLogin": "正在跳转到登录页面..."
  },
  "server": {
    "addServer": "添加服务器",
@@ -842,25 +850,5 @@
    "internalError": "内部错误",
    "internalErrorMessage": "处理 OAuth 回调时发生意外错误。",
    "closeWindow": "关闭窗口"
-  },
-  "oauthSso": {
-    "errors": {
-      "providerIdRequired": "需要提供身份验证提供商 ID",
-      "providerNotFound": "未找到 OAuth 身份验证提供商",
-      "missingState": "缺少 OAuth 状态参数",
-      "missingCode": "缺少授权码",
-      "invalidState": "OAuth 状态无效或已过期",
-      "authFailed": "OAuth 身份验证失败",
-      "userNotProvisioned": "用户未找到且自动创建用户已禁用"
-    },
-    "signInWith": "使用 {{provider}} 登录",
-    "orContinueWith": "或使用以下方式继续",
-    "continueWithProvider": "使用 {{provider}} 继续",
-    "loginWithSso": "使用 SSO 登录",
-    "providers": {
-      "google": "Google",
-      "microsoft": "Microsoft",
-      "github": "GitHub"
-    }
  }
 }
--- a/src/controllers/oauthSSOController.ts
+++ b/src/controllers/oauthSSOController.ts
@@ -0,0 +1,171 @@
+import { Request, Response } from 'express';
+import { loadSettings } from '../config/index.js';
+import {
+  isOAuthSSOEnabled,
+  isLocalAuthAllowed,
+  getEnabledProviders,
+  getProviderById,
+  generateAuthorizationUrl,
+  handleOAuthCallback as handleCallback,
+} from '../services/oauthSSOService.js';
+
+/**
+ * Get OAuth SSO configuration for frontend
+ * Returns list of enabled providers and whether local auth is allowed
+ */
+export const getSSOConfig = async (req: Request, res: Response): Promise<void> => {
+  try {
+    const enabled = isOAuthSSOEnabled();
+    const providers = getEnabledProviders();
+    const allowLocalAuth = isLocalAuthAllowed();
+
+    res.json({
+      success: true,
+      data: {
+        enabled,
+        providers,
+        allowLocalAuth,
+      },
+    });
+  } catch (error) {
+    console.error('Error getting SSO config:', error);
+    res.status(500).json({
+      success: false,
+      message: 'Failed to get SSO configuration',
+    });
+  }
+};
+
+/**
+ * Initiate OAuth SSO flow for a specific provider
+ * Redirects user to the OAuth provider's authorization page
+ */
+export const initiateSSOLogin = async (req: Request, res: Response): Promise<void> => {
+  const { provider } = req.params;
+
+  try {
+    // Check if SSO is enabled
+    if (!isOAuthSSOEnabled()) {
+      res.status(400).json({
+        success: false,
+        message: 'OAuth SSO is not enabled',
+      });
+      return;
+    }
+
+    // Check if provider exists
+    const providerConfig = getProviderById(provider);
+    if (!providerConfig) {
+      res.status(404).json({
+        success: false,
+        message: `OAuth provider '${provider}' not found or disabled`,
+      });
+      return;
+    }
+
+    // Build redirect URI
+    const settings = loadSettings();
+    const callbackBaseUrl =
+      settings.systemConfig?.oauthSSO?.callbackBaseUrl ||
+      `${req.protocol}://${req.get('host')}`;
+    const redirectUri = `${callbackBaseUrl}/api/auth/sso/${provider}/callback`;
+
+    // Generate authorization URL
+    const result = generateAuthorizationUrl(provider, redirectUri);
+    if (!result) {
+      res.status(500).json({
+        success: false,
+        message: 'Failed to generate authorization URL',
+      });
+      return;
+    }
+
+    // Store the return URL in a cookie if provided (for after-login redirect)
+    const returnUrl = req.query.returnUrl as string;
+    if (returnUrl) {
+      res.cookie('sso_return_url', returnUrl, {
+        httpOnly: true,
+        secure: req.secure,
+        maxAge: 10 * 60 * 1000, // 10 minutes
+        sameSite: 'lax',
+      });
+    }
+
+    // Redirect to OAuth provider
+    res.redirect(result.url);
+  } catch (error) {
+    console.error(`Error initiating SSO login for ${provider}:`, error);
+    res.status(500).json({
+      success: false,
+      message: 'Failed to initiate SSO login',
+    });
+  }
+};
+
+/**
+ * Handle OAuth callback from provider
+ * Exchanges code for tokens, gets user info, creates/updates user, returns JWT
+ * 
+ * Note: OAuth callback data (code, state) is received via query parameters as per OAuth 2.0 spec.
+ * This is secure because:
+ * - The authorization code is single-use and tied to a specific state
+ * - The state parameter prevents CSRF attacks
+ * - PKCE provides additional security for the token exchange
+ */
+export const handleSSOCallback = async (req: Request, res: Response): Promise<void> => {
+  const { provider } = req.params;
+  // lgtm[js/sensitive-get-query] - OAuth 2.0 requires code/state in query params
+  const { code, state, error: oauthError, error_description } = req.query;
+
+  try {
+    // Check for OAuth error from provider
+    if (oauthError) {
+      console.error(`OAuth SSO error from ${provider}:`, oauthError, error_description);
+      res.redirect(`/login?error=${encodeURIComponent(String(error_description || oauthError))}`);
+      return;
+    }
+
+    // Validate required parameters
+    if (!code || !state) {
+      res.redirect('/login?error=missing_oauth_parameters');
+      return;
+    }
+
+    // Build redirect URI (must match the one used in initiation)
+    const settings = loadSettings();
+    const callbackBaseUrl =
+      settings.systemConfig?.oauthSSO?.callbackBaseUrl ||
+      `${req.protocol}://${req.get('host')}`;
+    const redirectUri = `${callbackBaseUrl}/api/auth/sso/${provider}/callback`;
+
+    // Handle the callback
+    const result = await handleCallback(String(state), String(code), redirectUri);
+
+    if (!result.success) {
+      console.error(`OAuth SSO callback failed for ${provider}:`, result.error);
+      res.redirect(`/login?error=${encodeURIComponent(result.error || 'sso_failed')}`);
+      return;
+    }
+
+    // Get the return URL from cookie
+    const returnUrl = req.cookies?.sso_return_url || '/';
+    res.clearCookie('sso_return_url');
+
+    // Build redirect URL with token
+    // Note: For security, we use a short-lived token in URL and the frontend
+    // should immediately exchange it and store in localStorage
+    const redirectUrl = new URL(returnUrl, `${req.protocol}://${req.get('host')}`);
+
+    // For OAuth authorize flow, append token as query param
+    if (returnUrl.startsWith('/oauth/authorize')) {
+      redirectUrl.searchParams.set('token', result.token!);
+      res.redirect(redirectUrl.pathname + redirectUrl.search);
+    } else {
+      // For normal login, redirect to a special callback page that handles the token
+      res.redirect(`/sso-callback?token=${encodeURIComponent(result.token!)}&returnUrl=${encodeURIComponent(returnUrl)}`);
+    }
+  } catch (error) {
+    console.error(`Error handling SSO callback for ${provider}:`, error);
+    res.redirect('/login?error=sso_callback_error');
+  }
+};
--- a/src/controllers/oauthSsoController.ts
+++ b/src/controllers/oauthSsoController.ts
@@ -1,245 +0,0 @@
-/**
- * OAuth SSO Controller
- *
- * Handles OAuth SSO authentication endpoints.
- */
-
-import { Request, Response } from 'express';
-import jwt from 'jsonwebtoken';
-import {
-  generateAuthorizationUrl,
-  handleCallback,
-  getPublicProviderInfo,
-  isLocalAuthAllowed,
-  isOAuthSsoEnabled,
-  getOAuthSsoConfig as getSsoConfigFromService,
-} from '../services/oauthSsoService.js';
-import { JWT_SECRET } from '../config/jwt.js';
-import config from '../config/index.js';
-
-const TOKEN_EXPIRY = '24h';
-
-/**
- * Get the base URL for OAuth callbacks
- * Uses configured callbackBaseUrl if available, otherwise derives from request
- * This approach is more secure than blindly trusting forwarded headers
- */
-async function getCallbackBaseUrl(req: Request): Promise<string> {
-  // First, check if a callback base URL is configured (most secure option)
-  const ssoConfig = await getSsoConfigFromService();
-  if (ssoConfig?.callbackBaseUrl) {
-    return ssoConfig.callbackBaseUrl;
-  }
-
-  // Fall back to deriving from request (less secure, but works in simpler setups)
-  // Only trust forwarded headers if app is configured to trust proxy
-  if (req.app.get('trust proxy') && req.headers['x-forwarded-proto'] && req.headers['x-forwarded-host']) {
-    const proto = Array.isArray(req.headers['x-forwarded-proto'])
-      ? req.headers['x-forwarded-proto'][0]
-      : req.headers['x-forwarded-proto'];
-    const host = Array.isArray(req.headers['x-forwarded-host'])
-      ? req.headers['x-forwarded-host'][0]
-      : req.headers['x-forwarded-host'];
-    return `${proto}://${host}`;
-  }
-
-  return `${req.protocol}://${req.get('host')}`;
-}
-
-/**
- * Get OAuth SSO configuration for frontend
- * Returns enabled providers and whether local auth is allowed
- */
-export const getOAuthSsoConfig = async (req: Request, res: Response): Promise<void> => {
-  try {
-    const enabled = await isOAuthSsoEnabled();
-    const providers = await getPublicProviderInfo();
-    const localAuthAllowed = await isLocalAuthAllowed();
-
-    res.json({
-      success: true,
-      data: {
-        enabled,
-        providers,
-        localAuthAllowed,
-      },
-    });
-  } catch (error) {
-    console.error('Error getting OAuth SSO config:', error);
-    res.status(500).json({
-      success: false,
-      message: 'Failed to get OAuth SSO configuration',
-    });
-  }
-};
-
-/**
- * Initiate OAuth SSO login
- * Redirects user to the OAuth provider's authorization page
- */
-export const initiateOAuthLogin = async (req: Request, res: Response): Promise<void> => {
-  const t = (req as any).t || ((key: string) => key);
-
-  try {
-    const { providerId } = req.params;
-    const { returnUrl } = req.query;
-
-    if (!providerId) {
-      res.status(400).json({
-        success: false,
-        message: t('oauthSso.errors.providerIdRequired'),
-      });
-      return;
-    }
-
-    // Build callback URL
-    // Note: Use configured callback base URL from oauthSso config if available
-    // This avoids relying on potentially untrusted forwarded headers
-    const baseUrl = await getCallbackBaseUrl(req);
-
-    const callbackUrl = `${baseUrl}${config.basePath}/api/auth/sso/${providerId}/callback`;
-
-    // Generate authorization URL
-    const { url } = await generateAuthorizationUrl(
-      providerId,
-      callbackUrl,
-      typeof returnUrl === 'string' ? returnUrl : undefined,
-    );
-
-    // Redirect to OAuth provider
-    res.redirect(url);
-  } catch (error) {
-    console.error('Error initiating OAuth login:', error);
-    const errorMessage = error instanceof Error ? error.message : 'Failed to initiate OAuth login';
-    res.status(500).json({
-      success: false,
-      message: errorMessage,
-    });
-  }
-};
-
-/**
- * Handle OAuth callback from provider
- * Exchanges code for tokens and creates/updates user
- */
-export const handleOAuthCallback = async (req: Request, res: Response): Promise<void> => {
-  const t = (req as any).t || ((key: string) => key);
-
-  try {
-    const { providerId } = req.params;
-    const { code, state, error, error_description } = req.query;
-
-    // Handle OAuth errors
-    if (error) {
-      console.error(`OAuth error from provider ${providerId}:`, error, error_description);
-      const errorUrl = buildErrorRedirectUrl(String(error_description || error), req);
-      return res.redirect(errorUrl);
-    }
-
-    // Validate required parameters
-    if (!state) {
-      const errorUrl = buildErrorRedirectUrl(t('oauthSso.errors.missingState'), req);
-      return res.redirect(errorUrl);
-    }
-
-    if (!code) {
-      const errorUrl = buildErrorRedirectUrl(t('oauthSso.errors.missingCode'), req);
-      return res.redirect(errorUrl);
-    }
-
-    // Build callback URL (same as used in initiate)
-    const baseUrl = await getCallbackBaseUrl(req);
-
-    const callbackUrl = `${baseUrl}${config.basePath}/api/auth/sso/${providerId}/callback`;
-
-    // Full current URL with query params
-    const currentUrl = `${callbackUrl}?${new URLSearchParams(req.query as Record<string, string>).toString()}`;
-
-    // Exchange code for tokens and get user
-    const { user, returnUrl } = await handleCallback(
-      callbackUrl,
-      currentUrl,
-      String(state),
-    );
-
-    // Generate JWT token
-    const payload = {
-      user: {
-        username: user.username,
-        isAdmin: user.isAdmin || false,
-      },
-    };
-
-    const token = jwt.sign(payload, JWT_SECRET, { expiresIn: TOKEN_EXPIRY });
-
-    // Redirect to frontend with token
-    const redirectUrl = buildSuccessRedirectUrl(token, returnUrl, req);
-    res.redirect(redirectUrl);
-  } catch (error) {
-    console.error('Error handling OAuth callback:', error);
-    const errorMessage =
-      error instanceof Error ? error.message : 'Authentication failed';
-    const errorUrl = buildErrorRedirectUrl(errorMessage, req);
-    res.redirect(errorUrl);
-  }
-};
-
-/**
- * Get list of available OAuth providers
- */
-export const listOAuthProviders = async (req: Request, res: Response): Promise<void> => {
-  try {
-    const providers = await getPublicProviderInfo();
-    res.json({
-      success: true,
-      data: providers,
-    });
-  } catch (error) {
-    console.error('Error listing OAuth providers:', error);
-    res.status(500).json({
-      success: false,
-      message: 'Failed to list OAuth providers',
-    });
-  }
-};
-
-/**
- * Build redirect URL for successful authentication
- */
-function buildSuccessRedirectUrl(token: string, returnUrl: string | undefined, req: Request): string {
-  const baseUrl = getBaseUrl(req);
-  const targetPath = returnUrl || '/';
-  
-  // Use a special OAuth callback page that stores the token
-  const callbackPath = `${config.basePath}/oauth-callback`;
-  const params = new URLSearchParams({
-    token,
-    returnUrl: targetPath,
-  });
-
-  return `${baseUrl}${callbackPath}?${params.toString()}`;
-}
-
-/**
- * Build redirect URL for authentication errors
- */
-function buildErrorRedirectUrl(error: string, req: Request): string {
-  const baseUrl = getBaseUrl(req);
-  const loginPath = `${config.basePath}/login`;
-  const params = new URLSearchParams({
-    error: 'oauth_failed',
-    message: error,
-  });
-
-  return `${baseUrl}${loginPath}?${params.toString()}`;
-}
-
-/**
- * Get base URL from request
- */
-function getBaseUrl(req: Request): string {
-  if (req.headers['x-forwarded-proto'] && req.headers['x-forwarded-host']) {
-    return `${req.headers['x-forwarded-proto']}://${req.headers['x-forwarded-host']}`;
-  }
-  return `${req.protocol}://${req.get('host')}`;
-}
--- a/src/dao/SystemConfigDaoDbImpl.ts
+++ b/src/dao/SystemConfigDaoDbImpl.ts
@@ -22,7 +22,6 @@ export class SystemConfigDaoDbImpl implements SystemConfigDao {
      nameSeparator: config.nameSeparator,
      oauth: config.oauth as any,
      oauthServer: config.oauthServer as any,
-      oauthSso: config.oauthSso as any,
      enableSessionRebuild: config.enableSessionRebuild,
    };
  }
@@ -37,7 +36,6 @@ export class SystemConfigDaoDbImpl implements SystemConfigDao {
      nameSeparator: updated.nameSeparator,
      oauth: updated.oauth as any,
      oauthServer: updated.oauthServer as any,
-      oauthSso: updated.oauthSso as any,
      enableSessionRebuild: updated.enableSessionRebuild,
    };
  }
@@ -52,7 +50,6 @@ export class SystemConfigDaoDbImpl implements SystemConfigDao {
      nameSeparator: config.nameSeparator,
      oauth: config.oauth as any,
      oauthServer: config.oauthServer as any,
-      oauthSso: config.oauthSso as any,
      enableSessionRebuild: config.enableSessionRebuild,
    };
  }
--- a/src/dao/UserDaoDbImpl.ts
+++ b/src/dao/UserDaoDbImpl.ts
@@ -13,28 +13,25 @@ export class UserDaoDbImpl implements UserDao {
    this.repository = new UserRepository();
  }

-  private mapToIUser(u: any): IUser {
-    return {
+  async findAll(): Promise<IUser[]> {
+    const users = await this.repository.findAll();
+    return users.map((u) => ({
      username: u.username,
      password: u.password,
      isAdmin: u.isAdmin,
-      oauthProvider: u.oauthProvider,
-      oauthSubject: u.oauthSubject,
-      email: u.email,
-      displayName: u.displayName,
-      avatarUrl: u.avatarUrl,
-    };
-  }
-
-  async findAll(): Promise<IUser[]> {
-    const users = await this.repository.findAll();
-    return users.map(this.mapToIUser);
+      oauthLinks: u.oauthLinks ?? undefined,
+    }));
  }

  async findById(username: string): Promise<IUser | null> {
    const user = await this.repository.findByUsername(username);
    if (!user) return null;
-    return this.mapToIUser(user);
+    return {
+      username: user.username,
+      password: user.password,
+      isAdmin: user.isAdmin,
+      oauthLinks: user.oauthLinks ?? undefined,
+    };
  }

  async findByUsername(username: string): Promise<IUser | null> {
@@ -46,13 +43,14 @@ export class UserDaoDbImpl implements UserDao {
      username: entity.username,
      password: entity.password,
      isAdmin: entity.isAdmin || false,
-      oauthProvider: entity.oauthProvider,
-      oauthSubject: entity.oauthSubject,
-      email: entity.email,
-      displayName: entity.displayName,
-      avatarUrl: entity.avatarUrl,
+      oauthLinks: entity.oauthLinks ?? null,
    });
-    return this.mapToIUser(user);
+    return {
+      username: user.username,
+      password: user.password,
+      isAdmin: user.isAdmin,
+      oauthLinks: user.oauthLinks ?? undefined,
+    };
  }

  async createWithHashedPassword(
@@ -68,14 +66,15 @@ export class UserDaoDbImpl implements UserDao {
    const user = await this.repository.update(username, {
      password: entity.password,
      isAdmin: entity.isAdmin,
-      oauthProvider: entity.oauthProvider,
-      oauthSubject: entity.oauthSubject,
-      email: entity.email,
-      displayName: entity.displayName,
-      avatarUrl: entity.avatarUrl,
+      oauthLinks: entity.oauthLinks ?? undefined,
    });
    if (!user) return null;
-    return this.mapToIUser(user);
+    return {
+      username: user.username,
+      password: user.password,
+      isAdmin: user.isAdmin,
+      oauthLinks: user.oauthLinks ?? undefined,
+    };
  }

  async delete(username: string): Promise<boolean> {
@@ -106,6 +105,11 @@ export class UserDaoDbImpl implements UserDao {

  async findAdmins(): Promise<IUser[]> {
    const users = await this.repository.findAdmins();
-    return users.map(this.mapToIUser);
+    return users.map((u) => ({
+      username: u.username,
+      password: u.password,
+      isAdmin: u.isAdmin,
+      oauthLinks: u.oauthLinks ?? undefined,
+    }));
  }
 }
--- a/src/db/entities/SystemConfig.ts
+++ b/src/db/entities/SystemConfig.ts
@@ -30,8 +30,8 @@ export class SystemConfig {
  @Column({ type: 'simple-json', nullable: true })
  oauthServer?: Record<string, any>;

-  @Column({ name: 'oauth_sso', type: 'simple-json', nullable: true })
-  oauthSso?: Record<string, any>;
+  @Column({ type: 'simple-json', nullable: true })
+  oauthSSO?: Record<string, any>;

  @Column({ type: 'boolean', nullable: true })
  enableSessionRebuild?: boolean;
--- a/src/db/entities/User.ts
+++ b/src/db/entities/User.ts
@@ -5,6 +5,7 @@ import {
  CreateDateColumn,
  UpdateDateColumn,
 } from 'typeorm';
+import { IOAuthLink } from '../../types/index.js';

 /**
 * User entity for database storage
@@ -23,21 +24,8 @@ export class User {
  @Column({ type: 'boolean', default: false })
  isAdmin: boolean;

-  // OAuth SSO fields
-  @Column({ name: 'oauth_provider', type: 'varchar', length: 100, nullable: true })
-  oauthProvider?: string;
-
-  @Column({ name: 'oauth_subject', type: 'varchar', length: 255, nullable: true })
-  oauthSubject?: string;
-
-  @Column({ type: 'varchar', length: 255, nullable: true })
-  email?: string;
-
-  @Column({ name: 'display_name', type: 'varchar', length: 255, nullable: true })
-  displayName?: string;
-
-  @Column({ name: 'avatar_url', type: 'text', nullable: true })
-  avatarUrl?: string;
+  @Column({ type: 'simple-json', nullable: true })
+  oauthLinks: IOAuthLink[] | null;

  @CreateDateColumn({ name: 'created_at', type: 'timestamp' })
  createdAt: Date;
--- a/src/routes/index.ts
+++ b/src/routes/index.ts
@@ -66,6 +66,11 @@ import {
  getRegistryServerVersion,
 } from '../controllers/registryController.js';
 import { login, register, getCurrentUser, changePassword } from '../controllers/authController.js';
+import {
+  getSSOConfig,
+  initiateSSOLogin,
+  handleSSOCallback,
+} from '../controllers/oauthSSOController.js';
 import { getAllLogs, clearLogs, streamLogs } from '../controllers/logController.js';
 import {
  getRuntimeConfig,
@@ -112,12 +117,6 @@ import {
  updateBearerKey,
  deleteBearerKey,
 } from '../controllers/bearerKeyController.js';
-import {
-  getOAuthSsoConfig,
-  initiateOAuthLogin,
-  handleOAuthCallback as handleOAuthSsoCallback,
-  listOAuthProviders,
-} from '../controllers/oauthSsoController.js';
 import { auth } from '../middlewares/auth.js';

 const router = express.Router();
@@ -279,11 +278,10 @@ export const initRoutes = (app: express.Application): void => {
    changePassword,
  );

-  // OAuth SSO routes (no auth required - these are for logging in)
-  router.get('/auth/sso/config', getOAuthSsoConfig);
-  router.get('/auth/sso/providers', listOAuthProviders);
-  router.get('/auth/sso/:providerId', initiateOAuthLogin);
-  router.get('/auth/sso/:providerId/callback', handleOAuthSsoCallback);
+  // OAuth SSO routes (no auth required - public endpoints)
+  router.get('/auth/sso/config', getSSOConfig); // Get SSO configuration for frontend
+  router.get('/auth/sso/:provider', initiateSSOLogin); // Initiate SSO login
+  router.get('/auth/sso/:provider/callback', handleSSOCallback); // Handle OAuth callback

  // Runtime configuration endpoint (no auth required for frontend initialization)
  app.get(`${config.basePath}/config`, getRuntimeConfig);
--- a/src/services/oauthSSOService.ts
+++ b/src/services/oauthSSOService.ts
@@ -0,0 +1,600 @@
+import jwt from 'jsonwebtoken';
+import crypto from 'crypto';
+import { loadSettings } from '../config/index.js';
+import { JWT_SECRET } from '../config/jwt.js';
+import { OAuthSSOConfig, OAuthSSOProvider, IUser, IOAuthLink } from '../types/index.js';
+import { getUserDao } from '../dao/index.js';
+import { getDataService } from './services.js';
+
+// Built-in provider configurations for Google, GitHub, Microsoft
+const BUILTIN_PROVIDERS: Record<string, Omit<OAuthSSOProvider, 'clientId' | 'clientSecret' | 'id' | 'name'>> = {
+  google: {
+    type: 'google',
+    issuerUrl: 'https://accounts.google.com',
+    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+    scopes: ['openid', 'email', 'profile'],
+    attributeMapping: {
+      username: 'email',
+      email: 'email',
+      name: 'name',
+    },
+  },
+  github: {
+    type: 'github',
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    userInfoUrl: 'https://api.github.com/user',
+    scopes: ['read:user', 'user:email'],
+    attributeMapping: {
+      username: 'login',
+      email: 'email',
+      name: 'name',
+    },
+  },
+  microsoft: {
+    type: 'microsoft',
+    issuerUrl: 'https://login.microsoftonline.com/common/v2.0',
+    authorizationUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+    tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    userInfoUrl: 'https://graph.microsoft.com/oidc/userinfo',
+    scopes: ['openid', 'email', 'profile'],
+    attributeMapping: {
+      username: 'email',
+      email: 'email',
+      name: 'name',
+    },
+  },
+};
+
+// In-memory store for OAuth state (should be replaced with Redis/DB in production)
+const pendingStates = new Map<string, { provider: string; expiresAt: number; codeVerifier?: string }>();
+
+// JWT token expiry for SSO logins
+const TOKEN_EXPIRY = '24h';
+
+/**
+ * Get OAuth SSO configuration from settings
+ */
+export function getOAuthSSOConfig(): OAuthSSOConfig | undefined {
+  const settings = loadSettings();
+  return settings.systemConfig?.oauthSSO;
+}
+
+/**
+ * Check if OAuth SSO is enabled
+ */
+export function isOAuthSSOEnabled(): boolean {
+  const config = getOAuthSSOConfig();
+  return config?.enabled === true && (config.providers?.length ?? 0) > 0;
+}
+
+/**
+ * Check if local authentication is allowed alongside SSO
+ */
+export function isLocalAuthAllowed(): boolean {
+  const config = getOAuthSSOConfig();
+  // Default to true - allow local auth unless explicitly disabled
+  return config?.allowLocalAuth !== false;
+}
+
+/**
+ * Get list of enabled SSO providers for frontend display
+ */
+export function getEnabledProviders(): Array<{ id: string; name: string; type: string }> {
+  const config = getOAuthSSOConfig();
+  if (!config?.enabled || !config.providers) {
+    return [];
+  }
+
+  return config.providers
+    .filter((p) => p.enabled !== false)
+    .map((p) => ({
+      id: p.id,
+      name: p.name,
+      type: p.type,
+    }));
+}
+
+/**
+ * Get provider configuration by ID
+ */
+export function getProviderById(providerId: string): OAuthSSOProvider | undefined {
+  const config = getOAuthSSOConfig();
+  if (!config?.enabled || !config.providers) {
+    return undefined;
+  }
+
+  return config.providers.find((p) => p.id === providerId && p.enabled !== false);
+}
+
+/**
+ * Generate PKCE code verifier and challenge
+ */
+function generatePKCE(): { codeVerifier: string; codeChallenge: string } {
+  const codeVerifier = crypto.randomBytes(32).toString('base64url');
+  const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+  return { codeVerifier, codeChallenge };
+}
+
+/**
+ * Build the complete provider configuration (merge with built-in defaults)
+ */
+function buildProviderConfig(provider: OAuthSSOProvider): OAuthSSOProvider {
+  const builtin = BUILTIN_PROVIDERS[provider.type];
+  if (builtin && provider.type !== 'oidc') {
+    return {
+      ...builtin,
+      ...provider,
+      scopes: provider.scopes ?? builtin.scopes,
+      attributeMapping: { ...builtin.attributeMapping, ...provider.attributeMapping },
+    };
+  }
+  return provider;
+}
+
+/**
+ * Generate OAuth authorization URL for a provider
+ */
+export function generateAuthorizationUrl(
+  providerId: string,
+  redirectUri: string,
+): { url: string; state: string } | null {
+  const provider = getProviderById(providerId);
+  if (!provider) {
+    return null;
+  }
+
+  const config = buildProviderConfig(provider);
+  const authUrl = config.authorizationUrl;
+  if (!authUrl) {
+    console.error(`OAuth SSO: No authorization URL configured for provider ${providerId}`);
+    return null;
+  }
+
+  // Generate state and PKCE
+  const state = crypto.randomBytes(16).toString('hex');
+  const { codeVerifier, codeChallenge } = generatePKCE();
+
+  // Store state for validation (expires in 10 minutes)
+  pendingStates.set(state, {
+    provider: providerId,
+    expiresAt: Date.now() + 10 * 60 * 1000,
+    codeVerifier,
+  });
+
+  // Clean up expired states periodically
+  cleanupExpiredStates();
+
+  // Build authorization URL
+  const url = new URL(authUrl);
+  url.searchParams.set('client_id', config.clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('state', state);
+
+  // Add scopes
+  const scopes = config.scopes ?? ['openid', 'email', 'profile'];
+  url.searchParams.set('scope', scopes.join(' '));
+
+  // Add PKCE if not GitHub (GitHub doesn't support PKCE)
+  if (config.type !== 'github') {
+    url.searchParams.set('code_challenge', codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+  }
+
+  return { url: url.toString(), state };
+}
+
+/**
+ * Cleanup expired OAuth states
+ */
+function cleanupExpiredStates(): void {
+  const now = Date.now();
+  for (const [state, data] of pendingStates.entries()) {
+    if (data.expiresAt < now) {
+      pendingStates.delete(state);
+    }
+  }
+}
+
+/**
+ * Validate OAuth state and get stored data
+ */
+function validateState(state: string): { provider: string; codeVerifier?: string } | null {
+  const data = pendingStates.get(state);
+  if (!data) {
+    return null;
+  }
+
+  // Remove state to prevent replay
+  pendingStates.delete(state);
+
+  // Check expiration
+  if (data.expiresAt < Date.now()) {
+    return null;
+  }
+
+  return { provider: data.provider, codeVerifier: data.codeVerifier };
+}
+
+/**
+ * Exchange authorization code for tokens
+ */
+async function exchangeCodeForTokens(
+  provider: OAuthSSOProvider,
+  code: string,
+  redirectUri: string,
+  codeVerifier?: string,
+): Promise<{ accessToken: string; idToken?: string } | null> {
+  const config = buildProviderConfig(provider);
+  const tokenUrl = config.tokenUrl;
+  if (!tokenUrl) {
+    console.error(`OAuth SSO: No token URL configured for provider ${provider.id}`);
+    return null;
+  }
+
+  const params = new URLSearchParams();
+  params.set('grant_type', 'authorization_code');
+  params.set('code', code);
+  params.set('redirect_uri', redirectUri);
+  params.set('client_id', config.clientId);
+  params.set('client_secret', config.clientSecret);
+
+  // Add PKCE verifier if available (not for GitHub)
+  if (codeVerifier && config.type !== 'github') {
+    params.set('code_verifier', codeVerifier);
+  }
+
+  try {
+    const response = await fetch(tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body: params.toString(),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      console.error(`OAuth SSO: Token exchange failed for ${provider.id}:`, errorText);
+      return null;
+    }
+
+    const data = await response.json();
+    return {
+      accessToken: data.access_token,
+      idToken: data.id_token,
+    };
+  } catch (error) {
+    console.error(`OAuth SSO: Token exchange error for ${provider.id}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Get user info from the OAuth provider
+ */
+async function getUserInfo(
+  provider: OAuthSSOProvider,
+  accessToken: string,
+): Promise<Record<string, unknown> | null> {
+  const config = buildProviderConfig(provider);
+  const userInfoUrl = config.userInfoUrl;
+  if (!userInfoUrl) {
+    console.error(`OAuth SSO: No userinfo URL configured for provider ${provider.id}`);
+    return null;
+  }
+
+  try {
+    const response = await fetch(userInfoUrl, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      console.error(`OAuth SSO: UserInfo request failed for ${provider.id}:`, errorText);
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    console.error(`OAuth SSO: UserInfo error for ${provider.id}:`, error);
+    return null;
+  }
+}
+
+/**
+ * For GitHub, we need to make a separate request to get email if not public
+ */
+async function getGitHubEmail(accessToken: string): Promise<string | null> {
+  try {
+    const response = await fetch('https://api.github.com/user/emails', {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const emails = (await response.json()) as Array<{ email: string; primary: boolean; verified: boolean }>;
+    const primaryEmail = emails.find((e) => e.primary && e.verified);
+    return primaryEmail?.email ?? emails[0]?.email ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract user attributes from provider userinfo based on attribute mapping
+ */
+function extractUserAttributes(
+  provider: OAuthSSOProvider,
+  userInfo: Record<string, unknown>,
+): { providerId: string; username: string; email?: string; name?: string } {
+  const config = buildProviderConfig(provider);
+  const mapping = config.attributeMapping ?? {};
+
+  // Get provider user ID
+  let providerId: string;
+  if (provider.type === 'github') {
+    providerId = String(userInfo.id);
+  } else {
+    providerId = String(userInfo.sub ?? userInfo.id);
+  }
+
+  // Get username
+  const usernameField = mapping.username ?? 'email';
+  let username = String(userInfo[usernameField] ?? '');
+  if (!username && userInfo.email) {
+    username = String(userInfo.email);
+  }
+
+  // Get email
+  const emailField = mapping.email ?? 'email';
+  const email = userInfo[emailField] ? String(userInfo[emailField]) : undefined;
+
+  // Get display name
+  const nameField = mapping.name ?? 'name';
+  const name = userInfo[nameField] ? String(userInfo[nameField]) : undefined;
+
+  return { providerId, username, email, name };
+}
+
+/**
+ * Determine if user should be admin based on role mapping
+ */
+function determineAdminStatus(provider: OAuthSSOProvider, userInfo: Record<string, unknown>): boolean {
+  const config = buildProviderConfig(provider);
+  const roleMapping = config.roleMapping;
+
+  if (!roleMapping) {
+    return false;
+  }
+
+  // Check if admin claim is configured
+  if (roleMapping.adminClaim && roleMapping.adminValues?.length) {
+    const claimValue = userInfo[roleMapping.adminClaim];
+    if (claimValue) {
+      // Handle both single value and array claims
+      const values = Array.isArray(claimValue) ? claimValue : [claimValue];
+      for (const value of values) {
+        if (roleMapping.adminValues.includes(String(value))) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return roleMapping.defaultIsAdmin ?? false;
+}
+
+/**
+ * Handle OAuth callback - exchange code, get user info, create/update user, return JWT
+ */
+export async function handleOAuthCallback(
+  state: string,
+  code: string,
+  redirectUri: string,
+): Promise<{
+  success: boolean;
+  token?: string;
+  user?: { username: string; isAdmin: boolean; permissions?: string[] };
+  error?: string;
+}> {
+  // Validate state
+  const stateData = validateState(state);
+  if (!stateData) {
+    return { success: false, error: 'Invalid or expired OAuth state' };
+  }
+
+  // Get provider
+  const provider = getProviderById(stateData.provider);
+  if (!provider) {
+    return { success: false, error: 'OAuth provider not found or disabled' };
+  }
+
+  // Exchange code for tokens
+  const tokens = await exchangeCodeForTokens(provider, code, redirectUri, stateData.codeVerifier);
+  if (!tokens) {
+    return { success: false, error: 'Failed to exchange authorization code for tokens' };
+  }
+
+  // Get user info
+  let userInfo = await getUserInfo(provider, tokens.accessToken);
+  if (!userInfo) {
+    return { success: false, error: 'Failed to get user information from provider' };
+  }
+
+  // For GitHub, get email separately if not in userinfo
+  if (provider.type === 'github' && !userInfo.email) {
+    const email = await getGitHubEmail(tokens.accessToken);
+    if (email) {
+      userInfo = { ...userInfo, email };
+    }
+  }
+
+  // Extract user attributes
+  const { providerId, username, email, name } = extractUserAttributes(provider, userInfo);
+  if (!username) {
+    return { success: false, error: 'Could not determine username from OAuth provider' };
+  }
+
+  // Determine admin status
+  const isAdmin = determineAdminStatus(provider, userInfo);
+
+  // Find or create user
+  const userDao = getUserDao();
+  const config = buildProviderConfig(provider);
+
+  // First, try to find user by OAuth link
+  let user = await findUserByOAuthLink(provider.id, providerId);
+
+  if (!user) {
+    // Try to find by username (for linking existing accounts)
+    user = await userDao.findByUsername(username);
+
+    if (user) {
+      // Existing user found - link their account if allowed
+      if (config.allowLinking !== false) {
+        const oauthLink: IOAuthLink = {
+          provider: provider.id,
+          providerId,
+          email,
+          name,
+          linkedAt: new Date().toISOString(),
+        };
+        user = await linkOAuthAccount(user.username, oauthLink);
+      }
+    } else if (config.autoProvision !== false) {
+      // Auto-provision new user
+      try {
+        // Generate a random secure password (user won't need it with SSO)
+        const randomPassword = crypto.randomBytes(32).toString('hex');
+        user = await userDao.createWithHashedPassword(username, randomPassword, isAdmin);
+
+        // Link OAuth account
+        const oauthLink: IOAuthLink = {
+          provider: provider.id,
+          providerId,
+          email,
+          name,
+          linkedAt: new Date().toISOString(),
+        };
+        user = await linkOAuthAccount(username, oauthLink);
+
+        console.log(`OAuth SSO: Auto-provisioned user ${username} via ${provider.id}`);
+      } catch (error) {
+        console.error(`OAuth SSO: Failed to create user ${username}:`, error);
+        return { success: false, error: 'Failed to create user account' };
+      }
+    } else {
+      return { success: false, error: 'User account not found and auto-provisioning is disabled' };
+    }
+  }
+
+  if (!user) {
+    return { success: false, error: 'Failed to find or create user account' };
+  }
+
+  // Generate JWT token
+  const payload = {
+    user: {
+      username: user.username,
+      isAdmin: user.isAdmin || false,
+    },
+  };
+
+  return new Promise((resolve) => {
+    jwt.sign(payload, JWT_SECRET, { expiresIn: TOKEN_EXPIRY }, (err, token) => {
+      if (err || !token) {
+        console.error('OAuth SSO: Failed to generate JWT:', err);
+        resolve({ success: false, error: 'Failed to generate authentication token' });
+        return;
+      }
+
+      const dataService = getDataService();
+      resolve({
+        success: true,
+        token,
+        user: {
+          username: user!.username,
+          isAdmin: user!.isAdmin || false,
+          permissions: dataService.getPermissions(user!),
+        },
+      });
+    });
+  });
+}
+
+/**
+ * Find user by OAuth link
+ */
+async function findUserByOAuthLink(providerId: string, providerUserId: string): Promise<IUser | null> {
+  const userDao = getUserDao();
+  const users = await userDao.findAll();
+
+  for (const user of users) {
+    if (user.oauthLinks?.some((link) => link.provider === providerId && link.providerId === providerUserId)) {
+      return user;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Link OAuth account to existing user
+ */
+async function linkOAuthAccount(username: string, oauthLink: IOAuthLink): Promise<IUser | null> {
+  const userDao = getUserDao();
+  const user = await userDao.findByUsername(username);
+
+  if (!user) {
+    return null;
+  }
+
+  // Add or update OAuth link
+  const existingLinks = user.oauthLinks ?? [];
+  const linkIndex = existingLinks.findIndex((l) => l.provider === oauthLink.provider);
+
+  if (linkIndex >= 0) {
+    existingLinks[linkIndex] = oauthLink;
+  } else {
+    existingLinks.push(oauthLink);
+  }
+
+  return await userDao.update(username, { oauthLinks: existingLinks });
+}
+
+/**
+ * Unlink OAuth account from user
+ */
+export async function unlinkOAuthAccount(username: string, providerId: string): Promise<IUser | null> {
+  const userDao = getUserDao();
+  const user = await userDao.findByUsername(username);
+
+  if (!user || !user.oauthLinks) {
+    return null;
+  }
+
+  const updatedLinks = user.oauthLinks.filter((l) => l.provider !== providerId);
+  return await userDao.update(username, { oauthLinks: updatedLinks });
+}
+
+/**
+ * Get OAuth links for a user
+ */
+export async function getUserOAuthLinks(username: string): Promise<IOAuthLink[]> {
+  const userDao = getUserDao();
+  const user = await userDao.findByUsername(username);
+  return user?.oauthLinks ?? [];
+}
--- a/src/services/oauthSsoService.ts
+++ b/src/services/oauthSsoService.ts
@@ -1,546 +0,0 @@
-/**
- * OAuth SSO Service
- *
- * Handles OAuth 2.0 / OIDC SSO authentication for user login.
- * Supports Google, Microsoft, GitHub, and custom OIDC providers.
- */
-
-import * as client from 'openid-client';
-import crypto from 'crypto';
-import { getSystemConfigDao, getUserDao } from '../dao/index.js';
-import { IUser, OAuthSsoProviderConfig, OAuthSsoConfig } from '../types/index.js';
-
-// In-memory store for OAuth state (code verifier, state, etc.)
-// NOTE: This implementation uses in-memory storage which is suitable for single-instance deployments.
-// For multi-instance/scaled deployments, implement Redis or database-backed state storage
-// to ensure OAuth callbacks reach the correct instance where the state was stored.
-interface OAuthStateEntry {
-  codeVerifier: string;
-  providerId: string;
-  returnUrl?: string;
-  createdAt: number;
-}
-
-const stateStore = new Map<string, OAuthStateEntry>();
-const STATE_TTL_MS = 10 * 60 * 1000; // 10 minutes
-
-// Cleanup old state entries periodically
-let cleanupInterval: ReturnType<typeof setInterval> | null = null;
-
-function startStateCleanup(): void {
-  if (cleanupInterval) return;
-  cleanupInterval = setInterval(() => {
-    const now = Date.now();
-    for (const [state, entry] of stateStore.entries()) {
-      if (now - entry.createdAt > STATE_TTL_MS) {
-        stateStore.delete(state);
-      }
-    }
-  }, 60 * 1000); // Cleanup every minute
-}
-
-// Start cleanup on module load
-startStateCleanup();
-
-/**
- * Stop the state cleanup interval (useful for tests and graceful shutdown)
- */
-export function stopStateCleanup(): void {
-  if (cleanupInterval) {
-    clearInterval(cleanupInterval);
-    cleanupInterval = null;
-  }
-}
-
-// GitHub API response types for type safety
-interface GitHubUserResponse {
-  id: number;
-  login: string;
-  name?: string;
-  email?: string;
-  avatar_url?: string;
-}
-
-interface GitHubEmailResponse {
-  email: string;
-  primary: boolean;
-  verified: boolean;
-  visibility?: string;
-}
-
-// Provider configurations cache
-const providerConfigsCache = new Map<
-  string,
-  {
-    config: client.Configuration;
-    provider: OAuthSsoProviderConfig;
-  }
->();
-
-/**
- * Get OAuth SSO configuration from system config
- */
-export async function getOAuthSsoConfig(): Promise<OAuthSsoConfig | undefined> {
-  const systemConfigDao = getSystemConfigDao();
-  const systemConfig = await systemConfigDao.get();
-  return systemConfig?.oauthSso;
-}
-
-/**
- * Check if OAuth SSO is enabled
- */
-export async function isOAuthSsoEnabled(): Promise<boolean> {
-  const config = await getOAuthSsoConfig();
-  return config?.enabled === true && (config.providers?.length ?? 0) > 0;
-}
-
-/**
- * Get enabled OAuth SSO providers
- */
-export async function getEnabledProviders(): Promise<OAuthSsoProviderConfig[]> {
-  const config = await getOAuthSsoConfig();
-  if (!config?.enabled || !config.providers) {
-    return [];
-  }
-  return config.providers.filter((p) => p.enabled !== false);
-}
-
-/**
- * Get a specific provider by ID
- */
-export async function getProviderById(providerId: string): Promise<OAuthSsoProviderConfig | undefined> {
-  const providers = await getEnabledProviders();
-  return providers.find((p) => p.id === providerId);
-}
-
-/**
- * Get default scopes for a provider type
- */
-function getDefaultScopes(type: OAuthSsoProviderConfig['type']): string[] {
-  switch (type) {
-    case 'google':
-      return ['openid', 'email', 'profile'];
-    case 'microsoft':
-      return ['openid', 'email', 'profile', 'User.Read'];
-    case 'github':
-      return ['read:user', 'user:email'];
-    case 'oidc':
-    default:
-      return ['openid', 'email', 'profile'];
-  }
-}
-
-/**
- * Get provider discovery URL
- */
-function getDiscoveryUrl(provider: OAuthSsoProviderConfig): string | undefined {
-  if (provider.issuerUrl) {
-    return provider.issuerUrl;
-  }
-
-  switch (provider.type) {
-    case 'google':
-      return 'https://accounts.google.com';
-    case 'microsoft':
-      // Using common endpoint for multi-tenant
-      return 'https://login.microsoftonline.com/common/v2.0';
-    case 'github':
-      // GitHub doesn't support OIDC discovery, we'll use explicit endpoints
-      return undefined;
-    default:
-      return undefined;
-  }
-}
-
-/**
- * Get explicit OAuth endpoints for providers without OIDC discovery
- */
-function getExplicitEndpoints(provider: OAuthSsoProviderConfig): {
-  authorizationUrl: string;
-  tokenUrl: string;
-  userInfoUrl: string;
-} | undefined {
-  if (provider.type === 'github') {
-    return {
-      authorizationUrl: provider.authorizationUrl || 'https://github.com/login/oauth/authorize',
-      tokenUrl: provider.tokenUrl || 'https://github.com/login/oauth/access_token',
-      userInfoUrl: provider.userInfoUrl || 'https://api.github.com/user',
-    };
-  }
-
-  // For custom providers with explicit endpoints
-  if (provider.authorizationUrl && provider.tokenUrl && provider.userInfoUrl) {
-    return {
-      authorizationUrl: provider.authorizationUrl,
-      tokenUrl: provider.tokenUrl,
-      userInfoUrl: provider.userInfoUrl,
-    };
-  }
-
-  return undefined;
-}
-
-/**
- * Initialize and cache openid-client configuration for a provider
- */
-async function getClientConfig(
-  provider: OAuthSsoProviderConfig,
-  _callbackUrl: string,
-): Promise<client.Configuration> {
-  const cacheKey = provider.id;
-  const cached = providerConfigsCache.get(cacheKey);
-  if (cached) {
-    return cached.config;
-  }
-
-  let config: client.Configuration;
-
-  const discoveryUrl = getDiscoveryUrl(provider);
-
-  if (discoveryUrl) {
-    // Use OIDC discovery
-    config = await client.discovery(new URL(discoveryUrl), provider.clientId, provider.clientSecret);
-  } else {
-    // Use explicit endpoints for providers like GitHub
-    const endpoints = getExplicitEndpoints(provider);
-    if (!endpoints) {
-      throw new Error(
-        `Provider ${provider.id} requires either issuerUrl for OIDC discovery or explicit endpoints`,
-      );
-    }
-
-    // Create a manual server metadata configuration
-    const serverMetadata: client.ServerMetadata = {
-      issuer: provider.issuerUrl || `https://${provider.type}.oauth`,
-      authorization_endpoint: endpoints.authorizationUrl,
-      token_endpoint: endpoints.tokenUrl,
-      userinfo_endpoint: endpoints.userInfoUrl,
-    };
-
-    config = new client.Configuration(serverMetadata, provider.clientId, provider.clientSecret);
-  }
-
-  providerConfigsCache.set(cacheKey, { config, provider });
-  return config;
-}
-
-/**
- * Generate the authorization URL for a provider
- */
-export async function generateAuthorizationUrl(
-  providerId: string,
-  callbackUrl: string,
-  returnUrl?: string,
-): Promise<{ url: string; state: string }> {
-  const provider = await getProviderById(providerId);
-  if (!provider) {
-    throw new Error(`OAuth SSO provider not found: ${providerId}`);
-  }
-
-  const config = await getClientConfig(provider, callbackUrl);
-  const scopes = provider.scopes || getDefaultScopes(provider.type);
-
-  // Generate PKCE code verifier and challenge
-  const codeVerifier = client.randomPKCECodeVerifier();
-  const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);
-
-  // Generate state
-  const state = crypto.randomBytes(32).toString('base64url');
-
-  // Store state for callback verification
-  stateStore.set(state, {
-    codeVerifier,
-    providerId,
-    returnUrl,
-    createdAt: Date.now(),
-  });
-
-  // Build authorization URL parameters
-  const parameters: Record<string, string> = {
-    redirect_uri: callbackUrl,
-    scope: scopes.join(' '),
-    state,
-    code_challenge: codeChallenge,
-    code_challenge_method: 'S256',
-  };
-
-  // GitHub-specific: request user email access
-  if (provider.type === 'github') {
-    // GitHub doesn't use PKCE, but we'll still store the state
-    delete parameters.code_challenge;
-    delete parameters.code_challenge_method;
-  }
-
-  const url = client.buildAuthorizationUrl(config, parameters);
-
-  return { url: url.toString(), state };
-}
-
-/**
- * Exchange authorization code for tokens and user info
- */
-export async function handleCallback(
-  callbackUrl: string,
-  currentUrl: string,
-  state: string,
-): Promise<{
-  user: IUser;
-  isNewUser: boolean;
-  returnUrl?: string;
-}> {
-  // Verify and retrieve state
-  const stateEntry = stateStore.get(state);
-  if (!stateEntry) {
-    throw new Error('Invalid or expired OAuth state');
-  }
-
-  // Remove used state
-  stateStore.delete(state);
-
-  const provider = await getProviderById(stateEntry.providerId);
-  if (!provider) {
-    throw new Error(`OAuth SSO provider not found: ${stateEntry.providerId}`);
-  }
-
-  const config = await getClientConfig(provider, callbackUrl);
-
-  // Exchange code for tokens
-  let tokens: client.TokenEndpointResponse;
-
-  if (provider.type === 'github') {
-    // GitHub doesn't use PKCE
-    tokens = await client.authorizationCodeGrant(config, new URL(currentUrl), {
-      expectedState: state,
-    });
-  } else {
-    // OIDC providers with PKCE
-    tokens = await client.authorizationCodeGrant(config, new URL(currentUrl), {
-      pkceCodeVerifier: stateEntry.codeVerifier,
-      expectedState: state,
-    });
-  }
-
-  // Get user info
-  const userInfo = await getUserInfo(provider, config, tokens);
-
-  // Find or create user
-  const { user, isNewUser } = await findOrCreateUser(provider, userInfo);
-
-  return {
-    user,
-    isNewUser,
-    returnUrl: stateEntry.returnUrl,
-  };
-}
-
-/**
- * Fetch user info from the provider
- */
-async function getUserInfo(
-  provider: OAuthSsoProviderConfig,
-  config: client.Configuration,
-  tokens: client.TokenEndpointResponse,
-): Promise<{
-  sub: string;
-  email?: string;
-  name?: string;
-  picture?: string;
-  groups?: string[];
-  roles?: string[];
-  [key: string]: unknown;
-}> {
-  if (provider.type === 'github') {
-    // GitHub uses a different API for user info
-    const response = await fetch('https://api.github.com/user', {
-      headers: {
-        Authorization: `Bearer ${tokens.access_token}`,
-        Accept: 'application/json',
-      },
-    });
-
-    if (!response.ok) {
-      throw new Error(`Failed to fetch GitHub user info: ${response.statusText}`);
-    }
-
-    const data = (await response.json()) as GitHubUserResponse;
-
-    // Fetch email separately if not public
-    let email = data.email;
-    if (!email) {
-      const emailResponse = await fetch('https://api.github.com/user/emails', {
-        headers: {
-          Authorization: `Bearer ${tokens.access_token}`,
-          Accept: 'application/json',
-        },
-      });
-
-      if (emailResponse.ok) {
-        const emails = (await emailResponse.json()) as GitHubEmailResponse[];
-        const primaryEmail = emails.find((e) => e.primary);
-        email = primaryEmail?.email || emails[0]?.email;
-      }
-    }
-
-    return {
-      sub: String(data.id),
-      email,
-      name: data.name || data.login,
-      picture: data.avatar_url,
-    };
-  }
-
-  // Standard OIDC userinfo endpoint
-  const userInfoResponse = await client.fetchUserInfo(config, tokens.access_token!, client.skipSubjectCheck);
-
-  return {
-    sub: userInfoResponse.sub,
-    email: userInfoResponse.email as string | undefined,
-    name: userInfoResponse.name as string | undefined,
-    picture: userInfoResponse.picture as string | undefined,
-    groups: userInfoResponse.groups as string[] | undefined,
-    roles: userInfoResponse.roles as string[] | undefined,
-  };
-}
-
-/**
- * Find existing user or create new one based on OAuth profile
- */
-async function findOrCreateUser(
-  provider: OAuthSsoProviderConfig,
-  userInfo: {
-    sub: string;
-    email?: string;
-    name?: string;
-    picture?: string;
-    groups?: string[];
-    roles?: string[];
-    [key: string]: unknown;
-  },
-): Promise<{ user: IUser; isNewUser: boolean }> {
-  const userDao = getUserDao();
-
-  // Generate a unique username based on provider and subject
-  const oauthUsername = `${provider.id}:${userInfo.sub}`;
-
-  // Try to find existing user by OAuth identity
-  let user = await userDao.findByUsername(oauthUsername);
-
-  if (user) {
-    // Update user info if changed
-    const updates: Partial<IUser> = {};
-    if (userInfo.email && userInfo.email !== user.email) {
-      updates.email = userInfo.email;
-    }
-    if (userInfo.name && userInfo.name !== user.displayName) {
-      updates.displayName = userInfo.name;
-    }
-    if (userInfo.picture && userInfo.picture !== user.avatarUrl) {
-      updates.avatarUrl = userInfo.picture;
-    }
-
-    // Check admin status based on claims
-    const isAdmin = checkAdminClaim(provider, userInfo);
-    if (isAdmin !== user.isAdmin) {
-      updates.isAdmin = isAdmin;
-    }
-
-    if (Object.keys(updates).length > 0) {
-      await userDao.update(oauthUsername, updates);
-      user = { ...user, ...updates };
-    }
-
-    return { user, isNewUser: false };
-  }
-
-  // Check if auto-provisioning is enabled
-  if (provider.autoProvision === false) {
-    throw new Error(
-      `User not found and auto-provisioning is disabled for provider: ${provider.name}`,
-    );
-  }
-
-  // Create new user
-  const isAdmin = checkAdminClaim(provider, userInfo) || provider.defaultAdmin === true;
-
-  // Generate a random password for OAuth users (they won't use it)
-  const randomPassword = crypto.randomBytes(32).toString('hex');
-
-  const newUser = await userDao.createWithHashedPassword(oauthUsername, randomPassword, isAdmin);
-
-  // Update with OAuth-specific fields
-  const updatedUser = await userDao.update(oauthUsername, {
-    oauthProvider: provider.id,
-    oauthSubject: userInfo.sub,
-    email: userInfo.email,
-    displayName: userInfo.name,
-    avatarUrl: userInfo.picture,
-  });
-
-  return { user: updatedUser || newUser, isNewUser: true };
-}
-
-/**
- * Check if user should be granted admin based on provider claims
- */
-function checkAdminClaim(
-  provider: OAuthSsoProviderConfig,
-  userInfo: { groups?: string[]; roles?: string[]; [key: string]: unknown },
-): boolean {
-  if (!provider.adminClaim || !provider.adminClaimValues?.length) {
-    return false;
-  }
-
-  const claimValue = userInfo[provider.adminClaim];
-  if (!claimValue) {
-    return false;
-  }
-
-  // Handle array claims (groups, roles)
-  if (Array.isArray(claimValue)) {
-    return claimValue.some((v) => provider.adminClaimValues!.includes(String(v)));
-  }
-
-  // Handle string claims
-  return provider.adminClaimValues.includes(String(claimValue));
-}
-
-/**
- * Get public provider info for frontend
- */
-export async function getPublicProviderInfo(): Promise<
-  Array<{
-    id: string;
-    name: string;
-    type: string;
-    icon?: string;
-    buttonText?: string;
-  }>
-> {
-  const providers = await getEnabledProviders();
-  return providers.map((p) => ({
-    id: p.id,
-    name: p.name,
-    type: p.type,
-    icon: p.icon || p.type,
-    buttonText: p.buttonText,
-  }));
-}
-
-/**
- * Check if local auth is allowed
- */
-export async function isLocalAuthAllowed(): Promise<boolean> {
-  const config = await getOAuthSsoConfig();
-  // Default to true if not configured or SSO is disabled
-  if (!config?.enabled) {
-    return true;
-  }
-  return config.allowLocalAuth !== false;
-}
-
-/**
- * Clear provider configuration cache
- */
-export function clearProviderCache(): void {
-  providerConfigsCache.clear();
-}
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -5,17 +5,21 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { SmartRoutingConfig } from '../utils/smartRouting.js';

+// OAuth SSO linked account information
+export interface IOAuthLink {
+  provider: string; // Provider ID (e.g., 'google', 'github', 'microsoft', or custom OIDC provider name)
+  providerId: string; // User ID from the OAuth provider
+  email?: string; // Email from the OAuth provider
+  name?: string; // Display name from the OAuth provider
+  linkedAt?: string; // ISO timestamp when the account was linked
+}
+
 // User interface
 export interface IUser {
  username: string;
  password: string;
  isAdmin?: boolean;
-  // OAuth SSO fields
-  oauthProvider?: string; // OAuth provider ID (e.g., 'google', 'microsoft', 'github')
-  oauthSubject?: string; // OAuth subject (unique user ID from provider)
-  email?: string; // User email (from OAuth profile)
-  displayName?: string; // Display name (from OAuth profile)
-  avatarUrl?: string; // Avatar URL (from OAuth profile)
+  oauthLinks?: IOAuthLink[]; // Linked OAuth accounts for SSO
 }

 // Group interface for server grouping
@@ -130,43 +134,6 @@ export interface MCPRouterCallToolResponse {
  isError: boolean;
 }

-// OAuth SSO Provider Configuration for user authentication
-export type OAuthSsoProviderType = 'google' | 'microsoft' | 'github' | 'oidc';
-
-export interface OAuthSsoProviderConfig {
-  id: string; // Unique identifier for this provider (e.g., 'google', 'my-company-sso')
-  type: OAuthSsoProviderType; // Provider type
-  name: string; // Display name (e.g., 'Google', 'Microsoft', 'Company SSO')
-  enabled?: boolean; // Whether this provider is enabled (default: true)
-  clientId: string; // OAuth client ID
-  clientSecret: string; // OAuth client secret
-  // For OIDC providers, discovery URL or explicit endpoints
-  issuerUrl?: string; // OIDC issuer URL for auto-discovery (e.g., 'https://accounts.google.com')
-  // Explicit endpoints (optional, can be auto-discovered for OIDC)
-  authorizationUrl?: string; // OAuth authorization endpoint
-  tokenUrl?: string; // OAuth token endpoint
-  userInfoUrl?: string; // OAuth userinfo endpoint
-  // Scope configuration
-  scopes?: string[]; // OAuth scopes to request (default varies by provider)
-  // Role/admin mapping
-  adminClaim?: string; // Claim name to check for admin role (e.g., 'groups', 'roles')
-  adminClaimValues?: string[]; // Values that grant admin access (e.g., ['admin', 'mcphub-admins'])
-  // Auto-provisioning options
-  autoProvision?: boolean; // Auto-create users on first login (default: true)
-  defaultAdmin?: boolean; // Whether auto-provisioned users are admins by default (default: false)
-  // UI options
-  icon?: string; // Icon identifier for UI (e.g., 'google', 'microsoft', 'github', 'key')
-  buttonText?: string; // Custom button text (e.g., 'Sign in with Google')
-}
-
-// OAuth SSO configuration in SystemConfig
-export interface OAuthSsoConfig {
-  enabled?: boolean; // Enable/disable OAuth SSO globally
-  providers?: OAuthSsoProviderConfig[]; // List of configured SSO providers
-  allowLocalAuth?: boolean; // Allow local username/password auth alongside SSO (default: true)
-  callbackBaseUrl?: string; // Base URL for OAuth callbacks (auto-detected if not set)
-}
-
 // OAuth Provider Configuration for MCP Authorization Server
 export interface OAuthProviderConfig {
  enabled?: boolean; // Enable/disable OAuth provider
@@ -192,6 +159,55 @@ export interface OAuthProviderConfig {
  }>;
 }

+// OAuth SSO Provider Configuration for external identity providers (Google, Microsoft, GitHub, custom OIDC)
+export interface OAuthSSOProvider {
+  id: string; // Unique identifier for this provider (e.g., 'google', 'github', 'microsoft', 'custom-oidc')
+  name: string; // Display name shown on login page (e.g., 'Google', 'GitHub')
+  enabled?: boolean; // Enable/disable this provider (default: true)
+  type: 'google' | 'github' | 'microsoft' | 'oidc'; // Provider type for built-in or custom OIDC
+
+  // OAuth/OIDC endpoints (required for 'oidc' type, auto-discovered for built-in types)
+  issuerUrl?: string; // OIDC issuer URL for discovery (e.g., 'https://accounts.google.com')
+  authorizationUrl?: string; // OAuth authorization endpoint
+  tokenUrl?: string; // OAuth token endpoint
+  userInfoUrl?: string; // OIDC userinfo endpoint
+
+  // Client credentials
+  clientId: string; // OAuth client ID from the provider
+  clientSecret: string; // OAuth client secret from the provider
+
+  // Scope configuration
+  scopes?: string[]; // Scopes to request (default: ['openid', 'email', 'profile'])
+
+  // Role/admin mapping configuration
+  roleMapping?: {
+    // Map provider claims/groups to MCPHub admin role
+    adminClaim?: string; // Claim name to check for admin status (e.g., 'groups', 'roles')
+    adminValues?: string[]; // Values that grant admin access (e.g., ['admin', 'mcphub-admin'])
+    // Default role for new users (if not matched by adminValues)
+    defaultIsAdmin?: boolean; // Default admin status for auto-provisioned users (default: false)
+  };
+
+  // User attribute mapping (for custom OIDC providers)
+  attributeMapping?: {
+    username?: string; // Claim to use as username (default: 'email' or 'preferred_username')
+    email?: string; // Claim to use as email (default: 'email')
+    name?: string; // Claim to use as display name (default: 'name')
+  };
+
+  // Auto-provisioning settings
+  autoProvision?: boolean; // Auto-create users on first SSO login (default: true)
+  allowLinking?: boolean; // Allow existing users to link their accounts (default: true)
+}
+
+// OAuth SSO Configuration (stored in systemConfig.oauthSSO)
+export interface OAuthSSOConfig {
+  enabled?: boolean; // Enable/disable SSO functionality globally (default: false)
+  providers?: OAuthSSOProvider[]; // Array of configured SSO providers
+  callbackBaseUrl?: string; // Base URL for OAuth callbacks (auto-detected if not set)
+  allowLocalAuth?: boolean; // Allow local username/password auth alongside SSO (default: true)
+}
+
 export interface SystemConfig {
  routing?: {
    enableGlobalRoute?: boolean; // Controls whether the /sse endpoint without group is enabled
@@ -215,7 +231,7 @@ export interface SystemConfig {
  nameSeparator?: string; // Separator used between server name and tool/prompt name (default: '-')
  oauth?: OAuthProviderConfig; // OAuth provider configuration for upstream MCP servers
  oauthServer?: OAuthServerConfig; // OAuth authorization server configuration for MCPHub itself
-  oauthSso?: OAuthSsoConfig; // OAuth SSO configuration for user authentication
+  oauthSSO?: OAuthSSOConfig; // OAuth SSO configuration for external identity providers (Google, Microsoft, GitHub, OIDC)
  enableSessionRebuild?: boolean; // Controls whether server session rebuild is enabled
 }

--- a/src/utils/migration.ts
+++ b/src/utils/migration.ts
@@ -46,11 +46,7 @@ export async function migrateToDatabase(): Promise<boolean> {
            username: user.username,
            password: user.password,
            isAdmin: user.isAdmin || false,
-            oauthProvider: user.oauthProvider,
-            oauthSubject: user.oauthSubject,
-            email: user.email,
-            displayName: user.displayName,
-            avatarUrl: user.avatarUrl,
+            oauthLinks: user.oauthLinks ?? null,
          });
          console.log(`  - Created user: ${user.username}`);
        } else {
@@ -121,7 +117,6 @@ export async function migrateToDatabase(): Promise<boolean> {
        nameSeparator: settings.systemConfig.nameSeparator,
        oauth: settings.systemConfig.oauth || {},
        oauthServer: settings.systemConfig.oauthServer || {},
-        oauthSso: settings.systemConfig.oauthSso || {},
        enableSessionRebuild: settings.systemConfig.enableSessionRebuild,
      };
      await systemConfigRepo.update(systemConfig);
--- a/tests/services/oauthSSOService.test.ts
+++ b/tests/services/oauthSSOService.test.ts
@@ -0,0 +1,393 @@
+// Tests for OAuth SSO Service
+
+import {
+  isOAuthSSOEnabled,
+  isLocalAuthAllowed,
+  getEnabledProviders,
+  getProviderById,
+  generateAuthorizationUrl,
+} from '../../src/services/oauthSSOService.js';
+
+// Mock the config loading
+jest.mock('../../src/config/index.js', () => ({
+  loadSettings: jest.fn(),
+}));
+
+import { loadSettings } from '../../src/config/index.js';
+
+const mockLoadSettings = loadSettings as jest.MockedFunction<typeof loadSettings>;
+
+describe('OAuth SSO Service', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('isOAuthSSOEnabled', () => {
+    it('should return false when oauthSSO is not configured', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {},
+      });
+
+      expect(isOAuthSSOEnabled()).toBe(false);
+    });
+
+    it('should return false when oauthSSO.enabled is false', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: false,
+            providers: [
+              {
+                id: 'google',
+                name: 'Google',
+                type: 'google',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+              },
+            ],
+          },
+        },
+      });
+
+      expect(isOAuthSSOEnabled()).toBe(false);
+    });
+
+    it('should return false when no providers are configured', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [],
+          },
+        },
+      });
+
+      expect(isOAuthSSOEnabled()).toBe(false);
+    });
+
+    it('should return true when enabled and providers exist', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [
+              {
+                id: 'google',
+                name: 'Google',
+                type: 'google',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+              },
+            ],
+          },
+        },
+      });
+
+      expect(isOAuthSSOEnabled()).toBe(true);
+    });
+  });
+
+  describe('isLocalAuthAllowed', () => {
+    it('should return true by default when not configured', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {},
+      });
+
+      expect(isLocalAuthAllowed()).toBe(true);
+    });
+
+    it('should return true when allowLocalAuth is not explicitly set', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [],
+          },
+        },
+      });
+
+      expect(isLocalAuthAllowed()).toBe(true);
+    });
+
+    it('should return false when allowLocalAuth is false', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            allowLocalAuth: false,
+            providers: [],
+          },
+        },
+      });
+
+      expect(isLocalAuthAllowed()).toBe(false);
+    });
+
+    it('should return true when allowLocalAuth is true', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            allowLocalAuth: true,
+            providers: [],
+          },
+        },
+      });
+
+      expect(isLocalAuthAllowed()).toBe(true);
+    });
+  });
+
+  describe('getEnabledProviders', () => {
+    it('should return empty array when SSO is not enabled', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {},
+      });
+
+      expect(getEnabledProviders()).toEqual([]);
+    });
+
+    it('should return only enabled providers', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [
+              {
+                id: 'google',
+                name: 'Google',
+                type: 'google',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+                enabled: true,
+              },
+              {
+                id: 'github',
+                name: 'GitHub',
+                type: 'github',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+                enabled: false,
+              },
+              {
+                id: 'microsoft',
+                name: 'Microsoft',
+                type: 'microsoft',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+                // enabled is undefined, defaults to true
+              },
+            ],
+          },
+        },
+      });
+
+      const providers = getEnabledProviders();
+      expect(providers).toHaveLength(2);
+      expect(providers[0]).toEqual({ id: 'google', name: 'Google', type: 'google' });
+      expect(providers[1]).toEqual({ id: 'microsoft', name: 'Microsoft', type: 'microsoft' });
+    });
+  });
+
+  describe('getProviderById', () => {
+    it('should return undefined when provider not found', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [
+              {
+                id: 'google',
+                name: 'Google',
+                type: 'google',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+              },
+            ],
+          },
+        },
+      });
+
+      expect(getProviderById('github')).toBeUndefined();
+    });
+
+    it('should return undefined when provider is disabled', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [
+              {
+                id: 'google',
+                name: 'Google',
+                type: 'google',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+                enabled: false,
+              },
+            ],
+          },
+        },
+      });
+
+      expect(getProviderById('google')).toBeUndefined();
+    });
+
+    it('should return provider when found and enabled', () => {
+      const provider = {
+        id: 'google',
+        name: 'Google',
+        type: 'google' as const,
+        clientId: 'test-client-id',
+        clientSecret: 'test-client-secret',
+      };
+
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [provider],
+          },
+        },
+      });
+
+      expect(getProviderById('google')).toEqual(provider);
+    });
+  });
+
+  describe('generateAuthorizationUrl', () => {
+    it('should return null when provider not found', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [],
+          },
+        },
+      });
+
+      expect(generateAuthorizationUrl('google', 'http://localhost/callback')).toBeNull();
+    });
+
+    it('should generate authorization URL for Google provider', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [
+              {
+                id: 'google',
+                name: 'Google',
+                type: 'google',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+              },
+            ],
+          },
+        },
+      });
+
+      const result = generateAuthorizationUrl('google', 'http://localhost/callback');
+      expect(result).not.toBeNull();
+      expect(result!.url).toContain('https://accounts.google.com/o/oauth2/v2/auth');
+      expect(result!.url).toContain('client_id=test-client-id');
+      expect(result!.url).toContain('redirect_uri=http%3A%2F%2Flocalhost%2Fcallback');
+      expect(result!.url).toContain('response_type=code');
+      expect(result!.url).toContain('scope=openid+email+profile');
+      expect(result!.url).toContain('code_challenge=');
+      expect(result!.state).toBeDefined();
+    });
+
+    it('should generate authorization URL for GitHub provider without PKCE', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [
+              {
+                id: 'github',
+                name: 'GitHub',
+                type: 'github',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+              },
+            ],
+          },
+        },
+      });
+
+      const result = generateAuthorizationUrl('github', 'http://localhost/callback');
+      expect(result).not.toBeNull();
+      expect(result!.url).toContain('https://github.com/login/oauth/authorize');
+      expect(result!.url).not.toContain('code_challenge=');
+      expect(result!.state).toBeDefined();
+    });
+
+    it('should generate authorization URL for Microsoft provider', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [
+              {
+                id: 'microsoft',
+                name: 'Microsoft',
+                type: 'microsoft',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+              },
+            ],
+          },
+        },
+      });
+
+      const result = generateAuthorizationUrl('microsoft', 'http://localhost/callback');
+      expect(result).not.toBeNull();
+      expect(result!.url).toContain('https://login.microsoftonline.com/common/oauth2/v2.0/authorize');
+      expect(result!.url).toContain('code_challenge=');
+      expect(result!.state).toBeDefined();
+    });
+
+    it('should include custom scopes when configured', () => {
+      mockLoadSettings.mockReturnValue({
+        mcpServers: {},
+        systemConfig: {
+          oauthSSO: {
+            enabled: true,
+            providers: [
+              {
+                id: 'google',
+                name: 'Google',
+                type: 'google',
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+                scopes: ['custom-scope', 'another-scope'],
+              },
+            ],
+          },
+        },
+      });
+
+      const result = generateAuthorizationUrl('google', 'http://localhost/callback');
+      expect(result).not.toBeNull();
+      expect(result!.url).toContain('scope=custom-scope+another-scope');
+    });
+  });
+});
--- a/tests/services/oauthSsoService.test.ts
+++ b/tests/services/oauthSsoService.test.ts
@@ -1,235 +0,0 @@
-// Mock openid-client before importing services
-jest.mock('openid-client', () => ({
-  discovery: jest.fn(),
-  Configuration: jest.fn(),
-  randomPKCECodeVerifier: jest.fn(() => 'test-verifier'),
-  calculatePKCECodeChallenge: jest.fn(() => Promise.resolve('test-challenge')),
-  buildAuthorizationUrl: jest.fn(() => new URL('https://example.com/authorize')),
-  authorizationCodeGrant: jest.fn(),
-  fetchUserInfo: jest.fn(),
-  skipSubjectCheck: Symbol('skipSubjectCheck'),
-}));
-
-// Mock the DAO module
-jest.mock('../../src/dao/index.js', () => ({
-  getSystemConfigDao: jest.fn(),
-  getUserDao: jest.fn(),
-}));
-
-import * as daoModule from '../../src/dao/index.js';
-import {
-  isOAuthSsoEnabled,
-  getEnabledProviders,
-  getProviderById,
-  isLocalAuthAllowed,
-  getPublicProviderInfo,
-  clearProviderCache,
-  stopStateCleanup,
-} from '../../src/services/oauthSsoService.js';
-
-describe('OAuth SSO Service', () => {
-  const mockGetSystemConfigDao = daoModule.getSystemConfigDao as jest.MockedFunction<
-    typeof daoModule.getSystemConfigDao
-  >;
-  const mockGetUserDao = daoModule.getUserDao as jest.MockedFunction<typeof daoModule.getUserDao>;
-
-  // Stop the cleanup interval to prevent Jest from hanging
-  afterAll(() => {
-    stopStateCleanup();
-  });
-
-  const defaultSsoConfig = {
-    enabled: true,
-    allowLocalAuth: true,
-    providers: [
-      {
-        id: 'google',
-        type: 'google' as const,
-        name: 'Google',
-        enabled: true,
-        clientId: 'test-client-id',
-        clientSecret: 'test-client-secret',
-        scopes: ['openid', 'email', 'profile'],
-      },
-      {
-        id: 'github',
-        type: 'github' as const,
-        name: 'GitHub',
-        enabled: true,
-        clientId: 'test-github-client',
-        clientSecret: 'test-github-secret',
-      },
-      {
-        id: 'disabled-provider',
-        type: 'oidc' as const,
-        name: 'Disabled',
-        enabled: false,
-        clientId: 'disabled-client',
-        clientSecret: 'disabled-secret',
-      },
-    ],
-  };
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    clearProviderCache();
-
-    mockGetSystemConfigDao.mockReturnValue({
-      get: jest.fn().mockResolvedValue({
-        oauthSso: defaultSsoConfig,
-      }),
-    } as any);
-
-    mockGetUserDao.mockReturnValue({
-      findByUsername: jest.fn().mockResolvedValue(null),
-      createWithHashedPassword: jest.fn().mockResolvedValue({
-        username: 'google:12345',
-        password: 'hashed',
-        isAdmin: false,
-      }),
-      update: jest.fn().mockImplementation((username: string, data: any) =>
-        Promise.resolve({
-          username,
-          password: 'hashed',
-          isAdmin: false,
-          ...data,
-        })
-      ),
-    } as any);
-  });
-
-  describe('isOAuthSsoEnabled', () => {
-    it('should return true when OAuth SSO is enabled with providers', async () => {
-      const enabled = await isOAuthSsoEnabled();
-      expect(enabled).toBe(true);
-    });
-
-    it('should return false when OAuth SSO is disabled', async () => {
-      mockGetSystemConfigDao.mockReturnValue({
-        get: jest.fn().mockResolvedValue({
-          oauthSso: { ...defaultSsoConfig, enabled: false },
-        }),
-      } as any);
-
-      const enabled = await isOAuthSsoEnabled();
-      expect(enabled).toBe(false);
-    });
-
-    it('should return false when no providers are configured', async () => {
-      mockGetSystemConfigDao.mockReturnValue({
-        get: jest.fn().mockResolvedValue({
-          oauthSso: { ...defaultSsoConfig, providers: [] },
-        }),
-      } as any);
-
-      const enabled = await isOAuthSsoEnabled();
-      expect(enabled).toBe(false);
-    });
-  });
-
-  describe('getEnabledProviders', () => {
-    it('should return only enabled providers', async () => {
-      const providers = await getEnabledProviders();
-      expect(providers).toHaveLength(2);
-      expect(providers.map((p) => p.id)).toContain('google');
-      expect(providers.map((p) => p.id)).toContain('github');
-      expect(providers.map((p) => p.id)).not.toContain('disabled-provider');
-    });
-
-    it('should return empty array when SSO is disabled', async () => {
-      mockGetSystemConfigDao.mockReturnValue({
-        get: jest.fn().mockResolvedValue({
-          oauthSso: { ...defaultSsoConfig, enabled: false },
-        }),
-      } as any);
-
-      const providers = await getEnabledProviders();
-      expect(providers).toHaveLength(0);
-    });
-  });
-
-  describe('getProviderById', () => {
-    it('should return the correct provider by ID', async () => {
-      const provider = await getProviderById('google');
-      expect(provider).toBeDefined();
-      expect(provider?.id).toBe('google');
-      expect(provider?.type).toBe('google');
-      expect(provider?.name).toBe('Google');
-    });
-
-    it('should return undefined for non-existent provider', async () => {
-      const provider = await getProviderById('non-existent');
-      expect(provider).toBeUndefined();
-    });
-
-    it('should return undefined for disabled provider', async () => {
-      const provider = await getProviderById('disabled-provider');
-      expect(provider).toBeUndefined();
-    });
-  });
-
-  describe('isLocalAuthAllowed', () => {
-    it('should return true when local auth is allowed', async () => {
-      const allowed = await isLocalAuthAllowed();
-      expect(allowed).toBe(true);
-    });
-
-    it('should return false when local auth is disabled', async () => {
-      mockGetSystemConfigDao.mockReturnValue({
-        get: jest.fn().mockResolvedValue({
-          oauthSso: { ...defaultSsoConfig, allowLocalAuth: false },
-        }),
-      } as any);
-
-      const allowed = await isLocalAuthAllowed();
-      expect(allowed).toBe(false);
-    });
-
-    it('should return true when SSO is disabled (fallback)', async () => {
-      mockGetSystemConfigDao.mockReturnValue({
-        get: jest.fn().mockResolvedValue({
-          oauthSso: undefined,
-        }),
-      } as any);
-
-      const allowed = await isLocalAuthAllowed();
-      expect(allowed).toBe(true);
-    });
-  });
-
-  describe('getPublicProviderInfo', () => {
-    it('should return public info for enabled providers only', async () => {
-      const info = await getPublicProviderInfo();
-      expect(info).toHaveLength(2);
-
-      const googleInfo = info.find((p) => p.id === 'google');
-      expect(googleInfo).toBeDefined();
-      expect(googleInfo?.name).toBe('Google');
-      expect(googleInfo?.type).toBe('google');
-      expect(googleInfo?.icon).toBe('google');
-
-      // Ensure sensitive data is not exposed
-      expect((googleInfo as any)?.clientSecret).toBeUndefined();
-      expect((googleInfo as any)?.clientId).toBeUndefined();
-    });
-
-    it('should include buttonText when specified', async () => {
-      mockGetSystemConfigDao.mockReturnValue({
-        get: jest.fn().mockResolvedValue({
-          oauthSso: {
-            ...defaultSsoConfig,
-            providers: [
-              {
-                ...defaultSsoConfig.providers[0],
-                buttonText: 'Login with Google',
-              },
-            ],
-          },
-        }),
-      } as any);
-
-      const info = await getPublicProviderInfo();
-      expect(info[0].buttonText).toBe('Login with Google');
-    });
-  });
-});