Add lifespan OpenSearch bootstrap via service JWT

Introduce a one-shot OpenSearch security bootstrap during FastAPI lifespan that derives the admin username from a platform-issued service JWT. Adds PLATFORM_SERVICE_JWT and OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP settings, validates the presence of the token, decodes the admin username (new admin_username_from_service_jwt helper), waits for OpenSearch, and runs setup_opensearch_security before other startup tasks. Also update startup_tasks to skip OpenSearch setup when the lifespan bootstrap flag is enabled, and add logging and error handling for missing/invalid tokens.

Author: edwinjosechittilappilly

src/app/lifespan.py

@@ -12,6 +12,8 @@
 from fastapi import FastAPI
 
 from config.settings import (
+    OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP,
+    PLATFORM_SERVICE_JWT,
     RBAC_CACHE_BACKEND,
     RBAC_PERMISSION_CACHE_TTL_SECONDS,
     UVICORN_WORKER_COUNT,
@@ -191,6 +193,32 @@ async def run_startup(app: FastAPI):
         await mcp_lifespan_ctx.__aenter__()
         logger.info("FastMCP lifespan started")
 
+    # One-shot OpenSearch security bootstrap driven by the platform's
+    # service JWT. Runs synchronously (before startup_tasks) so the
+    # admin role mapping is in place before any other startup work
+    # talks to OpenSearch. The corresponding call inside startup_tasks
+    # is suppressed when this flag is on.
+    if OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP:
+        if not PLATFORM_SERVICE_JWT:
+            raise RuntimeError(
+                "OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP is enabled but "
+                "PLATFORM_SERVICE_JWT 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
+
+        admin_username = admin_username_from_service_jwt(PLATFORM_SERVICE_JWT)
+        if not admin_username:
+            raise RuntimeError(
+                "PLATFORM_SERVICE_JWT has no 'username' or 'sub' claim; "
+                "cannot bootstrap OpenSearch security"
+            )
+        await wait_for_opensearch()
+        logger.info("Bootstrapping OpenSearch security", admin_username=admin_username)
+        await setup_opensearch_security(clients.opensearch, admin_username=admin_username)
+        logger.info("OpenSearch security bootstrap completed", admin_username=admin_username)
+
     # Start index initialization in background to avoid blocking OIDC endpoints
     t1 = asyncio.create_task(startup_tasks(services))
     app.state.background_tasks.add(t1)

src/auth/ibm_auth.py

@@ -31,6 +31,22 @@ def decode_ibm_jwt(token: str) -> dict | None:
         return None
 
 
+def admin_username_from_service_jwt(token: str) -> str | None:
+    """Return the admin username carried by a platform-issued service JWT.
+
+    Decodes *token* unsigned (the platform issues it; we only parse claims)
+    and returns `username` if present, falling back to `sub`. Matches the
+    claim precedence used by the auth dependency in dependencies.py.
+    Returns None if the token cannot be decoded or has neither claim.
+    """
+    try:
+        claims = jwt.decode(token, options={"verify_signature": False})
+    except jwt.InvalidTokenError as exc:
+        logger.warning("Service JWT decode failed", error=str(exc))
+        return None
+    return claims.get("username") or claims.get("sub")
+
+
 async def fetch_ibm_public_key(url: str):
     """Fetch IBM's JWT public key PEM from *url* and cache it."""
     global _cached_public_key

src/config/settings.py

@@ -67,6 +67,11 @@
 IBM_AUTH_ENABLED = os.getenv("IBM_AUTH_ENABLED", "false").lower() in ("true", "1", "yes")
 PLATFORM_USERNAME = os.getenv("PLATFORM_USERNAME")
 PLATFORM_PASSWORD = os.getenv("PLATFORM_PASSWORD")
+# Platform-issued service JWT. When present and
+# OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP is on, lifespan decodes this
+# token to derive the admin username used to bootstrap the OpenSearch
+# security context (roles + all_access mapping).
+PLATFORM_SERVICE_JWT = os.getenv("PLATFORM_SERVICE_JWT")
 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")
@@ -106,6 +111,18 @@ def _resolve_skip_os_security_default() -> str:
     "OPENRAG_SKIP_OS_SECURITY_SETUP", _resolve_skip_os_security_default()
 ).lower() in ("true", "1", "yes")
 
+# Run setup_opensearch_security once during FastAPI lifespan startup,
+# using the admin username derived from PLATFORM_SERVICE_JWT. Intended
+# for platform-managed deployments (saas / on_prem) where the platform
+# issues a service token that identifies the admin user that must be
+# pinned into the all_access role mapping. Default off.
+#
+# When this flag is true the corresponding call inside startup_tasks()
+# is suppressed — bootstrap is the single source of truth on startup.
+OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP = os.getenv(
+    "OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP", "false"
+).lower() in ("true", "1", "yes")
+
 # Enable FastAPI's `debug` mode (verbose tracebacks in HTTP error responses
 # on the FastAPI app instance). Named explicitly so it isn't confused with
 # logging-level "debug" or other unrelated debug flags.

src/services/startup_orchestrator.py

@@ -9,6 +9,7 @@
 from config.settings import (
     DISABLE_INGEST_WITH_LANGFLOW,
     FETCH_OPENRAG_DOCS_AT_STARTUP,
+    OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP,
     OPENRAG_SKIP_OS_SECURITY_SETUP,
     clients,
     get_openrag_config,
@@ -69,12 +70,18 @@ async def startup_tasks(services):
         # Setup OpenSearch security (roles and mappings) after connection is established.
         # Skip entirely when the platform manages the security context externally
         # (SaaS / CPD): the call would otherwise either fail with 403/401 or
-        # overwrite a curated config.
+        # overwrite a curated config. Also skip when the lifespan-level
+        # bootstrap (driven by PLATFORM_SERVICE_JWT) has already handled it.
         if OPENRAG_SKIP_OS_SECURITY_SETUP:
             logger.info(
                 "Skipping OpenSearch security setup at startup "
                 "(OPENRAG_SKIP_OS_SECURITY_SETUP=true)"
             )
+        elif OPENRAG_BOOTSTRAP_OS_SECURITY_ON_STARTUP:
+            logger.info(
+                "Skipping OpenSearch security setup in startup_tasks "
+                "(handled by lifespan bootstrap)"
+            )
         else:
             try:
                 from utils.opensearch_utils import setup_opensearch_security