单点登录
Libre WebUI 支持 GitHub 和 Hugging Face OAuth，也可通过通用 OIDC 集成连接任何 OpenID Connect 提供商。OAuth 用户仍存储为本地用户并默认获得 user 角色；OIDC 可从 Claim 映射角色和组。
GitHub OAuth
在 GitHub Developer Settings 中创建 OAuth 应用。
本地 Callback URL：
http://localhost:3001/api/auth/oauth/github/callback
生产 Callback URL：
https://your-domain.example/api/auth/oauth/github/callback
后端 .env：
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
GitHub OAuth 请求 user:email 范围，新用户名带有 gh_ 前缀。
Hugging Face OAuth
在 Hugging Face 设置中创建 OAuth 应用。
本地 Callback URL：
http://localhost:3001/api/auth/oauth/huggingface/callback
生产 Callback URL：
https://your-domain.example/api/auth/oauth/huggingface/callback
后端 .env：
HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback
新用户名带有 hf_ 前缀。
通用 OIDC
任何提供 Discovery 文档的 OpenID Connect 提供商都可使用，例如 Keycloak、Authentik、Authelia、Okta、Entra ID、Google Workspace。 流程使用 PKCE（S256）、CSRF State 和在签名验证后的 ID Token 中验证的 Nonce；签名密钥来自 JWKS。
注册机密客户端：
https://your-domain.example/api/auth/oauth/oidc/callback
OIDC_ISSUER_URL=https://id.example.com/realms/main
OIDC_CLIENT_ID=libre-webui
OIDC_CLIENT_SECRET=...
OIDC_DISPLAY_NAME=Example SSO
可选策略：
# Require a verified email in one of these domains
OIDC_ALLOWED_EMAIL_DOMAINS=example.com,example.org
# Grant/remove the admin role based on a group claim on every login
OIDC_GROUP_CLAIM=groups
OIDC_ADMIN_GROUPS=libre-admins
# Reconcile Libre group memberships with the group claim on every login
OIDC_SYNC_GROUPS=true
身份通过稳定的 sub 关联，因此提供商账户改名后仍保留 Libre 账户。允许注册时，新用户名带 oidc_ 前缀。
已属于未关联本地账户的电子邮件会被拒绝，而非静默合并。启用 OIDC_SYNC_GROUPS=true 后，与 Claim 值同名的
Libre 组成员关系由 Claim 驱动；请先在设置中的用户管理选项卡创建组。
共享设置
BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example
未明确设置 Callback URL 时，Libre WebUI 从 BASE_URL 生成默认值。
限制
Libre WebUI 当前不提供 SAML 或 SCIM。域白名单和角色/组映射仅适用于通用 OIDC；GitHub 与 Hugging Face 用户始终以 user 创建并由管理界面管理。
故障排除
OAuth 按钮无响应 — 检查客户端 ID、Secret 和后端重启。
提供商拒绝 Callback — URL 必须完全一致。
用户只有普通权限 — OAuth 默认创建 user，需要时由管理员提升。