ContextQMD
Back to Lobehub

新身份验证方式开发指南

docs/development/basic/add-new-authentication-providers.zh-CN.mdx

2.1.565.7 KB
Original Source

新身份验证方式开发指南

LobeHub 使用 Auth.js v5 作为外部身份验证服务。Auth.js 是一个开源的身份验证库，它提供了一种简单的方式来实现身份验证和授权功能。本文档将介绍如何使用 Auth.js 来实现新的身份验证方式。

LobeHub 使用 Better Auth 作为身份验证服务。本文档介绍如何添加新的 SSO 身份验证提供商。

为了在 LobeHub 中添加新的身份验证提供者（例如添加 Okta)，你需要完成以下步骤：

Better Auth SSO 提供商分为两类：

类型说明示例
builtinBetter Auth 内置支持的提供商Google、GitHub、Microsoft、Apple
generic通过 Generic OIDC/OAuth 插件实现Okta、Auth0、Keycloak 等

添加新的 SSO 提供商

以添加 Okta 为例，介绍添加 generic 类型提供商的完整步骤。

步骤 1: 创建提供商定义文件

在 src/libs/better-auth/sso/providers/ 目录下创建 okta.ts：

ts
import { authEnv } from '@/envs/auth';

import { buildOidcConfig } from '../helpers';
import type { GenericProviderDefinition } from '../types';

const provider: GenericProviderDefinition<{
  AUTH_OKTA_ID: string;
  AUTH_OKTA_ISSUER: string;
  AUTH_OKTA_SECRET: string;
}> = {
  // 构建 OIDC 配置
  build: (env) =>
    buildOidcConfig({
      clientId: env.AUTH_OKTA_ID,
      clientSecret: env.AUTH_OKTA_SECRET,
      issuer: env.AUTH_OKTA_ISSUER,
      overrides: {
        // 可选：自定义用户信息映射
        mapProfileToUser: (profile) => ({
          email: profile.email,
          name: profile.name ?? profile.preferred_username ?? profile.email ?? profile.sub,
        }),
      },
      providerId: 'okta',
    }),

  // 环境变量检查
  checkEnvs: () => {
    return !!(authEnv.AUTH_OKTA_ID && authEnv.AUTH_OKTA_SECRET && authEnv.AUTH_OKTA_ISSUER)
      ? {
          AUTH_OKTA_ID: authEnv.AUTH_OKTA_ID,
          AUTH_OKTA_ISSUER: authEnv.AUTH_OKTA_ISSUER,
          AUTH_OKTA_SECRET: authEnv.AUTH_OKTA_SECRET,
        }
      : false;
  },

  // 提供商 ID（用于 AUTH_SSO_PROVIDERS 配置）
  id: 'okta',
  type: 'generic',
};

export default provider;

步骤 2: 注册提供商

在 src/libs/better-auth/sso/index.ts 中导入并注册：

ts
// 导入提供商
import Okta from './providers/okta';

// 添加到 providerDefinitions 数组
const providerDefinitions = [
  // ... 其他提供商
  Okta,
] as const;

步骤 3: 添加环境变量类型声明

在 src/envs/auth.ts 中添加类型声明：

ts
// ProcessEnv 接口中添加
AUTH_OKTA_ID?: string;
AUTH_OKTA_SECRET?: string;
AUTH_OKTA_ISSUER?: string;

// getAuthConfig server schema 中添加
AUTH_OKTA_ID: z.string().optional(),
AUTH_OKTA_SECRET: z.string().optional(),
AUTH_OKTA_ISSUER: z.string().optional(),

// runtimeEnv 中添加
AUTH_OKTA_ID: process.env.AUTH_OKTA_ID,
AUTH_OKTA_SECRET: process.env.AUTH_OKTA_SECRET,
AUTH_OKTA_ISSUER: process.env.AUTH_OKTA_ISSUER,

步骤 4: 更新文档（可选）

在 docs/self-hosting/auth.mdx 和 docs/self-hosting/auth.zh-CN.mdx 中添加提供商文档。

添加内置提供商

如果要添加 Better Auth 内置支持的提供商（如 Discord），步骤略有不同：

步骤 1: 创建提供商定义文件

ts
import { authEnv } from '@/envs/auth';

import type { BuiltinProviderDefinition } from '../types';

const provider: BuiltinProviderDefinition<{
  AUTH_DISCORD_ID: string;
  AUTH_DISCORD_SECRET: string;
}> = {
  build: (env) => ({
    clientId: env.AUTH_DISCORD_ID,
    clientSecret: env.AUTH_DISCORD_SECRET,
  }),
  checkEnvs: () => {
    return !!(authEnv.AUTH_DISCORD_ID && authEnv.AUTH_DISCORD_SECRET)
      ? {
          AUTH_DISCORD_ID: authEnv.AUTH_DISCORD_ID,
          AUTH_DISCORD_SECRET: authEnv.AUTH_DISCORD_SECRET,
        }
      : false;
  },
  id: 'discord',
  type: 'builtin',
};

export default provider;

步骤 2: 更新常量文件

在 src/libs/better-auth/constants.ts 中添加：

ts
export const BUILTIN_BETTER_AUTH_PROVIDERS = [
  'apple',
  'google',
  'github',
  'cognito',
  'microsoft',
  'discord', // 新增
] as const;

回调 URL 格式

配置 OAuth 应用时，回调 URL 格式为：

  • 内置提供商：https://yourdomain.com/api/auth/callback/{providerId}
  • Generic OIDC：https://yourdomain.com/api/auth/callback/{providerId}

使用新提供商

配置环境变量后，在 AUTH_SSO_PROVIDERS 中启用：

bash
AUTH_SSO_PROVIDERS=google,github,okta
AUTH_OKTA_ID=your-client-id
AUTH_OKTA_SECRET=your-client-secret
AUTH_OKTA_ISSUER=https://your-domain.okta.com

调试技巧

  1. 环境变量检查失败：确保所有必需的环境变量都已设置
  2. 回调 URL 错误：检查 OAuth 应用配置的回调 URL 是否正确
  3. 用户信息映射：通过 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内置提供商常量
src/envs/auth.ts环境变量定义
src/libs/better-auth/define-config.tsBetter Auth 配置