Skip to content

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

Python

fix: Add OpenSearch basic-auth for on-prem deployments, improve onboarding flow, and support asymmetric JWT signing (#1713)

Edwin Josee357cf16f4ad
diff --git a/src/api/settings/endpoints.py b/src/api/settings/endpoints.py
index 875b03c5c..9007694e4 100644
--- a/src/api/settings/endpoints.py
+++ b/src/api/settings/endpoints.py
@@ -1043,16 +1043,80 @@ async def onboarding(
# Initialize the OpenSearch index if embedding model is configured
if body.embedding_model or body.embedding_provider:
try:
- from config.settings import IBM_AUTH_ENABLED
from config.settings import clients as app_clients
+ from config.settings import (
+ get_openrag_service_token,
+ get_opensearch_password,
+ get_opensearch_username,
+ )
from main import init_index
+ from utils.run_mode_utils import (
+ is_run_mode_on_prem,
+ is_run_mode_oss,
+ is_run_mode_saas,
+ )
+ # Choose the OpenSearch client + admin identity for index/security
+ # setup, by run mode:
+ # saas -> platform service token (JWT); admin from its claim
+ # on_prem -> OpenSearch basic auth; OpenSearch username as admin
+ # oss -> OpenSearch basic auth; OpenSearch username as admin
opensearch_client = None
- if IBM_AUTH_ENABLED and user and user.jwt_token:
- opensearch_client = app_clients.create_user_opensearch_client(user.jwt_token)
+ admin_username = None
+ if is_run_mode_saas():
+ service_token = get_openrag_service_token()
+ if service_token:
+ # Prefer the platform service token so onboarding pins the
+ # same admin identity as the startup security bootstrap
+ # (see app/lifespan.py).
+ from auth.ibm_auth import admin_username_from_service_jwt
+
+ admin_username = admin_username_from_service_jwt(service_token)
+ if not admin_username:
+ raise RuntimeError(
+ "OPENRAG_SERVICE_TOKEN has no 'username' or 'sub' claim; "
+ "cannot determine OpenSearch admin during onboarding"
+ )
+ opensearch_client = app_clients.create_opensearch_client_from_jwt(
+ service_token
+ )
+ logger.info(
+ "Onboarding OpenSearch setup: saas mode, using platform service token",
+ admin_username=admin_username,
+ )
+ elif user:
+ # TODO: backward-compatibility fallback for saas deployments
+ # without OPENRAG_SERVICE_TOKEN — pins the onboarding user as
+ # admin instead of the platform service identity. Remove once
+ # the service token is always provided.
+ if user.jwt_token:
+ opensearch_client = app_clients.create_user_opensearch_client(
+ user.jwt_token
+ )
+ admin_username = user.user_id
+ logger.warning(
+ "Onboarding OpenSearch setup: saas mode without "
+ "OPENRAG_SERVICE_TOKEN; falling back to the onboarding user "
+ "as admin (backward-compatibility path, to be removed later)",
+ admin_username=admin_username,
+ )
+ else:
+ logger.info(
+ "Onboarding OpenSearch setup: saas mode with no service "
+ "token or user; using the unauthenticated global client"
+ )
+ elif is_run_mode_on_prem() or is_run_mode_oss():
+ admin_username = get_opensearch_username()
+ opensearch_client = app_clients.create_basic_opensearch_client(
+ admin_username, get_opensearch_password()
+ )
+ logger.info(
+ "Onboarding OpenSearch setup: %s mode, using OpenSearch basic auth"
+ % ("on_prem" if is_run_mode_on_prem() else "oss"),
+ admin_username=admin_username,
+ )
logger.info("Initializing OpenSearch index after onboarding configuration")
- admin_username = user.user_id if IBM_AUTH_ENABLED and user else None
await init_index(opensearch_client, admin_username=admin_username)
logger.info("OpenSearch index initialization completed successfully")
except Exception as e:
@@ -1069,6 +1133,7 @@ async def onboarding(
if should_ingest_sample_data:
try:
# Import the function here to avoid circular imports
+ from config.settings import IBM_AUTH_ENABLED
from main import ingest_default_documents_when_ready
if not config_manager.save_config_file(current_config):
diff --git a/src/app/lifespan.py b/src/app/lifespan.py
index 7be8e1fc8..c51b69693 100644
--- a/src/app/lifespan.py
+++ b/src/app/lifespan.py
@@ -21,6 +21,8 @@ from config.settings import (
clients,
get_openrag_config,
get_openrag_service_token,
+ get_opensearch_password,
+ get_opensearch_username,
)
from services.startup_orchestrator import startup_tasks
from utils.logging_config import get_logger
@@ -207,23 +209,47 @@ async def run_startup(app: FastAPI):
# talks to OpenSearch. The corresponding call inside startup_tasks
# is suppressed when this flag is on.
if OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP:
- service_token = get_openrag_service_token()
- if not service_token:
- raise RuntimeError(
- "OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP is enabled but "
- "OPENRAG_SERVICE_TOKEN is not set"
- )
- from auth.ibm_auth import admin_username_from_service_jwt
from utils.opensearch_init import wait_for_opensearch
from utils.opensearch_utils import setup_opensearch_security
+ from utils.run_mode_utils import (
+ is_run_mode_on_prem,
+ is_run_mode_oss,
+ )
- admin_username = admin_username_from_service_jwt(service_token)
- if not admin_username:
- raise RuntimeError(
- "OPENRAG_SERVICE_TOKEN has no 'username' or 'sub' claim; "
- "cannot bootstrap OpenSearch security"
+ # Choose the bootstrap OpenSearch client + admin identity, by run mode:
+ # saas -> platform service token (JWT); admin from its claim
+ # on_prem -> OpenSearch basic auth; OpenSearch username as admin
+ # oss -> OpenSearch basic auth; OpenSearch username as admin
+ if is_run_mode_on_prem() or is_run_mode_oss():
+ admin_username = get_opensearch_username()
+ opensearch_client = clients.create_basic_opensearch_client(
+ admin_username, get_opensearch_password()
+ )
+ logger.info(
+ "OpenSearch security bootstrap: %s mode, using OpenSearch basic auth"
+ % ("on_prem" if is_run_mode_on_prem() else "oss"),
+ admin_username=admin_username,
+ )
+ else:
+ service_token = get_openrag_service_token()
+ if not service_token:
+ raise RuntimeError(
+ "OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP is enabled but "
+ "OPENRAG_SERVICE_TOKEN is not set"
+ )
+ from auth.ibm_auth import admin_username_from_service_jwt
+
+ admin_username = admin_username_from_service_jwt(service_token)
+ if not admin_username:
+ raise RuntimeError(
+ "OPENRAG_SERVICE_TOKEN has no 'username' or 'sub' claim; "
+ "cannot bootstrap OpenSearch security"
+ )
+ opensearch_client = clients.create_opensearch_client_from_jwt(service_token)
+ logger.info(
+ "OpenSearch security bootstrap: saas mode, using platform service token",
+ admin_username=admin_username,
)
- opensearch_client = clients.create_opensearch_client_from_jwt(service_token)
try:
await wait_for_opensearch(opensearch_client)
logger.info("Bootstrapping OpenSearch security", admin_username=admin_username)
diff --git a/src/config/settings.py b/src/config/settings.py
index 3c3680acc..cadc63b7d 100644
--- a/src/config/settings.py
+++ b/src/config/settings.py
@@ -37,6 +37,21 @@ LANGFLOW_OPENSEARCH_PORT = get_env_int("LANGFLOW_OPENSEARCH_PORT", OPENSEARCH_PO
OPENSEARCH_USERNAME = os.getenv("OPENSEARCH_USERNAME", "admin")
OPENSEARCH_PASSWORD = os.getenv("OPENSEARCH_PASSWORD")
+
+
+def get_opensearch_username() -> str:
+ """OpenSearch admin/basic-auth username, read per-call so runtime/test
+ overrides (e.g. credentials supplied during onboarding) take effect without
+ a restart. Falls back to the value captured at import time, then "admin"."""
+ return os.getenv("OPENSEARCH_USERNAME") or OPENSEARCH_USERNAME or "admin"
+
+
+def get_opensearch_password() -> str | None:
+ """OpenSearch basic-auth password, read per-call so runtime/test overrides
+ take effect without a restart. Falls back to the import-time value."""
+ return os.getenv("OPENSEARCH_PASSWORD") or OPENSEARCH_PASSWORD
+
+
OPENRAG_FQDN = os.getenv("OPENRAG_FQDN")
LANGFLOW_URL = os.getenv("LANGFLOW_URL", "http://localhost:7860")
# Optional: public URL for browser links (e.g., http://localhost:7860)
@@ -78,6 +93,7 @@ IBM_JWT_PUBLIC_KEY_URL = os.getenv("IBM_JWT_PUBLIC_KEY_URL", "")
IBM_SESSION_COOKIE_NAME = os.getenv("IBM_SESSION_COOKIE_NAME", "ibm-openrag-session")
IBM_CREDENTIALS_HEADER = os.getenv("IBM_CREDENTIALS_HEADER", "X-IBM-LH-Credentials")
+
# ── JWT roles claim ─────────────────────────────────────────────
# These are exposed as functions (not module constants) so they are read
# per-call: auth/jwt_roles.py must pick up runtime overrides, and the unit
@@ -581,19 +597,48 @@ class AppClients:
self._docling_service = None
async def initialize(self):
- os_auth = None if IBM_AUTH_ENABLED else (OPENSEARCH_USERNAME, OPENSEARCH_PASSWORD)
-
- self.opensearch = AsyncOpenSearch(
- hosts=[{"host": OPENSEARCH_HOST, "port": OPENSEARCH_PORT}],
- connection_class=AIOHttpConnection,
- scheme="https",
- use_ssl=True,
- verify_certs=False,
- ssl_assert_fingerprint=None,
- http_auth=os_auth,
- http_compress=True,
+ from utils.run_mode_utils import (
+ is_run_mode_on_prem,
+ is_run_mode_oss,
+ is_run_mode_saas,
)
+ # Credentials for the global (backend-owned) writer client, by run mode:
+ # saas -> platform service token (JWT) when available, else unauthenticated
+ # on_prem -> OpenSearch basic auth
+ # oss -> OpenSearch basic auth
+ service_token = get_openrag_service_token() if is_run_mode_saas() else None
+ if service_token:
+ logger.info(
+ "Initializing global OpenSearch writer client: saas mode, "
+ "using platform service token"
+ )
+ self.opensearch = self.create_opensearch_client_from_jwt(service_token)
+ else:
+ if is_run_mode_on_prem() or is_run_mode_oss():
+ os_auth = (get_opensearch_username(), get_opensearch_password())
+ logger.info(
+ "Initializing global OpenSearch writer client: %s mode, "
+ "using OpenSearch basic auth" % ("on_prem" if is_run_mode_on_prem() else "oss")
+ )
+ else:
+ os_auth = None
+ logger.info(
+ "Initializing global OpenSearch writer client: saas mode without "
+ "service token, using the unauthenticated client"
+ )
+
+ self.opensearch = AsyncOpenSearch(
+ hosts=[{"host": OPENSEARCH_HOST, "port": OPENSEARCH_PORT}],
+ connection_class=AIOHttpConnection,
+ scheme="https",
+ use_ssl=True,
+ verify_certs=False,
+ ssl_assert_fingerprint=None,
+ http_auth=os_auth,
+ http_compress=True,
+ )
+
# Initialize patched OpenAI client if API key is available
# This allows the app to start even if OPENAI_API_KEY is not set yet
# (e.g., when it will be provided during onboarding)
diff --git a/src/services/langflow_ingest_token_service.py b/src/services/langflow_ingest_token_service.py
index 5e4d9e79c..b7a68ffac 100644
--- a/src/services/langflow_ingest_token_service.py
+++ b/src/services/langflow_ingest_token_service.py
@@ -8,14 +8,50 @@ from typing import Any
import jwt
from cachetools import TTLCache
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, ed448, ed25519, rsa
-from config.settings import LANGFLOW_INGEST_CALLBACK_TTL_SECONDS, SESSION_SECRET
+from config.settings import LANGFLOW_INGEST_CALLBACK_TTL_SECONDS
from services.document_index_writer import DocumentIndexContext
from utils.logging_config import get_logger
logger = get_logger(__name__)
+def _resolve_default_signing_config() -> tuple[Any, Any, str]:
+ """Prefer JWT_SIGNING_KEY when set; otherwise fall back to SESSION_SECRET."""
+ from config.settings import JWT_SIGNING_KEY, SESSION_SECRET
+
+ signing_key = JWT_SIGNING_KEY
+ if not signing_key:
+ return SESSION_SECRET, SESSION_SECRET, "HS256"
+
+ if signing_key.lstrip().startswith("-----BEGIN"):
+ key = serialization.load_pem_private_key(signing_key.encode(), password=None)
+ public_key = key.public_key()
+
+ if isinstance(key, rsa.RSAPrivateKey):
+ algorithm = "RS256"
+ elif isinstance(key, ec.EllipticCurvePrivateKey):
+ curve = key.curve
+ if isinstance(curve, ec.SECP256R1):
+ algorithm = "ES256"
+ elif isinstance(curve, ec.SECP384R1):
+ algorithm = "ES384"
+ elif isinstance(curve, ec.SECP521R1):
+ algorithm = "ES512"
+ else:
+ raise ValueError(f"Unsupported EC curve: {curve.name}")
+ elif isinstance(key, (ed25519.Ed25519PrivateKey, ed448.Ed448PrivateKey)):
+ algorithm = "EdDSA"
+ else:
+ raise ValueError(f"Unsupported private key type: {type(key)}")
+
+ return key, public_key, algorithm
+
+ return signing_key, signing_key, "HS256"
+
+
class LangflowIngestTokenService:
"""Mint and validate per-run ingest callback tokens.
@@ -25,10 +61,16 @@ class LangflowIngestTokenService:
"""
audience = "openrag-langflow-ingest"
- algorithm = "HS256"
def __init__(self, secret: str | None = None, ttl_seconds: int | None = None):
- self.secret = secret or SESSION_SECRET
+ if secret is not None:
+ self._signing_key = secret
+ self._verification_key = secret
+ self.algorithm = "HS256"
+ else:
+ self._signing_key, self._verification_key, self.algorithm = (
+ _resolve_default_signing_config()
+ )
self.ttl_seconds = max(ttl_seconds or LANGFLOW_INGEST_CALLBACK_TTL_SECONDS, 1)
self._finalized_jtis: TTLCache[str, bool] = TTLCache(
maxsize=8192,
@@ -50,13 +92,13 @@ class LangflowIngestTokenService:
"exp": now + self.ttl_seconds,
"ctx": self._context_to_payload(context),
}
- return jwt.encode(payload, self.secret, algorithm=self.algorithm)
+ return jwt.encode(payload, self._signing_key, algorithm=self.algorithm)
def validate_token(self, token: str) -> tuple[DocumentIndexContext, str]:
try:
payload = jwt.decode(
token,
- self.secret,
+ self._verification_key,
algorithms=[self.algorithm],
audience=self.audience,
)
@@ -91,7 +133,7 @@ class LangflowIngestTokenService:
try:
payload = jwt.decode(
token,
- self.secret,
+ self._verification_key,
algorithms=[self.algorithm],
audience=self.audience,
options={"verify_exp": False},
diff --git a/tests/unit/test_langflow_ingest_callback.py b/tests/unit/test_langflow_ingest_callback.py
index 4f17d4081..fabf09e45 100644
--- a/tests/unit/test_langflow_ingest_callback.py
+++ b/tests/unit/test_langflow_ingest_callback.py
@@ -383,3 +383,28 @@ def test_langflow_callback_global_vars_have_runtime_placeholders(config_path):
for variable_name in CALLBACK_GLOBAL_VARS:
assert f"{variable_name}=" in config_text or f'"{variable_name}":' in config_text
+
+
+def test_ingest_token_prefers_jwt_signing_key_over_session_secret(monkeypatch):
+ jwt_secret = "jwt-signing-secret-with-32-bytes!!"
+ session_secret = "session-secret-should-not-be-used"
+
+ monkeypatch.setattr("config.settings.JWT_SIGNING_KEY", jwt_secret)
+ monkeypatch.setattr("config.settings.SESSION_SECRET", session_secret)
+
+ token_service = LangflowIngestTokenService(ttl_seconds=60)
+ context = DocumentIndexContext(
+ document_id="doc-jwt",
+ filename="source.pdf",
+ mimetype="application/pdf",
+ embedding_model="text-embedding-3-small",
+ owner="user-1",
+ ingest_run_id="run-jwt",
+ )
+ token = token_service.create_token(context)
+
+ token_service.validate_token(token)
+
+ session_service = LangflowIngestTokenService(secret=session_secret, ttl_seconds=60)
+ with pytest.raises(ValueError, match="Invalid Langflow ingest token"):
+ session_service.validate_token(token)