OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
fix: Add forwarded JWT header auth and issuer utils for api users (#1697)
Edwin Joseece25b0a89f6
diff --git a/pyproject.toml b/pyproject.tomlindex 3540c7d6a..9884e2556 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -116,6 +116,7 @@ extend-immutable-calls = ["fastapi.Security","dependencies.require_permission","dependencies.require_all_permissions",+ "dependencies.require_api_key_permission",]# `bootstrap` must be the first import in any module that uses it@@ -143,14 +144,14 @@ no_strict_optional = truewarn_unused_ignores = trueexclude = ["flows/components"]-# FastAPI handlers in this module declare a Pydantic response model as+# FastAPI handlers in these modules declare a Pydantic response model as# their return type but legitimately return `JSONResponse(...)` on error# paths. The runtime accepts both, but the annotation can't be widened to# `SomeResponse | JSONResponse` because FastAPI then tries to derive an# OpenAPI schema from the union and fails. Suppress only the resulting-# return-value mismatches in this one file.+# return-value mismatches in these files.[[tool.mypy.overrides]]-module = "api.settings.endpoints"+module = ["api.settings.endpoints", "api.v1.settings"]disable_error_code = ["return-value"]diff --git a/src/api/v1/chat.py b/src/api/v1/chat.pyindex 65d0319de..328738e1d 100644--- a/src/api/v1/chat.py+++ b/src/api/v1/chat.py@@ -4,16 +4,18 @@ Public API v1 Chat endpoint.Provides chat functionality with streaming support and conversation history.Uses API key authentication. Routes through Langflow (chat_service.langflow_chat)."""+import json-from typing import Optional, Any, Dict+from typing import Anyfrom fastapi import Depends, HTTPException-from pydantic import BaseModelfrom fastapi.responses import JSONResponse, StreamingResponse-from utils.logging_config import get_logger-from auth_context import set_search_filters, set_search_limit, set_score_threshold, set_auth_context-from dependencies import get_chat_service, get_session_manager, get_api_key_user_async+from pydantic import BaseModel++from auth_context import set_auth_context, set_score_threshold, set_search_filters, set_search_limit+from dependencies import get_chat_service, get_session_manager, require_api_key_permissionfrom session_manager import User+from utils.logging_config import get_loggerlogger = get_logger(__name__)@@ -25,11 +27,11 @@ def _openrag_user_id(user: User) -> str:class ChatV1Body(BaseModel):message: strstream: bool = False- chat_id: Optional[str] = None- filters: Optional[Dict[str, Any]] = None+ chat_id: str | None = None+ filters: dict[str, Any] | None = Nonelimit: int = 10score_threshold: float = 0- filter_id: Optional[str] = None+ filter_id: str | None = Nonedef _extract_sources(item: dict) -> list[dict]:@@ -37,13 +39,15 @@ def _extract_sources(item: dict) -> list[dict]:sources = []for result in item.get("results", []):if isinstance(result, dict) and "text" in result:- sources.append({- "filename": result.get("filename", ""),- "text": result.get("text", ""),- "score": result.get("score", 0),- "page": result.get("page"),- "mimetype": result.get("mimetype"),- })+ sources.append(+ {+ "filename": result.get("filename", ""),+ "text": result.get("text", ""),+ "score": result.get("score", 0),+ "page": result.get("page"),+ "mimetype": result.get("mimetype"),+ }+ )return sources@@ -108,7 +112,7 @@ async def chat_create_endpoint(body: ChatV1Body,chat_service=Depends(get_chat_service),session_manager=Depends(get_session_manager),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("chat:use")),):"""Send a chat message via Langflow. POST /v1/chat"""message = body.message.strip()@@ -120,6 +124,7 @@ async def chat_create_endpoint(jwt_token = user.jwt_tokenif body.chat_id:from api.chat import _assert_owns+await _assert_owns(body.chat_id, storage_user_id)if body.filters:@@ -141,11 +146,15 @@ async def chat_create_endpoint(owner_email=user.email,storage_user_id=storage_user_id,)- chat_id_container = {}+ chat_id_container: dict[str, str] = {}return StreamingResponse(_transform_stream_to_sse(raw_stream, chat_id_container),media_type="text/event-stream",- headers={"Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no"},+ headers={+ "Cache-Control": "no-cache",+ "Connection": "keep-alive",+ "X-Accel-Buffering": "no",+ },)else:result = await chat_service.langflow_chat(@@ -160,16 +169,18 @@ async def chat_create_endpoint(owner_email=user.email,storage_user_id=storage_user_id,)- return JSONResponse({- "response": result.get("response", ""),- "chat_id": result.get("response_id"),- "sources": result.get("sources", []),- })+ return JSONResponse(+ {+ "response": result.get("response", ""),+ "chat_id": result.get("response_id"),+ "sources": result.get("sources", []),+ }+ )async def chat_list_endpoint(chat_service=Depends(get_chat_service),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("conversations:read:own")),):"""List all conversations for the authenticated user. GET /v1/chat"""try:@@ -193,7 +204,7 @@ async def chat_list_endpoint(async def chat_get_endpoint(chat_id: str,chat_service=Depends(get_chat_service),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("conversations:read:own")),):"""Get a specific conversation with full message history. GET /v1/chat/{chat_id}"""try:@@ -217,31 +228,40 @@ async def chat_get_endpoint("timestamp": msg.get("timestamp"),}# Include token usage if available (from Responses API)- usage = msg.get("response_data", {}).get("usage") if isinstance(msg.get("response_data"), dict) else None+ usage = (+ msg.get("response_data", {}).get("usage")+ if isinstance(msg.get("response_data"), dict)+ else None+ )if usage:message_data["usage"] = usagemessages.append(message_data)- return JSONResponse({- "chat_id": conversation.get("response_id"),- "title": conversation.get("title", ""),- "created_at": conversation.get("created_at"),- "last_activity": conversation.get("last_activity"),- "messages": messages,- })+ return JSONResponse(+ {+ "chat_id": conversation.get("response_id"),+ "title": conversation.get("title", ""),+ "created_at": conversation.get("created_at"),+ "last_activity": conversation.get("last_activity"),+ "messages": messages,+ }+ )except Exception as e:- logger.error("Failed to get conversation", error=str(e), user_id=user.user_id, chat_id=chat_id)+ logger.error(+ "Failed to get conversation", error=str(e), user_id=user.user_id, chat_id=chat_id+ )return JSONResponse({"error": f"Failed to get conversation: {str(e)}"}, status_code=500)async def chat_delete_endpoint(chat_id: str,chat_service=Depends(get_chat_service),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("conversations:delete:own")),):"""Delete a conversation. DELETE /v1/chat/{chat_id}"""try:from api.chat import _assert_owns+storage_user_id = _openrag_user_id(user)await _assert_owns(chat_id, storage_user_id)result = await chat_service.delete_session(storage_user_id, chat_id)@@ -257,5 +277,7 @@ async def chat_delete_endpoint(except HTTPException:raiseexcept Exception as e:- logger.error("Failed to delete conversation", error=str(e), user_id=user.user_id, chat_id=chat_id)+ logger.error(+ "Failed to delete conversation", error=str(e), user_id=user.user_id, chat_id=chat_id+ )return JSONResponse({"error": f"Failed to delete conversation: {str(e)}"}, status_code=500)diff --git a/src/api/v1/documents.py b/src/api/v1/documents.pyindex cd4ed381a..4860ff98f 100644--- a/src/api/v1/documents.py+++ b/src/api/v1/documents.py@@ -12,11 +12,11 @@ from pydantic import BaseModelfrom api.documents import delete_documents_by_filename_corefrom api.router import upload_ingest_routerfrom dependencies import (- get_api_key_user_async,get_document_service,get_langflow_file_service,get_session_manager,get_task_service,+ require_api_key_permission,)from session_manager import Userfrom utils.logging_config import get_logger@@ -39,7 +39,7 @@ async def ingest_endpoint(langflow_file_service=Depends(get_langflow_file_service),session_manager=Depends(get_session_manager),task_service=Depends(get_task_service),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("knowledge:upload")),):"""Ingest a document into the knowledge base.@@ -65,7 +65,7 @@ async def ingest_endpoint(async def all_tasks_enhanced_endpoint(task_service=Depends(get_task_service),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("knowledge:read:own")),):"""Get all ingestion tasks with structured failure metadata on failed files.@@ -86,7 +86,7 @@ async def all_tasks_enhanced_endpoint(async def task_status_endpoint(task_id: str,task_service=Depends(get_task_service),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("knowledge:read:own")),):"""Get the status of an ingestion task. GET /v1/tasks/{task_id}"""task_status = task_service.get_task_status(user.user_id, task_id)@@ -98,7 +98,7 @@ async def task_status_endpoint(async def task_status_enhanced_endpoint(task_id: str,task_service=Depends(get_task_service),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("knowledge:read:own")),):"""Get the status of an ingestion task with structured failure metadata.@@ -122,7 +122,7 @@ async def task_status_enhanced_endpoint(async def delete_document_endpoint(body: DeleteDocV1Body,session_manager=Depends(get_session_manager),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("knowledge:delete:own")),):"""Delete a document from the knowledge base. DELETE /v1/documents"""payload, status_code = await delete_documents_by_filename_core(diff --git a/src/api/v1/knowledge_filters.py b/src/api/v1/knowledge_filters.pyindex 5deccd3d8..f7a728869 100644--- a/src/api/v1/knowledge_filters.py+++ b/src/api/v1/knowledge_filters.py@@ -5,12 +5,15 @@ Provides knowledge filter management.Uses API key authentication — delegates to the main api/knowledge_filter.py handlersbut overrides the user dependency to use API keys."""+from fastapi import Depends+from api import knowledge_filterfrom dependencies import (+ get_api_key_user_async,get_knowledge_filter_service,get_session_manager,- get_api_key_user_async,+ require_api_key_permission,)from session_manager import User@@ -19,7 +22,7 @@ async def create_endpoint(body: knowledge_filter.CreateFilterBody,knowledge_filter_service=Depends(get_knowledge_filter_service),session_manager=Depends(get_session_manager),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("kf:create")),):"""Create a new knowledge filter.@@ -77,7 +80,7 @@ async def update_endpoint(body: knowledge_filter.UpdateFilterBody,knowledge_filter_service=Depends(get_knowledge_filter_service),session_manager=Depends(get_session_manager),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("kf:edit:own")),):"""Update a knowledge filter.@@ -97,7 +100,7 @@ async def delete_endpoint(filter_id: str,knowledge_filter_service=Depends(get_knowledge_filter_service),session_manager=Depends(get_session_manager),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("kf:edit:own")),):"""Delete a knowledge filter.diff --git a/src/api/v1/models.py b/src/api/v1/models.pyindex 1661bc0bf..7c48c762a 100644--- a/src/api/v1/models.py+++ b/src/api/v1/models.py@@ -4,12 +4,14 @@ Public API v1 Models endpoint.Lists available LLM and embedding models per provider.Uses API key authentication. Uses stored credentials from config."""+from fastapi import Dependsfrom fastapi.responses import JSONResponse+from config.settings import get_openrag_config-from utils.logging_config import get_logger-from dependencies import get_models_service, get_api_key_user_async+from dependencies import get_api_key_user_async, get_models_servicefrom session_manager import User+from utils.logging_config import get_loggerlogger = get_logger(__name__)@@ -21,21 +23,27 @@ async def _fetch_models(provider, config, models_service):if provider == "openai":api_key = config.providers.openai.api_keyif not api_key:- return None, JSONResponse({"error": "OpenAI API key not configured. Set it in Settings."}, status_code=400)+ return None, JSONResponse(+ {"error": "OpenAI API key not configured. Set it in Settings."}, status_code=400+ )models = await models_service.get_openai_models(api_key=api_key)return models, Noneif provider == "anthropic":api_key = config.providers.anthropic.api_keyif not api_key:- return None, JSONResponse({"error": "Anthropic API key not configured. Set it in Settings."}, status_code=400)+ return None, JSONResponse(+ {"error": "Anthropic API key not configured. Set it in Settings."}, status_code=400+ )models = await models_service.get_anthropic_models(api_key=api_key)return models, Noneif provider == "ollama":endpoint = config.providers.ollama.endpointif not endpoint:- return None, JSONResponse({"error": "Ollama endpoint not configured. Set it in Settings."}, status_code=400)+ return None, JSONResponse(+ {"error": "Ollama endpoint not configured. Set it in Settings."}, status_code=400+ )models = await models_service.get_ollama_models(endpoint=endpoint)return models, None@@ -44,12 +52,20 @@ async def _fetch_models(provider, config, models_service):endpoint = config.providers.watsonx.endpointproject_id = config.providers.watsonx.project_idif not api_key:- return None, JSONResponse({"error": "WatsonX API key not configured. Set it in Settings."}, status_code=400)+ return None, JSONResponse(+ {"error": "WatsonX API key not configured. Set it in Settings."}, status_code=400+ )if not endpoint:- return None, JSONResponse({"error": "WatsonX endpoint not configured. Set it in Settings."}, status_code=400)+ return None, JSONResponse(+ {"error": "WatsonX endpoint not configured. Set it in Settings."}, status_code=400+ )if not project_id:- return None, JSONResponse({"error": "WatsonX project ID not configured. Set it in Settings."}, status_code=400)- models = await models_service.get_ibm_models(endpoint=endpoint, api_key=api_key, project_id=project_id)+ return None, JSONResponse(+ {"error": "WatsonX project ID not configured. Set it in Settings."}, status_code=400+ )+ models = await models_service.get_ibm_models(+ endpoint=endpoint, api_key=api_key, project_id=project_id+ )return models, Nonediff --git a/src/api/v1/search.py b/src/api/v1/search.pyindex 2fa530615..4ed35c514 100644--- a/src/api/v1/search.py+++ b/src/api/v1/search.py@@ -4,22 +4,24 @@ Public API v1 Search endpoint.Provides semantic search functionality.Uses API key authentication."""-from typing import Any, Dict, Optional++from typing import Anyfrom fastapi import Depends-from pydantic import BaseModelfrom fastapi.responses import JSONResponse-from utils.logging_config import get_logger-from utils.opensearch_utils import OpenSearchDiskSpaceError, DISK_SPACE_ERROR_MESSAGE-from dependencies import get_search_service, get_api_key_user_async+from pydantic import BaseModel++from dependencies import get_search_service, require_api_key_permissionfrom session_manager import User+from utils.logging_config import get_logger+from utils.opensearch_utils import DISK_SPACE_ERROR_MESSAGE, OpenSearchDiskSpaceErrorlogger = get_logger(__name__)class SearchV1Body(BaseModel):query: str- filters: Optional[Dict[str, Any]] = None+ filters: dict[str, Any] | None = Nonelimit: int = 10score_threshold: float = 0@@ -27,7 +29,7 @@ class SearchV1Body(BaseModel):async def search_endpoint(body: SearchV1Body,search_service=Depends(get_search_service),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("search:use")),):"""Perform semantic search on documents. POST /v1/search"""query = body.query.strip()diff --git a/src/api/v1/settings.py b/src/api/v1/settings.pyindex 9166efa83..db6f3a4d3 100644--- a/src/api/v1/settings.py+++ b/src/api/v1/settings.py@@ -4,37 +4,46 @@ Public API v1 Settings endpoint.Provides access to configuration settings.Uses API key authentication."""-from api.settings import SettingsUpdateBody-from typing import Optionalfrom fastapi import Depends-from pydantic import BaseModelfrom fastapi.responses import JSONResponse-from utils.logging_config import get_logger+from pydantic import BaseModel++from api.settings import SettingsUpdateBodyfrom config.settings import get_openrag_config-from dependencies import get_api_key_user_async, get_models_service, get_session_manager+from dependencies import (+ get_api_key_user_async,+ get_models_service,+ get_session_manager,+ require_api_key_permission,+)from session_manager import User+from utils.logging_config import get_loggerlogger = get_logger(__name__)+class AgentSettings(BaseModel):- llm_provider: Optional[str] = None- llm_model: Optional[str] = None- system_prompt: Optional[str] = None+ llm_provider: str | None = None+ llm_model: str | None = None+ system_prompt: str | None = None+class KnowledgeSettings(BaseModel):- embedding_provider: Optional[str] = None- embedding_model: Optional[str] = None- chunk_size: Optional[int] = None- chunk_overlap: Optional[int] = None- table_structure: Optional[bool] = None- ocr: Optional[bool] = None- picture_descriptions: Optional[bool] = None+ embedding_provider: str | None = None+ embedding_model: str | None = None+ chunk_size: int | None = None+ chunk_overlap: int | None = None+ table_structure: bool | None = None+ ocr: bool | None = None+ picture_descriptions: bool | None = None+class SettingsResponse(BaseModel):agent: AgentSettingsknowledge: KnowledgeSettings+async def get_settings_endpoint(user: User = Depends(get_api_key_user_async),) -> SettingsResponse:@@ -65,10 +74,12 @@ async def get_settings_endpoint(async def update_settings_endpoint(body: SettingsUpdateBody,session_manager=Depends(get_session_manager),- user: User = Depends(get_api_key_user_async),+ user: User = Depends(require_api_key_permission("config:write")),models_service=Depends(get_models_service),):"""Update OpenRAG configuration settings. POST /v1/settings"""from api.settings import update_settings- return await update_settings(body=body, session_manager=session_manager, user=user, models_service=models_service)+ return await update_settings(+ body=body, session_manager=session_manager, user=user, models_service=models_service+ )diff --git a/src/config/settings.py b/src/config/settings.pyindex 234ef4127..20f282069 100644--- a/src/config/settings.py+++ b/src/config/settings.py@@ -107,6 +107,12 @@ def get_role_claim_viewer() -> str | None:return os.getenv("OPENRAG_ROLE_CLAIM_VIEWER")+def get_jwt_auth_header() -> str:+ """HTTP header that may carry a gateway-forwarded JWT for /v1 (API-key)+ callers. Read per-call so tests can override via monkeypatch.setenv."""+ return os.getenv("OPENRAG_JWT_AUTH_HEADER", "Authorization")++DOCLING_OCR_ENGINE = os.getenv("DOCLING_OCR_ENGINE")SEGMENT_WRITE_KEY = os.getenv("SEGMENT_WRITE_KEY", "")ENVIRONMENT = os.getenv("ENVIRONMENT", "")diff --git a/src/config/utils.py b/src/config/utils.pynew file mode 100644index 000000000..d283cd0b0--- /dev/null+++ b/src/config/utils.py@@ -0,0 +1,137 @@+from typing import Any+from urllib.parse import urlparse++import httpx+import jwt+from cachetools import TTLCache+from cryptography.hazmat.primitives.serialization import load_pem_public_key++from utils.logging_config import get_logger++logger = get_logger(__name__)++_ISSUER_PUBLIC_KEY_CACHE: TTLCache[str, Any] = TTLCache(maxsize=128, ttl=300)+++def _strip_bearer_prefix(token: str) -> str:+ scheme, _, value = token.partition(" ")+ return value if scheme.lower() == "bearer" and value else token+++def _load_public_key_from_payload(payload: Any, key_id: str | None = None):+ if isinstance(payload, str):+ return load_pem_public_key(payload.encode("utf-8"))++ if not isinstance(payload, dict):+ raise ValueError("Public key response must be PEM text or JSON")++ public_key_pem = payload.get("public_key") or payload.get("pem") or payload.get("key")+ if public_key_pem:+ if isinstance(public_key_pem, bytes):+ return load_pem_public_key(public_key_pem)+ return load_pem_public_key(str(public_key_pem).encode("utf-8"))++ jwks = payload.get("keys")+ if isinstance(jwks, list) and jwks:+ jwk = next(+ (candidate for candidate in jwks if key_id and candidate.get("kid") == key_id),+ jwks[0],+ )+ return jwt.PyJWK.from_dict(jwk).key++ if payload.get("kty"):+ return jwt.PyJWK.from_dict(payload).key++ raise ValueError("Public key response does not contain a supported key format")+++def get_public_key_from_issuer(+ issuer: str,+ key_id: str | None = None,+ *,+ verify_tls: bool = True,+ timeout: float = 10.0,+):+ """Fetch and cache a JWT verification public key (PEM / JWKS / JWK) from a+ JWT issuer URL. The issuer URL is expected to serve its own key material."""+ parsed = urlparse(issuer)+ if parsed.scheme not in ("http", "https") or not parsed.netloc:+ raise ValueError("Issuer must be an absolute HTTP(S) URL")++ cache_key = f"{issuer}#{key_id or ''}"+ cached = _ISSUER_PUBLIC_KEY_CACHE.get(cache_key)+ if cached is not None:+ return cached++ with httpx.Client(verify=verify_tls, timeout=timeout) as client:+ response = client.get(issuer)+ response.raise_for_status()++ content_type = response.headers.get("content-type", "")+ if "json" in content_type:+ key_payload = response.json()+ else:+ try:+ key_payload = response.json()+ except ValueError:+ key_payload = response.text++ public_key = _load_public_key_from_payload(key_payload, key_id)+ _ISSUER_PUBLIC_KEY_CACHE[cache_key] = public_key+ return public_key+++def verify_jwt_from_issuer(+ token: str,+ *,+ algorithms: tuple[str, ...] = ("ES256",),+ audience: str | list[str] | None = None,+ verify_tls: bool = True,+ timeout: float = 10.0,+) -> dict[str, Any] | None:+ """Verify a JWT by discovering the signing key from the token's own ``iss``+ claim (JWKS/PEM served at the issuer URL), then checking the signature and+ the standard ``iss``/``sub``/``exp``/``iat`` claims.++ There is NO issuer allowlist: the ``iss`` URL is trusted to publish its own+ verification keys. This suits a deployment where an upstream gateway has+ already authenticated the caller and forwards the JWT — the gateway controls+ which ``iss`` reaches this code. If the header can be set by untrusted+ clients, pin the issuer instead.+ """+ raw_token = _strip_bearer_prefix(token)+ try:+ header = jwt.get_unverified_header(raw_token)+ algorithm = header.get("alg")+ if algorithm not in algorithms:+ return None++ unverified_claims = jwt.decode(+ raw_token,+ options={"verify_signature": False, "verify_exp": False},+ )+ issuer = unverified_claims.get("iss")+ if not isinstance(issuer, str) or not issuer:+ return None++ public_key = get_public_key_from_issuer(+ issuer,+ header.get("kid"),+ verify_tls=verify_tls,+ timeout=timeout,+ )++ options: dict[str, Any] = {"require": ["iss", "sub", "exp", "iat"]}+ decode_kwargs: dict[str, Any] = {+ "algorithms": list(algorithms),+ "issuer": issuer,+ "options": options,+ }+ if audience is None:+ options["verify_aud"] = False+ else:+ decode_kwargs["audience"] = audience++ return jwt.decode(raw_token, public_key, **decode_kwargs)+ except (ValueError, httpx.HTTPError, jwt.InvalidTokenError):+ return Nonediff --git a/src/dependencies.py b/src/dependencies.pyindex 8f589b30b..0d5cd8f39 100644--- a/src/dependencies.py+++ b/src/dependencies.py@@ -324,6 +324,40 @@ def require_permission(perm: str):return _dep+def require_api_key_permission(perm: str):+ """Like ``require_permission``, but for the /v1 (API-key / forwarded-JWT)+ surface: resolves identity via ``get_api_key_user_async`` instead of+ ``get_current_user``.++ ``get_api_key_user_async`` has already attached ``user.db_user_id`` (and, on+ the forwarded-JWT path, synced the user's roles from the JWT), so the gate+ only needs to read permissions and compare. When ``OPENRAG_RBAC_ENFORCE`` is+ off the check is skipped and the authenticated user is returned unchanged —+ identical kill-switch behavior to ``require_permission``.+ """+ from services.rbac_service import is_rbac_enforced++ async def _dep(+ request: Request,+ user: User = Depends(get_api_key_user_async),+ rbac=Depends(get_rbac_service),+ ) -> User:+ if not is_rbac_enforced():+ return user+ db_user_id = user.db_user_id or user.user_id+ role_override = getattr(request.state, "api_key_role_ids", None)+ perms = await rbac.get_user_permissions(db_user_id, role_override=role_override)+ if perm not in perms:+ await rbac.audit_denied(db_user_id, perm)+ raise HTTPException(+ status_code=403,+ detail={"error": "permission_denied", "required": perm},+ )+ return user++ return _dep++def require_all_permissions(required_perms: Sequence[str]):"""FastAPI dependency factory enforcing all listed permissions."""required = tuple(required_perms)@@ -362,6 +396,34 @@ def require_all_permissions(required_perms: Sequence[str]):# ─────────────────────────────────────────────+def _stage_jwt_roles(request: Request, claims: dict, user_id: str | None) -> None:+ """Extract OpenRAG roles from decoded JWT *claims* and stash them on+ ``request.state.jwt_roles`` so the subsequent ``_attach_db_user_id`` call+ syncs them to the DB.++ Behavior mirrors the ibm-openrag-session cookie path:+ * RBAC off (``jwt_roles_enabled()`` False) -> ``jwt_roles = None`` so the+ legacy default-role path runs and existing DB roles are not clobbered.+ * RBAC on -> roles are extracted; if the JWT carries no recognized+ OpenRAG role, raise HTTP 401.+ """+ from auth.jwt_roles import extract_jwt_role_names, jwt_roles_enabled++ jwt_roles: list[str] | None = None+ if jwt_roles_enabled():+ jwt_roles = extract_jwt_role_names(claims)+ if not jwt_roles:+ logger.warning(+ "JWT carries no recognized OpenRAG role claim",+ user_id=user_id,+ )+ raise HTTPException(+ status_code=401,+ detail="User has no OpenRAG roles assigned",+ )+ request.state.jwt_roles = jwt_roles++async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:"""Authenticate via IBM AMS.@@ -378,7 +440,6 @@ async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:"""import auth.ibm_auth as ibm_authfrom auth.ibm_auth import extract_ibm_credentials- from auth.jwt_roles import extract_jwt_role_names, jwt_roles_enabledfrom config.settings import (IBM_CREDENTIALS_HEADER,IBM_SESSION_COOKIE_NAME,@@ -414,7 +475,9 @@ async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:user_id = Noneemail = Nonename = None- jwt_roles: list[str] | None = None+ # Default for the no-token / no-claims / no-sub cases; overwritten by+ # _stage_jwt_roles when a valid JWT subject is present.+ request.state.jwt_roles = Noneif ibm_token:logger.debug("[AUTH] IBM JWT token found in request cookies")claims = ibm_auth.decode_ibm_jwt(ibm_token)@@ -429,22 +492,9 @@ async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:user_id = claims.get("username", sub)email = claims.get("username", sub)name = claims.get("display_name", claims.get("username", sub))- # Only consume the roles claim when JWT-role sync is- # active. When RBAC is off, leave jwt_roles as None so- # the legacy bootstrap-or-default-role path runs and the- # user's DB roles are NOT clobbered by an empty claim.- if jwt_roles_enabled():- jwt_roles = extract_jwt_role_names(claims)- if not jwt_roles:- logger.warning(- "IBM JWT carries no recognized OpenRAG role claim",- user_id=user_id,- )- raise HTTPException(- status_code=401,- detail="User has no OpenRAG roles assigned",- )- request.state.jwt_roles = jwt_roles+ # RBAC off -> jwt_roles stays None (legacy default-role path,+ # existing DB roles untouched). RBAC on -> extract + 401 if none.+ _stage_jwt_roles(request, claims, user_id)if lh_credentials and lh_credentials.strip() != "":logger.debug("[AUTH] IBM LH credentials found in request headers")@@ -654,6 +704,9 @@ async def get_api_key_user_async(Async dependency: require API key or IBM authentication.Accepts:+ - A gateway-forwarded JWT in the configurable OPENRAG_JWT_AUTH_HEADER+ (default ``Authorization``). When present and verifiable, the JWT is the+ source of identity; under RBAC it also supplies (and enforces) roles.- X-API-Key: orag_... header- Authorization: Bearer orag_... header- X-Username + X-Api-Key headers (when IBM_AUTH_ENABLED)@@ -662,6 +715,42 @@ async def get_api_key_user_async("""import base64+ # ── JWT-in-header path ───────────────────────────────────────────────+ # An upstream gateway may forward the end-user's JWT in a configurable+ # header. Its signature is verified by discovering the issuer's keys from+ # the token's own `iss` claim (config.utils.verify_jwt_from_issuer); when+ # valid the JWT becomes the source of identity. Under RBAC it also supplies+ # the user's roles (synced via request.state.jwt_roles ->+ # _attach_db_user_id), with a 401 when no recognized role is present.+ from auth.jwt_roles import jwt_roles_enabled+ from config.settings import get_jwt_auth_header+ from config.utils import verify_jwt_from_issuer++ raw_jwt = request.headers.get(get_jwt_auth_header(), "")+ if raw_jwt and raw_jwt.strip():+ token = raw_jwt[7:].strip() if raw_jwt.startswith("Bearer ") else raw_jwt.strip()+ claims = verify_jwt_from_issuer(token, verify_tls=False)+ sub = claims.get("sub") if claims else None+ if sub:+ user = User(+ user_id=claims.get("username", sub),+ email=claims.get("username", sub),+ name=claims.get("display_name", claims.get("username", sub)),+ picture=None,+ # Same provider as the cookie path so the forwarded user+ # resolves to the SAME users row (oauth_provider, oauth_subject).+ provider="ibm_ams",+ jwt_token=f"Bearer {token}",+ )+ _stage_jwt_roles(request, claims, user.user_id)+ request.state.user = user+ return await _attach_db_user_id(request, user)+ if jwt_roles_enabled():+ # A JWT was asserted but failed verification/decode. Under RBAC we+ # must not silently downgrade to the API-key identity.+ raise HTTPException(status_code=401, detail="Invalid or unverifiable JWT")+ # RBAC off + missing/invalid JWT -> fall through to the API-key path.+# IBM auth path: X-Username + X-Api-Key forwarded by the MCP via the SDKfrom config.settings import IBM_AUTH_ENABLEDdiff --git a/tests/unit/config/test_jwt_auth_header.py b/tests/unit/config/test_jwt_auth_header.pynew file mode 100644index 000000000..fb227be39--- /dev/null+++ b/tests/unit/config/test_jwt_auth_header.py@@ -0,0 +1,22 @@+"""config.settings.get_jwt_auth_header — per-call accessor for the header that+carries a gateway-forwarded JWT to the /v1 (API-key) surface."""++import sys+from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent.parent.parent+SRC = ROOT / "src"+if str(SRC) not in sys.path:+ sys.path.insert(0, str(SRC))++from config.settings import get_jwt_auth_header # noqa: E402+++def test_default_header(monkeypatch):+ monkeypatch.delenv("OPENRAG_JWT_AUTH_HEADER", raising=False)+ assert get_jwt_auth_header() == "Authorization"+++def test_override_header(monkeypatch):+ monkeypatch.setenv("OPENRAG_JWT_AUTH_HEADER", "X-Forwarded-Access-Token")+ assert get_jwt_auth_header() == "X-Forwarded-Access-Token"diff --git a/tests/unit/dependencies/test_jwt_header_auth.py b/tests/unit/dependencies/test_jwt_header_auth.pynew file mode 100644index 000000000..231b22018--- /dev/null+++ b/tests/unit/dependencies/test_jwt_header_auth.py@@ -0,0 +1,180 @@+"""JWT-in-header auth on the /v1 (API-key) surface.++Covers the shared role-staging helper ``_stage_jwt_roles`` and the JWT-header+branch of ``get_api_key_user_async`` in ``src/dependencies.py``.++The branch verifies a gateway-forwarded JWT (config.utils.verify_jwt_from_issuer)+and, when valid, makes the JWT the source of identity; under RBAC it also+supplies/enforces roles. We monkeypatch ``verify_jwt_from_issuer`` (no real keys+needed) and ``_attach_db_user_id`` (no DB needed) to isolate the dependency+logic, and drive RBAC on/off via ``OPENRAG_RBAC_ENFORCE``.+"""++import sys+from pathlib import Path+from types import SimpleNamespace++import pytest+from fastapi import HTTPException++ROOT = Path(__file__).resolve().parent.parent.parent.parent+SRC = ROOT / "src"+if str(SRC) not in sys.path:+ sys.path.insert(0, str(SRC))++import config.utils as config_utils # noqa: E402+import dependencies as deps # noqa: E402+from dependencies import _stage_jwt_roles, get_api_key_user_async # noqa: E402+++class _FakeRequest:+ """Minimal stand-in for starlette Request used by the auth dependency."""++ def __init__(self, headers: dict | None = None):+ self.headers = headers or {}+ self.cookies: dict[str, str] = {}+ self.state = SimpleNamespace()++[email protected](autouse=True)+def _role_claim_env(monkeypatch):+ """Known role-claim mapping for every test."""+ monkeypatch.setenv("OPENRAG_JWT_ROLES_CLAIM", "openrag_roles")+ monkeypatch.setenv("OPENRAG_ROLE_CLAIM_ADMIN", "admin")+ monkeypatch.setenv("OPENRAG_ROLE_CLAIM_DEVELOPER", "manager")+ monkeypatch.setenv("OPENRAG_ROLE_CLAIM_USER", "user")+ monkeypatch.delenv("OPENRAG_ROLE_CLAIM_VIEWER", raising=False)+ # Pin the JWT header name so tests stay decoupled from its default.+ monkeypatch.setenv("OPENRAG_JWT_AUTH_HEADER", "X-OpenRAG-JWT")+++# ── _stage_jwt_roles ────────────────────────────────────────────────────+++def test_stage_roles_rbac_off_is_noop(monkeypatch):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "false")+ req = _FakeRequest()+ _stage_jwt_roles(req, {"openrag_roles": ["admin"]}, "alice")+ assert req.state.jwt_roles is None+++def test_stage_roles_rbac_on_extracts(monkeypatch):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ req = _FakeRequest()+ _stage_jwt_roles(req, {"openrag_roles": ["manager"]}, "alice")+ assert req.state.jwt_roles == ["developer"]+++def test_stage_roles_rbac_on_no_role_401(monkeypatch):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ req = _FakeRequest()+ with pytest.raises(HTTPException) as exc:+ _stage_jwt_roles(req, {"sub": "alice"}, "alice")+ assert exc.value.status_code == 401+++# ── get_api_key_user_async — JWT header branch ──────────────────────────+++def _patch_attach(monkeypatch):+ """Replace _attach_db_user_id with a passthrough that records state."""+ captured = {}++ async def _fake_attach(request, user):+ captured["jwt_roles"] = getattr(request.state, "jwt_roles", "UNSET")+ captured["user"] = user+ return user++ monkeypatch.setattr(deps, "_attach_db_user_id", _fake_attach)+ return captured+++def _patch_verify(monkeypatch, claims):+ monkeypatch.setattr(config_utils, "verify_jwt_from_issuer", lambda *a, **k: claims)+++async def test_valid_jwt_rbac_off_identity_only(monkeypatch, _patch_attach):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "false")+ _patch_verify(monkeypatch, {"sub": "s1", "username": "alice", "display_name": "Alice"})+ req = _FakeRequest({"X-OpenRAG-JWT": "Bearer tok"})++ user = await get_api_key_user_async(req, api_key_service=None, session_manager=None)++ assert user.provider == "ibm_ams"+ assert user.user_id == "alice"+ assert user.name == "Alice"+ assert user.jwt_token == "Bearer tok"+ assert _patch_attach["jwt_roles"] is None # identity only, no roles+++async def test_valid_jwt_rbac_on_syncs_roles(monkeypatch, _patch_attach):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ _patch_verify(monkeypatch, {"sub": "s1", "username": "alice", "openrag_roles": ["admin"]})+ req = _FakeRequest({"X-OpenRAG-JWT": "tok"}) # raw, no Bearer prefix++ user = await get_api_key_user_async(req, api_key_service=None, session_manager=None)++ assert user.user_id == "alice"+ assert user.jwt_token == "Bearer tok"+ # roles staged BEFORE _attach_db_user_id ran (so the DB sync sees them)+ assert _patch_attach["jwt_roles"] == ["admin"]+++async def test_valid_jwt_rbac_on_no_role_401(monkeypatch, _patch_attach):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ _patch_verify(monkeypatch, {"sub": "s1", "username": "alice"}) # no roles claim+ req = _FakeRequest({"X-OpenRAG-JWT": "tok"})++ with pytest.raises(HTTPException) as exc:+ await get_api_key_user_async(req, api_key_service=None, session_manager=None)+ assert exc.value.status_code == 401+ assert exc.value.detail == "User has no OpenRAG roles assigned"+++async def test_invalid_jwt_rbac_on_401(monkeypatch, _patch_attach):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ _patch_verify(monkeypatch, None) # verification failed+ req = _FakeRequest({"X-OpenRAG-JWT": "garbage"})++ with pytest.raises(HTTPException) as exc:+ await get_api_key_user_async(req, api_key_service=None, session_manager=None)+ assert exc.value.status_code == 401+ assert exc.value.detail == "Invalid or unverifiable JWT"+++async def test_invalid_jwt_rbac_off_falls_through_to_api_key(monkeypatch):+ """RBAC off + bad JWT -> ignore the JWT and require an API key (terminal 401)."""+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "false")+ monkeypatch.setenv("IBM_AUTH_ENABLED", "false")+ _patch_verify(monkeypatch, None)+ req = _FakeRequest({"X-OpenRAG-JWT": "garbage"}) # no API key header++ with pytest.raises(HTTPException) as exc:+ await get_api_key_user_async(req, api_key_service=None, session_manager=None)+ # Fell through to the API-key path's terminal "API key required".+ assert exc.value.status_code == 401+ assert exc.value.detail["error"] == "API key required"+++async def test_no_header_does_not_engage_jwt_path(monkeypatch):+ """No JWT header -> the JWT branch is skipped entirely (regression guard)."""+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ monkeypatch.setenv("IBM_AUTH_ENABLED", "false")++ def _boom(*a, **k): # must never be called when no header present+ raise AssertionError("verify_jwt_from_issuer should not run without the header")++ monkeypatch.setattr(config_utils, "verify_jwt_from_issuer", _boom)+ req = _FakeRequest({})++ with pytest.raises(HTTPException) as exc:+ await get_api_key_user_async(req, api_key_service=None, session_manager=None)+ assert exc.value.status_code == 401+ assert exc.value.detail["error"] == "API key required"diff --git a/tests/unit/dependencies/test_require_api_key_permission.py b/tests/unit/dependencies/test_require_api_key_permission.pynew file mode 100644index 000000000..27ba40348--- /dev/null+++ b/tests/unit/dependencies/test_require_api_key_permission.py@@ -0,0 +1,158 @@+"""require_api_key_permission — RBAC gate for the /v1 (API-key / forwarded-JWT)+surface.++Mirrors require_permission but resolves identity via get_api_key_user_async.+Same kill-switch bypass and 403 detail shape. We seed an in-memory catalog,+build admin/user/viewer personas, override get_api_key_user_async ++get_rbac_service, and drive a probe route plus one real /v1 handler to prove the+gate is wired end-to-end.+"""++import sys+from pathlib import Path++import httpx+import pytest+import pytest_asyncio+from fastapi import Depends, FastAPI, Request+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine+from sqlmodel import SQLModel++ROOT = Path(__file__).resolve().parent.parent.parent.parent+SRC = ROOT / "src"+if str(SRC) not in sys.path:+ sys.path.insert(0, str(SRC))++import db.models # noqa: E402,F401+from api.v1.documents import delete_document_endpoint # noqa: E402+from db.repositories import RoleRepo # noqa: E402+from db.seed import seed_roles_and_permissions # noqa: E402+from dependencies import ( # noqa: E402+ get_api_key_user_async,+ get_rbac_service,+ get_session_manager,+ require_api_key_permission,+)+from services.rbac_service import RBACService # noqa: E402+from services.user_service import ensure_user_row # noqa: E402+from session_manager import User # noqa: E402+++@pytest_asyncio.fixture+async def app(monkeypatch):+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ engine = create_async_engine(+ "sqlite+aiosqlite:///:memory:",+ connect_args={"check_same_thread": False},+ )+ async with engine.begin() as conn:+ await conn.run_sync(SQLModel.metadata.create_all)+ SessionLocal = async_sessionmaker(engine, expire_on_commit=False)++ personas: dict[str, User] = {}+ async with SessionLocal() as s:+ await seed_roles_and_permissions(s)+ role_repo = RoleRepo(s)+ user_role = await role_repo.get_by_name("user")++ async def _persona(uid: str, role_name: str) -> User:+ row = await ensure_user_row(+ s, User(user_id=uid, email=f"{uid}@x", name=uid, provider="ibm_ams")+ )+ if role_name != "user": # default role is already "user"+ await role_repo.revoke_role(row.id, user_role.id)+ await role_repo.assign_role(row.id, (await role_repo.get_by_name(role_name)).id)+ return User(user_id=row.id, email=f"{uid}@x", name=uid, provider="ibm_ams")++ personas["admin"] = await _persona("admin-sub", "admin")+ personas["user"] = await _persona("user-sub", "user")+ personas["viewer"] = await _persona("viewer-sub", "viewer")+ await s.commit()++ rbac = RBACService(SessionLocal)+ fastapi_app = FastAPI()++ async def _stub_api_user(request: Request) -> User:+ return personas[request.headers.get("X-Test-Persona", "user")]++ fastapi_app.dependency_overrides[get_api_key_user_async] = _stub_api_user+ fastapi_app.dependency_overrides[get_rbac_service] = lambda: rbac+ # Stubbed so the real /v1 handler's sibling deps resolve; the gate still+ # raises 403 for a denied persona before the body runs.+ fastapi_app.dependency_overrides[get_session_manager] = lambda: object()++ @fastapi_app.get("/probe/users-delete")+ async def _probe_admin(user=Depends(require_api_key_permission("users:delete"))):+ return {"user_id": user.user_id}++ @fastapi_app.get("/probe/chat-use")+ async def _probe_chat(user=Depends(require_api_key_permission("chat:use"))):+ return {"user_id": user.user_id}++ # A real gated /v1 handler. The gate runs as a dependency *before* the+ # handler body, so a denied request never reaches the delete core (no+ # service overrides needed for the 403 path).+ fastapi_app.add_api_route("/v1/documents", delete_document_endpoint, methods=["DELETE"])++ yield fastapi_app, personas+ await engine.dispose()+++def _client(fastapi_app):+ return httpx.AsyncClient(transport=httpx.ASGITransport(app=fastapi_app), base_url="http://t")+++async def test_kill_switch_off_bypasses(app, monkeypatch):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "false")+ fastapi_app, _ = app+ async with _client(fastapi_app) as c:+ # 'user' lacks users:delete, but the kill switch lets it through+ r = await c.get("/probe/users-delete", headers={"X-Test-Persona": "user"})+ assert r.status_code == 200+++async def test_admin_passes_when_enforced(app, monkeypatch):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ fastapi_app, _ = app+ async with _client(fastapi_app) as c:+ r = await c.get("/probe/users-delete", headers={"X-Test-Persona": "admin"})+ assert r.status_code == 200+++async def test_user_denied_when_enforced(app, monkeypatch):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ fastapi_app, _ = app+ async with _client(fastapi_app) as c:+ r = await c.get("/probe/users-delete", headers={"X-Test-Persona": "user"})+ assert r.status_code == 403+ assert r.json()["detail"]["required"] == "users:delete"+++async def test_user_passes_perm_it_holds(app, monkeypatch):+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ fastapi_app, _ = app+ async with _client(fastapi_app) as c:+ r = await c.get("/probe/chat-use", headers={"X-Test-Persona": "user"})+ assert r.status_code == 200+++async def test_real_v1_delete_blocks_viewer(app, monkeypatch):+ """End-to-end wiring: DELETE /v1/documents is gated on knowledge:delete:own.+ A viewer lacks it, so the real handler returns 403 from the gate before the+ body runs."""+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")+ fastapi_app, _ = app+ async with _client(fastapi_app) as c:+ r = await c.request(+ "DELETE",+ "/v1/documents",+ json={"filename": "x.txt"},+ headers={"X-Test-Persona": "viewer"},+ )+ assert r.status_code == 403+ assert r.json()["detail"]["required"] == "knowledge:delete:own"