🔐 feat: Admin Auth. Routes with Secure Cross-Origin Token Exchange (#11297)

* feat: implement admin authentication with OpenID & Local Auth proxy support

* feat: implement admin OAuth exchange flow with caching support

- Added caching for admin OAuth exchange codes with a short TTL.
- Introduced new endpoints for generating and exchanging admin OAuth codes.
- Updated relevant controllers and routes to handle admin panel redirects and token exchanges.
- Enhanced logging for better traceability of OAuth operations.

* refactor: enhance OpenID strategy mock to support multiple verify callbacks

- Updated the OpenID strategy mock to store and retrieve verify callbacks by strategy name.
- Improved backward compatibility by maintaining a method to get the last registered callback.
- Adjusted tests to utilize the new callback retrieval methods, ensuring clarity in the verification process for the 'openid' strategy.

* refactor: reorder import statements for better organization

* refactor: admin OAuth flow with improved URL handling and validation

- Added a utility function to retrieve the admin panel URL, defaulting to a local development URL if not set in the environment.
- Updated the OAuth exchange endpoint to include validation for the authorization code format.
- Refactored the admin panel redirect logic to handle URL parsing more robustly, ensuring accurate origin comparisons.
- Removed redundant local URL definitions from the codebase for better maintainability.

* refactor: remove deprecated requireAdmin middleware and migrate to TypeScript

- Deleted the old requireAdmin middleware file and its references in the middleware index.
- Introduced a new TypeScript version of the requireAdmin middleware with enhanced error handling and logging.
- Updated routes to utilize the new requireAdmin middleware, ensuring consistent access control for admin routes.

* feat: add requireAdmin middleware for admin role verification

- Introduced requireAdmin middleware to enforce admin role checks for authenticated users.
- Implemented comprehensive error handling and logging for unauthorized access attempts.
- Added unit tests to validate middleware functionality and ensure proper behavior for different user roles.
- Updated middleware index to include the new requireAdmin export.

api/server/controllers/auth/oauth.js

@@ -0,0 +1,79 @@
+const { CacheKeys } = require('librechat-data-provider');
+const { logger, DEFAULT_SESSION_EXPIRY } = require('@librechat/data-schemas');
+const {
+  isEnabled,
+  getAdminPanelUrl,
+  isAdminPanelRedirect,
+  generateAdminExchangeCode,
+} = require('@librechat/api');
+const { syncUserEntraGroupMemberships } = require('~/server/services/PermissionService');
+const { setAuthTokens, setOpenIDAuthTokens } = require('~/server/services/AuthService');
+const getLogStores = require('~/cache/getLogStores');
+const { checkBan } = require('~/server/middleware');
+const { generateToken } = require('~/models');
+
+const domains = {
+  client: process.env.DOMAIN_CLIENT,
+  server: process.env.DOMAIN_SERVER,
+};
+
+function createOAuthHandler(redirectUri = domains.client) {
+  /**
+   * A handler to process OAuth authentication results.
+   * @type {Function}
+   * @param {ServerRequest} req - Express request object.
+   * @param {ServerResponse} res - Express response object.
+   * @param {NextFunction} next - Express next middleware function.
+   */
+  return async (req, res, next) => {
+    try {
+      if (res.headersSent) {
+        return;
+      }
+
+      await checkBan(req, res);
+      if (req.banned) {
+        return;
+      }
+
+      /** Check if this is an admin panel redirect (cross-origin) */
+      if (isAdminPanelRedirect(redirectUri, getAdminPanelUrl(), domains.client)) {
+        /** For admin panel, generate exchange code instead of setting cookies */
+        const cache = getLogStores(CacheKeys.ADMIN_OAUTH_EXCHANGE);
+        const sessionExpiry = Number(process.env.SESSION_EXPIRY) || DEFAULT_SESSION_EXPIRY;
+        const token = await generateToken(req.user, sessionExpiry);
+
+        /** Get refresh token from tokenset for OpenID users */
+        const refreshToken =
+          req.user.tokenset?.refresh_token || req.user.federatedTokens?.refresh_token;
+
+        const exchangeCode = await generateAdminExchangeCode(cache, req.user, token, refreshToken);
+
+        const callbackUrl = new URL(redirectUri);
+        callbackUrl.searchParams.set('code', exchangeCode);
+        logger.info(`[OAuth] Admin panel redirect with exchange code for user: ${req.user.email}`);
+        return res.redirect(callbackUrl.toString());
+      }
+
+      /** Standard OAuth flow - set cookies and redirect */
+      if (
+        req.user &&
+        req.user.provider == 'openid' &&
+        isEnabled(process.env.OPENID_REUSE_TOKENS) === true
+      ) {
+        await syncUserEntraGroupMemberships(req.user, req.user.tokenset.access_token);
+        setOpenIDAuthTokens(req.user.tokenset, req, res, req.user._id.toString());
+      } else {
+        await setAuthTokens(req.user._id, res);
+      }
+      res.redirect(redirectUri);
+    } catch (err) {
+      logger.error('Error in setting authentication tokens:', err);
+      next(err);
+    }
+  };
+}
+
+module.exports = {
+  createOAuthHandler,
+};

api/server/index.js

@@ -134,6 +134,7 @@ const startServer = async () => {
   app.use('/oauth', routes.oauth);
   /* API Endpoints */
   app.use('/api/auth', routes.auth);
+  app.use('/api/admin', routes.adminAuth);
   app.use('/api/actions', routes.actions);
   app.use('/api/keys', routes.keys);
   app.use('/api/user', routes.user);

api/server/routes/admin/auth.js

@@ -0,0 +1,127 @@
+const express = require('express');
+const passport = require('passport');
+const { randomState } = require('openid-client');
+const { logger } = require('@librechat/data-schemas');
+const { CacheKeys } = require('librechat-data-provider');
+const {
+  requireAdmin,
+  getAdminPanelUrl,
+  exchangeAdminCode,
+  createSetBalanceConfig,
+} = require('@librechat/api');
+const { loginController } = require('~/server/controllers/auth/LoginController');
+const { createOAuthHandler } = require('~/server/controllers/auth/oauth');
+const { getAppConfig } = require('~/server/services/Config');
+const getLogStores = require('~/cache/getLogStores');
+const { getOpenIdConfig } = require('~/strategies');
+const middleware = require('~/server/middleware');
+const { Balance } = require('~/db/models');
+
+const setBalanceConfig = createSetBalanceConfig({
+  getAppConfig,
+  Balance,
+});
+
+const router = express.Router();
+
+router.post(
+  '/login/local',
+  middleware.logHeaders,
+  middleware.loginLimiter,
+  middleware.checkBan,
+  middleware.requireLocalAuth,
+  requireAdmin,
+  setBalanceConfig,
+  loginController,
+);
+
+router.get('/verify', middleware.requireJwtAuth, requireAdmin, (req, res) => {
+  const { password: _p, totpSecret: _t, __v, ...user } = req.user;
+  user.id = user._id.toString();
+  res.status(200).json({ user });
+});
+
+router.get('/oauth/openid/check', (req, res) => {
+  const openidConfig = getOpenIdConfig();
+  if (!openidConfig) {
+    return res.status(404).json({
+      error: 'OpenID configuration not found',
+      error_code: 'OPENID_NOT_CONFIGURED',
+    });
+  }
+  res.status(200).json({ message: 'OpenID check successful' });
+});
+
+router.get('/oauth/openid', (req, res, next) => {
+  return passport.authenticate('openidAdmin', {
+    session: false,
+    state: randomState(),
+  })(req, res, next);
+});
+
+router.get(
+  '/oauth/openid/callback',
+  passport.authenticate('openidAdmin', {
+    failureRedirect: `${getAdminPanelUrl()}/auth/openid/callback?error=auth_failed&error_description=Authentication+failed`,
+    failureMessage: true,
+    session: false,
+  }),
+  requireAdmin,
+  setBalanceConfig,
+  middleware.checkDomainAllowed,
+  createOAuthHandler(`${getAdminPanelUrl()}/auth/openid/callback`),
+);
+
+/** Regex pattern for valid exchange codes: 64 hex characters */
+const EXCHANGE_CODE_PATTERN = /^[a-f0-9]{64}$/i;
+
+/**
+ * Exchange OAuth authorization code for tokens.
+ * This endpoint is called server-to-server by the admin panel.
+ * The code is one-time-use and expires in 30 seconds.
+ *
+ * POST /api/admin/oauth/exchange
+ * Body: { code: string }
+ * Response: { token: string, refreshToken: string, user: object }
+ */
+router.post('/oauth/exchange', middleware.loginLimiter, async (req, res) => {
+  try {
+    const { code } = req.body;
+
+    if (!code) {
+      logger.warn('[admin/oauth/exchange] Missing authorization code');
+      return res.status(400).json({
+        error: 'Missing authorization code',
+        error_code: 'MISSING_CODE',
+      });
+    }
+
+    if (typeof code !== 'string' || !EXCHANGE_CODE_PATTERN.test(code)) {
+      logger.warn('[admin/oauth/exchange] Invalid authorization code format');
+      return res.status(400).json({
+        error: 'Invalid authorization code format',
+        error_code: 'INVALID_CODE_FORMAT',
+      });
+    }
+
+    const cache = getLogStores(CacheKeys.ADMIN_OAUTH_EXCHANGE);
+    const result = await exchangeAdminCode(cache, code);
+
+    if (!result) {
+      return res.status(401).json({
+        error: 'Invalid or expired authorization code',
+        error_code: 'INVALID_OR_EXPIRED_CODE',
+      });
+    }
+
+    res.json(result);
+  } catch (error) {
+    logger.error('[admin/oauth/exchange] Error:', error);
+    res.status(500).json({
+      error: 'Internal server error',
+      error_code: 'INTERNAL_ERROR',
+    });
+  }
+});
+
+module.exports = router;

api/server/routes/index.js

@@ -1,6 +1,7 @@
 const accessPermissions = require('./accessPermissions');
 const assistants = require('./assistants');
 const categories = require('./categories');
+const adminAuth = require('./admin/auth');
 const endpoints = require('./endpoints');
 const staticRoute = require('./static');
 const messages = require('./messages');
@@ -28,6 +29,7 @@ const mcp = require('./mcp');
 module.exports = {
   mcp,
   auth,
+  adminAuth,
   keys,
   user,
   tags,

api/server/routes/oauth.js

@@ -4,10 +4,9 @@ const passport = require('passport');
 const { randomState } = require('openid-client');
 const { logger } = require('@librechat/data-schemas');
 const { ErrorTypes } = require('librechat-data-provider');
-const { isEnabled, createSetBalanceConfig } = require('@librechat/api');
-const { checkDomainAllowed, loginLimiter, logHeaders, checkBan } = require('~/server/middleware');
-const { syncUserEntraGroupMemberships } = require('~/server/services/PermissionService');
-const { setAuthTokens, setOpenIDAuthTokens } = require('~/server/services/AuthService');
+const { createSetBalanceConfig } = require('@librechat/api');
+const { checkDomainAllowed, loginLimiter, logHeaders } = require('~/server/middleware');
+const { createOAuthHandler } = require('~/server/controllers/auth/oauth');
 const { getAppConfig } = require('~/server/services/Config');
 const { Balance } = require('~/db/models');
 
@@ -26,32 +25,7 @@ const domains = {
 router.use(logHeaders);
 router.use(loginLimiter);
 
-const oauthHandler = async (req, res, next) => {
-  try {
-    if (res.headersSent) {
-      return;
-    }
-
-    await checkBan(req, res);
-    if (req.banned) {
-      return;
-    }
-    if (
-      req.user &&
-      req.user.provider == 'openid' &&
-      isEnabled(process.env.OPENID_REUSE_TOKENS) === true
-    ) {
-      await syncUserEntraGroupMemberships(req.user, req.user.tokenset.access_token);
-      setOpenIDAuthTokens(req.user.tokenset, req, res, req.user._id.toString());
-    } else {
-      await setAuthTokens(req.user._id, res);
-    }
-    res.redirect(domains.client);
-  } catch (err) {
-    logger.error('Error in setting authentication tokens:', err);
-    next(err);
-  }
-};
+const oauthHandler = createOAuthHandler();
 
 router.get('/error', (req, res) => {
   /** A single error message is pushed by passport when authentication fails. */