11 · 认证与安全（Authentication and Security）

认证与安全（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/11-authentication-and-security

翻译时间：2026-06-09T16:10:18.612Z

翻译模型：deepseek-chat

原文字符数：8113

项目：Open WebUI (open-webui)

---

身份认证与安全

相关源文件

以下文件为本 wiki 页面的生成提供了上下文：

• backend/open_webui/config.py
• backend/open_webui/env.py
• backend/open_webui/main.py
• backend/open_webui/routers/auths.py
• backend/open_webui/utils/auth.py
• backend/open_webui/utils/oauth.py
• src/lib/apis/auths/index.ts
• src/lib/components/chat/Settings/Account.svelte
• src/lib/components/chat/Settings/Audio.svelte
• src/routes/auth/+page.svelte

本文档对 Open WebUI 中全面的身份认证与授权系统进行了高层概述。该系统支持从传统的密码登录到企业级 LDAP 和 OAuth 2.1 集成的多种认证方式。

身份认证方法概述

Open WebUI 实现了多层身份认证策略，可通过环境变量进行切换。会话管理的主要入口点是 auths 路由器，它负责处理 JWT 签发和用户验证。

1. 密码认证：使用 bcrypt 进行安全哈希的标准邮箱/密码登录 backend/open_webui/utils/auth.py:166-168。
2. OAuth 2.1 / OIDC：通过 authlib 集成 Google、Microsoft、GitHub 等提供商以及自定义 OIDC 服务器 backend/open_webui/utils/oauth.py:20-22。
3. LDAP/Active Directory：使用 ldap3 库进行企业用户同步和身份认证 backend/open_webui/routers/auths.py:88-90。
4. 可信头部：通过 WEBUI_AUTH_TRUSTED_EMAIL_HEADER 将认证委托给反向代理 backend/open_webui/env.py:42。
5. API 密钥：通过 create_api_key 创建的哈希密钥，用于程序化访问 backend/open_webui/utils/auth.py:66。

有关实现的技术细节，请参阅身份认证方法。

身份认证决策流程

下图展示了系统如何使用 FastAPI 依赖项从传入请求中确定用户身份。

flowchart TD
    Request["传入的 FastAPI 请求"] --> AuthCheck{"WEBUI_AUTH<br/>已启用？"}
    AuthCheck -- "否" --> Anonymous["匿名用户"]
    AuthCheck -- "是" --> HeaderCheck{"Authorization<br/>头部？"}

    HeaderCheck -- "Bearer sk-..." --> APIKey["API 密钥验证<br/>get_http_authorization_cred()"]
    HeaderCheck -- "Bearer JWT" --> JWTCheck["JWT 验证<br/>decode_token()"]
    HeaderCheck -- "无" --> CookieCheck{"存在 'token'<br/>Cookie？"}

    CookieCheck -- "是" --> JWTCheck
    CookieCheck -- "否" --> TrustedCheck{"已配置可信<br/>头部？"}

    TrustedCheck -- "是" --> TrustedAuth["头部认证<br/>WEBUI_AUTH_TRUSTED_EMAIL_HEADER"]
    TrustedCheck -- "否" --> Unauthorized["401 未授权"]

    APIKey --> UserFetch["get_current_user()<br/>从用户数据库获取"]
    JWTCheck --> UserFetch
    TrustedAuth --> UserFetch

    UserFetch --> RoleCheck{"角色 != 'pending'？"}
    RoleCheck -- "是" --> Authorized["授权请求"]
    RoleCheck -- "否" --> Forbidden["403 禁止访问"]

图示：FastAPI 依赖注入系统中的身份认证逻辑流程。

来源：backend/open_webui/utils/auth.py:163-221，backend/open_webui/routers/auths.py:170-228

OAuth 和 OIDC 集成

Open WebUI 具有基于 authlib 库的强大 OAuth 集成功能。它支持 MCP（模型上下文协议）等环境中的动态客户端注册，并处理角色和组的复杂声明映射。

• 动态注册：使用 RFC 7591 通过 MCPOAuthClientMetadata 自动向 OIDC 提供商注册客户端 backend/open_webui/utils/oauth.py:95-97。
• 声明映射：将 OAUTH_GROUPS_CLAIM 和 OAUTH_ROLES_CLAIM 等提供商声明映射到内部实体 backend/open_webui/utils/oauth.py:126-128。
• 会话存储：在存储到 OAuthSessions 模型 backend/open_webui/models/oauth_sessions.py 之前，使用 FERNET 加密 OAuth 令牌 backend/open_webui/utils/oauth.py:178-187。

有关配置和提供商支持的详细信息，请参阅OAuth 集成。

来源：backend/open_webui/utils/oauth.py:36-66，backend/open_webui/utils/oauth.py:116-141，backend/open_webui/env.py:135

LDAP 和 Active 目录

LDAP 集成允许组织利用现有身份提供商。它通过 auths 路由器进行管理，并支持：

• 用户预配置：在成功 LDAP 绑定后，通过 create_session_response 自动创建账户 backend/open_webui/routers/auths.py:100-149。
• 组同步：将 LDAP 组同步到内部 Groups backend/open_webui/routers/auths.py:29。
• 安全性：支持 Tls 配置以实现安全连接 backend/open_webui/routers/auths.py:88。

有关设置说明和属性映射，请参阅LDAP 集成。

来源：backend/open_webui/routers/auths.py:113-143，backend/open_webui/routers/auths.py:52-53

访问控制和 RBAC

授权通过基于角色的访问控制（RBAC）系统强制执行。系统区分 admin、user 和 pending 角色，并在数据库级别管理细粒度权限。

代码实体关联

下图将自然语言角色与执行这些角色的具体代码实体和模型关联起来。

classDiagram
    class UserModel {
        +id: str
        +email: str
        +role: str
        +name: str
        +profile_image_url: str
    }
    class Users {
        +get_user_by_id(id)
        +get_users()
        +update_user_role(id, role)
    }
    class GroupModel {
        +id: str
        +name: str
        +permissions: dict
    }
    class Groups {
        +create_new_group()
        +get_groups()
        +add_user_to_group()
    }
    class AccessControl {
        +has_permission(user_id, permission, db)
        +get_permissions(user_id, config, db)
    }
    class AuthUtils {
        +get_current_user()
        +get_admin_user()
        +get_verified_user()
    }

    AuthUtils --> Users : "调用 Users.get_user_by_id"
    AuthUtils --> AccessControl : "检查权限"
    Users ..> UserModel : "管理"
    Groups ..> GroupModel : "管理"
    AccessControl ..> Groups : "查询用户组"

图示：身份认证工具与数据模型之间的关系。

有关详细的权限矩阵和 SCIM 2.0 预配置，请参阅访问控制和 RBAC。

来源：backend/open_webui/utils/access_control.py:77-78，backend/open_webui/models/users.py:124，backend/open_webui/routers/auths.py:68-70

令牌和会话管理

Open WebUI 的安全性依赖于 JWT 和 OAuth 会话的生命周期管理。

• JWT 生命周期：令牌使用 WEBUI_SECRET_KEY backend/open_webui/env.py:39 和 HS256 算法 backend/open_webui/utils/auth.py:51 进行签名。过期时间由 JWT_EXPIRES_IN backend/open_webui/config.py:66 控制。
• 撤销：可以通过 Redis 使用 jti 声明撤销令牌 backend/open_webui/utils/auth.py:231-235。invalidate_token 函数处理每个令牌的撤销 backend/open_webui/utils/auth.py:65。
• 加密：敏感 OAuth 客户端数据通过 encrypt_data 使用从 OAUTH_CLIENT_INFO_ENCRYPTION_KEY 派生的 Fernet 密钥进行加密 backend/open_webui/utils/oauth.py:180-198。

有关令牌结构和 Redis 支持的会话存储的详细信息，请参阅令牌和会话管理。

来源：backend/open_webui/utils/auth.py:200-212，backend/open_webui/utils/auth.py:222-240，backend/open_webui/utils/oauth.py:193-204