Authelia 集成 Open WebUI通过 OpenID Connect 1.0 实现单点登录与基于组的角色管理【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本指南以 Authelia 的 OpenID Connect 1.0 Provider 为身份提供方IdP将 Open WebUI 配置为受信任的 Relying Party客户端应用实现通过 Authelia 登录页完成认证、借助groups声明完成应用内角色映射的完整闭环。阅读本文后你将能够在 Authelia 中注册 Open WebUI 客户端并通过环境变量.env或 Docker Compose完成 Open WebUI 侧的全部接入配置同时掌握 PKCE、客户端密钥哈希存储、角色授权策略等安全要点。测试版本与前提假设本集成指南在以下版本组合下完成验证组件版本Autheliav4.39.24Open WebUIv0.6.13示例配置基于以下假设实际部署时请替换为你的真实域名与凭据Application Root URL应用根地址https://ai.example.com/Authelia Root URL身份提供方地址https://auth.example.com/Client IDopen-webuiClient Secretinsecure_secret本文中的域名example.com与子域auth/ai均为占位符正文中的地址均可按你的实际环境替换。前置准备生成安全的 Client ID 与 Client Secret示例中的client_id与client_secret仅用于演示。Authelia 官方明确建议不要在生产环境直接使用本文示例值而应使用随机生成的凭据。生成方式参见 Authelia 集成 FAQ 中的「如何生成 Client Identifier 或 Client Secret」一节命令如下生成 Client ID72 位、仅含 RFC3986 非保留字符避免被客户端 URL 编码问题干扰authelia crypto rand --length 72 --charset rfc3986生成 Client Secret 并输出可直接写入 Authelia 配置的 PBKDF2 哈希推荐避免明文存储authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986上述命令会同时打印原始随机值与 URL 编码后的值若两者不同可直接将哈希结果填入 Authelia 配置将原始值填入 Open WebUI 环境变量。在容器环境下可在命令前加docker run --rm authelia/authelia:latest执行。Authelia 端注册 Open WebUI 为 OIDC 客户端客户端注册配置在 Authelia 的configuration.yml中于identity_providers.oidc.clients列表内添加如下客户端注册配置identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. ## See: https://www.authelia.com/c/oidc clients: - client_id: open-webui client_name: Open WebUI client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # The digest of insecure_secret. public: false authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 redirect_uris: - https://ai.example.com/oauth/oidc/callback scopes: - openid - profile - groups - email response_types: - code grant_types: - authorization_code access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_basic注意本示例仅包含客户端注册片段。你必须同时按 OpenID Connect 1.0 Provider 配置指南 完成identity_providers.oidc下的必需元素如 issuer、密钥等配置否则 Provider 无法正常工作。关键参数逐项解读以下参数说明以 OpenID Connect 1.0 Clients 配置文档 为准client_id客户端唯一标识必须与 Open WebUI 中配置的OAUTH_CLIENT_ID完全一致。约束为长度不超过 100 字符、仅包含 RFC3986 非保留字符、且在全部已注册客户端中唯一。client_name展示在 Authelia 同意页 / 管理界面中的友好名称默认与client_id相同。client_secretAuthelia 与应用共享的密钥必须与 Open WebUI 中配置的OAUTH_CLIENT_SECRET一致。强烈建议以 PBKDF2 等哈希形式存储如示例中$pbkdf2-sha512$...即insecure_secret的摘要明文存储虽仍被接受但已弃用不保证未来版本继续支持详见 FAQ 的 Plaintext 一节。若哈希迭代成本过高可能导致客户端请求超时可参考 FAQ 的「Tuning the work factors」调整。public: false声明为机密型confidential客户端表示应用有能力保管凭据。Open WebUI 使用client_secret_basic在 Token 端点认证因此必须为false。authorization_policy: two_factor访问该客户端所需的 Authelia 授权策略示例要求用户完成双重认证2FA才能授权。可依据你的安全要求调整为one_factor或deny等。require_pkce: truepkce_challenge_method: S256强制启用 PKCEProof Key for Code ExchangeRFC7636并要求使用S256挑战方法即对code_verifier计算 SHA-256 摘要后再 Base64URL 编码作为code_challenge。PKCE 可有效缓解授权码拦截攻击即使对于无法在 Token 端点认证的公开客户端同样有效属于推荐的安全加固项。redirect_uris合法的回调地址白名单必须包含 Open WebUI 的回调端点https://ai.example.com/oauth/oidc/callback。所有未在此列出的回调都会被判定为不安全并拒绝该列表大小写敏感且 URI 必须携带http或httpsscheme。scopes允许该客户端请求的权限范围示例授予openid、profile、groups、email。其中groups是后续 Open WebUI 角色管理OAUTH_ROLES_CLAIMgroups所依赖的核心声明。response_types: [code]仅允许授权码Authorization Code响应类型。Authelia 官方安全建议优先仅使用code其余响应类型安全性相对较低。grant_types: [authorization_code]限定客户端只能通过授权码流程在 Token 端点换取令牌。access_token_signed_response_alg: none与userinfo_signed_response_alg: noneAccess Token 与 UserInfo 响应不进行 JWS 签名直接返回 JSON。Open WebUI 按此方式消费令牌这是该集成能够工作的前提之一。token_endpoint_auth_method: client_secret_basic客户端在 Token 端点使用 HTTP Basic 认证方式提交client_id/client_secret。注意按 RFC6749 Appendix B 要求二者在编码进 Basic 头前必须经过 URL 转义——这正是推荐使用仅含非保留字符随机串作为凭据的原因。关于 OIDC 客户端的通用注意事项client_id与client_secret在本文中仅为可读性与演示目的生产环境务必按上文命令重新生成注册客户端仅完成一半工作Provider 级配置identity_providers.oidc下的 issuer、密钥材料等不可缺失请对照 Provider 配置文档 核对Authelia 作为 OpenID Connect 1.0 Provider 已通过 OpenID Certified™。Open WebUI 端通过环境变量接入Open WebUI 的 OAuth/OIDC 接入仅有一种配置方式——环境变量。需在 Open WebUI 服务启动前设置以下变量使其指向 Authelia 并完成凭据、范围与角色映射的声明。标准环境变量.envWEBUI_URLhttps://ai.example.com ENABLE_OAUTH_SIGNUPtrue OAUTH_MERGE_ACCOUNTS_BY_EMAILtrue OAUTH_CLIENT_IDopen-webui OAUTH_CLIENT_SECRETinsecure_secret OPENID_PROVIDER_URLhttps://auth.example.com/.well-known/openid-configuration OAUTH_PROVIDER_NAMEAuthelia OAUTH_SCOPESopenid email profile groups ENABLE_OAUTH_ROLE_MANAGEMENTtrue OAUTH_ALLOWED_ROLESopenwebui,openwebui-admin OAUTH_ADMIN_ROLESopenwebui-admin OAUTH_ROLES_CLAIMgroups OAUTH_CODE_CHALLENGE_METHODS256Docker Compose 写法services: open-webui: environment: WEBUI_URL: https://ai.example.com ENABLE_OAUTH_SIGNUP: true OAUTH_MERGE_ACCOUNTS_BY_EMAIL: true OAUTH_CLIENT_ID: open-webui OAUTH_CLIENT_SECRET: insecure_secret OPENID_PROVIDER_URL: https://auth.example.com/.well-known/openid-configuration OAUTH_PROVIDER_NAME: Authelia OAUTH_SCOPES: openid email profile groups ENABLE_OAUTH_ROLE_MANAGEMENT: true OAUTH_ALLOWED_ROLES: openwebui,openwebui-admin OAUTH_ADMIN_ROLES: openwebui-admin OAUTH_ROLES_CLAIM: groups OAUTH_CODE_CHALLENGE_METHOD: S256环境变量逐项说明环境变量示例值作用WEBUI_URLhttps://ai.example.comOpen WebUI 对外可访问的完整根地址用于回调与校验ENABLE_OAUTH_SIGNUPtrue允许通过 OAuth 登录自动创建注册本地账号OAUTH_MERGE_ACCOUNTS_BY_EMAILtrue按邮箱将 OAuth 身份与已有本地账号合并避免重复建号OAUTH_CLIENT_IDopen-webui与 Authelia 客户端配置中的client_id严格一致OAUTH_CLIENT_SECRETinsecure_secret与 Authelia 客户端配置中client_secret对应的原始明文非哈希OPENID_PROVIDER_URLhttps://auth.example.com/.well-known/openid-configurationAuthelia 的 OIDC Discovery 端点地址Open WebUI 据此自动发现授权、令牌、UserInfo 等端点OAUTH_PROVIDER_NAMEAuthelia登录页面上展示的提供方名称OAUTH_SCOPESopenid email profile groups授权请求携带的 scope须与 Authelia 客户端scopes集合兼容ENABLE_OAUTH_ROLE_MANAGEMENTtrue启用基于 OAuth 声明的角色管理OAUTH_ALLOWED_ROLESopenwebui,openwebui-admin允许登录的角色白名单只有声明中命中这些值的用户才被允许登录OAUTH_ADMIN_ROLESopenwebui-admin命中该值的用户将被授予 Open WebUI 管理员权限OAUTH_ROLES_CLAIMgroups指定从 ID Token / UserInfo 的哪个声明中读取角色与 Authelia 的groupsscope 对应OAUTH_CODE_CHALLENGE_METHODS256PKCE 挑战方法必须与 Authelia 客户端pkce_challenge_method一致角色管理与权限映射机制本集成最具价值的一点是借助 Authelia 的groups声明把身份目录中的用户组直接映射为 Open WebUI 的应用角色登录门槛只有属于openwebui或openwebui-admin组的用户才能登录。该限制通过OAUTH_ALLOWED_ROLES实现——Authelia 在 UserInfo / ID Token 中返回的groups声明对应 Authelia 客户端的groupsscope会被 Open WebUI 逐值比对不在白名单内的用户将被拒绝。管理员指派拥有openwebui-admin组的用户自动成为 Open WebUI 管理员通过OAUTH_ADMIN_ROLES配置。这免去了在应用内手工逐人授权组变更即时反映到下次登录/刷新。这种做法的前提是 Authelia 侧已为相关用户配置好组信息如通过 用户数据库文件 或 LDAP 目录的组属性并在客户端scopes中授予groups。角色管理的两端配置必须对齐Authelia 负责「发布组声明」Open WebUI 负责「消费组声明」。安全要点与排错提示安全要点凭据随机化使用authelia crypto rand与authelia crypto hash generate pbkdf2生成并哈希凭据避免使用演示值密钥哈希存储Authelia 配置中存哈希$pbkdf2-sha512$...Open WebUI 中存原始值两侧分离保管强制 PKCErequire_pkce: true与OAUTH_CODE_CHALLENGE_METHODS256两侧必须同时启用且方法一致S256优于plain最小化授权response_types仅保留code、grant_types仅保留authorization_code按需裁剪scopes域名与回调校验redirect_uris与WEBUI_URL必须使用完全一致的公开地址且与 Authelia 实际经反向代理暴露的 URL 匹配。常见排错方向回调 302/错误检查redirect_uris是否精确包含https://ai.example.com/oauth/oidc/callback大小写敏感并确认WEBUI_URL与之同源Discovery 端点异常OPENID_PROVIDER_URL应指向https://auth.example.com/.well-known/openid-configuration。若返回的 issuer 与端点地址不正确通常是因为X-Forwarded-Proto/X-Forwarded-Host头未正确传递需经由反向代理访问而非直连 Authelia 端口详见 FAQ「Why doesnt the discovery endpoint return the correct issuer and endpoint URLs?」一节无法换取令牌若授权请求成功但 Token 端点无请求到达优先检查 Open WebUI 容器能否访问 Authelia 的 Token 端点/api/oidc/token并核对client_id/client_secret是否与 Authelia 侧一致、是否被 URL 编码问题干扰这正是推荐纯非保留字符凭据的原因角色不生效确认 Authelia 客户端已授予groupsscope、用户确实属于对应组且OAUTH_ROLES_CLAIMgroups与OAUTH_ALLOWED_ROLES/OAUTH_ADMIN_ROLES取值拼写一致。验证与参考配置完成后可通过以下路径验证集成是否生效访问https://ai.example.com并点击登录应被重定向至https://auth.example.com的 Authelia 登录页完成单因素或双因素认证并同意授权后浏览器应跳回 Open WebUI 的/oauth/oidc/callback随后以对应角色进入应用以openwebui-admin组用户登录可验证管理员权限授予是否生效。本指南对应的原始文档位于 Open WebUI 集成页面客户端全部可用配置项参见 OpenID Connect 1.0 Clients 配置文档Provider 侧配置参见 OpenID Connect 1.0 Provider 配置文档更完整的协议与端点背景可阅读 OpenID Connect 1.0 集成介绍 与 集成 FAQ。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考