Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

fix: resolve lakehouse credentials on the /v1 JWT auth path and gate knowledge-filter reads (#1861)

Edwin Jose0b3e0d1b69ff
diff --git a/src/api/knowledge_filter.py b/src/api/knowledge_filter.py
index 7f0e1a315..88b19cba3 100644
--- a/src/api/knowledge_filter.py
+++ b/src/api/knowledge_filter.py
@@ -1,20 +1,20 @@
-from typing import Optional, Any, List
+import json
+import uuid
+from datetime import datetime
+from typing import Any
from fastapi import Depends, Request
-from pydantic import BaseModel
from fastapi.responses import JSONResponse
-import uuid
-import json
-from datetime import datetime
-from utils.logging_config import get_logger
+from pydantic import BaseModel
+
from dependencies import (
get_knowledge_filter_service,
get_monitor_service,
get_session_manager,
- get_current_user,
require_permission,
)
from session_manager import User
+from utils.logging_config import get_logger
logger = get_logger(__name__)
@@ -55,9 +55,9 @@ def normalize_query_data(query_data: str | dict) -> str:
class CreateFilterBody(BaseModel):
name: str
description: str = ""
- queryData: Optional[Any] = None
- allowedUsers: List[str] = []
- allowedGroups: List[str] = []
+ queryData: Any | None = None
+ allowedUsers: list[str] = []
+ allowedGroups: list[str] = []
class SearchFiltersBody(BaseModel):
@@ -66,15 +66,15 @@ class SearchFiltersBody(BaseModel):
class UpdateFilterBody(BaseModel):
- name: Optional[str] = None
- description: Optional[str] = None
- queryData: Optional[Any] = None
- allowedUsers: Optional[List[str]] = None
- allowedGroups: Optional[List[str]] = None
+ name: str | None = None
+ description: str | None = None
+ queryData: Any | None = None
+ allowedUsers: list[str] | None = None
+ allowedGroups: list[str] | None = None
class SubscribeBody(BaseModel):
- notification_config: Optional[dict] = None
+ notification_config: dict | None = None
async def create_knowledge_filter(
@@ -129,7 +129,7 @@ async def search_knowledge_filters(
body: SearchFiltersBody,
knowledge_filter_service=Depends(get_knowledge_filter_service),
session_manager=Depends(get_session_manager),
- user: User = Depends(get_current_user),
+ user: User = Depends(require_permission("kf:read")),
):
"""Search for knowledge filters by name, description, or query content"""
jwt_token = user.jwt_token
@@ -151,7 +151,7 @@ async def get_knowledge_filter(
filter_id: str,
knowledge_filter_service=Depends(get_knowledge_filter_service),
session_manager=Depends(get_session_manager),
- user: User = Depends(get_current_user),
+ user: User = Depends(require_permission("kf:read")),
):
"""Get a specific knowledge filter by ID"""
jwt_token = user.jwt_token
@@ -185,7 +185,9 @@ async def update_knowledge_filter(
filter_id, user_id=user.user_id, jwt_token=jwt_token
)
if not existing_result.get("success"):
- return JSONResponse({"error": "Knowledge filter not found or access denied"}, status_code=404)
+ return JSONResponse(
+ {"error": "Knowledge filter not found or access denied"}, status_code=404
+ )
existing_filter = existing_result["filter"]
@@ -193,7 +195,9 @@ async def update_knowledge_filter(
filter_id, user_id=user.user_id, jwt_token=jwt_token
)
if not delete_result.get("success"):
- return JSONResponse({"error": "Failed to delete existing knowledge filter"}, status_code=500)
+ return JSONResponse(
+ {"error": "Failed to delete existing knowledge filter"}, status_code=500
+ )
query_data = body.queryData if body.queryData is not None else existing_filter["query_data"]
try:
@@ -205,11 +209,17 @@ async def update_knowledge_filter(
updated_filter = {
"id": filter_id,
"name": body.name if body.name is not None else existing_filter["name"],
- "description": body.description if body.description is not None else existing_filter["description"],
+ "description": body.description
+ if body.description is not None
+ else existing_filter["description"],
"query_data": normalized_query_data,
"owner": existing_filter["owner"],
- "allowed_users": body.allowedUsers if body.allowedUsers is not None else existing_filter.get("allowed_users", []),
- "allowed_groups": body.allowedGroups if body.allowedGroups is not None else existing_filter.get("allowed_groups", []),
+ "allowed_users": body.allowedUsers
+ if body.allowedUsers is not None
+ else existing_filter.get("allowed_users", []),
+ "allowed_groups": body.allowedGroups
+ if body.allowedGroups is not None
+ else existing_filter.get("allowed_groups", []),
"created_at": existing_filter["created_at"],
"updated_at": datetime.utcnow().isoformat(),
}
@@ -246,7 +256,9 @@ async def delete_knowledge_filter(
error_msg = result.get("error", "")
if "not found" in error_msg.lower() or "already deleted" in error_msg.lower():
return JSONResponse(result, status_code=404)
- elif "access denied" in error_msg.lower() or "insufficient permissions" in error_msg.lower():
+ elif (
+ "access denied" in error_msg.lower() or "insufficient permissions" in error_msg.lower()
+ ):
return JSONResponse(result, status_code=403)
else:
return JSONResponse(result, status_code=500)
@@ -258,7 +270,7 @@ async def subscribe_to_knowledge_filter(
knowledge_filter_service=Depends(get_knowledge_filter_service),
monitor_service=Depends(get_monitor_service),
session_manager=Depends(get_session_manager),
- user: User = Depends(get_current_user),
+ user: User = Depends(require_permission("kf:read")),
):
"""Create a subscription to a knowledge filter"""
jwt_token = user.jwt_token
@@ -267,7 +279,9 @@ async def subscribe_to_knowledge_filter(
filter_id, user_id=user.user_id, jwt_token=jwt_token
)
if not filter_result.get("success"):
- return JSONResponse({"error": "Knowledge filter not found or access denied"}, status_code=404)
+ return JSONResponse(
+ {"error": "Knowledge filter not found or access denied"}, status_code=404
+ )
filter_doc = filter_result["filter"]
@@ -315,7 +329,7 @@ async def list_knowledge_filter_subscriptions(
filter_id: str,
knowledge_filter_service=Depends(get_knowledge_filter_service),
session_manager=Depends(get_session_manager),
- user: User = Depends(get_current_user),
+ user: User = Depends(require_permission("kf:read")),
):
"""List subscriptions for a knowledge filter"""
jwt_token = user.jwt_token
@@ -341,7 +355,7 @@ async def cancel_knowledge_filter_subscription(
knowledge_filter_service=Depends(get_knowledge_filter_service),
monitor_service=Depends(get_monitor_service),
session_manager=Depends(get_session_manager),
- user: User = Depends(get_current_user),
+ user: User = Depends(require_permission("kf:read")),
):
"""Cancel a subscription to a knowledge filter"""
jwt_token = user.jwt_token
@@ -350,7 +364,9 @@ async def cancel_knowledge_filter_subscription(
filter_id, user_id=user.user_id, jwt_token=jwt_token
)
if not subscriptions_result.get("success"):
- return JSONResponse({"error": "Knowledge filter not found or access denied"}, status_code=404)
+ return JSONResponse(
+ {"error": "Knowledge filter not found or access denied"}, status_code=404
+ )
subscription = None
for sub in subscriptions_result.get("subscriptions", []):
@@ -368,7 +384,9 @@ async def cancel_knowledge_filter_subscription(
)
if remove_result.get("success"):
- return JSONResponse({"success": True, "message": "Subscription cancelled successfully"}, status_code=200)
+ return JSONResponse(
+ {"success": True, "message": "Subscription cancelled successfully"}, status_code=200
+ )
else:
return JSONResponse({"error": "Failed to cancel subscription"}, status_code=500)
diff --git a/src/api/v1/knowledge_filters.py b/src/api/v1/knowledge_filters.py
index f7a728869..50ce656bb 100644
--- a/src/api/v1/knowledge_filters.py
+++ b/src/api/v1/knowledge_filters.py
@@ -10,7 +10,6 @@ from fastapi import Depends
from api import knowledge_filter
from dependencies import (
- get_api_key_user_async,
get_knowledge_filter_service,
get_session_manager,
require_api_key_permission,
@@ -41,7 +40,7 @@ async def search_endpoint(
body: knowledge_filter.SearchFiltersBody,
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:read")),
):
"""
Search knowledge filters.
@@ -60,7 +59,7 @@ async def get_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:read")),
):
"""
Get a specific knowledge filter by ID.
diff --git a/src/db/seed.py b/src/db/seed.py
index 5e5d2b115..625bc204d 100644
--- a/src/db/seed.py
+++ b/src/db/seed.py
@@ -59,6 +59,7 @@ PERMISSIONS: list[tuple[str, str, str]] = [
("knowledge", "read:own", "Read own documents"),
("knowledge", "read:all", "Read all documents"),
("kf", "create", "Create knowledge filters"),
+ ("kf", "read", "Read knowledge filters"),
("kf", "edit:own", "Edit own knowledge filters"),
("kf", "edit:any", "Edit any knowledge filter"),
("kf", "share", "Share knowledge filters"),
@@ -118,6 +119,7 @@ def _developer_perms() -> set[str]:
"knowledge:delete:own",
"knowledge:read:own",
"kf:create",
+ "kf:read",
"kf:edit:own",
"chat:use",
"search:use",
@@ -142,6 +144,7 @@ def _user_perms() -> set[str]:
"knowledge:delete:own",
"knowledge:read:own",
"kf:create",
+ "kf:read",
"kf:edit:own",
"chat:use",
"search:use",
@@ -158,6 +161,7 @@ def _viewer_perms() -> set[str]:
return {
"chat:use",
"search:use",
+ "kf:read",
"conversations:read:own",
"conversations:delete:own",
"flows:read",
diff --git a/src/dependencies.py b/src/dependencies.py
index 3c8ea6747..77236195c 100644
--- a/src/dependencies.py
+++ b/src/dependencies.py
@@ -496,6 +496,73 @@ def _stage_jwt_roles(request: Request, claims: dict, user_id: str | None) -> Non
request.state.jwt_roles = jwt_roles
+async def _resolve_lakehouse_credentials(
+ request: Request, user_id: str | None
+) -> tuple[str | None, str | None]:
+ """Resolve the lakehouse Basic credentials used for the user-scoped
+ OpenSearch client. Shared by the session-cookie surface (``_get_ibm_user``)
+ and the /v1 JWT-in-header surface (``get_api_key_user_async``):
+
+ 1. The configured credentials header (Traefik production). Also
+ persisted to the connections store so background processes and
+ later header-less requests can reuse them.
+ 2. The user's stored ``ibm_credentials`` connection.
+
+ Returns ``(opensearch_username, base64_basic_credentials)`` or
+ ``(None, None)``. Never raises — callers degrade to the user's JWT.
+ """
+ from auth.ibm_auth import extract_ibm_credentials
+ from config.settings import IBM_CREDENTIALS_HEADER
+
+ connector_service = None
+ app_state = getattr(getattr(request, "app", None), "state", None)
+ services = getattr(app_state, "services", None)
+ if services:
+ connector_service = services.get("connector_service")
+
+ lh_credentials = request.headers.get(IBM_CREDENTIALS_HEADER, "")
+ if lh_credentials and lh_credentials.strip() != "":
+ logger.debug("[AUTH] IBM LH credentials found in request headers")
+ opensearch_username, _ = extract_ibm_credentials(lh_credentials)
+ upsert_user_id = user_id or opensearch_username
+ if connector_service and upsert_user_id:
+ logger.debug("[AUTH] Upserting IBM LH credentials to connections store")
+ try:
+ await connector_service.connection_manager.upsert_ibm_credentials(
+ user_id=upsert_user_id,
+ basic_credentials=lh_credentials,
+ username=upsert_user_id,
+ )
+ except Exception as exc: # noqa: BLE001 — persistence is best-effort
+ logger.warning(
+ "[AUTH] Failed to persist IBM LH credentials to connections store",
+ user_id=upsert_user_id,
+ error=str(exc),
+ )
+ return opensearch_username, lh_credentials
+
+ if connector_service and user_id:
+ try:
+ connections = await connector_service.connection_manager.list_connections(
+ user_id=user_id, connector_type="ibm_credentials"
+ )
+ except Exception as exc: # noqa: BLE001 — auth must degrade, not 500
+ logger.warning(
+ "[AUTH] Failed to read IBM LH credentials from connections store",
+ user_id=user_id,
+ error=str(exc),
+ )
+ connections = []
+ if connections:
+ lh_credentials = connections[0].config.get("basic_credentials")
+ if lh_credentials and lh_credentials.strip() != "":
+ logger.debug("[AUTH] IBM LH credentials found in connections store")
+ opensearch_username, _ = extract_ibm_credentials(lh_credentials)
+ return opensearch_username, lh_credentials
+
+ return None, None
+
+
async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:
"""Authenticate via upstream auth.
@@ -512,7 +579,6 @@ async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:
from auth.ibm_auth import extract_ibm_credentials
from auth.jwt_roles import jwt_roles_enabled
from config.settings import (
- IBM_CREDENTIALS_HEADER,
IBM_SESSION_COOKIE_NAME,
PLATFORM_PASSWORD,
PLATFORM_USERNAME,
@@ -541,9 +607,6 @@ async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:
request.state.user = user
return user
- # ── Option 0: Configurable credentials header (Traefik production) ───
-
- lh_credentials = request.headers.get(IBM_CREDENTIALS_HEADER, "")
# When RBAC/JWT-role sync is on, the gateway forwards the end-user JWT in the
# configured header; use it as the source of identity and roles. When RBAC is
# off, preserve the existing ibm-openrag-session cookie flow.
@@ -592,25 +655,12 @@ async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:
# 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")
- opensearch_username, _ = extract_ibm_credentials(lh_credentials)
- logger.debug("[AUTH] IBM LH credentials extracted successfully")
+ opensearch_username, lh_credentials = await _resolve_lakehouse_credentials(request, user_id)
+
+ if lh_credentials:
user_id = user_id or opensearch_username
email = email or opensearch_username
name = name or opensearch_username
-
- # Persist credentials to connections.json for reuse by background processes
- connector_service = request.app.state.services.get("connector_service")
- if connector_service and user_id:
- logger.debug("[AUTH] Upserting IBM LH credentials to connections.json")
- await connector_service.connection_manager.upsert_ibm_credentials(
- user_id=user_id,
- basic_credentials=lh_credentials,
- username=user_id,
- )
- logger.debug("[AUTH] IBM LH credentials upserted successfully")
-
user = User(
user_id=user_id,
email=email,
@@ -626,39 +676,18 @@ async def _get_ibm_user(request: Request, required: bool) -> Optional["User"]:
return user
if ibm_token and user_id:
- logger.debug("[AUTH] IBM JWT cookie present and user_id found")
- logger.debug("[AUTH] LH credentials not available in header, reading from connections.json")
- # lh credentials not available in header, read from connections service
- connector_service = request.app.state.services.get("connector_service")
- if connector_service:
- connections = await connector_service.connection_manager.list_connections(
- user_id=user_id, connector_type="ibm_credentials"
- )
- if connections:
- lh_credentials = connections[0].config.get("basic_credentials")
- opensearch_username = None
- opensearch_credentials = None
- jwt_token = f"Bearer {ibm_token}"
- if lh_credentials and lh_credentials.strip() != "":
- logger.debug("[AUTH] IBM LH credentials found in connections.json")
- opensearch_username, _ = extract_ibm_credentials(lh_credentials)
- logger.debug("[AUTH] IBM LH credentials extracted successfully")
- opensearch_credentials = lh_credentials
- logger.debug("[AUTH] IBM LH credentials set successfully")
- jwt_token = f"Basic {lh_credentials}"
- else:
- logger.warning(
- "[AUTH] IBM LH credentials not found in header or connections store. Using JWT token instead."
- )
+ logger.warning(
+ "[AUTH] IBM LH credentials not found in header or connections store. Using JWT token instead."
+ )
user = User(
user_id=user_id,
email=email,
name=name,
picture=None,
provider="ibm_ams",
- jwt_token=jwt_token,
- opensearch_username=opensearch_username,
- opensearch_credentials=opensearch_credentials,
+ jwt_token=f"Bearer {ibm_token}",
+ opensearch_username=None,
+ opensearch_credentials=None,
)
logger.debug("[AUTH] User created successfully")
request.state.user = user
@@ -815,7 +844,7 @@ async def get_api_key_user_async(
# 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.settings import IBM_AUTH_ENABLED, get_jwt_auth_header
from config.utils import resolve_jwt_claims
raw_jwt = request.headers.get(get_jwt_auth_header(), "")
@@ -840,17 +869,72 @@ async def get_api_key_user_async(
jwt_token=f"Bearer {token}",
)
_stage_jwt_roles(request, claims, user.user_id)
+ # The forwarded JWT is primary for ALL operations (identity, roles,
+ # and downstream OpenSearch calls, which validate it via OIDC) —
+ # same as the session surface (_get_ibm_user). NOTE (gateway
+ # requirement): under RBAC this JWT is also the authoritative role
+ # source. Traefik must mint it with the user's real OpenRAG role
+ # claims (same as the UI session JWT), otherwise every /v1 call
+ # re-syncs the user down to whatever the claim carries.
request.state.user = user
- return await _attach_db_user_id(request, user)
+ return await _attach_request_user(request, user, session_manager)
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")
+ logger.error(
+ "[AUTH] JWT in request header failed verification/decode",
+ header_name=get_jwt_auth_header(),
+ )
+ raise HTTPException(
+ status_code=401,
+ detail={
+ "error": "invalid_jwt",
+ "message": (
+ f"The JWT in the '{get_jwt_auth_header()}' header could not be "
+ "verified or decoded. Ensure the gateway forwards a valid, "
+ "unexpired user JWT issued by a trusted identity provider."
+ ),
+ },
+ )
# RBAC off + missing/invalid JWT -> fall through to the API-key path.
+ else:
+ from utils.run_mode_utils import is_run_mode_saas
+
+ if is_run_mode_saas() and jwt_roles_enabled():
+ # In saas the gateway is responsible for forwarding the end-user
+ # JWT on every API/MCP request; its absence is a gateway
+ # misconfiguration, not a normal client state.
+ logger.error(
+ "[AUTH] JWT not found in request header — run_mode=saas with "
+ "RBAC enabled requires the gateway to forward the user JWT",
+ header_name=get_jwt_auth_header(),
+ )
+ if IBM_AUTH_ENABLED:
+ # No JWT — fall back to lakehouse Basic credentials (credentials
+ # header, upserted to the connections store), mirroring the
+ # session surface's header branch in _get_ibm_user.
+ os_username, lh_credentials = await _resolve_lakehouse_credentials(request, None)
+ if lh_credentials:
+ logger.info(
+ "[AUTH] Using IBM LH credentials as JWT token",
+ username=os_username,
+ )
+ user = User(
+ user_id=os_username,
+ email=os_username,
+ name=os_username,
+ picture=None,
+ provider="ibm_ams",
+ jwt_token=f"Basic {lh_credentials}",
+ opensearch_username=os_username,
+ opensearch_credentials=lh_credentials,
+ )
+ request.state.user = user
+ return await _attach_request_user(request, user, session_manager)
- from config.settings import IBM_AUTH_ENABLED
-
- # Upstream auth path: X-Username + X-Api-Key forwarded by the MCP via the SDK.
+ # Upstream auth path: X-Username + X-Api-Key sent directly by an MCP/SDK
+ # client. Not the SaaS path — there, Traefik consumes these headers for
+ # login and injects the JWT handled by the branch above.
if IBM_AUTH_ENABLED:
ibm_username = request.headers.get("X-Username")
ibm_api_key = request.headers.get("X-Api-Key")
diff --git a/tests/unit/db/test_rbac_seed_idempotency.py b/tests/unit/db/test_rbac_seed_idempotency.py
index 7f6a13137..41749d1e9 100644
--- a/tests/unit/db/test_rbac_seed_idempotency.py
+++ b/tests/unit/db/test_rbac_seed_idempotency.py
@@ -1,13 +1,12 @@
"""Verify db.seed.seed_roles_and_permissions is idempotent."""
-import os
import sys
from pathlib import Path
import pytest
import pytest_asyncio
-from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from sqlalchemy import select
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from sqlmodel import SQLModel
ROOT = Path(__file__).resolve().parent.parent.parent.parent
@@ -54,7 +53,13 @@ async def test_seed_creates_expected_rows(session):
admin_role = next(r for r in roles if r.name == "admin")
admin_perm_ids = {
rp.permission_id
- for rp in (await session.execute(select(RolePermission).where(RolePermission.role_id == admin_role.id))).scalars().all()
+ for rp in (
+ await session.execute(
+ select(RolePermission).where(RolePermission.role_id == admin_role.id)
+ )
+ )
+ .scalars()
+ .all()
}
assert len(admin_perm_ids) == len(PERMISSIONS)
@@ -85,3 +90,10 @@ async def test_role_permission_map_references_known_perms(session):
for role_name, expected in ROLE_PERMISSION_MAP.items():
missing = expected - perm_names
assert not missing, f"role {role_name} references unknown perms: {missing}"
+
+
+def test_every_builtin_role_grants_kf_read():
+ """Knowledge-filter read is gated (require_*_permission("kf:read")) on both
+ API surfaces; every built-in role must hold it or KF search/get breaks."""
+ for role_name, expected in ROLE_PERMISSION_MAP.items():
+ assert "kf:read" in expected, f"role {role_name} lacks kf:read"
diff --git a/tests/unit/dependencies/test_auth_jwt_attachment.py b/tests/unit/dependencies/test_auth_jwt_attachment.py
index 8f5b8102e..e2585c73b 100644
--- a/tests/unit/dependencies/test_auth_jwt_attachment.py
+++ b/tests/unit/dependencies/test_auth_jwt_attachment.py
@@ -45,7 +45,7 @@ def _request(cookies: dict[str, str] | None = None):
def _auth_settings(monkeypatch):
monkeypatch.setattr("config.settings.IBM_AUTH_ENABLED", False)
- async def _resolve_db_user_id(user):
+ async def _resolve_db_user_id(user, jwt_roles=None):
return user.user_id
monkeypatch.setattr(dependencies, "_resolve_db_user_id", _resolve_db_user_id)
diff --git a/tests/unit/dependencies/test_jwt_header_auth.py b/tests/unit/dependencies/test_jwt_header_auth.py
index 97ee6321b..f9e030af9 100644
--- a/tests/unit/dependencies/test_jwt_header_auth.py
+++ b/tests/unit/dependencies/test_jwt_header_auth.py
@@ -22,6 +22,9 @@ SRC = ROOT / "src"
if str(SRC) not in sys.path:
sys.path.insert(0, str(SRC))
+import base64 # noqa: E402
+
+import config.settings as app_settings # noqa: E402
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
@@ -30,10 +33,12 @@ 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):
+ def __init__(self, headers: dict | None = None, services: dict | None = None):
self.headers = headers or {}
self.cookies: dict[str, str] = {}
self.state = SimpleNamespace()
+ if services is not None:
+ self.app = SimpleNamespace(state=SimpleNamespace(services=services))
@pytest.fixture(autouse=True)
@@ -78,15 +83,15 @@ def test_stage_roles_rbac_on_no_role_401(monkeypatch):
@pytest.fixture
def _patch_attach(monkeypatch):
- """Replace _attach_db_user_id with a passthrough that records state."""
+ """Replace _attach_request_user with a passthrough that records state."""
captured = {}
- async def _fake_attach(request, user):
+ async def _fake_attach(request, user, session_manager, token_hint=None):
captured["jwt_roles"] = getattr(request.state, "jwt_roles", "UNSET")
captured["user"] = user
return user
- monkeypatch.setattr(deps, "_attach_db_user_id", _fake_attach)
+ monkeypatch.setattr(deps, "_attach_request_user", _fake_attach)
return captured
@@ -144,7 +149,8 @@ async def test_invalid_jwt_rbac_on_401(monkeypatch, _patch_attach):
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"
+ assert exc.value.detail["error"] == "invalid_jwt"
+ assert "could not be verified" in exc.value.detail["message"]
@pytest.mark.asyncio
@@ -178,3 +184,187 @@ async def test_no_header_does_not_engage_jwt_path(monkeypatch):
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"
+
+
+# ── get_api_key_user_async — lakehouse credential resolution (IBM auth) ─
+#
+# In SaaS, Traefik authenticates X-Username/X-Api-Key and injects the JWT.
+# When the JWT is present it is primary for ALL operations (identity, roles,
+# OpenSearch via OIDC) — credential resolution is skipped entirely. Only when
+# the JWT is absent do lakehouse Basic credentials (credentials header)
+# become the jwt_token, mirroring _get_ibm_user's header branch.
+
+_B64 = base64.b64encode(b"alice:secret").decode()
+_CLAIMS = {"sub": "s1", "username": "alice", "openrag_roles": ["admin"]}
+
+
+class _FakeConnectionManager:
+ def __init__(self, stored_credentials: str | None = None, broken: bool = False):
+ self.stored_credentials = stored_credentials
+ self.broken = broken
+ self.upserts: list[dict] = []
+
+ async def upsert_ibm_credentials(self, user_id, basic_credentials, username):
+ if self.broken:
+ raise RuntimeError("connections store unavailable")
+ self.upserts.append(
+ {"user_id": user_id, "basic_credentials": basic_credentials, "username": username}
+ )
+
+ async def list_connections(self, user_id, connector_type):
+ if self.broken:
+ raise RuntimeError("connections store unavailable")
+ if self.stored_credentials is None:
+ return []
+ return [SimpleNamespace(config={"basic_credentials": self.stored_credentials})]
+
+
+def _ibm_setup(monkeypatch, stored_credentials=None, broken=False):
+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")
+ monkeypatch.setattr(app_settings, "IBM_AUTH_ENABLED", True)
+ _patch_verify(monkeypatch, dict(_CLAIMS))
+ manager = _FakeConnectionManager(stored_credentials, broken=broken)
+ services = {"connector_service": SimpleNamespace(connection_manager=manager)}
+ return manager, services
+
+
+async def test_jwt_present_keeps_bearer_and_skips_credential_resolution(monkeypatch, _patch_attach):
+ """JWT present -> it is primary for everything; the credentials header is
+ ignored and nothing is persisted."""
+ manager, services = _ibm_setup(monkeypatch)
+ req = _FakeRequest(
+ {"X-OpenRAG-JWT": "Bearer tok", "X-IBM-LH-Credentials": _B64},
+ services=services,
+ )
+
+ user = await get_api_key_user_async(req, api_key_service=None, session_manager=None)
+
+ assert user.user_id == "alice" # identity stays JWT-derived
+ assert user.jwt_token == "Bearer tok"
+ assert user.opensearch_username is None
+ assert user.opensearch_credentials is None
+ assert manager.upserts == []
+
+
+async def test_jwt_present_never_queries_connections_store(monkeypatch, _patch_attach):
+ """A broken connections store cannot affect a JWT-authenticated request
+ because the store is never consulted when the JWT is present."""
+ _, services = _ibm_setup(monkeypatch, stored_credentials=_B64, broken=True)
+ req = _FakeRequest({"X-OpenRAG-JWT": "Bearer tok"}, services=services)
+
+ user = await get_api_key_user_async(req, api_key_service=None, session_manager=None)
+
+ assert user.jwt_token == "Bearer tok"
+ assert user.opensearch_credentials is None
+
+
+async def test_jwt_without_credentials_keeps_bearer(monkeypatch, _patch_attach):
+ """No lakehouse creds anywhere -> the JWT is the token (primary path)."""
+ _, services = _ibm_setup(monkeypatch)
+ req = _FakeRequest({"X-OpenRAG-JWT": "Bearer tok"}, services=services)
+
+ user = await get_api_key_user_async(req, api_key_service=None, session_manager=None)
+
+ assert user.jwt_token == "Bearer tok"
+ assert user.opensearch_credentials is None
+
+
+async def test_no_jwt_uses_lh_credentials_as_token(monkeypatch, _patch_attach):
+ """No JWT -> lakehouse credentials from the header become the Basic
+ jwt_token and the identity, mirroring _get_ibm_user's header branch."""
+ manager, services = _ibm_setup(monkeypatch)
+ req = _FakeRequest({"X-IBM-LH-Credentials": _B64}, services=services)
+
+ user = await get_api_key_user_async(req, api_key_service=None, session_manager=None)
+
+ assert user.user_id == "alice" # from the decoded credentials
+ assert user.jwt_token == f"Basic {_B64}"
+ assert user.opensearch_username == "alice"
+ assert user.opensearch_credentials == _B64
+ assert manager.upserts == [{"user_id": "alice", "basic_credentials": _B64, "username": "alice"}]
+
+
+async def test_no_jwt_broken_store_still_returns_header_credentials(monkeypatch, _patch_attach):
+ """A connections-store failure must not 500 the request: header credentials
+ are still used even when persisting them fails."""
+ _, services = _ibm_setup(monkeypatch, broken=True)
+ req = _FakeRequest({"X-IBM-LH-Credentials": _B64}, services=services)
+
+ user = await get_api_key_user_async(req, api_key_service=None, session_manager=None)
+
+ assert user.jwt_token == f"Basic {_B64}"
+ assert user.opensearch_credentials == _B64
+
+
+async def test_no_jwt_saas_rbac_on_logs_error(monkeypatch, _patch_attach):
+ """saas + RBAC enabled + no JWT header -> a clear error is logged and the
+ request still proceeds via the credentials-header fallback."""
+ manager, services = _ibm_setup(monkeypatch)
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "saas")
+ errors: list[str] = []
+ monkeypatch.setattr(deps.logger, "error", lambda msg, **kw: errors.append(msg))
+ req = _FakeRequest({"X-IBM-LH-Credentials": _B64}, services=services)
+
+ user = await get_api_key_user_async(req, api_key_service=None, session_manager=None)
+
+ assert user.jwt_token == f"Basic {_B64}"
+ assert any("JWT not found" in m for m in errors)
+
+
+async def test_no_jwt_saas_rbac_off_no_error_log(monkeypatch):
+ """saas + RBAC off + no JWT -> no error log (legacy API-key behavior)."""
+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "false")
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "saas")
+ monkeypatch.setattr(app_settings, "IBM_AUTH_ENABLED", False)
+ errors: list[str] = []
+ monkeypatch.setattr(deps.logger, "error", lambda msg, **kw: errors.append(msg))
+ 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 # API key required
+ assert errors == []
+
+
+async def test_invalid_jwt_rbac_on_logs_error(monkeypatch, _patch_attach):
+ """Header present but unverifiable under RBAC -> 401 plus a clear
+ 'failed verification' error log (distinct from the not-found case)."""
+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")
+ _patch_verify(monkeypatch, None)
+ errors: list[str] = []
+ monkeypatch.setattr(deps.logger, "error", lambda msg, **kw: errors.append(msg))
+ 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 any("failed verification" in m for m in errors)
+
+
+async def test_x_username_headers_never_become_credentials(monkeypatch, _patch_attach):
+ """X-Username/X-Api-Key are Traefik's login concern — when the JWT is
+ present the backend must not build OpenSearch credentials from them."""
+ _, services = _ibm_setup(monkeypatch)
+ req = _FakeRequest(
+ {
+ "X-OpenRAG-JWT": "Bearer tok",
+ "X-Username": "alice",
+ "X-Api-Key": "lakehouse-api-key",
+ },
+ services=services,
+ )
+
+ 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" # not a Basic token minted from X-*
+ assert user.opensearch_credentials is None
diff --git a/tests/unit/dependencies/test_require_api_key_permission.py b/tests/unit/dependencies/test_require_api_key_permission.py
index 27ba40348..e9b4a6258 100644
--- a/tests/unit/dependencies/test_require_api_key_permission.py
+++ b/tests/unit/dependencies/test_require_api_key_permission.py
@@ -25,10 +25,12 @@ if str(SRC) not in sys.path:
import db.models # noqa: E402,F401
from api.v1.documents import delete_document_endpoint # noqa: E402
+from api.v1.knowledge_filters import search_endpoint as kf_search_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_knowledge_filter_service,
get_rbac_service,
get_session_manager,
require_api_key_permission,
@@ -67,6 +69,15 @@ async def app(monkeypatch):
personas["admin"] = await _persona("admin-sub", "admin")
personas["user"] = await _persona("user-sub", "user")
personas["viewer"] = await _persona("viewer-sub", "viewer")
+
+ # A user with no roles at all — every gated route must 403.
+ norole_row = await ensure_user_row(
+ s, User(user_id="norole-sub", email="norole@x", name="norole", provider="ibm_ams")
+ )
+ await role_repo.revoke_role(norole_row.id, user_role.id)
+ personas["norole"] = User(
+ user_id=norole_row.id, email="norole@x", name="norole", provider="ibm_ams"
+ )
await s.commit()
rbac = RBACService(SessionLocal)
@@ -89,10 +100,17 @@ async def app(monkeypatch):
async def _probe_chat(user=Depends(require_api_key_permission("chat:use"))):
return {"user_id": user.user_id}
+ @fastapi_app.get("/probe/kf-read")
+ async def _probe_kf_read(user=Depends(require_api_key_permission("kf:read"))):
+ 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"])
+ # Real KF search handler — proves the kf:read gate is wired on /v1.
+ fastapi_app.dependency_overrides[get_knowledge_filter_service] = lambda: object()
+ fastapi_app.add_api_route("/v1/knowledge-filters/search", kf_search_endpoint, methods=["POST"])
yield fastapi_app, personas
await engine.dispose()
@@ -140,6 +158,34 @@ async def test_user_passes_perm_it_holds(app, monkeypatch):
assert r.status_code == 200
+async def test_kf_read_granted_to_every_builtin_role(app, monkeypatch):
+ """All built-in roles (even viewer) hold kf:read, so KF search/get keep
+ working for existing API consumers once the gate is enforced."""
+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")
+ fastapi_app, _ = app
+ async with _client(fastapi_app) as c:
+ for persona in ("admin", "user", "viewer"):
+ r = await c.get("/probe/kf-read", headers={"X-Test-Persona": persona})
+ assert r.status_code == 200, persona
+
+
+async def test_real_v1_kf_search_gated_on_kf_read(app, monkeypatch):
+ """End-to-end wiring: POST /v1/knowledge-filters/search now requires
+ kf:read instead of accepting any authenticated caller."""
+ monkeypatch.setenv("OPENRAG_RBAC_ENFORCE", "true")
+ fastapi_app, _ = app
+ async with _client(fastapi_app) as c:
+ r = await c.post(
+ "/v1/knowledge-filters/search",
+ json={"query": ""},
+ headers={"X-Test-Persona": "norole"},
+ )
+ assert r.status_code == 403
+ assert r.json()["detail"]["required"] == "kf:read"
+
+
@pytest.mark.asyncio
async def test_real_v1_delete_blocks_viewer(app, monkeypatch):
"""End-to-end wiring: DELETE /v1/documents is gated on knowledge:delete:own.