Skip to content

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

Python

refactor (#2032)

Edwin Jose1591ee4d0061
diff --git a/src/auth/permission_dependencies.py b/src/auth/permission_dependencies.py
new file mode 100644
index 000000000..4142fd9ee
--- /dev/null
+++ b/src/auth/permission_dependencies.py
@@ -0,0 +1,143 @@
+"""Permission enforcement helpers for request identity dependencies."""
+
+import dataclasses
+from collections.abc import Sequence
+
+from fastapi import HTTPException, Request
+
+from auth.request_identity import _attach_db_user_id
+from auth.user_identity_cache import _resolve_db_user_id
+from session_manager import User
+
+
+async def enforce_permission(request: Request, user: User, rbac, perm: str) -> User:
+ """Enforce one browser-authenticated permission."""
+ from services.rbac_service import is_rbac_enforced
+
+ if not is_rbac_enforced():
+ # RBAC kill-switch: still resolve the DB id so downstream
+ # ownership checks that compare against it keep working.
+ return await _attach_db_user_id(request, user)
+ role_override = getattr(request.state, "api_key_role_ids", None)
+ db_user_id = await _resolve_db_user_id(user)
+ user = dataclasses.replace(user, db_user_id=db_user_id)
+ request.state.db_user_id = db_user_id
+ request.state.user = user
+ 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
+
+
+async def enforce_any_permission(
+ request: Request,
+ user: User,
+ rbac,
+ required: Sequence[str],
+) -> User:
+ """Require at least one browser-authenticated permission."""
+ from services.rbac_service import is_rbac_enforced
+
+ if not is_rbac_enforced():
+ return await _attach_db_user_id(request, user)
+ role_override = getattr(request.state, "api_key_role_ids", None)
+ db_user_id = await _resolve_db_user_id(user)
+ user = dataclasses.replace(user, db_user_id=db_user_id)
+ request.state.db_user_id = db_user_id
+ request.state.user = user
+ perms = await rbac.get_user_permissions(db_user_id, role_override=role_override)
+ if not any(perm in perms for perm in required):
+ await rbac.audit_denied(db_user_id, "|".join(required))
+ raise HTTPException(
+ status_code=403,
+ detail={"error": "permission_denied", "required": list(required)},
+ )
+ return user
+
+
+async def enforce_all_permissions(
+ request: Request,
+ user: User,
+ rbac,
+ required: Sequence[str],
+) -> User:
+ """Require all listed browser-authenticated permissions."""
+ from services.rbac_service import is_rbac_enforced
+
+ if not is_rbac_enforced():
+ return await _attach_db_user_id(request, user)
+ role_override = getattr(request.state, "api_key_role_ids", None)
+ db_user_id = await _resolve_db_user_id(user)
+ user = dataclasses.replace(user, db_user_id=db_user_id)
+ request.state.db_user_id = db_user_id
+ request.state.user = user
+ perms = await rbac.get_user_permissions(db_user_id, role_override=role_override)
+ missing = [perm for perm in required if perm not in perms]
+ if missing:
+ await rbac.audit_denied(db_user_id, ",".join(missing))
+ raise HTTPException(
+ status_code=403,
+ detail={"error": "permission_denied", "required": list(required)},
+ )
+ return user
+
+
+async def enforce_api_key_permission(request: Request, user: User, rbac, perm: str) -> User:
+ """Enforce one API-key or forwarded-JWT permission."""
+ from services.rbac_service import is_rbac_enforced
+
+ 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
+
+
+async def enforce_api_key_any_permission(
+ request: Request,
+ user: User,
+ rbac,
+ required: Sequence[str],
+) -> User:
+ """Require at least one API-key or forwarded-JWT permission."""
+ from services.rbac_service import is_rbac_enforced
+
+ 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 not any(perm in perms for perm in required):
+ await rbac.audit_denied(db_user_id, "|".join(required))
+ raise HTTPException(
+ status_code=403,
+ detail={"error": "permission_denied", "required": list(required)},
+ )
+ return user
+
+
+async def has_effective_permission(
+ request: Request,
+ user: User,
+ rbac,
+ perm: str,
+) -> bool:
+ """Check a permission using the same RBAC and API-key override semantics as route gates."""
+ from services.rbac_service import is_rbac_enforced
+
+ if not is_rbac_enforced():
+ return True
+ user_id = user.db_user_id or user.user_id
+ role_override = getattr(request.state, "api_key_role_ids", None)
+ return await rbac.has_permission(user_id, perm, role_override=role_override)
diff --git a/src/auth/request_identity.py b/src/auth/request_identity.py
new file mode 100644
index 000000000..7308bb215
--- /dev/null
+++ b/src/auth/request_identity.py
@@ -0,0 +1,698 @@
+"""Request identity resolution for browser, upstream, and API-key auth."""
+
+import base64
+import dataclasses
+import hashlib
+from typing import Optional
+
+from fastapi import HTTPException, Request
+
+from auth.user_identity_cache import _resolve_db_user_id
+from session_manager import User
+from utils.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Header names whose values must never be logged verbatim. Logged as a
+# redacted fingerprint (length + sha prefix) so a value can be correlated
+# across hops without exposing the secret.
+_SENSITIVE_HEADERS = {
+ "authorization",
+ "x-openrag-api-jwt",
+ "x-api-key",
+ "x-username",
+ "cookie",
+ "x-ibm-lh-credentials",
+}
+
+
+def _redact_header(name: str, value: str) -> str:
+ """Redact a header value for logging — never emit the raw secret."""
+ if not value:
+ return ""
+ if name.lower() in _SENSITIVE_HEADERS:
+ digest = hashlib.sha256(value.encode("utf-8")).hexdigest()[:8]
+ return f"<redacted len={len(value)} sha={digest}>"
+ return value
+
+
+async def _attach_db_user_id(request: Request, user: User | None) -> User | None:
+ """Attach the internal SQL users.id to the request user.
+
+ `User.user_id` remains the external auth subject used in JWT/OpenSearch
+ flows. `User.db_user_id` is the OpenRAG owner id used by SQL-backed
+ RBAC and ownership tables.
+ """
+ if user is None:
+ request.state.db_user_id = None
+ request.state.user = None
+ return None
+ jwt_roles = getattr(request.state, "jwt_roles", None)
+ from config.settings import is_dev_role_toggle_enabled
+
+ if is_dev_role_toggle_enabled():
+ jwt_roles = None
+ db_user_id = await _resolve_db_user_id(user, jwt_roles=jwt_roles)
+ user_with_db_id = dataclasses.replace(user, db_user_id=db_user_id)
+ request.state.db_user_id = db_user_id
+ request.state.user = user_with_db_id
+ return user_with_db_id
+
+
+async def _attach_opensearch_jwt(
+ request: Request,
+ user: User | None,
+ session_manager,
+ token_hint: str | None = None,
+) -> User | None:
+ """Attach OpenSearch auth state and refresh DLS principal lookup state."""
+ if user is None:
+ return None
+
+ effective_token = session_manager.get_effective_jwt_token(
+ user.user_id,
+ token_hint if token_hint is not None else user.jwt_token,
+ )
+ if effective_token != user.jwt_token:
+ user = dataclasses.replace(user, jwt_token=effective_token)
+
+ services = getattr(getattr(request, "app", None), "state", None)
+ services = getattr(services, "services", {}) or {}
+ dls_principal_service = services.get("dls_principal_service")
+
+ if dls_principal_service is not None:
+ try:
+ principals = await dls_principal_service.refresh_user_principals(user)
+ request.state.opensearch_dls_principals = principals
+ except Exception as e:
+ logger.warning(
+ "Failed to refresh OpenSearch DLS principals",
+ user_id=user.user_id,
+ error=str(e),
+ )
+
+ request.state.opensearch_group_roles = []
+
+ return user
+
+
+async def _attach_request_user(
+ request: Request,
+ user: User | None,
+ session_manager,
+ token_hint: str | None = None,
+) -> User | None:
+ user_with_opensearch_jwt = await _attach_opensearch_jwt(
+ request,
+ user,
+ session_manager,
+ token_hint=token_hint,
+ )
+ return await _attach_db_user_id(request, user_with_opensearch_jwt)
+
+
+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",
+ )
+ logger.debug(f"JWT roles: {jwt_roles}")
+ 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 (``resolve_api_key_user``).
+ """
+ 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.
+
+ 0. Configured credentials header containing OpenSearch credentials.
+ 1. Configured session cookie. When JWT-role sync is enabled, the JWT is
+ instead read from the gateway-forwarded header named by ``get_jwt_auth_header()``;
+ identity and roles both come from that token.
+ 2. Local dev basic-auth cookie.
+
+ If *required* is True, raises HTTP 401 when none is present.
+ If *required* is False, returns None instead of raising.
+ """
+ import auth.ibm_auth as ibm_auth
+ from auth.ibm_auth import extract_ibm_credentials
+ from auth.jwt_roles import jwt_roles_enabled
+ from config.settings import (
+ IBM_SESSION_COOKIE_NAME,
+ PLATFORM_PASSWORD,
+ PLATFORM_USERNAME,
+ get_jwt_auth_header,
+ )
+ from config.utils import resolve_jwt_claims
+
+ # ── Option -1: Environment variable override (local dev/calls) ───────
+
+ if PLATFORM_USERNAME and PLATFORM_PASSWORD:
+ logger.debug("[AUTH] Using PLATFORM_USERNAME and PLATFORM_PASSWORD from environment")
+ creds = f"{PLATFORM_USERNAME}:{PLATFORM_PASSWORD}"
+ lh_credentials = base64.b64encode(creds.encode()).decode()
+ user = User(
+ user_id=PLATFORM_USERNAME,
+ email=PLATFORM_USERNAME,
+ name=PLATFORM_USERNAME,
+ picture=None,
+ provider="ibm_ams_env",
+ jwt_token=f"Basic {lh_credentials}",
+ opensearch_username=PLATFORM_USERNAME,
+ opensearch_credentials=lh_credentials,
+ )
+ request.state.user = user
+ return user
+
+ # 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.
+ if jwt_roles_enabled():
+ header_name = get_jwt_auth_header()
+ raw_jwt = request.headers.get(header_name, "")
+ logger.debug(
+ "[AUTH] JWT-role header lookup",
+ header_name=header_name,
+ jwt_present=bool(raw_jwt and raw_jwt.strip()),
+ )
+ ibm_token = (
+ raw_jwt[7:].strip() if raw_jwt.startswith("Bearer ") else raw_jwt.strip()
+ ) or None
+
+ claims = resolve_jwt_claims(ibm_token)
+ else:
+ ibm_token = request.cookies.get(IBM_SESSION_COOKIE_NAME)
+ claims = None
+ user_id = None
+ email = None
+ name = 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 = None
+ if ibm_token:
+ if claims is None:
+ logger.debug("[AUTH] IBM JWT token found in request cookies")
+ claims = ibm_auth.decode_ibm_jwt(ibm_token)
+ if claims is not None:
+ logger.debug(
+ "[AUTH] JWT claims resolved"
+ if jwt_roles_enabled()
+ else "[AUTH] IBM JWT claims decoded successfully"
+ )
+ sub = claims.get("sub")
+ if not sub:
+ logger.warning(
+ "IBM JWT is missing required 'sub' claim; treating as unauthenticated"
+ )
+ else:
+ user_id = claims.get("username", sub)
+ email = claims.get("username", sub)
+ name = claims.get("display_name", claims.get("username", sub))
+ # 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)
+
+ from utils.run_mode_utils import is_run_mode_saas
+
+ saas_rbac = is_run_mode_saas() and jwt_roles_enabled()
+
+ # The forwarded end-user JWT is the OpenSearch credential — OpenSearch's
+ # openid_auth_domain validates it via the backend JWKS. Build it once; it's
+ # used both as the saas+rbac authoritative credential and as the header-less
+ # fallback in other modes.
+ jwt_user = None
+ if ibm_token and user_id:
+ jwt_user = User(
+ user_id=user_id,
+ email=email,
+ name=name,
+ picture=None,
+ provider="ibm_ams",
+ jwt_token=f"Bearer {ibm_token}",
+ opensearch_username=None,
+ opensearch_credentials=None,
+ )
+
+ # In SaaS + RBAC the JWT is authoritative: the lakehouse `X-IBM-LH-Credentials`
+ # Basic credential must NOT override it (when the gateway began injecting that
+ # header, OpenSearch rejected the Basic cred with 401 and every data-plane call
+ # surfaced as a misleading 403 "insufficient permissions"). Return before
+ # `_resolve_lakehouse_credentials` so its connections-store upsert side effect
+ # is also skipped. Mirrors the /v1 surface, which already treats the JWT as
+ # primary.
+ if saas_rbac:
+ if jwt_user:
+ logger.debug(
+ "[AUTH] User created from forwarded JWT (saas+rbac; lakehouse creds bypassed)"
+ )
+ request.state.user = jwt_user
+ return jwt_user
+ # saas + RBAC but no valid forwarded JWT (missing header, undecodable, or no
+ # `sub`). Do NOT degrade to lakehouse Basic creds or the debug cookie — that
+ # would authenticate (and write DB user/role rows) under a roles-less
+ # identity. Fail loud, mirroring resolve_api_key_user's saas_rbac branch.
+ request.state.user = None
+ if required:
+ logger.error(
+ "[AUTH] No valid forwarded JWT under saas+RBAC; refusing lakehouse/basic fallback",
+ jwt_present=bool(ibm_token),
+ )
+ raise HTTPException(
+ status_code=401,
+ detail={
+ "error": "invalid_jwt" if ibm_token else "missing_user_jwt",
+ "message": (
+ "No valid user JWT was forwarded by the gateway. In SaaS/RBAC "
+ "mode the gateway must forward the end-user JWT on every request."
+ ),
+ },
+ )
+ return None
+
+ # Other modes: lakehouse Basic creds take precedence when present.
+ 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
+ user = User(
+ user_id=user_id,
+ email=email,
+ name=name,
+ picture=None,
+ provider="ibm_ams",
+ jwt_token=f"Basic {lh_credentials}",
+ opensearch_username=opensearch_username,
+ opensearch_credentials=lh_credentials,
+ )
+ logger.debug("[AUTH] User created successfully")
+ request.state.user = user
+ return user
+
+ if jwt_user:
+ logger.warning(
+ "[AUTH] IBM LH credentials not found in header or connections store. Using JWT token instead."
+ )
+ request.state.user = jwt_user
+ return jwt_user
+
+ if ibm_token and not user_id:
+ logger.warning("IBM JWT cookie present but could not extract user_id from claims.")
+ request.state.user = None
+ return None
+
+ auth_header = request.cookies.get("ibm-auth-basic", "")
+ if auth_header.startswith("Basic "):
+ logger.debug("[AUTH] Debug mode enabled, extracting IBM LH credentials from cookie")
+ username, _ = extract_ibm_credentials(auth_header)
+ logger.debug("[AUTH] IBM LH credentials extracted successfully")
+ user = User(
+ user_id=username,
+ email=username,
+ name=username,
+ picture=None,
+ provider="ibm_ams_basic",
+ jwt_token=auth_header,
+ opensearch_username=username,
+ opensearch_credentials=auth_header,
+ )
+ logger.debug("[AUTH] User created successfully")
+ request.state.user = user
+ return user
+
+ # ── Neither present ──────────────────────────────────────────────────
+ if required:
+ raise HTTPException(status_code=401, detail="IBM authentication required")
+ request.state.user = None
+ return None
+
+
+async def resolve_current_user(request: Request, session_manager) -> User:
+ """Require JWT cookie authentication and attach request identity state."""
+ from config.settings import IBM_AUTH_ENABLED, is_no_auth_mode
+ from session_manager import AnonymousUser
+
+ # Upstream cookie auth takes priority when enabled.
+ if IBM_AUTH_ENABLED:
+ logger.debug("[AUTH] IBM auth mode enabled, getting current user")
+ user = await _get_ibm_user(request, required=True)
+ if user and user.user_id and user.user_id not in session_manager.users:
+ session_manager.users[user.user_id] = user
+ return await _attach_request_user(request, user, session_manager)
+
+ if is_no_auth_mode():
+ user = AnonymousUser()
+ return await _attach_request_user(request, user, session_manager)
+
+ auth_token = request.cookies.get("auth_token")
+ if not auth_token:
+ raise HTTPException(status_code=401, detail="Authentication required")
+
+ user = session_manager.get_user_from_token(auth_token)
+ if not user:
+ raise HTTPException(status_code=401, detail="Authentication required")
+
+ return await _attach_request_user(
+ request,
+ user,
+ session_manager,
+ token_hint=auth_token,
+ )
+
+
+async def resolve_optional_user(request: Request, session_manager) -> User | None:
+ """Optionally extract JWT cookie user and attach request identity state."""
+ from config.settings import IBM_AUTH_ENABLED, is_no_auth_mode
+ from session_manager import AnonymousUser
+
+ # Upstream cookie auth takes priority when enabled.
+ if IBM_AUTH_ENABLED:
+ logger.debug("[AUTH] IBM auth mode enabled, getting optional user")
+ user = await _get_ibm_user(request, required=False)
+ if user and user.user_id and user.user_id not in session_manager.users:
+ session_manager.users[user.user_id] = user
+ if user:
+ return await _attach_request_user(request, user, session_manager)
+ request.state.db_user_id = None
+ return None
+
+ if is_no_auth_mode():
+ user = AnonymousUser()
+ return await _attach_request_user(request, user, session_manager)
+
+ auth_token = request.cookies.get("auth_token")
+ if not auth_token:
+ request.state.user = None
+ return None
+
+ user = session_manager.get_user_from_token(auth_token)
+ if user:
+ return await _attach_request_user(
+ request,
+ user,
+ session_manager,
+ token_hint=auth_token,
+ )
+ request.state.user = None
+ request.state.db_user_id = None
+ return None
+
+
+async def resolve_api_key_user(request: Request, api_key_service, session_manager) -> User:
+ """Require API key or upstream authentication and attach request identity state."""
+ # ── 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 (
+ IBM_AUTH_ENABLED,
+ get_api_jwt_header,
+ get_jwt_auth_header,
+ )
+ from config.utils import resolve_jwt_claims
+ from utils.run_mode_utils import is_run_mode_saas
+
+ # SaaS/RBAC: the gateway MUST forward the end-user JWT on every /v1 request.
+ # When it doesn't, we must NOT silently degrade to lakehouse Basic creds —
+ # that path does DB user writes under a degraded identity and can clobber the
+ # shared users row the same person sees on UI login. Fail loud (401) with no
+ # DB side effects instead; explicit orag_ API-key auth still works.
+ saas_rbac = is_run_mode_saas() and jwt_roles_enabled()
+
+ # Primary: the gateway-forwarded JWT header (default Authorization).
+ # Fallback: the API/MCP add-on header — FastMCP strips Authorization before
+ # proxying an MCP tool call to this /v1 handler, so MCP/API callers supply
+ # the JWT in get_api_jwt_header() instead.
+ jwt_header = get_jwt_auth_header()
+ raw_jwt = request.headers.get(jwt_header, "")
+
+ safe_headers = {k: _redact_header(k, v) for k, v in request.headers.items()}
+ logger.debug("[AUTH] Incoming /v1 request headers (redacted)", headers=safe_headers)
+
+ if not (raw_jwt and raw_jwt.strip()):
+ jwt_header = get_api_jwt_header()
+ raw_jwt = request.headers.get(jwt_header, "")
+ logger.debug(
+ "[AUTH] API-key path JWT header lookup",
+ header_name=jwt_header,
+ jwt_present=bool(raw_jwt and raw_jwt.strip()),
+ jwt_preview=_redact_header(jwt_header, raw_jwt),
+ )
+ if raw_jwt and raw_jwt.strip():
+ token = raw_jwt[7:].strip() if raw_jwt.startswith("Bearer ") else raw_jwt.strip()
+ claims = resolve_jwt_claims(token)
+ 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)
+ logger.debug(
+ "[AUTH] API user authenticated via JWT",
+ user_id=user.user_id,
+ roles=getattr(request.state, "jwt_roles", None),
+ )
+ # 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_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.
+ logger.error(
+ "[AUTH] JWT in request header failed verification/decode",
+ header_name=jwt_header,
+ jwt_preview=_redact_header(jwt_header, raw_jwt),
+ )
+ raise HTTPException(
+ status_code=401,
+ detail={
+ "error": "invalid_jwt",
+ "message": (
+ f"The JWT in the '{jwt_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:
+ if saas_rbac:
+ # 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. Fail fast here —
+ # before any lakehouse / X-Username / API-key fallback — so no DB
+ # user/role write ever runs under a degraded (roles-less) identity.
+ 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=jwt_header,
+ authorization_present=bool(request.headers.get("authorization")),
+ api_jwt_present=bool(request.headers.get(get_api_jwt_header())),
+ seen_auth_headers={
+ k: _redact_header(k, v)
+ for k, v in request.headers.items()
+ if k.lower() in _SENSITIVE_HEADERS
+ },
+ )
+ raise HTTPException(
+ status_code=401,
+ detail={
+ "error": "missing_user_jwt",
+ "message": (
+ "No user JWT was forwarded by the gateway. In SaaS/RBAC "
+ "mode the gateway must forward the end-user JWT on every "
+ "/v1 request."
+ ),
+ },
+ )
+ 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)
+
+ # 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")
+ if ibm_username and ibm_api_key:
+ # check if ibm api key is base 64 encoded
+ userpass = f"{ibm_username}:{ibm_api_key}"
+ ibm_api_key_b64 = base64.b64encode(userpass.encode("utf-8")).decode("utf-8")
+
+ user = User(
+ user_id=ibm_username,
+ email=ibm_username,
+ name=ibm_username,
+ picture=None,
+ provider="ibm_ams",
+ jwt_token=f"Basic {ibm_api_key_b64}",
+ opensearch_username=ibm_username,
+ opensearch_credentials=ibm_api_key_b64,
+ )
+ return await _attach_request_user(request, user, session_manager)
+
+ # API key path
+ api_key = request.headers.get("X-API-Key")
+ if not api_key or not api_key.startswith("orag_"):
+ auth_header = request.headers.get("Authorization", "")
+ if auth_header.startswith("Bearer "):
+ token = auth_header[7:]
+ if token.startswith("orag_"):
+ api_key = token
+
+ if not api_key:
+ # saas_rbac is already handled by the fail-fast 401 above (no JWT ->
+ # missing_user_jwt), so reaching here means non-saas_rbac: prompt for
+ # an API key as before.
+ raise HTTPException(
+ status_code=401,
+ detail={
+ "error": "API key required",
+ "message": "Provide API key via X-API-Key header or Authorization: Bearer header",
+ },
+ )
+
+ user_info = await api_key_service.validate_key(api_key)
+ if not user_info:
+ raise HTTPException(
+ status_code=401,
+ detail={
+ "error": "Invalid API key",
+ "message": "The provided API key is invalid or has been revoked",
+ },
+ )
+
+ user = User(
+ user_id=user_info["user_id"],
+ email=user_info["user_email"],
+ name=user_info.get("name", "API User"),
+ picture=None,
+ provider="api_key",
+ )
+
+ # Register the API key user so get_effective_jwt_token can find them
+ if user.user_id not in session_manager.users:
+ session_manager.users[user.user_id] = user
+
+ request.state.api_key_id = user_info["key_id"]
+ # Phase 2 will populate api_key_role_ids from the SQL api_keys table.
+ # In Phase 1 we leave it unset so require_permission falls back to the
+ # user's live role membership (no privilege escalation possible).
+ request.state.api_key_role_ids = getattr(request.state, "api_key_role_ids", None)
+
+ return await _attach_request_user(request, user, session_manager)
diff --git a/src/auth/user_identity_cache.py b/src/auth/user_identity_cache.py
new file mode 100644
index 000000000..0f9d5c72d
--- /dev/null
+++ b/src/auth/user_identity_cache.py
@@ -0,0 +1,138 @@
+"""SQL user identity cache for authenticated requests.
+
+The request auth surface carries external OAuth subjects in ``User.user_id``.
+RBAC and ownership tables use the internal SQL ``users.id``. This module owns
+that translation, including the per-process cache and first-login race lock.
+"""
+
+import asyncio
+
+from cachetools import TTLCache
+from fastapi import HTTPException
+
+from session_manager import User
+from utils.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Maps composite "{provider}:{subject}" -> SQL users.id. Doubles as the
+# "we've already ensured a DB row for this user" cache so we don't pay
+# the round-trip on every authenticated request. Cleared on user/role
+# mutations via the rbac service invalidation hook.
+#
+# Necessary because legacy-migrated rows have id == user_id while older
+# Phase-1 new rows had id == uuid4(); permission lookups need the SQL id,
+# not the OAuth subject.
+#
+# The key is composite (provider, subject), NOT just user_id, because the
+# OAuth subject string alone is not unique across providers — e.g. the
+# synthetic `AnonymousUser` (provider="none", user_id="anonymous") must
+# not collide with a hypothetical real user whose IdP issued the same
+# subject string. Identity in this codebase is the (provider, subject)
+# pair (see `ensure_user_row` and the `(oauth_provider, oauth_subject)`
+# UNIQUE constraint on the users table).
+_ENSURED_USER_IDS: TTLCache[str, str] = TTLCache(maxsize=4096, ttl=300)
+
+# Per-(provider, subject) asyncio.Lock used to serialize concurrent
+# first-time `_ensure_db_user` calls for the SAME identity. Without
+# this, two requests racing through the cache miss → INSERT path both
+# observe an empty users table, both attempt INSERT, and the second
+# fails with `UNIQUE constraint failed: users.email_lookup_hash`. The
+# lock is scoped per-identity so unrelated logins never block each
+# other (and so two providers issuing the same subject string don't
+# share a lock).
+_ENSURE_LOCKS: dict[str, asyncio.Lock] = {}
+
+
+def _user_cache_key(user: User) -> str:
+ """Composite cache/lock key for a `User`.
+
+ Mirrors the (oauth_provider, oauth_subject) UNIQUE constraint in
+ the users table. The fallback to "unknown" matches `ensure_user_row`'s
+ behavior when `user.provider` is empty.
+ """
+ return f"{user.provider or 'unknown'}:{user.user_id}"
+
+
+async def _ensure_db_user(user: User, jwt_roles: list[str] | None = None) -> str | None:
+ """Best-effort DB upsert for the authenticated user. Returns the SQL
+ `users.id` for this user (so callers can cache the OAuth-sub → DB-id
+ mapping). Returns None on failure.
+
+ When ``jwt_roles`` is not None, the user's DB role assignments are
+ reconciled against it on every call — the per-process cache short-
+ circuits the user-row INSERT but not the role sync. Pass None to
+ preserve pre-JWT-roles behavior.
+
+ No-ops for anonymous users in no-auth mode beyond the very first call
+ (which does set up the synthetic anonymous row + role). Failures are
+ logged but never block the request.
+ """
+ if not user or not user.user_id:
+ return None
+ cache_key = _user_cache_key(user)
+ cached_db_id = _ENSURED_USER_IDS.get(cache_key)
+ if cached_db_id is not None and jwt_roles is None:
+ return cached_db_id
+
+ # Serialize concurrent first-time ensures for the SAME identity so a
+ # second caller observes the first's committed row instead of
+ # racing through the cache miss → INSERT path. Per-(provider,
+ # subject) lock so unrelated users never block each other.
+ lock = _ENSURE_LOCKS.setdefault(cache_key, asyncio.Lock())
+ async with lock:
+ cached_db_id = _ENSURED_USER_IDS.get(cache_key)
+ if cached_db_id is not None and jwt_roles is None:
+ return cached_db_id
+ try:
+ from db.engine import SessionLocal, init_engine
+ from services.user_service import ensure_user_row, sync_jwt_roles
+
+ if SessionLocal is None:
+ init_engine()
+ from db.engine import SessionLocal as _SessionLocal
+
+ if _SessionLocal is None:
+ return None
+ async with _SessionLocal() as session:
+ if cached_db_id is not None and jwt_roles is not None:
+ # User row already exists in this process; just reconcile
+ # roles from the JWT.
+ await sync_jwt_roles(session, cached_db_id, jwt_roles)
+ await session.commit()
+ return cached_db_id
+ db_row = await ensure_user_row(session, user, jwt_roles=jwt_roles)
+ await session.commit()
+ _ENSURED_USER_IDS[cache_key] = db_row.id
+ return db_row.id
+ except HTTPException:
+ raise
+ except Exception as exc: # noqa: BLE001
+ logger.warning("ensure_user_row failed", user_id=user.user_id, error=str(exc))
+ return None
+
+
+async def _resolve_db_user_id(user: User, jwt_roles: list[str] | None = None) -> str:
+ """Translate an authenticated `User` to the SQL ``users.id`` used by RBAC."""
+ if not user or not user.user_id:
+ return ""
+ if jwt_roles is None:
+ cached = _ENSURED_USER_IDS.get(_user_cache_key(user))
+ if cached is not None:
+ return cached
+ resolved = await _ensure_db_user(user, jwt_roles=jwt_roles)
+ return resolved or user.user_id
+
+
+def invalidate_user_ensured_cache(
+ oauth_provider: str | None = None,
+ oauth_subject: str | None = None,
+) -> None:
+ """Pop the ensure-cache + lock for a single identity, or clear all."""
+ if oauth_provider is None or oauth_subject is None:
+ _ENSURED_USER_IDS.clear()
+ _ENSURE_LOCKS.clear()
+ return
+ key = f"{oauth_provider or 'unknown'}:{oauth_subject}"
+ _ENSURED_USER_IDS.pop(key, None)
+ _ENSURE_LOCKS.pop(key, None)
diff --git a/src/dependencies.py b/src/dependencies.py
index 320aadcaa..8f7a95af4 100644
--- a/src/dependencies.py
+++ b/src/dependencies.py
@@ -15,86 +15,88 @@ Usage:
...
"""
-import asyncio
-import dataclasses
-import hashlib
from collections.abc import AsyncIterator, Sequence
-from typing import Optional
-from cachetools import TTLCache
-from fastapi import Depends, HTTPException, Request
+from fastapi import Depends, Request
from sqlalchemy.ext.asyncio import AsyncSession
+from auth.permission_dependencies import (
+ enforce_all_permissions,
+ enforce_any_permission,
+ enforce_api_key_any_permission,
+ enforce_api_key_permission,
+ enforce_permission,
+ has_effective_permission,
+)
+from auth.request_identity import (
+ _attach_db_user_id,
+ _attach_opensearch_jwt,
+ _attach_request_user,
+ _get_ibm_user,
+ _redact_header,
+ _resolve_lakehouse_credentials,
+ _stage_jwt_roles,
+ resolve_api_key_user,
+ resolve_current_user,
+ resolve_optional_user,
+)
+from auth.user_identity_cache import (
+ _ENSURE_LOCKS,
+ _ENSURED_USER_IDS,
+ _ensure_db_user,
+ _resolve_db_user_id,
+ _user_cache_key,
+ invalidate_user_ensured_cache,
+)
from session_manager import User
-from utils.logging_config import get_logger
-
-logger = get_logger(__name__)
-
-# Header names whose values must never be logged verbatim. Logged as a
-# redacted fingerprint (length + sha prefix) so a value can be correlated
-# across hops without exposing the secret.
-_SENSITIVE_HEADERS = {
- "authorization",
- "x-openrag-api-jwt",
- "x-api-key",
- "x-username",
- "cookie",
- "x-ibm-lh-credentials",
-}
-
-
-def _redact_header(name: str, value: str) -> str:
- """Redact a header value for logging — never emit the raw secret.
-
- Sensitive headers become ``'<redacted len=NN sha=abcd1234>'`` so values
- can be correlated across hops without exposing the token; non-sensitive
- headers pass through unchanged.
- """
- if not value:
- return ""
- if name.lower() in _SENSITIVE_HEADERS:
- digest = hashlib.sha256(value.encode("utf-8")).hexdigest()[:8]
- return f"<redacted len={len(value)} sha={digest}>"
- return value
-
-
-# Maps composite "{provider}:{subject}" -> SQL users.id. Doubles as the
-# "we've already ensured a DB row for this user" cache so we don't pay
-# the round-trip on every authenticated request. Cleared on user/role
-# mutations via the rbac service invalidation hook.
-#
-# Necessary because legacy-migrated rows have id == user_id while older
-# Phase-1 new rows had id == uuid4(); permission lookups need the SQL id,
-# not the OAuth subject.
-#
-# The key is composite (provider, subject), NOT just user_id, because the
-# OAuth subject string alone is not unique across providers — e.g. the
-# synthetic `AnonymousUser` (provider="none", user_id="anonymous") must
-# not collide with a hypothetical real user whose IdP issued the same
-# subject string. Identity in this codebase is the (provider, subject)
-# pair (see `ensure_user_row` and the `(oauth_provider, oauth_subject)`
-# UNIQUE constraint on the users table).
-_ENSURED_USER_IDS: TTLCache[str, str] = TTLCache(maxsize=4096, ttl=300)
-
-# Per-(provider, subject) asyncio.Lock used to serialize concurrent
-# first-time `_ensure_db_user` calls for the SAME identity. Without
-# this, two requests racing through the cache miss → INSERT path both
-# observe an empty users table, both attempt INSERT, and the second
-# fails with `UNIQUE constraint failed: users.email_lookup_hash`. The
-# lock is scoped per-identity so unrelated logins never block each
-# other (and so two providers issuing the same subject string don't
-# share a lock).
-_ENSURE_LOCKS: dict[str, asyncio.Lock] = {}
-
-
-def _user_cache_key(user: User) -> str:
- """Composite cache/lock key for a `User`.
-
- Mirrors the (oauth_provider, oauth_subject) UNIQUE constraint in
- the users table. The fallback to "unknown" matches `ensure_user_row`'s
- behavior when `user.provider` is empty.
- """
- return f"{user.provider or 'unknown'}:{user.user_id}"
+
+__all__ = [
+ "_ENSURE_LOCKS",
+ "_ENSURED_USER_IDS",
+ "_attach_db_user_id",
+ "_attach_opensearch_jwt",
+ "_attach_request_user",
+ "_ensure_db_user",
+ "_get_ibm_user",
+ "_redact_header",
+ "_resolve_db_user_id",
+ "_resolve_lakehouse_credentials",
+ "_stage_jwt_roles",
+ "_user_cache_key",
+ "get_api_key_service",
+ "get_api_key_user_async",
+ "get_auth_service",
+ "get_chat_service",
+ "get_connector_service",
+ "get_current_user",
+ "get_db_session",
+ "get_dls_principal_service",
+ "get_docling_polling_service",
+ "get_docling_service",
+ "get_document_index_writer",
+ "get_document_service",
+ "get_flows_service",
+ "get_group_acl_service",
+ "get_knowledge_filter_service",
+ "get_langflow_file_service",
+ "get_langflow_ingest_token_service",
+ "get_models_service",
+ "get_monitor_service",
+ "get_optional_user",
+ "get_rbac_service",
+ "get_search_service",
+ "get_services",
+ "get_session_manager",
+ "get_task_service",
+ "get_workspace_config_service",
+ "has_effective_permission",
+ "invalidate_user_ensured_cache",
+ "require_all_permissions",
+ "require_any_permission",
+ "require_api_key_any_permission",
+ "require_api_key_permission",
+ "require_permission",
+]
# ─────────────────────────────────────────────
@@ -208,219 +210,40 @@ async def get_db_session() -> AsyncIterator[AsyncSession]:
yield session
-async def _ensure_db_user(user: User, jwt_roles: list[str] | None = None) -> str | None:
- """Best-effort DB upsert for the authenticated user. Returns the SQL
- `users.id` for this user (so callers can cache the OAuth-sub → DB-id
- mapping). Returns None on failure.
-
- When ``jwt_roles`` is not None, the user's DB role assignments are
- reconciled against it on every call — the per-process cache short-
- circuits the user-row INSERT but not the role sync. Pass None to
- preserve pre-JWT-roles behavior.
-
- No-ops for anonymous users in no-auth mode beyond the very first call
- (which does set up the synthetic anonymous row + role). Failures are
- logged but never block the request.
- """
- if not user or not user.user_id:
- return None
- cache_key = _user_cache_key(user)
- cached_db_id = _ENSURED_USER_IDS.get(cache_key)
- if cached_db_id is not None and jwt_roles is None:
- return cached_db_id
-
- # Serialize concurrent first-time ensures for the SAME identity so a
- # second caller observes the first's committed row instead of
- # racing through the cache miss → INSERT path. Per-(provider,
- # subject) lock so unrelated users never block each other.
- lock = _ENSURE_LOCKS.setdefault(cache_key, asyncio.Lock())
- async with lock:
- cached_db_id = _ENSURED_USER_IDS.get(cache_key)
- if cached_db_id is not None and jwt_roles is None:
- return cached_db_id
- try:
- from db.engine import SessionLocal, init_engine
- from services.user_service import ensure_user_row, sync_jwt_roles
-
- if SessionLocal is None:
- init_engine()
- from db.engine import SessionLocal as _SessionLocal
-
- if _SessionLocal is None:
- return None
- async with _SessionLocal() as session:
- if cached_db_id is not None and jwt_roles is not None:
- # User row already exists in this process; just reconcile
- # roles from the JWT.
- await sync_jwt_roles(session, cached_db_id, jwt_roles)
- await session.commit()
- return cached_db_id
- db_row = await ensure_user_row(session, user, jwt_roles=jwt_roles)
- await session.commit()
- _ENSURED_USER_IDS[cache_key] = db_row.id
- return db_row.id
- except HTTPException:
- raise
- except Exception as exc: # noqa: BLE001
- logger.warning("ensure_user_row failed", user_id=user.user_id, error=str(exc))
- return None
-
-
-async def _resolve_db_user_id(user: User, jwt_roles: list[str] | None = None) -> str:
- """Translate an authenticated `User` (which carries the JWT/OAuth
- subject) to the SQL `users.id` used by the RBAC tables. Falls back to
- `user.user_id` if no DB row can be resolved (no-auth mode, transient
- DB error, etc.) so caller behavior degrades gracefully.
-
- When ``jwt_roles`` is not None, role sync runs on every call (the cache
- only short-circuits the INSERT, not the reconcile step).
- """
- if not user or not user.user_id:
- return ""
- if jwt_roles is None:
- cached = _ENSURED_USER_IDS.get(_user_cache_key(user))
- if cached is not None:
- return cached
- resolved = await _ensure_db_user(user, jwt_roles=jwt_roles)
- return resolved or user.user_id
-
-
-async def _attach_db_user_id(request: Request, user: User | None) -> User | None:
- """Attach the internal SQL users.id to the request user.
-
- `User.user_id` remains the external auth subject used in JWT/OpenSearch
- flows. `User.db_user_id` is the OpenRAG owner id used by SQL-backed
- RBAC and ownership tables.
- """
- if user is None:
- request.state.db_user_id = None
- request.state.user = None
- return None
- jwt_roles = getattr(request.state, "jwt_roles", None)
- from config.settings import is_dev_role_toggle_enabled
-
- if is_dev_role_toggle_enabled():
- jwt_roles = None
- db_user_id = await _resolve_db_user_id(user, jwt_roles=jwt_roles)
- user_with_db_id = dataclasses.replace(user, db_user_id=db_user_id)
- request.state.db_user_id = db_user_id
- request.state.user = user_with_db_id
- return user_with_db_id
-
-
-async def _attach_opensearch_jwt(
+async def get_current_user(
request: Request,
- user: User | None,
- session_manager,
- token_hint: str | None = None,
-) -> User | None:
- """Attach OpenSearch auth state and refresh DLS principal lookup state."""
- if user is None:
- return None
-
- effective_token = session_manager.get_effective_jwt_token(
- user.user_id,
- token_hint if token_hint is not None else user.jwt_token,
- )
- if effective_token != user.jwt_token:
- user = dataclasses.replace(user, jwt_token=effective_token)
-
- services = getattr(getattr(request, "app", None), "state", None)
- services = getattr(services, "services", {}) or {}
- dls_principal_service = services.get("dls_principal_service")
-
- if dls_principal_service is not None:
- try:
- principals = await dls_principal_service.refresh_user_principals(user)
- request.state.opensearch_dls_principals = principals
- except Exception as e:
- logger.warning(
- "Failed to refresh OpenSearch DLS principals",
- user_id=user.user_id,
- error=str(e),
- )
-
- request.state.opensearch_group_roles = []
-
- return user
-
-
-async def _attach_request_user(
+ session_manager=Depends(get_session_manager),
+) -> User:
+ """Require JWT cookie authentication."""
+ return await resolve_current_user(request, session_manager)
+
+
+async def get_optional_user(
request: Request,
- user: User | None,
- session_manager,
- token_hint: str | None = None,
+ session_manager=Depends(get_session_manager),
) -> User | None:
- user_with_opensearch_jwt = await _attach_opensearch_jwt(
- request,
- user,
- session_manager,
- token_hint=token_hint,
- )
- return await _attach_db_user_id(request, user_with_opensearch_jwt)
-
-
-def invalidate_user_ensured_cache(
- oauth_provider: str | None = None,
- oauth_subject: str | None = None,
-) -> None:
- """Pop the ensure-cache + lock for a single identity, or clear all
- if neither argument is provided.
-
- Called after admin mutations so role changes are picked up promptly.
- Identity is the (oauth_provider, oauth_subject) composite — the same
- shape used as the cache key.
- """
- if oauth_provider is None or oauth_subject is None:
- _ENSURED_USER_IDS.clear()
- _ENSURE_LOCKS.clear()
- return
- key = f"{oauth_provider or 'unknown'}:{oauth_subject}"
- _ENSURED_USER_IDS.pop(key, None)
- _ENSURE_LOCKS.pop(key, None)
+ """Optionally extract JWT cookie user."""
+ return await resolve_optional_user(request, session_manager)
-# ─────────────────────────────────────────────
-# Permission enforcement
-# ─────────────────────────────────────────────
+async def get_api_key_user_async(
+ request: Request,
+ api_key_service=Depends(get_api_key_service),
+ session_manager=Depends(get_session_manager),
+) -> User:
+ """Require API key or upstream authentication."""
+ return await resolve_api_key_user(request, api_key_service, session_manager)
def require_permission(perm: str):
- """FastAPI dependency factory enforcing a permission on the current user.
-
- Raises HTTP 403 with `{required: <perm>}` when the user lacks it.
- Honors API key role snapshots via `request.state.api_key_role_ids`.
-
- When ``OPENRAG_RBAC_ENFORCE=false`` the check is skipped and the
- authenticated user is returned unconditionally. The startup event
- in ``src/main.py`` refuses to boot when this flag is combined with
- a ``saas`` or ``on_prem`` run mode, so the bypass cannot silently
- land in production.
- """
- from services.rbac_service import is_rbac_enforced
+ """FastAPI dependency factory enforcing a permission on the current user."""
async def _dep(
request: Request,
user: User = Depends(get_current_user),
rbac=Depends(get_rbac_service),
) -> User:
- if not is_rbac_enforced():
- # RBAC kill-switch: still resolve the DB id so downstream
- # ownership checks that compare against it keep working.
- return await _attach_db_user_id(request, user)
- role_override = getattr(request.state, "api_key_role_ids", None)
- db_user_id = await _resolve_db_user_id(user)
- user = dataclasses.replace(user, db_user_id=db_user_id)
- request.state.db_user_id = db_user_id
- request.state.user = user
- 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 await enforce_permission(request, user, rbac, perm)
return _dep
@@ -431,780 +254,56 @@ def require_any_permission(required_perms: Sequence[str]):
if not required:
raise ValueError("require_any_permission requires at least one permission")
- from services.rbac_service import is_rbac_enforced
-
async def _dep(
request: Request,
user: User = Depends(get_current_user),
rbac=Depends(get_rbac_service),
) -> User:
- if not is_rbac_enforced():
- return await _attach_db_user_id(request, user)
- role_override = getattr(request.state, "api_key_role_ids", None)
- db_user_id = await _resolve_db_user_id(user)
- user = dataclasses.replace(user, db_user_id=db_user_id)
- request.state.db_user_id = db_user_id
- request.state.user = user
- perms = await rbac.get_user_permissions(db_user_id, role_override=role_override)
- if not any(perm in perms for perm in required):
- await rbac.audit_denied(db_user_id, "|".join(required))
- raise HTTPException(
- status_code=403,
- detail={"error": "permission_denied", "required": list(required)},
- )
- return user
+ return await enforce_any_permission(request, user, rbac, required)
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
+def require_all_permissions(required_perms: Sequence[str]):
+ """FastAPI dependency factory enforcing all listed permissions."""
+ required = tuple(required_perms)
+ if not required:
+ raise ValueError("require_all_permissions requires at least one permission")
async def _dep(
request: Request,
- user: User = Depends(get_api_key_user_async),
+ user: User = Depends(get_current_user),
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 await enforce_all_permissions(request, user, rbac, required)
return _dep
-def require_api_key_any_permission(required_perms: Sequence[str]):
- """Require at least one permission for an API-key or forwarded-JWT request."""
- required = tuple(required_perms)
- if not required:
- raise ValueError("require_api_key_any_permission requires at least one permission")
-
- from services.rbac_service import is_rbac_enforced
+def require_api_key_permission(perm: str):
+ """FastAPI dependency factory enforcing one /v1 permission."""
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 not any(perm in perms for perm in required):
- await rbac.audit_denied(db_user_id, "|".join(required))
- raise HTTPException(
- status_code=403,
- detail={"error": "permission_denied", "required": list(required)},
- )
- return user
+ return await enforce_api_key_permission(request, user, rbac, perm)
return _dep
-async def has_effective_permission(
- request: Request,
- user: User,
- rbac,
- perm: str,
-) -> bool:
- """Check a permission using the same RBAC and API-key override semantics as route gates."""
- from services.rbac_service import is_rbac_enforced
-
- if not is_rbac_enforced():
- return True
- user_id = user.db_user_id or user.user_id
- role_override = getattr(request.state, "api_key_role_ids", None)
- return await rbac.has_permission(user_id, perm, role_override=role_override)
-
-
-def require_all_permissions(required_perms: Sequence[str]):
- """FastAPI dependency factory enforcing all listed permissions."""
+def require_api_key_any_permission(required_perms: Sequence[str]):
+ """Require at least one permission for an API-key or forwarded-JWT request."""
required = tuple(required_perms)
if not required:
- raise ValueError("require_all_permissions requires at least one permission")
-
- from services.rbac_service import is_rbac_enforced
+ raise ValueError("require_api_key_any_permission requires at least one permission")
async def _dep(
request: Request,
- user: User = Depends(get_current_user),
+ user: User = Depends(get_api_key_user_async),
rbac=Depends(get_rbac_service),
) -> User:
- if not is_rbac_enforced():
- return await _attach_db_user_id(request, user)
- role_override = getattr(request.state, "api_key_role_ids", None)
- db_user_id = await _resolve_db_user_id(user)
- user = dataclasses.replace(user, db_user_id=db_user_id)
- request.state.db_user_id = db_user_id
- request.state.user = user
- perms = await rbac.get_user_permissions(db_user_id, role_override=role_override)
- missing = [perm for perm in required if perm not in perms]
- if missing:
- await rbac.audit_denied(db_user_id, ",".join(missing))
- raise HTTPException(
- status_code=403,
- detail={"error": "permission_denied", "required": list(required)},
- )
- return user
+ return await enforce_api_key_any_permission(request, user, rbac, required)
return _dep
-
-
-# ─────────────────────────────────────────────
-# Upstream authentication helper
-# ─────────────────────────────────────────────
-
-
-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",
- )
- logger.debug(f"JWT roles: {jwt_roles}")
- 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.
-
- 0. Configured credentials header containing OpenSearch credentials.
- 1. Configured session cookie. When JWT-role sync is enabled, the JWT is
- instead read from the gateway-forwarded header named by ``get_jwt_auth_header()``;
- identity and roles both come from that token.
- 2. Local dev basic-auth cookie.
-
- If *required* is True, raises HTTP 401 when none is present.
- If *required* is False, returns None instead of raising.
- """
- import auth.ibm_auth as ibm_auth
- from auth.ibm_auth import extract_ibm_credentials
- from auth.jwt_roles import jwt_roles_enabled
- from config.settings import (
- IBM_SESSION_COOKIE_NAME,
- PLATFORM_PASSWORD,
- PLATFORM_USERNAME,
- get_jwt_auth_header,
- )
- from config.utils import resolve_jwt_claims
-
- # ── Option -1: Environment variable override (local dev/calls) ───────
-
- if PLATFORM_USERNAME and PLATFORM_PASSWORD:
- import base64
-
- logger.debug("[AUTH] Using PLATFORM_USERNAME and PLATFORM_PASSWORD from environment")
- creds = f"{PLATFORM_USERNAME}:{PLATFORM_PASSWORD}"
- lh_credentials = base64.b64encode(creds.encode()).decode()
- user = User(
- user_id=PLATFORM_USERNAME,
- email=PLATFORM_USERNAME,
- name=PLATFORM_USERNAME,
- picture=None,
- provider="ibm_ams_env",
- jwt_token=f"Basic {lh_credentials}",
- opensearch_username=PLATFORM_USERNAME,
- opensearch_credentials=lh_credentials,
- )
- request.state.user = user
- return user
-
- # 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.
- if jwt_roles_enabled():
- header_name = get_jwt_auth_header()
- raw_jwt = request.headers.get(header_name, "")
- logger.debug(
- "[AUTH] JWT-role header lookup",
- header_name=header_name,
- jwt_present=bool(raw_jwt and raw_jwt.strip()),
- )
- ibm_token = (
- raw_jwt[7:].strip() if raw_jwt.startswith("Bearer ") else raw_jwt.strip()
- ) or None
-
- claims = resolve_jwt_claims(ibm_token)
- else:
- ibm_token = request.cookies.get(IBM_SESSION_COOKIE_NAME)
- claims = None
- user_id = None
- email = None
- name = 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 = None
- if ibm_token:
- if claims is None:
- logger.debug("[AUTH] IBM JWT token found in request cookies")
- claims = ibm_auth.decode_ibm_jwt(ibm_token)
- if claims is not None:
- logger.debug(
- "[AUTH] JWT claims resolved"
- if jwt_roles_enabled()
- else "[AUTH] IBM JWT claims decoded successfully"
- )
- sub = claims.get("sub")
- if not sub:
- logger.warning(
- "IBM JWT is missing required 'sub' claim; treating as unauthenticated"
- )
- else:
- user_id = claims.get("username", sub)
- email = claims.get("username", sub)
- name = claims.get("display_name", claims.get("username", sub))
- # 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)
-
- from utils.run_mode_utils import is_run_mode_saas
-
- saas_rbac = is_run_mode_saas() and jwt_roles_enabled()
-
- # The forwarded end-user JWT is the OpenSearch credential — OpenSearch's
- # openid_auth_domain validates it via the backend JWKS. Build it once; it's
- # used both as the saas+rbac authoritative credential and as the header-less
- # fallback in other modes.
- jwt_user = None
- if ibm_token and user_id:
- jwt_user = User(
- user_id=user_id,
- email=email,
- name=name,
- picture=None,
- provider="ibm_ams",
- jwt_token=f"Bearer {ibm_token}",
- opensearch_username=None,
- opensearch_credentials=None,
- )
-
- # In SaaS + RBAC the JWT is authoritative: the lakehouse `X-IBM-LH-Credentials`
- # Basic credential must NOT override it (when the gateway began injecting that
- # header, OpenSearch rejected the Basic cred with 401 and every data-plane call
- # surfaced as a misleading 403 "insufficient permissions"). Return before
- # `_resolve_lakehouse_credentials` so its connections-store upsert side effect
- # is also skipped. Mirrors the /v1 surface, which already treats the JWT as
- # primary.
- if saas_rbac:
- if jwt_user:
- logger.debug(
- "[AUTH] User created from forwarded JWT (saas+rbac; lakehouse creds bypassed)"
- )
- request.state.user = jwt_user
- return jwt_user
- # saas + RBAC but no valid forwarded JWT (missing header, undecodable, or no
- # `sub`). Do NOT degrade to lakehouse Basic creds or the debug cookie — that
- # would authenticate (and write DB user/role rows) under a roles-less
- # identity. Fail loud, mirroring get_api_key_user_async's saas_rbac branch.
- request.state.user = None
- if required:
- logger.error(
- "[AUTH] No valid forwarded JWT under saas+RBAC; refusing lakehouse/basic fallback",
- jwt_present=bool(ibm_token),
- )
- raise HTTPException(
- status_code=401,
- detail={
- "error": "invalid_jwt" if ibm_token else "missing_user_jwt",
- "message": (
- "No valid user JWT was forwarded by the gateway. In SaaS/RBAC "
- "mode the gateway must forward the end-user JWT on every request."
- ),
- },
- )
- return None
-
- # Other modes: lakehouse Basic creds take precedence when present.
- 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
- user = User(
- user_id=user_id,
- email=email,
- name=name,
- picture=None,
- provider="ibm_ams",
- jwt_token=f"Basic {lh_credentials}",
- opensearch_username=opensearch_username,
- opensearch_credentials=lh_credentials,
- )
- logger.debug("[AUTH] User created successfully")
- request.state.user = user
- return user
-
- if jwt_user:
- logger.warning(
- "[AUTH] IBM LH credentials not found in header or connections store. Using JWT token instead."
- )
- request.state.user = jwt_user
- return jwt_user
-
- if ibm_token and not user_id:
- logger.warning("IBM JWT cookie present but could not extract user_id from claims.")
- request.state.user = None
- return None
-
- auth_header = request.cookies.get("ibm-auth-basic", "")
- if auth_header.startswith("Basic "):
- logger.debug("[AUTH] Debug mode enabled, extracting IBM LH credentials from cookie")
- username, _ = extract_ibm_credentials(auth_header)
- logger.debug("[AUTH] IBM LH credentials extracted successfully")
- user = User(
- user_id=username,
- email=username,
- name=username,
- picture=None,
- provider="ibm_ams_basic",
- jwt_token=auth_header,
- opensearch_username=username,
- opensearch_credentials=auth_header,
- )
- logger.debug("[AUTH] User created successfully")
- request.state.user = user
- return user
-
- # ── Neither present ──────────────────────────────────────────────────
- if required:
- raise HTTPException(status_code=401, detail="IBM authentication required")
- request.state.user = None
- return None
-
-
-# ─────────────────────────────────────────────
-# Authentication dependencies
-# ─────────────────────────────────────────────
-
-
-async def get_current_user(
- request: Request,
- session_manager=Depends(get_session_manager),
-) -> User:
- """
- Require JWT cookie authentication.
-
- Sets request.state.user.
- Raises HTTP 401 if the user is not authenticated.
- """
- from config.settings import IBM_AUTH_ENABLED, is_no_auth_mode
- from session_manager import AnonymousUser
-
- # Upstream cookie auth takes priority when enabled.
- if IBM_AUTH_ENABLED:
- logger.debug("[AUTH] IBM auth mode enabled, getting current user")
- user = await _get_ibm_user(request, required=True)
- if user and user.user_id and user.user_id not in session_manager.users:
- session_manager.users[user.user_id] = user
- return await _attach_request_user(request, user, session_manager)
-
- if is_no_auth_mode():
- user = AnonymousUser()
- return await _attach_request_user(request, user, session_manager)
-
- auth_token = request.cookies.get("auth_token")
- if not auth_token:
- raise HTTPException(status_code=401, detail="Authentication required")
-
- user = session_manager.get_user_from_token(auth_token)
- if not user:
- raise HTTPException(status_code=401, detail="Authentication required")
-
- return await _attach_request_user(
- request,
- user,
- session_manager,
- token_hint=auth_token,
- )
-
-
-async def get_optional_user(
- request: Request,
- session_manager=Depends(get_session_manager),
-) -> User | None:
- """
- Optionally extract JWT cookie user.
-
- Sets request.state.user (may be None).
- Never raises — returns None if unauthenticated.
- """
- from config.settings import IBM_AUTH_ENABLED, is_no_auth_mode
- from session_manager import AnonymousUser
-
- # Upstream cookie auth takes priority when enabled.
- if IBM_AUTH_ENABLED:
- logger.debug("[AUTH] IBM auth mode enabled, getting optional user")
- user = await _get_ibm_user(request, required=False)
- if user and user.user_id and user.user_id not in session_manager.users:
- session_manager.users[user.user_id] = user
- if user:
- return await _attach_request_user(request, user, session_manager)
- request.state.db_user_id = None
- return None
-
- if is_no_auth_mode():
- user = AnonymousUser()
- return await _attach_request_user(request, user, session_manager)
-
- auth_token = request.cookies.get("auth_token")
- if not auth_token:
- request.state.user = None
- return None
-
- user = session_manager.get_user_from_token(auth_token)
- if user:
- return await _attach_request_user(
- request,
- user,
- session_manager,
- token_hint=auth_token,
- )
- request.state.user = None
- request.state.db_user_id = None
- return None
-
-
-async def get_api_key_user_async(
- request: Request,
- api_key_service=Depends(get_api_key_service),
- session_manager=Depends(get_session_manager),
-) -> User:
- """
- Async dependency: require API key or upstream 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 upstream auth mode is enabled
-
- Raises HTTP 401 if no valid credentials are provided.
- """
- 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 (
- IBM_AUTH_ENABLED,
- get_api_jwt_header,
- get_jwt_auth_header,
- )
- from config.utils import resolve_jwt_claims
- from utils.run_mode_utils import is_run_mode_saas
-
- # SaaS/RBAC: the gateway MUST forward the end-user JWT on every /v1 request.
- # When it doesn't, we must NOT silently degrade to lakehouse Basic creds —
- # that path does DB user writes under a degraded identity and can clobber the
- # shared users row the same person sees on UI login. Fail loud (401) with no
- # DB side effects instead; explicit orag_ API-key auth still works.
- saas_rbac = is_run_mode_saas() and jwt_roles_enabled()
-
- # Primary: the gateway-forwarded JWT header (default Authorization).
- # Fallback: the API/MCP add-on header — FastMCP strips Authorization before
- # proxying an MCP tool call to this /v1 handler, so MCP/API callers supply
- # the JWT in get_api_jwt_header() instead.
- jwt_header = get_jwt_auth_header()
- raw_jwt = request.headers.get(jwt_header, "")
-
- safe_headers = {k: _redact_header(k, v) for k, v in request.headers.items()}
- logger.debug("[AUTH] Incoming /v1 request headers (redacted)", headers=safe_headers)
-
- if not (raw_jwt and raw_jwt.strip()):
- jwt_header = get_api_jwt_header()
- raw_jwt = request.headers.get(jwt_header, "")
- logger.debug(
- "[AUTH] API-key path JWT header lookup",
- header_name=jwt_header,
- jwt_present=bool(raw_jwt and raw_jwt.strip()),
- jwt_preview=_redact_header(jwt_header, raw_jwt),
- )
- if raw_jwt and raw_jwt.strip():
- token = raw_jwt[7:].strip() if raw_jwt.startswith("Bearer ") else raw_jwt.strip()
- claims = resolve_jwt_claims(token)
- 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)
- logger.debug(
- "[AUTH] API user authenticated via JWT",
- user_id=user.user_id,
- roles=getattr(request.state, "jwt_roles", None),
- )
- # 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_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.
- logger.error(
- "[AUTH] JWT in request header failed verification/decode",
- header_name=jwt_header,
- jwt_preview=_redact_header(jwt_header, raw_jwt),
- )
- raise HTTPException(
- status_code=401,
- detail={
- "error": "invalid_jwt",
- "message": (
- f"The JWT in the '{jwt_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:
- if saas_rbac:
- # 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. Fail fast here —
- # before any lakehouse / X-Username / API-key fallback — so no DB
- # user/role write ever runs under a degraded (roles-less) identity.
- 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=jwt_header,
- authorization_present=bool(request.headers.get("authorization")),
- api_jwt_present=bool(request.headers.get(get_api_jwt_header())),
- seen_auth_headers={
- k: _redact_header(k, v)
- for k, v in request.headers.items()
- if k.lower() in _SENSITIVE_HEADERS
- },
- )
- raise HTTPException(
- status_code=401,
- detail={
- "error": "missing_user_jwt",
- "message": (
- "No user JWT was forwarded by the gateway. In SaaS/RBAC "
- "mode the gateway must forward the end-user JWT on every "
- "/v1 request."
- ),
- },
- )
- 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)
-
- # 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")
- if ibm_username and ibm_api_key:
- # check if ibm api key is base 64 encoded
- userpass = f"{ibm_username}:{ibm_api_key}"
- ibm_api_key_b64 = base64.b64encode(userpass.encode("utf-8")).decode("utf-8")
-
- user = User(
- user_id=ibm_username,
- email=ibm_username,
- name=ibm_username,
- picture=None,
- provider="ibm_ams",
- jwt_token=f"Basic {ibm_api_key_b64}",
- opensearch_username=ibm_username,
- opensearch_credentials=ibm_api_key_b64,
- )
- return await _attach_request_user(request, user, session_manager)
-
- # API key path
- api_key = request.headers.get("X-API-Key")
- if not api_key or not api_key.startswith("orag_"):
- auth_header = request.headers.get("Authorization", "")
- if auth_header.startswith("Bearer "):
- token = auth_header[7:]
- if token.startswith("orag_"):
- api_key = token
-
- if not api_key:
- # saas_rbac is already handled by the fail-fast 401 above (no JWT ->
- # missing_user_jwt), so reaching here means non-saas_rbac: prompt for
- # an API key as before.
- raise HTTPException(
- status_code=401,
- detail={
- "error": "API key required",
- "message": "Provide API key via X-API-Key header or Authorization: Bearer header",
- },
- )
-
- user_info = await api_key_service.validate_key(api_key)
- if not user_info:
- raise HTTPException(
- status_code=401,
- detail={
- "error": "Invalid API key",
- "message": "The provided API key is invalid or has been revoked",
- },
- )
-
- user = User(
- user_id=user_info["user_id"],
- email=user_info["user_email"],
- name=user_info.get("name", "API User"),
- picture=None,
- provider="api_key",
- )
-
- # Register the API key user so get_effective_jwt_token can find them
- if user.user_id not in session_manager.users:
- session_manager.users[user.user_id] = user
-
- request.state.api_key_id = user_info["key_id"]
- # Phase 2 will populate api_key_role_ids from the SQL api_keys table.
- # In Phase 1 we leave it unset so require_permission falls back to the
- # user's live role membership (no privilege escalation possible).
- request.state.api_key_role_ids = getattr(request.state, "api_key_role_ids", None)
-
- return await _attach_request_user(request, user, session_manager)
diff --git a/tests/unit/dependencies/test_auth_jwt_attachment.py b/tests/unit/dependencies/test_auth_jwt_attachment.py
index e2585c73b..7af17c397 100644
--- a/tests/unit/dependencies/test_auth_jwt_attachment.py
+++ b/tests/unit/dependencies/test_auth_jwt_attachment.py
@@ -9,7 +9,7 @@ SRC = ROOT / "src"
if str(SRC) not in sys.path:
sys.path.insert(0, str(SRC))
-import dependencies # noqa: E402
+import auth.request_identity as request_identity # noqa: E402
from dependencies import get_current_user, get_optional_user # noqa: E402
from session_manager import User # noqa: E402
@@ -48,7 +48,7 @@ def _auth_settings(monkeypatch):
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)
+ monkeypatch.setattr(request_identity, "_resolve_db_user_id", _resolve_db_user_id)
@pytest.mark.asyncio
diff --git a/tests/unit/dependencies/test_ibm_auth.py b/tests/unit/dependencies/test_ibm_auth.py
index 9552951f9..c41dc90be 100644
--- a/tests/unit/dependencies/test_ibm_auth.py
+++ b/tests/unit/dependencies/test_ibm_auth.py
@@ -10,7 +10,7 @@ SRC = ROOT / "src"
if str(SRC) not in sys.path:
sys.path.insert(0, str(SRC))
-from dependencies import _get_ibm_user # noqa: E402
+from auth.request_identity import _get_ibm_user # noqa: E402
@pytest.mark.asyncio
diff --git a/tests/unit/dependencies/test_ibm_header_auth.py b/tests/unit/dependencies/test_ibm_header_auth.py
index aac5017fb..3d3e07a7e 100644
--- a/tests/unit/dependencies/test_ibm_header_auth.py
+++ b/tests/unit/dependencies/test_ibm_header_auth.py
@@ -21,7 +21,7 @@ if str(SRC) not in sys.path:
import auth.ibm_auth as ibm_auth # noqa: E402
import config.settings as app_settings # noqa: E402
-from dependencies import _get_ibm_user # noqa: E402
+from auth.request_identity import _get_ibm_user # noqa: E402
COOKIE_NAME = "ibm-openrag-session"
diff --git a/tests/unit/dependencies/test_jwt_header_auth.py b/tests/unit/dependencies/test_jwt_header_auth.py
index 5c17d18a6..1572595bc 100644
--- a/tests/unit/dependencies/test_jwt_header_auth.py
+++ b/tests/unit/dependencies/test_jwt_header_auth.py
@@ -24,10 +24,15 @@ if str(SRC) not in sys.path:
import base64 # noqa: E402
+import auth.request_identity as deps # 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
+from auth.request_identity import ( # noqa: E402
+ _stage_jwt_roles,
+)
+from auth.request_identity import ( # noqa: E402
+ resolve_api_key_user as get_api_key_user_async,
+)
class _FakeRequest:
diff --git a/tests/unit/dependencies/test_require_permission.py b/tests/unit/dependencies/test_require_permission.py
index 39600f359..7d1f7afdd 100644
--- a/tests/unit/dependencies/test_require_permission.py
+++ b/tests/unit/dependencies/test_require_permission.py
@@ -25,6 +25,7 @@ if str(SRC) not in sys.path:
sys.path.insert(0, str(SRC))
import db.models # noqa: E402,F401
+from auth.user_identity_cache import _ENSURED_USER_IDS, _user_cache_key # noqa: E402
from db.models import ( # noqa: E402
Permission,
Role,
@@ -34,8 +35,6 @@ from db.models import User as UserRow # noqa: E402
from db.repositories import RoleRepo # noqa: E402
from db.seed import seed_roles_and_permissions # noqa: E402
from dependencies import ( # noqa: E402
- _ENSURED_USER_IDS,
- _user_cache_key,
get_current_user,
get_rbac_service,
require_all_permissions,
diff --git a/tests/unit/services/test_bootstrap_race.py b/tests/unit/services/test_bootstrap_race.py
index 9cd498d19..ac58a554f 100644
--- a/tests/unit/services/test_bootstrap_race.py
+++ b/tests/unit/services/test_bootstrap_race.py
@@ -1,11 +1,4 @@
-"""First-admin bootstrap must yield exactly one admin even under
-concurrent first-sign-ins.
-
-Two `ensure_user_row` calls fired with `asyncio.gather` against an empty
-DB: both observe `count_admins == 0`, both attempt to grant admin. The
-post-grant rollback (lexicographic tie-break) must demote the loser
-before either request returns.
-"""
+"""Default-role bootstrap must remain race-safe under concurrent sign-ins."""
import asyncio
import sys
@@ -29,7 +22,8 @@ from session_manager import User # noqa: E402
@pytest_asyncio.fixture
-async def session_factory():
+async def session_factory(monkeypatch):
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
engine = create_async_engine(
"sqlite+aiosqlite:///:memory:",
connect_args={"check_same_thread": False},
@@ -45,13 +39,8 @@ async def session_factory():
@pytest.mark.asyncio
-async def test_bootstrap_race_yields_single_admin(session_factory):
- """Two concurrent first-sign-ins → exactly one admin.
-
- Each call uses its own session (mirrors what FastAPI does per
- request). The post-grant rollback must observe the second admin
- and demote whichever caller is not min(user_id).
- """
+async def test_bootstrap_race_assigns_default_role(session_factory):
+ """Two concurrent first-sign-ins both receive the default role."""
async def signin(user_id: str) -> None:
async with session_factory() as session:
@@ -66,23 +55,20 @@ async def test_bootstrap_race_yields_single_admin(session_factory):
)
await session.commit()
- # SQLite serializes writes, so true parallelism is limited; but the
- # service does several reads/writes per call, so even on SQLite the
- # interleaving exercises the rollback branch.
await asyncio.gather(signin("alice"), signin("bob"))
async with session_factory() as session:
- admins = await RoleRepo(session).list_admin_user_ids()
+ repo = RoleRepo(session)
+ alice_roles = await repo.list_user_roles("alice")
+ bob_roles = await repo.list_user_roles("bob")
- assert len(admins) == 1, f"expected 1 admin, got {admins}"
- # Lexicographic min wins
- assert admins[0] == "alice"
+ assert {r.name for r in alice_roles} == {"user"}
+ assert {r.name for r in bob_roles} == {"user"}
@pytest.mark.asyncio
-async def test_bootstrap_loser_falls_through_to_default_role(session_factory):
- """The demoted bootstrap loser must still end up with the default
- role, not zero roles."""
+async def test_concurrent_signins_do_not_grant_admin(session_factory):
+ """Concurrent first sign-ins must not grant admin implicitly."""
async def signin(user_id: str) -> None:
async with session_factory() as session:
@@ -101,19 +87,16 @@ async def test_bootstrap_loser_falls_through_to_default_role(session_factory):
async with session_factory() as session:
repo = RoleRepo(session)
- admins = await repo.list_admin_user_ids()
+ alice_roles = await repo.list_user_roles("alice")
zach_roles = await repo.list_user_roles("zach")
- assert admins == ["alice"]
- role_names = {r.name for r in zach_roles}
- # Default role is "user" (set by OPENRAG_DEFAULT_ROLE, default "user")
- assert "user" in role_names, f"loser should have default role, got {role_names}"
- assert "admin" not in role_names
+ assert {r.name for r in alice_roles} == {"user"}
+ assert {r.name for r in zach_roles} == {"user"}
@pytest.mark.asyncio
async def test_no_race_single_signin_unchanged(session_factory):
- """Sanity check — when there's no race, the first user becomes admin."""
+ """Sanity check — one sign-in gets the default role."""
async with session_factory() as session:
await ensure_user_row(
session,
@@ -121,8 +104,8 @@ async def test_no_race_single_signin_unchanged(session_factory):
)
await session.commit()
async with session_factory() as session:
- admins = await RoleRepo(session).list_admin_user_ids()
- assert admins == ["solo"]
+ roles = await RoleRepo(session).list_user_roles("solo")
+ assert {r.name for r in roles} == {"user"}
@pytest.mark.asyncio
@@ -144,7 +127,7 @@ async def test_concurrent_signins_same_user_no_integrity_error(session_factory,
monkeypatch.setattr(_engine_mod, "SessionLocal", session_factory, raising=False)
- from dependencies import _ENSURE_LOCKS, _ENSURED_USER_IDS, _ensure_db_user
+ from auth.user_identity_cache import _ENSURE_LOCKS, _ENSURED_USER_IDS, _ensure_db_user
_ENSURED_USER_IDS.clear()
_ENSURE_LOCKS.clear()
@@ -229,7 +212,7 @@ async def test_cache_keys_are_per_provider_subject_pair(session_factory, monkeyp
monkeypatch.setattr(_engine_mod, "SessionLocal", session_factory, raising=False)
- from dependencies import _ENSURE_LOCKS, _ENSURED_USER_IDS, _ensure_db_user
+ from auth.user_identity_cache import _ENSURE_LOCKS, _ENSURED_USER_IDS, _ensure_db_user
_ENSURED_USER_IDS.clear()
_ENSURE_LOCKS.clear()
@@ -274,7 +257,7 @@ async def test_invalidate_pops_only_target_identity(session_factory, monkeypatch
monkeypatch.setattr(_engine_mod, "SessionLocal", session_factory, raising=False)
- from dependencies import (
+ from auth.user_identity_cache import (
_ENSURE_LOCKS,
_ENSURED_USER_IDS,
_ensure_db_user,