ContextQMD
Back to Lobehub

LobeHub 身份验证服务配置

docs/self-hosting/auth.zh-CN.mdx

2.1.5612.6 KB
Original Source

身份验证服务

LobeHub 支持使用 Better Auth 配置外部身份验证服务，供企业 / 组织内部使用，统一管理用户授权。

Better Auth

Better Auth 是一个现代化、框架无关的身份验证库，旨在提供全面、安全、灵活的身份验证解决方案。它支持多种认证方式，包括邮箱 / 密码登录、魔法链接登录以及多种 OAuth/SSO 提供商。

主要特性

  • 邮箱 / 密码认证：内置支持传统的邮箱和密码登录，采用安全的密码哈希算法
  • 邮箱验证：可选的邮箱验证流程，支持自定义邮件模板
  • 魔法链接登录：通过邮件魔法链接实现无密码认证
  • OAuth/SSO 支持：集成 Google、GitHub、Microsoft、AWS Cognito 等主流身份提供商
  • 通用 OIDC/OAuth：支持任何符合 OpenID Connect 或 OAuth 2.0 标准的提供商

快速开始

要在 LobeHub 中启用 Better Auth，请设置以下环境变量：

环境变量类型描述
AUTH_SECRET必选用于加密会话令牌的密钥。使用以下命令生成：openssl rand -base64 32
NEXT_PUBLIC_AUTH_URL必选浏览器可访问的 Better Auth 基础 URL（例如 http://localhost:3010、https://LobeHub.com）。Vercel 部署时可选（会自动从 VERCEL_URL 获取）
AUTH_SSO_PROVIDERS可选启用的 SSO 提供商列表，以逗号分隔，例如 google,github,microsoft

支持的 SSO 提供商

提供商值环境变量
GooglegoogleAUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET
GitHubgithubAUTH_GITHUB_ID, AUTH_GITHUB_SECRET
MicrosoftmicrosoftAUTH_MICROSOFT_ID, AUTH_MICROSOFT_SECRET, AUTH_MICROSOFT_AUTHORITY_URL, AUTH_MICROSOFT_TENANT_ID
AppleappleAUTH_APPLE_CLIENT_ID, AUTH_APPLE_CLIENT_SECRET
AWS CognitocognitoAUTH_COGNITO_ID, AUTH_COGNITO_SECRET, AUTH_COGNITO_DOMAIN, AUTH_COGNITO_REGION, AUTH_COGNITO_USERPOOL_ID
Auth0auth0AUTH_AUTH0_ID, AUTH_AUTH0_SECRET, AUTH_AUTH0_ISSUER
AutheliaautheliaAUTH_AUTHELIA_ID, AUTH_AUTHELIA_SECRET, AUTH_AUTHELIA_ISSUER
AuthentikauthentikAUTH_AUTHENTIK_ID, AUTH_AUTHENTIK_SECRET, AUTH_AUTHENTIK_ISSUER
CasdoorcasdoorAUTH_CASDOOR_ID, AUTH_CASDOOR_SECRET, AUTH_CASDOOR_ISSUER
Cloudflare Zero Trustcloudflare-zero-trustAUTH_CLOUDFLARE_ZERO_TRUST_ID, AUTH_CLOUDFLARE_ZERO_TRUST_SECRET, AUTH_CLOUDFLARE_ZERO_TRUST_ISSUER
KeycloakkeycloakAUTH_KEYCLOAK_ID, AUTH_KEYCLOAK_SECRET, AUTH_KEYCLOAK_ISSUER
LogtologtoAUTH_LOGTO_ID, AUTH_LOGTO_SECRET, AUTH_LOGTO_ISSUER
OktaoktaAUTH_OKTA_ID, AUTH_OKTA_SECRET, AUTH_OKTA_ISSUER
ZITADELzitadelAUTH_ZITADEL_ID, AUTH_ZITADEL_SECRET, AUTH_ZITADEL_ISSUER
Generic OIDCgeneric-oidcAUTH_GENERIC_OIDC_ID, AUTH_GENERIC_OIDC_SECRET, AUTH_GENERIC_OIDC_ISSUER
飞书feishuAUTH_FEISHU_APP_ID, AUTH_FEISHU_APP_SECRET
微信wechatAUTH_WECHAT_ID, AUTH_WECHAT_SECRET

点击下方提供商查看详细配置指南：

<Cards> <Card href={'/zh/docs/self-hosting/auth/providers/password'} title={'邮箱密码'} />

<Card href={'/zh/docs/self-hosting/auth/providers/github'} title={'GitHub'} />

<Card href={'/zh/docs/self-hosting/auth/providers/google'} title={'Google'} />

<Card href={'/zh/docs/self-hosting/auth/providers/microsoft'} title={'Microsoft'} />

<Card href={'/zh/docs/self-hosting/auth/providers/apple'} title={'Apple'} />

<Card href={'/zh/docs/self-hosting/auth/providers/cognito'} title={'AWS Cognito'} />

<Card href={'/zh/docs/self-hosting/auth/providers/auth0'} title={'Auth0'} />

<Card href={'/zh/docs/self-hosting/auth/providers/authelia'} title={'Authelia'} />

<Card href={'/zh/docs/self-hosting/auth/providers/authentik'} title={'Authentik'} />

<Card href={'/zh/docs/self-hosting/auth/providers/casdoor'} title={'Casdoor'} />

<Card href={'/zh/docs/self-hosting/auth/providers/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />

<Card href={'/zh/docs/self-hosting/auth/providers/keycloak'} title={'Keycloak'} />

<Card href={'/zh/docs/self-hosting/auth/providers/logto'} title={'Logto'} />

<Card href={'/zh/docs/self-hosting/auth/providers/okta'} title={'Okta'} />

<Card href={'/zh/docs/self-hosting/auth/providers/zitadel'} title={'ZITADEL'} />

<Card href={'/zh/docs/self-hosting/auth/providers/generic-oidc'} title={'Generic OIDC'} />

<Card href={'/zh/docs/self-hosting/auth/providers/feishu'} title={'飞书'} />

<Card href={'/zh/docs/self-hosting/auth/providers/wechat'} title={'微信'} /> </Cards>

回调 URL 格式

配置 OAuth 提供商时，请使用以下回调 URL 格式：

  • 开发环境：http://localhost:3210/api/auth/callback/{provider}
  • 生产环境：https://yourdomain.com/api/auth/callback/{provider}

邮箱密码选项

禁用邮箱密码登录（仅 SSO 模式）：

设置 AUTH_DISABLE_EMAIL_PASSWORD=1 可在登录页面隐藏邮箱输入框，并将注册页面重定向至登录页面。用户只能通过已配置的 SSO 提供商登录。启用前请确保至少配置了一个 SSO 提供商。

限制注册邮箱或域名：

设置 AUTH_ALLOWED_EMAILS，以逗号分隔多个值：

bash
# 仅允许 @example.com 邮箱
AUTH_ALLOWED_EMAILS=example.com

# 允许多个域名和特定邮箱
AUTH_ALLOWED_EMAILS=example.com,company.org,[email protected]

<Callout type={'info'}> AUTH_ALLOWED_EMAILS 仅限制哪些邮箱可以注册，不会验证邮箱所有权。结合 AUTH_EMAIL_VERIFICATION=1 可确保用户确实拥有其注册邮箱。 </Callout>

OAuth 快速配置示例

Google OAuth：

  1. 在 Google Cloud Console 创建 OAuth 凭据
  2. 设置授权重定向 URI：https://yourdomain.com/api/auth/callback/google
  3. 配置环境变量：
bash
AUTH_SSO_PROVIDERS=google
AUTH_GOOGLE_ID=xxxxx.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx

GitHub OAuth：

  1. 在 GitHub 开发者设置 创建 OAuth App
  2. 设置回调 URL：https://yourdomain.com/api/auth/callback/github
  3. 配置环境变量：
bash
AUTH_SSO_PROVIDERS=github
AUTH_GITHUB_ID=Ov23xxxxxxxxxxxxx
AUTH_GITHUB_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

邮件服务配置

邮件服务用于邮箱验证、密码重置和魔法链接发送。

SMTP 配置：

bash
SMTP_HOST=smtp.gmail.com        # SMTP 服务器地址
SMTP_PORT=587                   # TLS 使用 587（推荐），SSL 使用 465
SMTP_SECURE=false               # port 465 时设为 true，port 587 时设为 false
[email protected]
SMTP_PASS=your-app-specific-password  # Gmail 需使用应用专用密码
[email protected]      # 可选，默认为 SMTP_USER

详细配置请参阅 邮件服务配置。

<Callout type={'tip'}> 前往 环境变量 可查阅所有 Better Auth 相关变量详情。 </Callout>

会话存储配置（可选）

默认情况下，Better Auth 使用数据库存储会话数据。你可以配置 Redis 作为二级存储，以获得更好的性能和跨实例会话共享能力。

环境变量类型描述
REDIS_URL可选Redis 连接 URL，配置后自动启用 Redis 会话存储
REDIS_PREFIX可选Redis 键前缀，默认为 lobechat

<Callout type={'info'}> 配置 Redis 后，认证会话数据将存储在 Redis 中，可以实现跨多个服务实例的会话共享，并提升会话验证速度。详细配置请参阅 Redis 缓存服务。 </Callout>

常见问题

Better Auth 支持哪些 SSO 提供商？

Better Auth 支持内置提供商（Google、GitHub、Microsoft、Apple、AWS Cognito）和通用 OIDC 提供商（Auth0、Authelia、Authentik、Casdoor、Cloudflare Zero Trust、Keycloak、Logto、Okta、ZITADEL、Generic OIDC、飞书、微信）。

如何启用多个 SSO 提供商？

设置 AUTH_SSO_PROVIDERS 环境变量，使用逗号分隔多个提供商，例如 google,github,microsoft。顺序决定登录页面上的显示顺序。

Casdoor 用户只有 username 没有 email 怎么办？

当前身份验证方案强依赖 email。请在 Casdoor 中为用户配置有效的 email 地址。 强烈建议使用真实有效的邮箱，否则密码重置、魔法链接登录等功能将无法使用。

邮箱可以随便乱填吗？

强烈不建议。请务必填写真实有效的邮箱地址。使用虚假邮箱会导致以下问题：

  • 密码重置功能无法使用
  • 魔法链接登录无法使用
  • 邮箱验证无法通过
  • 忘记密码时可能无法找回账户

这适用于所有身份验证方式，包括 Casdoor 等 SSO 提供商。请确保用户配置了有效的邮箱地址。

如何启用仅 SSO 模式（禁用邮箱密码登录）？

设置 AUTH_DISABLE_EMAIL_PASSWORD=1 可禁用邮箱密码登录。启用后：

  • 登录页面将隐藏邮箱输入框，仅显示 SSO 登录按钮
  • 注册页面将重定向到登录页面
  • 用户只能通过配置的 SSO 提供商登录

启用此选项前，请确保已通过 AUTH_SSO_PROVIDERS 配置了至少一个 SSO 提供商。

如何限制只允许特定邮箱或域名注册？

设置 AUTH_ALLOWED_EMAILS 环境变量，支持完整邮箱地址或域名，以逗号分隔。例如：

  • 只允许 example.com 域名：AUTH_ALLOWED_EMAILS=example.com
  • 允许多个域名和特定邮箱：AUTH_ALLOWED_EMAILS=example.com,company.org,[email protected]

<Callout type={'info'}> 注意：AUTH_ALLOWED_EMAILS 仅限制哪些邮箱地址可以注册，但不会验证邮箱所有权。如果需要确保用户确实拥有其注册的邮箱地址，请设置 AUTH_EMAIL_VERIFICATION=1 以启用邮箱验证。这需要配置邮件服务（SMTP）。 </Callout>

Webhook 支持

允许 LobeHub 在身份提供商中用户信息更新时接收通知。支持的提供商包括 Casdoor 和 Logto。请参考具体提供商文档进行配置。

其他 SSO 提供商

如果你需要使用上述列表中未包含的 SSO 提供商，可以使用 Generic OIDC 来配置任何符合 OpenID Connect 或 OAuth 2.0 标准的提供商。

欢迎提交 Pull Request 来添加更多内置 SSO 提供商支持。详情请参考 Better Auth 文档。