Authentication and Authorization

Relevant source files

• api/apps/__init__.py
• api/apps/backward_compat.py
• api/settings.py
• api/utils/api_utils.py
• api/utils/validation_utils.py
• cmd/ragflow_server.go
• conf/service_conf.yaml
• docker/service_conf.yaml.template
• docs/references/http_api_reference.md
• docs/references/python_api_reference.md
• docs/release_notes.md
• internal/admin/handler.go
• internal/admin/handler_ee.go
• internal/admin/router_ee.go
• internal/admin/service.go
• internal/admin/service_ee.go
• internal/common/http.go
• internal/common/version.go
• internal/common/version_ee.go
• internal/common/version_test.go
• internal/dao/user.go
• internal/engine/clickhouse/clickhouse_ee.go
• internal/handler/user.go
• internal/ingestion/registry/cross_domain_test.go
• internal/router/router_ee.go
• internal/server/config.go
• internal/server/server_ee.go
• internal/service/user.go
• internal/utility/token.go
• sdk/python/ragflow_sdk/modules/__init__.py
• sdk/python/ragflow_sdk/modules/agent.py
• sdk/python/ragflow_sdk/modules/base.py
• sdk/python/ragflow_sdk/modules/chat.py
• sdk/python/ragflow_sdk/modules/chunk.py
• sdk/python/ragflow_sdk/modules/dataset.py
• sdk/python/ragflow_sdk/modules/document.py
• sdk/python/ragflow_sdk/modules/session.py
• sdk/python/ragflow_sdk/ragflow.py
• test/testcases/test_web_api/test_system_app/test_apps_init_unit.py
• web/src/components/document-preview/md/index.tsx
• web/src/constants/markdown-remark-plugins.ts

This document describes RAGFlow's multi-method authentication and authorization system. RAGFlow supports three primary authentication mechanisms: API key authentication (including Beta tokens), session-based authentication for web UI interactions, and OAuth/OIDC for single-sign-on integration. It covers the implementation across the Python (Quart) and Go (Gin) backend layers, ensuring unified security policies.

Overview

RAGFlow implements a flexible authentication architecture that serves different client types across its polyglot backend:

• JWT/Session Authentication: Primarily used by the React web frontend. It supports JWT decoding via URLSafeTimedSerializer and falls back to server-side session cookies managed via Redis api/apps/__init__.py79-83 api/apps/__init__.py110-142
• API Key Authentication: Used by the Python SDK and HTTP API clients. The APIToken model manages these credentials api/db/db_models.py26
• Beta Token Authentication: A specialized API token path for public bot integrations and agent access, allowing controlled access to specific chat dialogs api/apps/__init__.py170-183
• Go Backend Auth: The Go server implements handlers to maintain compatibility with Python's session and token logic, particularly for the admin and ingestion layers internal/admin/handler.go94-137

Authorization is tenant-based. Each authenticated user is associated with a tenant_id (often identical to the user ID for the owner) that controls access to datasets, chat assistants, and system resources api/db/services/user_service.py27 internal/service/user.go194-206

Sources: api/apps/__init__.py94-107 api/apps/__init__.py110-142 internal/admin/handler.go94-137 internal/service/user.go194-206

Authentication Flow and Decorators

The @login_required Decorator (Python)

In the Python backend, route protection is primarily handled by the login_required decorator defined in api/apps/__init__.py. This decorator supports multiple authentication types simultaneously (JWT, API, BETA) api/apps/__init__.py227-247

Title: Authentication Resolution Flow in "api.apps.login_required"

Sources: api/apps/__init__.py144-225 api/apps/__init__.py227-247

Current User Proxy

RAGFlow provides a current_user proxy, allowing developers to access the authenticated user's details throughout the request lifecycle without passing user objects explicitly api/apps/__init__.py249-250

• current_user: A LocalProxy that resolves to g.user api/apps/__init__.py250
• g.auth_type: Stores the method used for the current request (e.g., JWT, API, or BETA) api/apps/__init__.py139-140

Sources: api/apps/__init__.py249-250 api/apps/__init__.py139-140

Authentication Methods

API and Beta Token Authentication

API keys provide programmatic access. The system distinguishes between standard token (general API access) and beta tokens (public bot/agent interfaces).

• Standard API Tokens: Linked to a tenant and validated against the APIToken table api/apps/__init__.py202-218
• Beta Tokens: Used for specific chat completions where full user credentials are not required, often used in embedded chat widgets api/apps/__init__.py170-183

Sources: api/apps/__init__.py170-183 api/apps/__init__.py202-218

JWT and Session Authentication

The web UI uses session-based authentication. When a user logs in, the UserService (Python) or UserService (Go) validates credentials.

User Login Flow

Title: Login Sequence in "internal.service.UserService" and "api.apps.user_app"

Implementation detail: RAGFlow supports multiple hashing algorithms via Go compatibility (pbkdf2, scrypt) to match Python's password verification logic internal/service/user.go130-133 api/apps/__init__.py187-188

Sources: api/apps/__init__.py110-142 internal/service/user.go105-161 api/utils/api_utils.py136-154

Admin and Go Backend Authorization

The Go backend (admin and ingestion services) implements its own authentication logic to verify tokens issued by the Python layer.

• Admin Login: Only users with is_superuser set to true can access admin endpoints internal/admin/handler.go111-114
• Token Verification: The Go side uses utility.DumpAccessToken and the shared SECRET_KEY retrieved via server.GetSecretKey(redis.Get()) to validate tokens internal/admin/handler.go116-126
• Logout: In Go, logout invalidates the token by prefixing it with INVALID_ in the database internal/admin/service.go97-104

Sources: internal/admin/handler.go111-126 internal/admin/service.go97-104 internal/admin/service.go120-135

Validation and Error Handling

RAGFlow uses a robust validation layer to ensure request integrity before authentication/authorization checks.

• JSON Validation: validate_and_parse_json_request performs content-type verification and schema validation using Pydantic api/utils/validation_utils.py36-113
• Error Codes: Standard HTTP codes are used for auth failures (401 Unauthorized, 403 Forbidden) docs/references/http_api_reference.md18-24
• Error Responses: The server_error_response function maps exceptions to RetCode.UNAUTHORIZED when applicable api/utils/api_utils.py136-154

Sources: api/utils/validation_utils.py36-113 api/utils/api_utils.py136-154 docs/references/http_api_reference.md18-24

Configuration and Security Settings

Authentication behavior is controlled via service_conf.yaml and environment variables:

Setting	Description	File Reference
SECRET_KEY	Key used for JWT signing and session encryption	api/apps/__init__.py82
authentication.client.switch	Toggle for client-side API key authentication	conf/service_conf.yaml161-165
oauth	Configuration for GitHub, OIDC, and OAuth2 providers	conf/service_conf.yaml138-160
RESPONSE_TIMEOUT	Timeout for slow LLM responses (default 600s)	api/apps/__init__.py73
disable_password_login	Disables standard password auth when OAuth is preferred	docker/service_conf.yaml.template182

Sources: conf/service_conf.yaml138-165 api/apps/__init__.py73-83 docker/service_conf.yaml.template182