Skip to content

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

Python

chore: RBAC test scripts and sync roles (#1757)

Edwin Josece4e7277a9d0
diff --git a/.env.example b/.env.example
index e3e25326b..e259a7c86 100644
--- a/.env.example
+++ b/.env.example
@@ -361,3 +361,12 @@ OPENRAG_STORAGE_MODE=db
# overrides are also bypassed. Set to `true` to turn the permissions
# system on for multi-user deployments. Available in all run modes.
# OPENRAG_RBAC_ENFORCE=true
+
+# Default role for new users (JWT role sync off). Does not change existing
+# users unless OPENRAG_SYNC_DEFAULT_ROLE is also enabled.
+# OPENRAG_DEFAULT_ROLE=user
+# OPENRAG_NOAUTH_ROLE=admin
+
+# Dev-only (OSS run mode): run scripts/sync_default_user_roles.py manually
+# to migrate users when OPENRAG_DEFAULT_ROLE changes. Ignored in saas/on_prem.
+# OPENRAG_SYNC_DEFAULT_ROLE=false
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 000000000..c3e0dd321
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,119 @@
+# OpenRAG scripts
+
+## Sync default user roles (`sync_default_user_roles.py`)
+
+Dev-only helper for RBAC in **OSS run mode** (`OPENRAG_RUN_MODE=oss`): updates
+existing users in the SQL DB when `OPENRAG_DEFAULT_ROLE` changes. Requires:
+
+```env
+OPENRAG_RUN_MODE=oss
+OPENRAG_SYNC_DEFAULT_ROLE=true
+OPENRAG_DEFAULT_ROLE=admin # target role: admin | developer | user | viewer
+```
+
+Ignored in `saas` and `on_prem` — those modes assign roles from JWT claims.
+
+Uses the default SQLite DB at `data/openrag.db` unless `DATABASE_URL` is set.
+
+### Promote all `user` roles to `OPENRAG_DEFAULT_ROLE`
+
+Use this when users still have the `user` role but you want them on whatever
+role is set in `OPENRAG_DEFAULT_ROLE` (for example `admin`):
+
+```bash
+OPENRAG_SYNC_DEFAULT_ROLE=true \
+OPENRAG_DEFAULT_ROLE=admin \
+uv run python scripts/sync_default_user_roles.py --from-role user
+```
+
+### Explicit from → to (ignores env target)
+
+When both roles are on the CLI, the target comes from `--to-role`, not
+`OPENRAG_DEFAULT_ROLE`:
+
+```bash
+OPENRAG_SYNC_DEFAULT_ROLE=true \
+uv run python scripts/sync_default_user_roles.py --from-role admin --to-role user
+```
+
+Migrates every user whose **only** role is `admin` to `user`, regardless of
+what `OPENRAG_DEFAULT_ROLE` is set to.
+
+What it does:
+
+- Finds every user whose **only** role is `user`
+- Assigns them the role from `OPENRAG_DEFAULT_ROLE` (here: `admin`)
+- Skips users with multiple roles or a different single role
+- Updates the stored baseline in `workspace_config.meta`
+
+Preview without writing:
+
+```bash
+OPENRAG_SYNC_DEFAULT_ROLE=true \
+OPENRAG_DEFAULT_ROLE=admin \
+uv run python scripts/sync_default_user_roles.py --from-role user --dry-run
+```
+
+Replace `user` with any source role, and set `OPENRAG_DEFAULT_ROLE` to the
+target role you want.
+
+### Other commands
+
+| Command | Purpose |
+| --- | --- |
+| `uv run python scripts/sync_default_user_roles.py` | Sync when env default changed since last recorded baseline |
+| `--dry-run` | Show changes without writing to the DB |
+| `--from-role ROLE` | Source role for this run (overrides stored baseline) |
+| `--to-role ROLE` | Target role (overrides `OPENRAG_DEFAULT_ROLE`; requires `--from-role`) |
+| `--from-noauth-role ROLE` | Source role for the anonymous user |
+| `--to-noauth-role ROLE` | Target role for anonymous user (overrides `OPENRAG_NOAUTH_ROLE`) |
+| `--record-baseline` | Save current env defaults; do not change any user |
+
+### After running
+
+Restart the backend (or wait for `OPENRAG_PERM_CACHE_TTL`, default 60s) so
+permission checks pick up the new roles. Verify with:
+
+```bash
+curl -b "auth_token=..." http://localhost:8000/users/me
+```
+
+### Notes
+
+- Intended for local OSS dev workflows, not production role management.
+- If the script reports stale users but updates none, use `--from-role` with
+ the role those users currently have.
+
+## Reset onboarding (`reset_onboarding.py`)
+
+Re-triggers the onboarding wizard by resetting workspace config in the DB
+(`OPENRAG_STORAGE_MODE=db` by default):
+
+```bash
+uv run python scripts/reset_onboarding.py
+```
+
+What it does:
+
+- Sets `workspace_config.meta.edited` to `false` (`GET /api/onboarding-status` → `onboarded: false`)
+- Clears `workspace_config.onboarding` (including `current_step` → `0`)
+- In `hybrid` / `files` mode, also updates `config.yaml`
+
+Optional flags:
+
+| Flag | Purpose |
+| --- | --- |
+| `--dry-run` | Preview without writing |
+| `--reset-models` | Also clear selected LLM and embedding models |
+
+Example — full wizard reset including model picks:
+
+```bash
+uv run python scripts/reset_onboarding.py --reset-models
+```
+
+After running, **restart the backend** and reload the app.
+
+This script does **not** delete ingested documents, knowledge filters, Langflow
+flows, or conversations. For a full teardown, use the authenticated API endpoint
+`POST /settings/rollback-onboarding` instead.
diff --git a/scripts/reset_onboarding.py b/scripts/reset_onboarding.py
new file mode 100644
index 000000000..d1c9ca1a2
--- /dev/null
+++ b/scripts/reset_onboarding.py
@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Reset onboarding state in the DB so the wizard shows again.
+
+Sets ``meta.edited=false`` and clears the ``onboarding`` section in
+``workspace_config``. In hybrid/files mode, config.yaml is updated too.
+
+Does **not** remove ingested documents, knowledge filters, or Langflow
+flow edits. For that, use POST /settings/rollback-onboarding via the API.
+
+Usage:
+ uv run python scripts/reset_onboarding.py
+ uv run python scripts/reset_onboarding.py --dry-run
+ uv run python scripts/reset_onboarding.py --reset-models
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+ sys.path.insert(0, str(SRC))
+
+
+async def main() -> int:
+ parser = argparse.ArgumentParser(
+ description="Reset onboarding in workspace_config to re-trigger the wizard.",
+ )
+ parser.add_argument(
+ "--dry-run",
+ action="store_true",
+ help="Show what would change without writing",
+ )
+ parser.add_argument(
+ "--reset-models",
+ action="store_true",
+ help="Also clear selected LLM and embedding models (back to openai defaults)",
+ )
+ args = parser.parse_args()
+
+ from config.storage_mode import db_writes_enabled, get_storage_mode
+ from services.onboarding_reset import reset_onboarding
+
+ mode = get_storage_mode()
+ print(f"Storage mode: {mode}")
+
+ session = None
+ if db_writes_enabled():
+ import db.engine as db_engine
+
+ db_engine.init_engine()
+ SessionLocal = db_engine.SessionLocal
+ if SessionLocal is None:
+ print("Database engine is not configured (check DATABASE_URL).", file=sys.stderr)
+ return 1
+
+ async with SessionLocal() as session:
+ result = await reset_onboarding(
+ session,
+ reset_models=args.reset_models,
+ dry_run=args.dry_run,
+ )
+ if not args.dry_run:
+ await session.commit()
+ else:
+ result = await reset_onboarding(
+ None,
+ reset_models=args.reset_models,
+ dry_run=args.dry_run,
+ )
+
+ if args.dry_run:
+ print(
+ f"Dry run — would set edited=false and onboarding.current_step=0 "
+ f"(was edited={result.previous_edited!r}, step={result.previous_step!r})."
+ )
+ if args.reset_models:
+ print("Would also clear LLM and embedding model selections.")
+ else:
+ targets = []
+ if result.db_updated:
+ targets.append("workspace_config (DB)")
+ if result.yaml_updated:
+ targets.append("config.yaml")
+ print(f"Onboarding reset written to: {', '.join(targets) or 'nothing'}")
+ print("Restart the backend, then reload the app to see the onboarding wizard.")
+
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(asyncio.run(main()))
diff --git a/scripts/sync_default_user_roles.py b/scripts/sync_default_user_roles.py
new file mode 100644
index 000000000..a2c02809c
--- /dev/null
+++ b/scripts/sync_default_user_roles.py
@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Sync existing user roles when OPENRAG_DEFAULT_ROLE env values change.
+
+Requires ``OPENRAG_SYNC_DEFAULT_ROLE=true``. OSS run mode only
+(``OPENRAG_RUN_MODE=oss``). Run manually via ``scripts/sync_default_user_roles.py``.
+
+Usage:
+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py
+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py --dry-run
+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py --record-baseline
+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py --from-role user
+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py --from-role admin --to-role user
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+ sys.path.insert(0, str(SRC))
+
+
+async def main() -> int:
+ parser = argparse.ArgumentParser(
+ description="Sync DB user roles after OPENRAG_DEFAULT_ROLE / OPENRAG_NOAUTH_ROLE change.",
+ )
+ parser.add_argument(
+ "--dry-run",
+ action="store_true",
+ help="Show eligible updates without writing to the DB",
+ )
+ parser.add_argument(
+ "--record-baseline",
+ action="store_true",
+ help="Record current env defaults without updating any users",
+ )
+ parser.add_argument(
+ "--from-role",
+ metavar="ROLE",
+ help=(
+ "Treat ROLE as the previous default for this run only "
+ "(fixes a baseline recorded before users were migrated)"
+ ),
+ )
+ parser.add_argument(
+ "--from-noauth-role",
+ metavar="ROLE",
+ help="Like --from-role but for the anonymous/no-auth user",
+ )
+ parser.add_argument(
+ "--to-role",
+ metavar="ROLE",
+ help="Target role for regular users (overrides OPENRAG_DEFAULT_ROLE for this run)",
+ )
+ parser.add_argument(
+ "--to-noauth-role",
+ metavar="ROLE",
+ help="Target role for the anonymous user (overrides OPENRAG_NOAUTH_ROLE for this run)",
+ )
+ args = parser.parse_args()
+
+ if args.to_role is not None and args.from_role is None and not args.record_baseline:
+ print(
+ "--to-role requires --from-role so the script knows which users to migrate.",
+ file=sys.stderr,
+ )
+ return 1
+
+ import db.engine as db_engine
+ from config.settings import is_default_role_sync_enabled
+ from services.default_role_sync import sync_default_roles_if_changed
+
+ if not is_default_role_sync_enabled():
+ from utils.run_mode_utils import get_run_mode, is_run_mode_oss
+
+ if not is_run_mode_oss():
+ print(
+ "Default role sync is only available when OPENRAG_RUN_MODE=oss "
+ f"(current: {get_run_mode()!r}).",
+ file=sys.stderr,
+ )
+ else:
+ print(
+ "OPENRAG_SYNC_DEFAULT_ROLE is not enabled. "
+ "Set OPENRAG_SYNC_DEFAULT_ROLE=true and retry.",
+ file=sys.stderr,
+ )
+ return 1
+
+ db_engine.init_engine()
+ SessionLocal = db_engine.SessionLocal
+ if SessionLocal is None:
+ print("Database engine is not configured.", file=sys.stderr)
+ return 1
+
+ if args.from_role or args.to_role:
+ print(
+ "Role migration:",
+ f"{args.from_role or '(from baseline/env)'} -> {args.to_role or '(from env)'}",
+ )
+ else:
+ print("Using OPENRAG_DEFAULT_ROLE and OPENRAG_NOAUTH_ROLE from the environment.")
+ if args.dry_run:
+ print("Dry run — no writes.")
+
+ async with SessionLocal() as session:
+ result = await sync_default_roles_if_changed(
+ session,
+ dry_run=args.dry_run,
+ force_baseline=args.record_baseline,
+ from_role=args.from_role,
+ from_noauth_role=args.from_noauth_role,
+ to_role=args.to_role,
+ to_noauth_role=args.to_noauth_role,
+ )
+ if not args.dry_run:
+ await session.commit()
+
+ if result.baseline_recorded and not result.changes and args.record_baseline:
+ print("Baseline recorded; no user rows changed.")
+ elif result.updated_users == 0:
+ print("No eligible users to update.")
+ if result.stale_users:
+ print(
+ f"Found {result.stale_users} user(s) whose sole role differs from "
+ "OPENRAG_DEFAULT_ROLE but the stored baseline already matches env. "
+ "Re-run with:\n"
+ " --from-role user # or whichever role they currently have"
+ )
+ else:
+ verb = "Would update" if args.dry_run else "Updated"
+ print(f"{verb} {result.updated_users} user(s):")
+ for change in result.changes:
+ print(f" - user {change['user_id']}: {change['from_role']} -> {change['to_role']}")
+ if result.skipped_users:
+ print(f"Skipped {result.skipped_users} user(s) (multi-role or non-default role).")
+
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(asyncio.run(main()))
diff --git a/src/config/settings.py b/src/config/settings.py
index b12e59353..1516d430b 100644
--- a/src/config/settings.py
+++ b/src/config/settings.py
@@ -197,6 +197,30 @@ def get_role_claim_viewer() -> str | None:
return os.getenv("OPENRAG_ROLE_CLAIM_VIEWER")
+def get_default_user_role() -> str:
+ """Built-in role assigned to new users when JWT role sync is off."""
+ return os.getenv("OPENRAG_DEFAULT_ROLE", "user")
+
+
+def get_noauth_user_role() -> str:
+ """Built-in role for the synthetic anonymous user in no-auth mode."""
+ return os.getenv("OPENRAG_NOAUTH_ROLE", "admin")
+
+
+def is_default_role_sync_enabled() -> bool:
+ """When true, sync eligible existing users if default-role env vars change.
+
+ Only active in ``OPENRAG_RUN_MODE=oss``. SaaS and on-prem assign roles
+ via JWT sync; env-driven bulk migration is an OSS dev workflow.
+ """
+ from utils.run_mode_utils import is_run_mode_oss
+
+ if not is_run_mode_oss():
+ return False
+ raw = os.getenv("OPENRAG_SYNC_DEFAULT_ROLE", "false").strip().lower()
+ return raw in ("true", "1", "yes", "on")
+
+
def get_openrag_service_token() -> str | None:
"""Platform-issued service JWT used at startup to bootstrap the OpenSearch
security context (admin role mapping). Read per-call — like the JWT-claim
diff --git a/src/services/default_role_sync.py b/src/services/default_role_sync.py
new file mode 100644
index 000000000..69c79f737
--- /dev/null
+++ b/src/services/default_role_sync.py
@@ -0,0 +1,307 @@
+"""Sync DB user roles when OPENRAG_DEFAULT_ROLE / OPENRAG_NOAUTH_ROLE change.
+
+Opt-in via ``OPENRAG_SYNC_DEFAULT_ROLE=true``. OSS run mode only
+(``OPENRAG_RUN_MODE=oss``). Run manually via ``scripts/sync_default_user_roles.py``.
+
+Only users with *exactly one* role matching the previously recorded env
+default are updated. Users with multiple roles or a manually changed
+single role are left untouched.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from config.settings import (
+ get_default_user_role,
+ get_noauth_user_role,
+ is_default_role_sync_enabled,
+)
+from db.repositories import AuditRepo, RoleRepo, UserRepo
+from db.repositories.workspace_config_repo import WorkspaceConfigRepo
+from utils.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+META_SECTION = "meta"
+SYNC_STATE_KEY = "rbac_default_role_sync"
+PAGE_SIZE = 100
+# Code defaults when no baseline exists yet (matches user_service / settings).
+IMPLICIT_DEFAULT_USER_ROLE = "user"
+IMPLICIT_DEFAULT_NOAUTH_ROLE = "admin"
+
+
+@dataclass
+class DefaultRoleSyncResult:
+ enabled: bool
+ dry_run: bool
+ baseline_recorded: bool = False
+ default_role_changed: bool = False
+ noauth_role_changed: bool = False
+ updated_users: int = 0
+ skipped_users: int = 0
+ stale_users: int = 0
+ old_default_role: str | None = None
+ new_default_role: str = ""
+ old_noauth_role: str | None = None
+ new_noauth_role: str = ""
+ changes: list[dict[str, str]] = field(default_factory=list)
+
+ def as_log_kwargs(self) -> dict[str, Any]:
+ return {
+ "enabled": self.enabled,
+ "dry_run": self.dry_run,
+ "baseline_recorded": self.baseline_recorded,
+ "default_role_changed": self.default_role_changed,
+ "noauth_role_changed": self.noauth_role_changed,
+ "updated_users": self.updated_users,
+ "skipped_users": self.skipped_users,
+ "stale_users": self.stale_users,
+ "old_default_role": self.old_default_role,
+ "new_default_role": self.new_default_role,
+ "old_noauth_role": self.old_noauth_role,
+ "new_noauth_role": self.new_noauth_role,
+ "change_count": len(self.changes),
+ }
+
+
+def _read_sync_state(meta: dict[str, Any]) -> dict[str, str | None]:
+ state = meta.get(SYNC_STATE_KEY) or {}
+ return {
+ "default_role": state.get("default_role"),
+ "noauth_role": state.get("noauth_role"),
+ }
+
+
+async def _write_sync_state(
+ repo: WorkspaceConfigRepo,
+ *,
+ default_role: str,
+ noauth_role: str,
+ dry_run: bool,
+) -> None:
+ if dry_run:
+ return
+ meta = await repo.get_section(META_SECTION) or {}
+ meta = dict(meta)
+ meta[SYNC_STATE_KEY] = {
+ "default_role": default_role,
+ "noauth_role": noauth_role,
+ }
+ await repo.upsert(META_SECTION, meta)
+
+
+def _is_noauth_user(user) -> bool:
+ return user.oauth_subject == "anonymous"
+
+
+async def _count_stale_default_users(
+ session: AsyncSession,
+ *,
+ expected_role: str,
+) -> int:
+ """Users with a single role that differs from the current env default."""
+ role_repo = RoleRepo(session)
+ user_repo = UserRepo(session)
+ stale = 0
+ offset = 0
+ while True:
+ users = await user_repo.list_all(limit=PAGE_SIZE, offset=offset)
+ if not users:
+ break
+ for user in users:
+ if _is_noauth_user(user):
+ continue
+ roles = await role_repo.list_user_roles(user.id)
+ if len(roles) == 1 and roles[0].name != expected_role:
+ stale += 1
+ offset += PAGE_SIZE
+ return stale
+
+
+async def sync_default_roles_if_changed(
+ session: AsyncSession,
+ *,
+ dry_run: bool = False,
+ force_baseline: bool = False,
+ from_role: str | None = None,
+ from_noauth_role: str | None = None,
+ to_role: str | None = None,
+ to_noauth_role: str | None = None,
+ enabled: bool | None = None,
+) -> DefaultRoleSyncResult:
+ """Apply env default-role changes to eligible existing users.
+
+ When ``force_baseline`` is true, record the current env values without
+ mutating any user rows (useful after enabling the flag on an existing DB).
+
+ ``from_role`` / ``from_noauth_role`` override the stored baseline for one
+ run — use when the baseline was recorded before users were migrated
+ (e.g. baseline and env are both ``admin`` but users still have ``user``).
+
+ ``to_role`` / ``to_noauth_role`` override ``OPENRAG_DEFAULT_ROLE`` /
+ ``OPENRAG_NOAUTH_ROLE`` for this run when set explicitly on the CLI.
+ """
+ flag_enabled = is_default_role_sync_enabled() if enabled is None else enabled
+ new_default = to_role if to_role is not None else get_default_user_role()
+ new_noauth = to_noauth_role if to_noauth_role is not None else get_noauth_user_role()
+
+ result = DefaultRoleSyncResult(
+ enabled=flag_enabled,
+ dry_run=dry_run,
+ new_default_role=new_default,
+ new_noauth_role=new_noauth,
+ )
+
+ if not flag_enabled:
+ logger.debug("Default role sync skipped — OPENRAG_SYNC_DEFAULT_ROLE is off")
+ return result
+
+ config_repo = WorkspaceConfigRepo(session)
+ meta = await config_repo.get_section(META_SECTION) or {}
+ state = _read_sync_state(meta)
+ stored_default = state["default_role"]
+ stored_noauth = state["noauth_role"]
+
+ if force_baseline:
+ await _write_sync_state(
+ config_repo,
+ default_role=new_default,
+ noauth_role=new_noauth,
+ dry_run=dry_run,
+ )
+ result.baseline_recorded = True
+ logger.info(
+ "Recorded RBAC default-role baseline",
+ default_role=new_default,
+ noauth_role=new_noauth,
+ dry_run=dry_run,
+ )
+ return result
+
+ if from_role is not None:
+ old_default = from_role
+ elif stored_default is not None:
+ old_default = stored_default
+ else:
+ old_default = IMPLICIT_DEFAULT_USER_ROLE
+ result.baseline_recorded = True
+
+ if from_noauth_role is not None:
+ old_noauth = from_noauth_role
+ elif stored_noauth is not None:
+ old_noauth = stored_noauth
+ else:
+ old_noauth = IMPLICIT_DEFAULT_NOAUTH_ROLE
+ result.baseline_recorded = True
+
+ result.old_default_role = old_default
+ result.old_noauth_role = old_noauth
+
+ result.default_role_changed = old_default != new_default
+ result.noauth_role_changed = old_noauth != new_noauth
+ if not result.default_role_changed and not result.noauth_role_changed:
+ result.stale_users = await _count_stale_default_users(session, expected_role=new_default)
+ if stored_default is None or stored_noauth is None:
+ await _write_sync_state(
+ config_repo,
+ default_role=new_default,
+ noauth_role=new_noauth,
+ dry_run=dry_run,
+ )
+ result.baseline_recorded = True
+ logger.debug(
+ "Default role sync: env defaults unchanged",
+ stale_users=result.stale_users,
+ )
+ return result
+
+ role_repo = RoleRepo(session)
+ user_repo = UserRepo(session)
+ audit_repo = AuditRepo(session)
+
+ default_role_row = await role_repo.get_by_name(new_default)
+ noauth_role_row = await role_repo.get_by_name(new_noauth)
+ if result.default_role_changed and default_role_row is None:
+ logger.warning(
+ "Default role sync: target default role not found in DB",
+ role_name=new_default,
+ )
+ if result.noauth_role_changed and noauth_role_row is None:
+ logger.warning(
+ "Default role sync: target no-auth role not found in DB",
+ role_name=new_noauth,
+ )
+
+ offset = 0
+ while True:
+ users = await user_repo.list_all(limit=PAGE_SIZE, offset=offset)
+ if not users:
+ break
+
+ for user in users:
+ is_noauth = _is_noauth_user(user)
+ if is_noauth:
+ if not result.noauth_role_changed:
+ continue
+ old_role_name = old_noauth
+ new_role_name = new_noauth
+ target_role = noauth_role_row
+ else:
+ if not result.default_role_changed:
+ continue
+ old_role_name = old_default
+ new_role_name = new_default
+ target_role = default_role_row
+
+ if not old_role_name or old_role_name == new_role_name or target_role is None:
+ result.skipped_users += 1
+ continue
+
+ roles = await role_repo.list_user_roles(user.id)
+ if len(roles) != 1 or roles[0].name != old_role_name:
+ result.skipped_users += 1
+ continue
+
+ change = {
+ "user_id": user.id,
+ "oauth_provider": user.oauth_provider or "",
+ "oauth_subject": user.oauth_subject or "",
+ "from_role": old_role_name,
+ "to_role": new_role_name,
+ }
+ result.changes.append(change)
+
+ if dry_run:
+ result.updated_users += 1
+ continue
+
+ await role_repo.revoke_role(user.id, roles[0].id)
+ await role_repo.assign_role(user.id, target_role.id)
+ await audit_repo.write(
+ event="user.roles_synced",
+ actor_user_id=None,
+ target_type="user",
+ target_id=user.id,
+ audit_metadata={
+ "added": [new_role_name],
+ "removed": [old_role_name],
+ "source": "default_role_env_sync",
+ },
+ )
+ result.updated_users += 1
+
+ offset += PAGE_SIZE
+
+ await _write_sync_state(
+ config_repo,
+ default_role=new_default,
+ noauth_role=new_noauth,
+ dry_run=dry_run,
+ )
+
+ logger.info("Default role sync finished", **result.as_log_kwargs())
+ return result
diff --git a/src/services/onboarding_reset.py b/src/services/onboarding_reset.py
new file mode 100644
index 000000000..9031bf43f
--- /dev/null
+++ b/src/services/onboarding_reset.py
@@ -0,0 +1,151 @@
+"""Reset workspace onboarding state so the wizard shows again.
+
+Updates ``workspace_config`` (and config.yaml in hybrid/files mode).
+Does not delete OpenSearch documents, Langflow flows, or conversations —
+use the API ``rollback_onboarding`` endpoint for a full teardown.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from config.config_manager import OnboardingState, config_manager
+from config.storage_mode import db_writes_enabled, file_writes_enabled, get_storage_mode
+from db.repositories.workspace_config_repo import WorkspaceConfigRepo
+from utils.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class OnboardingResetResult:
+ dry_run: bool
+ reset_models: bool
+ storage_mode: str
+ db_updated: bool = False
+ yaml_updated: bool = False
+ previous_edited: bool | None = None
+ previous_step: Any = None
+
+ def as_log_kwargs(self) -> dict[str, Any]:
+ return {
+ "dry_run": self.dry_run,
+ "reset_models": self.reset_models,
+ "storage_mode": self.storage_mode,
+ "db_updated": self.db_updated,
+ "yaml_updated": self.yaml_updated,
+ "previous_edited": self.previous_edited,
+ "previous_step": self.previous_step,
+ }
+
+
+def _fresh_onboarding_dict() -> dict[str, Any]:
+ return asdict(OnboardingState())
+
+
+def _apply_model_reset(section: dict[str, Any], *, llm: bool) -> dict[str, Any]:
+ updated = dict(section or {})
+ if llm:
+ updated["llm_model"] = ""
+ updated["llm_provider"] = "openai"
+ else:
+ updated["embedding_model"] = ""
+ updated["embedding_provider"] = "openai"
+ return updated
+
+
+async def reset_onboarding_in_db(
+ session: AsyncSession,
+ *,
+ reset_models: bool = False,
+ dry_run: bool = False,
+) -> OnboardingResetResult:
+ result = OnboardingResetResult(
+ dry_run=dry_run,
+ reset_models=reset_models,
+ storage_mode=get_storage_mode(),
+ )
+
+ repo = WorkspaceConfigRepo(session)
+ rows = await repo.list_all()
+
+ meta = dict(rows.get("meta") or {})
+ onboarding = dict(rows.get("onboarding") or {})
+ result.previous_edited = bool(meta.get("edited", False))
+ result.previous_step = onboarding.get("current_step")
+
+ meta["edited"] = False
+ fresh_onboarding = _fresh_onboarding_dict()
+
+ if not dry_run:
+ await repo.upsert("meta", meta)
+ await repo.upsert("onboarding", fresh_onboarding)
+ if reset_models:
+ await repo.upsert(
+ "agent",
+ _apply_model_reset(rows.get("agent") or {}, llm=True),
+ )
+ await repo.upsert(
+ "knowledge",
+ _apply_model_reset(rows.get("knowledge") or {}, llm=False),
+ )
+ result.db_updated = True
+
+ logger.info("Onboarding reset in DB", **result.as_log_kwargs())
+ return result
+
+
+def reset_onboarding_yaml(*, reset_models: bool = False, dry_run: bool = False) -> bool:
+ """Reset onboarding flags in config.yaml (hybrid / files mode)."""
+ if dry_run:
+ return False
+
+ config = config_manager.load_config()
+ config.edited = False
+ config.onboarding = OnboardingState()
+ if reset_models:
+ config.agent.llm_model = ""
+ config.agent.llm_provider = "openai"
+ config.knowledge.embedding_model = ""
+ config.knowledge.embedding_provider = "openai"
+
+ config_manager._config = config
+ return config_manager.save_config_file(config)
+
+
+async def reset_onboarding(
+ session: AsyncSession | None = None,
+ *,
+ reset_models: bool = False,
+ dry_run: bool = False,
+) -> OnboardingResetResult:
+ """Reset onboarding across the active storage backend(s)."""
+ mode = get_storage_mode()
+ result = OnboardingResetResult(
+ dry_run=dry_run,
+ reset_models=reset_models,
+ storage_mode=mode,
+ )
+
+ if db_writes_enabled():
+ if session is None:
+ raise ValueError("session is required when DB writes are enabled")
+ db_result = await reset_onboarding_in_db(
+ session,
+ reset_models=reset_models,
+ dry_run=dry_run,
+ )
+ result.db_updated = db_result.db_updated
+ result.previous_edited = db_result.previous_edited
+ result.previous_step = db_result.previous_step
+
+ if file_writes_enabled():
+ result.yaml_updated = reset_onboarding_yaml(
+ reset_models=reset_models,
+ dry_run=dry_run,
+ )
+
+ return result
diff --git a/tests/unit/services/test_default_role_sync.py b/tests/unit/services/test_default_role_sync.py
new file mode 100644
index 000000000..38850524b
--- /dev/null
+++ b/tests/unit/services/test_default_role_sync.py
@@ -0,0 +1,218 @@
+"""Tests for env-driven default role sync."""
+
+import sys
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlmodel import SQLModel
+
+ROOT = Path(__file__).resolve().parent.parent.parent.parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+ sys.path.insert(0, str(SRC))
+
+import db.models # noqa: E402,F401
+from db.repositories import RoleRepo, WorkspaceConfigRepo # noqa: E402
+from db.seed import seed_roles_and_permissions # noqa: E402
+from services.default_role_sync import sync_default_roles_if_changed # noqa: E402
+from services.user_service import ensure_user_row # noqa: E402
+from session_manager import User # noqa: E402
+
+
+@pytest_asyncio.fixture
+async def session():
+ engine = create_async_engine(
+ "sqlite+aiosqlite:///:memory:",
+ connect_args={"check_same_thread": False},
+ )
+ async with engine.begin() as conn:
+ await conn.run_sync(SQLModel.metadata.create_all)
+ SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+ async with SessionLocal() as s:
+ await seed_roles_and_permissions(s)
+ await s.commit()
+ yield s
+ await engine.dispose()
+
+
+def _user(uid: str) -> User:
+ return User(user_id=uid, email=f"{uid}@example.com", name=uid, provider="google")
+
+
+async def test_sync_skipped_outside_oss(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
+ user_row = await ensure_user_row(session, _user("u1"))
+ await session.commit()
+
+ monkeypatch.setenv("OPENRAG_RUN_MODE", "saas")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")
+ result = await sync_default_roles_if_changed(session)
+ roles = await RoleRepo(session).list_user_roles(user_row.id)
+
+ assert result.enabled is False
+ assert result.updated_users == 0
+ assert [r.name for r in roles] == ["user"]
+
+
+async def test_sync_disabled_is_noop(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "false")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
+ row = await ensure_user_row(session, _user("u1"))
+ await session.commit()
+
+ result = await sync_default_roles_if_changed(session, enabled=False)
+ roles = await RoleRepo(session).list_user_roles(row.id)
+
+ assert result.updated_users == 0
+ assert [r.name for r in roles] == ["user"]
+
+
+async def test_first_run_with_unchanged_env_records_baseline(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
+ user_row = await ensure_user_row(session, _user("u1"))
+ await session.commit()
+
+ result = await sync_default_roles_if_changed(session, enabled=True)
+ await session.commit()
+
+ roles = await RoleRepo(session).list_user_roles(user_row.id)
+ meta = await WorkspaceConfigRepo(session).get_section("meta")
+
+ assert result.baseline_recorded is True
+ assert result.updated_users == 0
+ assert [r.name for r in roles] == ["user"]
+ assert meta["rbac_default_role_sync"]["default_role"] == "user"
+
+
+async def test_first_run_migrates_from_implicit_user_default(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
+ user_row = await ensure_user_row(session, _user("u1"))
+ await session.commit()
+
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")
+ result = await sync_default_roles_if_changed(session, enabled=True)
+ await session.commit()
+
+ roles = await RoleRepo(session).list_user_roles(user_row.id)
+ meta = await WorkspaceConfigRepo(session).get_section("meta")
+
+ assert result.updated_users == 1
+ assert [r.name for r in roles] == ["admin"]
+ assert meta["rbac_default_role_sync"]["default_role"] == "admin"
+
+
+async def test_from_role_overrides_wrong_baseline(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
+ user_row = await ensure_user_row(session, _user("u1"))
+ await session.commit()
+
+ meta_repo = WorkspaceConfigRepo(session)
+ await meta_repo.upsert(
+ "meta",
+ {"rbac_default_role_sync": {"default_role": "admin", "noauth_role": "admin"}},
+ )
+ await session.commit()
+
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")
+ result = await sync_default_roles_if_changed(session, enabled=True, from_role="user")
+ await session.commit()
+
+ roles = await RoleRepo(session).list_user_roles(user_row.id)
+ assert result.updated_users == 1
+ assert [r.name for r in roles] == ["admin"]
+
+
+async def test_env_change_updates_single_role_users(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
+ user_row = await ensure_user_row(session, _user("u1"))
+ await sync_default_roles_if_changed(session, enabled=True)
+ await session.commit()
+
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")
+ result = await sync_default_roles_if_changed(session, enabled=True)
+ await session.commit()
+
+ roles = await RoleRepo(session).list_user_roles(user_row.id)
+
+ assert result.updated_users == 1
+ assert [r.name for r in roles] == ["admin"]
+
+
+async def test_skips_multi_role_users(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
+ user_row = await ensure_user_row(session, _user("u1"))
+ role_repo = RoleRepo(session)
+ dev_role = await role_repo.get_by_name("developer")
+ await role_repo.assign_role(user_row.id, dev_role.id)
+ await sync_default_roles_if_changed(session, enabled=True)
+ await session.commit()
+
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")
+ result = await sync_default_roles_if_changed(session, enabled=True)
+ await session.commit()
+
+ roles = await RoleRepo(session).list_user_roles(user_row.id)
+
+ assert result.updated_users == 0
+ assert result.skipped_users == 1
+ assert {r.name for r in roles} == {"user", "developer"}
+
+
+async def test_explicit_to_role_overrides_env(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")
+ user_row = await ensure_user_row(session, _user("u1"))
+ role_repo = RoleRepo(session)
+ user_role = await role_repo.get_by_name("user")
+ admin_role = await role_repo.get_by_name("admin")
+ await role_repo.revoke_role(user_row.id, user_role.id)
+ await role_repo.assign_role(user_row.id, admin_role.id)
+ await WorkspaceConfigRepo(session).upsert(
+ "meta",
+ {"rbac_default_role_sync": {"default_role": "admin", "noauth_role": "admin"}},
+ )
+ await session.commit()
+
+ result = await sync_default_roles_if_changed(
+ session, enabled=True, from_role="admin", to_role="user"
+ )
+ await session.commit()
+
+ roles = await RoleRepo(session).list_user_roles(user_row.id)
+ assert result.updated_users == 1
+ assert [r.name for r in roles] == ["user"]
+
+
+async def test_dry_run_does_not_write(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")
+ user_row = await ensure_user_row(session, _user("u1"))
+ await sync_default_roles_if_changed(session, enabled=True)
+ await session.commit()
+
+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "viewer")
+ result = await sync_default_roles_if_changed(session, enabled=True, dry_run=True)
+
+ roles = await RoleRepo(session).list_user_roles(user_row.id)
+ meta = await WorkspaceConfigRepo(session).get_section("meta")
+
+ assert result.updated_users == 1
+ assert [r.name for r in roles] == ["user"]
+ assert meta is None or meta.get("rbac_default_role_sync", {}).get("default_role") == "user"
diff --git a/tests/unit/services/test_onboarding_reset.py b/tests/unit/services/test_onboarding_reset.py
new file mode 100644
index 000000000..643b15d8d
--- /dev/null
+++ b/tests/unit/services/test_onboarding_reset.py
@@ -0,0 +1,101 @@
+"""Tests for onboarding reset."""
+
+import sys
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlmodel import SQLModel
+
+ROOT = Path(__file__).resolve().parent.parent.parent.parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+ sys.path.insert(0, str(SRC))
+
+import db.models # noqa: E402,F401
+from db.repositories import WorkspaceConfigRepo # noqa: E402
+from services.onboarding_reset import reset_onboarding_in_db # noqa: E402
+
+
+@pytest_asyncio.fixture
+async def session():
+ engine = create_async_engine(
+ "sqlite+aiosqlite:///:memory:",
+ connect_args={"check_same_thread": False},
+ )
+ async with engine.begin() as conn:
+ await conn.run_sync(SQLModel.metadata.create_all)
+ SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+ async with SessionLocal() as s:
+ yield s
+ await engine.dispose()
+
+
+async def test_reset_onboarding_clears_edited_and_step(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_STORAGE_MODE", "db")
+ repo = WorkspaceConfigRepo(session)
+ await repo.upsert("meta", {"edited": True})
+ await repo.upsert(
+ "onboarding",
+ {"current_step": 4, "selected_nudge": "docs", "openrag_docs_filter_id": "kf-1"},
+ )
+ await repo.upsert("agent", {"llm_model": "gpt-4o", "llm_provider": "openai"})
+ await session.commit()
+
+ result = await reset_onboarding_in_db(session)
+ await session.commit()
+
+ meta = await repo.get_section("meta")
+ onboarding = await repo.get_section("onboarding")
+ agent = await repo.get_section("agent")
+
+ assert result.previous_edited is True
+ assert result.previous_step == 4
+ assert meta["edited"] is False
+ assert onboarding["current_step"] == 0
+ assert onboarding.get("selected_nudge") is None
+ assert onboarding.get("openrag_docs_filter_id") is None
+ assert agent["llm_model"] == "gpt-4o"
+
+
+async def test_reset_models_clears_llm_and_embedding(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_STORAGE_MODE", "db")
+ repo = WorkspaceConfigRepo(session)
+ await repo.upsert("meta", {"edited": True})
+ await repo.upsert("onboarding", {"current_step": 4})
+ await repo.upsert("agent", {"llm_model": "gpt-4o", "llm_provider": "anthropic"})
+ await repo.upsert(
+ "knowledge",
+ {"embedding_model": "text-embedding-3-small", "embedding_provider": "anthropic"},
+ )
+ await session.commit()
+
+ await reset_onboarding_in_db(session, reset_models=True)
+ await session.commit()
+
+ agent = await repo.get_section("agent")
+ knowledge = await repo.get_section("knowledge")
+
+ assert agent["llm_model"] == ""
+ assert agent["llm_provider"] == "openai"
+ assert knowledge["embedding_model"] == ""
+ assert knowledge["embedding_provider"] == "openai"
+
+
+async def test_dry_run_does_not_write(session, monkeypatch):
+ monkeypatch.setenv("OPENRAG_STORAGE_MODE", "db")
+ repo = WorkspaceConfigRepo(session)
+ await repo.upsert("meta", {"edited": True})
+ await repo.upsert("onboarding", {"current_step": 2})
+ await session.commit()
+
+ await reset_onboarding_in_db(session, dry_run=True)
+
+ meta = await repo.get_section("meta")
+ onboarding = await repo.get_section("onboarding")
+ assert meta["edited"] is True
+ assert onboarding["current_step"] == 2