Docs revamp

2026-10-16 00:14:31 +00:00 · 2026-06-26 11:56:20 +04:00
1 parent 1acb836332
commit 5c19d972d2
@@ -0,0 +1,149 @@
+---
+title: Access Control, Roles & Teams
+description: How DocsGPT models permissions — global admin/user roles (RBAC), the admin dashboard, teams with per-team roles, and sharing agents, sources, prompts, and tools.
+---
+
+import { Callout } from 'nextra/components'
+
+# Access Control, Roles & Teams
+
+DocsGPT has two independent permission planes:
+
+- **Global RBAC** — every user holds the `admin` or `user` role for the whole instance. Admins can manage other users and see instance-wide usage and audit data.
+- **Team roles** — within a team a user is a `team_admin` or `team_member`, and resources can be shared to teams or individual members.
+
+The two planes never mix: a global `admin` is a superuser over *all* teams, but a `team_admin` is **not** a global admin.
+
+<Callout type="info" emoji="🔒">
+Roles are resolved **server-side on every request** and are never trusted from the JWT. The frontend route guards are cosmetic — the server-side decorators are the real boundary. Persisted roles apply under `AUTH_TYPE=oidc`; token-only modes (`simple_jwt`, `session_jwt`) can never hold the admin role.
+</Callout>
+
+## Global roles (RBAC)
+
+| Role | Capabilities |
+| --- | --- |
+| `user` | The default. Owns their own conversations, sources, agents, prompts, and tools. |
+| `admin` | Everything a user can do, plus the [admin dashboard](#admin-dashboard): user management, force-logout, role management, and instance-wide usage/audit. |
+
+To see the roles the current request resolves to, call:
+
+```text
+GET /api/user/me   →   { "user_id": "...", "roles": ["user"], "email": "...", "name": "...", "picture": "..." }
+```
+
+This is the canonical way to check a caller's effective roles (distinct from `/api/config`, which only reports the instance `auth_type`).
+
+## Granting admin
+
+There are four ways an account becomes an admin:
+
+1. **The `grant_admin` script** — run `python scripts/grant_admin.py <user_id>` on the server to grant (or `--revoke` / `--list`) the admin role directly. This is the canonical bootstrap for the first admin.
+2. **OIDC group mapping** — `OIDC_ADMIN_GROUPS` auto-grants admin to members of the listed IdP groups. See [below](#admin-via-oidc-groups).
+3. **Local no-auth mode** — `LOCAL_MODE_ADMIN=true` grants admin when `AUTH_TYPE=None` (self-host, no authentication).
+4. **Grant by an existing admin** — through the admin API/dashboard.
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `OIDC_ADMIN_GROUPS` | — | Comma-separated IdP groups whose members are granted the global `admin` role. Re-checked at every login and silent renewal. Unset = no OIDC admin mapping. |
+| `LOCAL_MODE_ADMIN` | `false` | Grants admin in no-auth mode only (`AUTH_TYPE=None`). |
+
+<Callout type="warning" emoji="⚠️">
+**Never set `LOCAL_MODE_ADMIN=true` on a networked deployment.** It only makes sense for a single-user local install with `AUTH_TYPE=None`, where there is no identity to check.
+</Callout>
+
+### Bootstrapping the first admin
+
+Granting admin through the dashboard itself requires *already being* an admin, which creates a chicken-and-egg problem on a fresh deployment. Break it one of these ways:
+
+- **Run the script** on the server: `python scripts/grant_admin.py <user_id>` (the `user_id` is the OIDC `sub`). The grant is written to `user_roles` with `source='manual'` and takes effect on the user's next request. Use `--list` to see current admins and `--revoke` to remove a manual grant.
+- Set `OIDC_ADMIN_GROUPS` to a group you belong to, and sign in — you become an admin automatically.
+- For a no-auth local install, use `LOCAL_MODE_ADMIN=true`.
+
+### Admin via OIDC groups
+
+When `OIDC_ADMIN_GROUPS` is set, group membership is mapped to the admin role at every sign-in *and* every [silent renewal](/Deploying/OIDC-SSO#silent-session-renewal) — so removing a user from the admin group revokes their admin at the next renewal, just like the [sign-in allowlist](/Deploying/OIDC-SSO#restricting-sign-in-by-group). It is independent of `OIDC_ALLOWED_GROUPS` (which controls *whether* a user may sign in at all). Leaving `OIDC_ADMIN_GROUPS` unset never mass-revokes admin.
+
+```env
+OIDC_ADMIN_GROUPS=platform-admins
+# OIDC_GROUPS_CLAIM=groups   # only if your IdP uses a different claim name
+```
+
+If your IdP only exposes groups via the userinfo endpoint, DocsGPT backfills them from there during reconciliation, the same as the allowlist.
+
+## Admin dashboard
+
+Admins get a dashboard backed by a REST surface under `/api/admin` (every endpoint requires the admin role). All mutating actions are written to the `auth_events` audit log with the acting admin recorded in the metadata.
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | `/api/admin/overview` | Instance overview counts. |
+| `GET` | `/api/admin/users` | List users (paginated; supports a `user_id` filter). |
+| `GET` | `/api/admin/users/<id>` | Drill into a single user. |
+| `PATCH` | `/api/admin/users/<id>` | Activate / deactivate a user (deactivation revokes their sessions). |
+| `POST` | `/api/admin/users/<id>/role` | Grant the admin role (guards against removing the last admin). |
+| `DELETE` | `/api/admin/users/<id>/role` | Revoke the admin role. |
+| `POST` | `/api/admin/users/<id>/revoke-sessions` | Force-logout a user. |
+| `GET` | `/api/admin/admins` | List current admins. |
+| `GET` | `/api/admin/usage` | Token-usage series and top users. |
+| `GET` | `/api/admin/audit` | Authentication/admin audit feed. |
+| `GET` | `/api/admin/devices/audit` | Remote-device audit feed. |
+| `GET` | `/api/admin/teams` | Instance-wide oversight of all teams. |
+
+<Callout type="info" emoji="ℹ️">
+Deactivating a user via the dashboard works for any auth type, while OIDC deployments can also offboard through [SCIM](/Deploying/OIDC-SSO#scim-user-provisioning). Both revoke live sessions immediately.
+</Callout>
+
+## Teams
+
+Teams let a group of users collaborate and share resources. Teams are self-serve — any user can create one and manage its membership.
+
+### Team roles
+
+| Role | Capabilities |
+| --- | --- |
+| `team_member` | Belongs to the team; can use resources shared with the team. |
+| `team_admin` | Manages membership and team settings. Implies `team_member`. |
+
+The team **owner** is a distinct concept from `team_admin`: ownership can be transferred, and a global `admin` is treated as a superuser over every team.
+
+### Managing a team
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` / `POST` | `/api/teams` | List your teams / create a team. |
+| `GET` / `PATCH` / `DELETE` | `/api/teams/<id>` | Read, update, or delete a team. |
+| `GET` / `POST` | `/api/teams/<id>/members` | List members / add a member. |
+| `PATCH` / `DELETE` | `/api/teams/<id>/members/<member_id>` | Change a member's role / remove (or leave). |
+| `POST` | `/api/teams/<id>/transfer_owner` | Transfer ownership. |
+
+Membership and removal are guarded so a team can never be left without an admin (the last-admin guard).
+
+<Callout type="info" emoji="ℹ️">
+Members are added by email (or subject id). The invitee **must have signed in at least once** so DocsGPT can resolve them to a user account.
+</Callout>
+
+## Sharing resources with a team
+
+Four resource types can be shared: **agents**, **sources**, **prompts**, and **tools**. Sharing is **additive** — it grants access to others without changing ownership.
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` / `POST` / `DELETE` | `/api/teams/<id>/grants` | List, create, or revoke a share within a team. |
+| `GET` | `/api/resource_shares` | List shares visible to the caller. |
+
+Sharing rules:
+
+- Only the **owner** of a resource can share it.
+- A share targets either the **whole team** or a **single member**.
+- Each share carries an access level: **`viewer`** (read-only) or **`editor`** (read and modify).
+- `editor` is not the same as owner — an editor can change a resource but cannot delete it or re-share it.
+- Shared tools run server-side with the **owner's** credentials; a grantee never sees the owner's secrets.
+
+## Audit log
+
+Access-control actions are appended to the `auth_events` table alongside the [authentication events](/Deploying/OIDC-SSO#login-auditing). This includes admin actions — `admin_user_activated` / `admin_user_deactivated`, `admin_sessions_revoked`, `role_granted` / `role_revoked` (with `metadata.source` = `manual` or `oidc_group`) — and team events (`team.create`, `team.member_add`, `team.member_role`, `team.member_remove`, `team.share`, `team.unshare`, `team.transfer_owner`, `team.delete`). The acting admin is recorded in the event metadata.
+
+## Related
+
+- [SSO with OIDC](/Deploying/OIDC-SSO) — sign-in, group allowlists, and the `auth_events` table.
+- [App Configuration](/Deploying/DocsGPT-Settings) — the full settings reference.
@@ -388,6 +388,54 @@ gated by CI/CD).
  migration path.
 </Callout>

+## Retrieval & RAG Settings
+
+These control how sources are retrieved and whether the advanced RAG features are available. See [Per-Source Configuration](/Sources/Per-source-configuration) and [GraphRAG](/Sources/GraphRAG) for details.
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `RETRIEVERS_ENABLED` | `["classic", "default"]` | Allow-list of retrievers usable instance-wide. Valid keys: `classic`, `default`, `hybrid`, `graphrag`. A per-source `retriever` must be within this list. |
+| `PER_SOURCE_RETRIEVAL_ENABLED` | `true` | Master switch for per-source retrieval config. When `false`, all sources fall back to the classic retriever regardless of their stored config. |
+| `GRAPHRAG_ENABLED` | `false` | Enable [GraphRAG](/Sources/GraphRAG). Requires `VECTOR_STORE=pgvector`. |
+| `GRAPHRAG_EXTRACTION_MODEL` | unset | Model used for ingest-time graph extraction. Unset reuses the instance default model. |
+| `GRAPHRAG_MAX_CHUNKS_FOR_EXTRACTION` | `2000` | Hard cap on chunks extracted per source (cost control). |
+
+## Embeddings Settings
+
+See [Embeddings](/Models/embeddings) for full guidance.
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `EMBEDDINGS_NAME` | `huggingface_sentence-transformers/all-mpnet-base-v2` | The embedding model. |
+| `EMBEDDINGS_BASE_URL` | unset | Base URL of a remote OpenAI-compatible embeddings server. Setting it routes all embedding calls there. |
+| `EMBEDDINGS_KEY` | unset | Optional bearer token for the remote embeddings server. |
+| `EMBEDDINGS_MAX_INPUT_TOKENS` | unset | Truncate each remote embedding input to N tokens (guards servers that reject oversized inputs). |
+
+## Tools Settings
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `DEFAULT_CHAT_TOOLS` | `["memory", "read_webpage", "scheduler"]` | Tools enabled automatically in regular (agentless) chats. See [Tools Basics](/Tools/basics#default-chat-tools). |
+
+## Admin & Access Settings
+
+See [Access Control, Roles & Teams](/Deploying/Access-Control) for the full model.
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `OIDC_ADMIN_GROUPS` | unset | Comma-separated IdP groups granted the global `admin` role (OIDC only). |
+| `LOCAL_MODE_ADMIN` | `false` | Grants admin in no-auth mode (`AUTH_TYPE=None`) only. **Never enable on a networked deployment.** |
+
+## LLM Provider Settings
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `OPENAI_RESPONSES_STORE` | `false` | When `true`, allows OpenAI to persist [Responses API](/Models/cloud-providers#openai-responses-api-and-reasoning) state server-side. |
+
+## Realtime Events Settings
+
+The realtime notifications channel has its own settings — see [Realtime Events & Notifications](/Agents/notifications) (`ENABLE_SSE_PUSH`, `EVENTS_STREAM_MAXLEN`, `SSE_MAX_CONCURRENT_PER_USER`, and related).
+
 ## Exploring More Settings

 These are just the basic settings to get you started. The `settings.py` file contains many more advanced options that you can explore to further customize DocsGPT, such as:
@@ -43,6 +43,7 @@ Sessions last `OIDC_SESSION_LIFETIME_SECONDS` (8 hours by default) and renew wit
 | `OIDC_SESSION_LIFETIME_SECONDS` | no | `28800` (8h) | Lifetime of the DocsGPT session JWT. Sessions renew before expiry — see [Silent session renewal](#silent-session-renewal). |
 | `OIDC_PROVIDER_NAME` | no | — | Display name on the sign-in button: `Acme SSO` renders "Sign in with Acme SSO". Unset, the button shows a generic "SSO". |
 | `OIDC_ALLOWED_GROUPS` | no | — | Comma-separated group allowlist. Unset, any authenticated IdP user may sign in — see [Restricting sign-in by group](#restricting-sign-in-by-group). |
+| `OIDC_ADMIN_GROUPS` | no | — | Comma-separated groups whose members are granted the global `admin` role. Re-checked at every login and renewal — see [Granting admin via groups](#granting-admin-via-groups). |
 | `OIDC_GROUPS_CLAIM` | no | `groups` | ID-token/userinfo claim carrying the user's group membership. |
 | `JWT_SECRET_KEY` | recommended | auto-generated | Signs DocsGPT session tokens. Set it explicitly in production — required when running multiple API replicas. |

@@ -108,6 +109,16 @@ Getting groups into the token:
 - **Authentik** includes group names in the `groups` claim through its default `profile` scope — no extra configuration needed.
 - **Keycloak** does not emit groups by default. On the client, open **Client scopes → the client's dedicated scope → Add mapper → By configuration → Group Membership**, set the claim name to `groups`, and turn **Full group path** off so the claim carries plain names (`devs`) rather than paths (`/devs`).

+## Granting admin via groups
+
+Separately from *who may sign in*, you can map an IdP group to the global **admin** role with `OIDC_ADMIN_GROUPS`:
+
+```env
+OIDC_ADMIN_GROUPS=platform-admins
+```
+
+Members of the listed groups are granted admin; the mapping is re-evaluated at every login **and** every [silent renewal](#silent-session-renewal), so removing a user from the admin group revokes their admin at the next renewal (exactly like the sign-in allowlist). It is independent of `OIDC_ALLOWED_GROUPS`, and leaving it unset never mass-revokes admin. On a fresh deployment this is the only way to create the first admin. For the full roles, teams, and admin-dashboard model see [Access Control, Roles & Teams](/Deploying/Access-Control).
+
 ## Silent session renewal

 The DocsGPT session JWT lives for `OIDC_SESSION_LIFETIME_SECONDS` (default 8 hours). Sessions renew without user-visible interruptions, in one of two ways:
@@ -183,6 +194,12 @@ Authentication activity is recorded in `auth_events`, an append-only Postgres ta
 | `oidc_refresh` | A session is silently renewed. |
 | `backchannel_logout` | The IdP revokes sessions via back-channel logout. |
 | `scim_created` / `scim_deactivated` / `scim_reactivated` | SCIM lifecycle changes. |
+| `role_granted` / `role_revoked` | The admin role is granted/revoked (`metadata.source` is `manual` or `oidc_group`). |
+| `admin_user_activated` / `admin_user_deactivated` | An admin activates/deactivates a user. |
+| `admin_sessions_revoked` | An admin force-logs-out a user. |
+| `team.*` | Team management — `team.create`, `team.member_add`, `team.member_role`, `team.member_remove`, `team.share`, `team.unshare`, `team.transfer_owner`, `team.delete`. |
+
+The acting admin is recorded in the event metadata. See [Access Control, Roles & Teams](/Deploying/Access-Control) for the admin and team features that emit these events.

 There is no UI for these events yet — query the table directly:

@@ -7,6 +7,10 @@ export default {
    "title": "🔐 SSO with OIDC",
    "href": "/Deploying/OIDC-SSO"
  },
+  "Access-Control": {
+    "title": "👥 Access Control & Teams",
+    "href": "/Deploying/Access-Control"
+  },
  "Docker-Deploying": {
    "title": "🛳️ Docker Setup",
    "href": "/Deploying/Docker-Deploying"