feat: add {{USER_GROUPS}} and {{USER_GROUP_IDS}} placeholders for custom forwarded headers (#27236)

Custom per-connection headers can now forward the user's groups to
upstream backends via two new template placeholders:

- {{USER_GROUPS}}: comma-separated group names
- {{USER_GROUP_IDS}}: comma-separated group ids

The group lookup is async, so get_custom_headers becomes an async
wrapper around the sync template substitution (parse_custom_headers)
and fetches groups lazily — only when a header value actually
references a groups placeholder. The external document loader path
runs in a worker thread without an event loop, so Loader.aload
prefetches the groups before offloading and passes them through to
ExternalDocumentLoader.


Claude-Session: https://claude.ai/code/session_01EbBEfTyu8fFJmC13rnQthT

Co-authored-by: Claude <noreply@anthropic.com>

backend/open_webui/retrieval/loaders/external_document.py

@@ -6,7 +6,7 @@ from urllib.parse import quote
 import requests
 from langchain_core.document_loaders import BaseLoader
 from langchain_core.documents import Document
-from open_webui.utils.headers import get_custom_headers, include_user_info_headers
+from open_webui.utils.headers import include_user_info_headers, parse_custom_headers
 
 log = logging.getLogger(__name__)
 
@@ -19,6 +19,7 @@ class ExternalDocumentLoader(BaseLoader):
         api_key: str,
         mime_type=None,
         user=None,
+        user_groups=None,
         headers=None,
         metadata=None,
         **kwargs,
@@ -30,6 +31,7 @@ class ExternalDocumentLoader(BaseLoader):
         self.mime_type = mime_type
 
         self.user = user
+        self.user_groups = user_groups
         self.headers = headers
         self.metadata = metadata
 
@@ -49,7 +51,7 @@ class ExternalDocumentLoader(BaseLoader):
         except Exception:
             pass
 
-        headers.update(get_custom_headers(self.headers, self.user, self.metadata))
+        headers.update(parse_custom_headers(self.headers, self.user, self.metadata, user_groups=self.user_groups))
 
         if self.user is not None:
             headers = include_user_info_headers(headers, self.user)

backend/open_webui/retrieval/loaders/main.py

@@ -28,6 +28,7 @@ from open_webui.retrieval.loaders.external_document import ExternalDocumentLoade
 from open_webui.retrieval.loaders.mineru import MinerULoader
 from open_webui.retrieval.loaders.mistral import MistralLoader
 from open_webui.retrieval.loaders.paddleocr_vl import PADDLEOCR_VL_SUPPORTED_EXTENSIONS, PaddleOCRVLLoader
+from open_webui.utils.headers import get_user_groups_for_custom_headers
 
 logging.basicConfig(stream=sys.stdout, level=GLOBAL_LOG_LEVEL)
 log = logging.getLogger(__name__)
@@ -246,6 +247,7 @@ class Loader:
     def __init__(self, engine: str = '', **kwargs):
         self.engine = engine
         self.user = kwargs.get('user', None)
+        self.user_groups = kwargs.get('user_groups', None)
         self.metadata = kwargs.get('metadata', {})
         self.kwargs = kwargs
 
@@ -264,6 +266,13 @@ class Loader:
         loop for the entire parse — minutes for large PDFs. This offloads
         the work to a worker thread so the loop stays responsive.
         """
+        # Group lookup is async-only, so it must happen before `load`
+        # is offloaded to a thread without a running event loop.
+        if self.engine == 'external' and self.user_groups is None:
+            self.user_groups = await get_user_groups_for_custom_headers(
+                self.kwargs.get('EXTERNAL_DOCUMENT_LOADER_HEADERS'), self.user
+            )
+
         return await asyncio.to_thread(self.load, filename, file_content_type, file_path)
 
     def _is_text_file(self, file_ext: str, file_content_type: str) -> bool:
@@ -429,6 +438,7 @@ class Loader:
                 api_key=self.kwargs.get('EXTERNAL_DOCUMENT_LOADER_API_KEY'),
                 mime_type=file_content_type,
                 user=self.user,
+                user_groups=self.user_groups,
                 headers=self.kwargs.get('EXTERNAL_DOCUMENT_LOADER_HEADERS'),
                 metadata={
                     **self.metadata,