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

---
title: 新身份验证提供商开发指南
---

# 新身份验证提供商开发指南

LobeChat 使用 [Better Auth](https://www.better-auth.com) 作为身份验证服务。本文档介绍如何添加新的 SSO 身份验证提供商。

## 架构概述

Better Auth SSO 提供商分为两类：

| 类型        | 说明                         | 示例                            |
| --------- | -------------------------- | ----------------------------- |
| `builtin` | Better 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/advanced/auth.mdx` 和 `docs/self-hosting/advanced/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.ts`   | Better Auth 配置 |