新身份验证方式开发指南
LobeHub 使用 Better Auth 作为外部身份验证服务。Better Auth 是一个开源的身份验证库,它提供了一种简单的方式来实现身份验证和授权功能。本文档将介绍如何添加新的 SSO 身份验证提供商。
为了在 LobeHub 中添加新的身份验证提供者(例如添加 GitLab),你需要完成以下步骤:
Better Auth SSO 提供商分为两类:
| 类型 | 说明 | 示例 |
|---|---|---|
builtin | Better Auth 内置支持的提供商 | Google、GitHub、Microsoft、Apple |
generic | 通过 Generic OIDC/OAuth 插件实现 | Auth0、Keycloak、Okta 等 |
添加新的 SSO 提供商
以添加 GitLab(代码库中尚未实现)为例,介绍添加 generic 类型提供商的完整步骤。
步骤 1: 创建提供商定义文件
在 src/libs/better-auth/sso/providers/ 目录下创建 gitlab.ts:
TypeScript
步骤 2: 注册提供商
在 src/libs/better-auth/sso/index.ts 中导入并注册:
TypeScript
步骤 3: 添加环境变量类型声明
在 packages/env/src/auth.ts 中添加类型声明:
TypeScript
步骤 4: 更新文档(可选)
在 docs/self-hosting/auth.mdx 和 docs/self-hosting/auth.zh-CN.mdx 中添加提供商文档。
添加内置提供商
如果要添加 Better Auth 内置支持的提供商(如 Discord),步骤略有不同:
步骤 1: 创建提供商定义文件
TypeScript
步骤 2: 更新常量文件
在 src/libs/better-auth/constants.ts 中添加:
TypeScript
回调 URL 格式
配置 OAuth 应用时,回调 URL 格式为:
- 内置提供商:
https://yourdomain.com/api/auth/callback/{providerId} - Generic OIDC:
https://yourdomain.com/api/auth/callback/{providerId}
使用新提供商
配置环境变量后,在 AUTH_SSO_PROVIDERS 中启用:
Shell
调试技巧
- 环境变量检查失败:确保所有必需的环境变量都已设置
- 回调 URL 错误:检查 OAuth 应用配置的回调 URL 是否正确
- 用户信息映射:通过
mapProfileToUser自定义从 OAuth profile 到用户信息的映射
相关文件
| 文件 | 说明 |
|---|---|
src/libs/better-auth/sso/providers/*.ts | 提供商定义 |
src/libs/better-auth/sso/index.ts | 提供商注册 |
src/libs/better-auth/sso/types.ts | 类型定义 |
src/libs/better-auth/sso/helpers.ts | 辅助函数 |
src/libs/better-auth/constants.ts | 内置提供商常量 |
packages/env/src/auth.ts | 环境变量定义 |
src/libs/better-auth/define-config.ts | Better Auth 配置 |