Qdrant RBAC

qdrant-mcp-rbac

Maintained by Fidonis · See TRADEMARK.md for the trademark notice.

A FastMCP server that exposes a Qdrant vector database over streamable HTTP with OIDC-based authentication (Keycloak-compatible) and role-based access control mapped onto Qdrant's native JWT access rules.

Role grants are stored as data inside a dedicated Qdrant collection, not in configuration files — admins manage them at runtime via MCP tools.

┌──────────┐   OIDC Bearer   ┌─────────────────┐   Qdrant JWT    ┌──────────┐

│ MCP host │ ──────────────▶ │ qdrant-mcp-rbac │ ──────────────▶ │ Qdrant │ │ (client) │ │ (FastMCP) │ │ │ └──────────┘ └─────────────────┘ │ ┌─────┐ │ │ │ │_rbac│ │ ▼ │ │_acl │ │ Keycloak │ └─────┘ │ (JWKS, OIDC discovery) └──────────┘

Quick start (Docker)

docker run --rm -p 8000:8000 \

-e OIDC_ISSUER_URL=https://kc.example.com/realms/myrealm \ -e OIDC_AUDIENCE=mcp-server \ -e QDRANT_URL=http://qdrant:6333 \ -e QDRANT_JWT_SECRET= \ ghcr.io/fidonis/qdrant-mcp-rbac:latest

/mcp is the streamable-HTTP endpoint, /health is unauthenticated. See the full docker/.env.example for every variable.

How it works

1. The MCP client sends a request with an OIDC access token (Authorization: Bearer …).
2. The OIDCAuthMiddleware validates the token against the OIDC provider's JWKS (signature, expiry, audience, issuer; see Token validation).
3. The JWTBuilder derives a Qdrant JWT for the user:

• If the user is in the break-glass admin role (RBAC_ADMIN_ROLE), a global-manage token is minted directly.
• Otherwise, the AclResolver returns the cached role -> [grants] mapping built from the ACL collection (RBAC_ACL_COLLECTION, default _rbac_acl).

1. The Qdrant JWT is attached to the request scope.
2. Each MCP tool checks the user's effective access for the targeted collection and forwards the request to Qdrant using the derived JWT.

Token validation

Tokens are validated with PyJWT against the keys published by the issuer ({OIDC_ISSUER_URL}/.well-known/openid-configuration, then its jwks_uri):

• Signature algorithm comes from the signing key (its alg, or RS256 / ES256 for an RSA / EC key without one), never from the token header. Only RS256, RS384, RS512, ES256, ES384 and ES512 are accepted; symmetric (HS*) and none tokens are rejected.
• Required claims: exp, aud (must contain OIDC_AUDIENCE), iss (must equal the issuer in the discovery document) and a non-empty sub. A token without exp or aud is rejected. nbf is enforced when present.
• `iat` is not checked, so clock skew between this host and the identity provider does not reject freshly issued tokens.
• Key rotation: keys are cached for OIDC_JWKS_CACHE_TTL seconds. A token with an unknown kid triggers exactly one JWKS refresh before it is rejected.
• Roles are read from realm_access.roles and from every resource_access. .roles.

ACL collection schema

Each grant is one point in _rbac_acl. The point id is a deterministic uuid5(role, collection), so re-granting is idempotent. Payload:

{ "role": "data-scientist", "collection": "embeddings_v2", "access": "rw" }

access is one of:

• r – read-only
• rw – read & write
• m – manage (global; collection is informational, convention: "*")

The collection is auto-created on first read by the server using a self-minted service token.

Document-level access control (doc_policy)

Collection-level access decides whether a role can read a collection at all. A grant may additionally carry an optional doc_policy that restricts which individual documents (points) inside that collection the role can see. The server translates the policy into a Qdrant payload filter and injects it as a must clause on every read — search_collection, search_collection_by_text, scroll_collection, and list_documents (faceting only over documents the role may see). Caller-supplied query_filter values are preserved; the doc filter is added alongside, so both apply together.

Grants without doc_policy behave exactly as before — every document in the collection is visible.

Schema

{

"default": "allow" | "deny", "conditions": [ { "field": " ", "mode": "allow" | "deny", "values": [" ", "…"] } ] }

• default: "allow" — every document is visible by default; deny conditions hide matching ones.
• default: "deny" — no documents are visible by default; allow conditions expose matching ones.
• values: ["*"] — wildcard meaning "all documents". On an allow condition (default-deny) it cancels the filter, exposing the whole collection; on a deny condition (default-allow) it returns an empty result set.
• default: "deny" with no allow conditions → empty result set.

Multiple conditions of the same mode are unioned (a document is hidden by any deny condition; a document is exposed by any allow condition).

Multi-role merge

When a user holds several grants on the same collection (via different roles), the server merges their policies using the most-permissive rule:

• If any matching grant has no doc_policy, the user is unrestricted on that collection.
• If any matching grant has default: "allow", the merged policy is default: "allow" with the union of those grants' deny conditions (default-deny grants are ignored).
• Otherwise all grants are default: "deny" and their allow conditions are unioned.

Recommended payload field: acl_tags

A new optional acl_tags: list[str] field is reserved for documents that need access control. It is never required — documents without acl_tags remain fully functional:

• In default-allow grants, an untagged document is never matched by a deny condition on acl_tags → always visible.
• In default-deny grants, an untagged document never satisfies an allow condition on acl_tags → implicitly hidden.

The bootstrap script demo/bootstrap/vectorize.py reads an optional demo/data/acl_tags.yml sidecar mapping each Markdown source (POSIX path relative to the data directory) to a list of tags applied to every chunk ingested from that file.

Examples

Default-allow, deny confidential documents:

{

"role": "finance-analyst", "collection": "finance", "access": "r", "doc_policy": { "default": "allow", "conditions": [ { "field": "acl_tags", "mode": "deny", "values": ["confidential", "board-only"] } ] } }

Default-deny, allow only public documents:

{

"role": "guest", "collection": "finance", "access": "r", "doc_policy": { "default": "deny", "conditions": [ { "field": "acl_tags", "mode": "allow", "values": ["public"] } ] } }

Filtering on the source field (no acl_tags required):

{

"role": "junior-analyst", "collection": "finance", "access": "r", "doc_policy": { "default": "deny", "conditions": [ { "field": "source", "mode": "allow", "values": ["annual-report.md", "q4-summary.md"] } ] } }

grant_access accepts the same shape:

{

"tool": "grant_access", "args": { "role": "guest", "collection": "finance", "access": "r", "doc_policy": { "default": "deny", "conditions": [ { "field": "acl_tags", "mode": "allow", "values": ["public"] } ] } } }

Layout

The repo separates the production server (src/) from demo material (demo/). src/ and each project under demo/ is its own uv project with its own pyproject.toml and .venv — there is no virtual environment in the repo root.

src/                       # uv project: the FastMCP server

pyproject.toml uv.lock .venv/ # created by uv sync (gitignored) .env # local config (gitignored) .env.example # template for .env main.py # Entry point (uvicorn) config.py # Settings (pydantic-settings, .env) auth/ models.py # OIDCClaims, CollectionAccess, AclEntry, QdrantToken oidc.py # JWKS-based OIDC token validator (PyJWT) acl.py # AclResolver: TTL-cached read of the ACL collection jwt_builder.py # Builds Qdrant JWTs from claims + ACL mapping qdrant/ client.py # AsyncQdrantClient factory (per-request, JWT-scoped) collections.py # Thin async wrappers around Qdrant collection operations meta.py # Read/write helpers for the _collection_meta system collection mcp_app/ # named mcp_app to avoid shadowing the installed mcp SDK server.py # FastMCP instance + Starlette app wiring tools.py # MCP tools: data tools + ACL admin tools middleware.py # ASGI auth middleware: OIDC → Qdrant JWT

tests/ # pytest suite, run from src/ (kept out of the Docker image) fakes/oidc.py # In-process OIDC issuer: RSA key, JWKS, token minting test_doc_filter.py test_facet.py test_jwt_builder.py test_oidc_validator.py test_scroll.py

demo/ # everything for the end-to-end demo README.md # Demo quickstart (order of operations) bootstrap/ # uv project: vectorize Markdown → Qdrant collections pyproject.toml uv.lock .venv/ vectorize.py client/ # uv project: OIDC + LLM CLI client pyproject.toml uv.lock .venv/ client.py agent.py oidc.py config.py data/ # demo seed data (Markdown, collection = file stem up to the first "-") finance-2025.md finance-2026.md finance-aquise.md it.md sales.md

Setup

Prerequisites

• Python 3.11+
• uv installed
• A reachable OIDC provider (e.g. Keycloak)
• A reachable Qdrant instance with JWT RBAC enabled

Install

cd src

uv sync

This creates src/.venv with all dependencies. The repo root has no .venv of its own.

Configure

Copy the example env file and adjust values:

cp src/.env.example src/.env

The server reads src/.env (resolved relative to config.py), so keep it inside src/ regardless of the working directory you run from.

Important variables:

| EMBEDDING_API_KEY | Optional bearer token for