身份验证

MkSaaS 使用 Better Auth 进行身份验证，模板提供了一个灵活且安全的系统，支持多种身份验证方法、会话管理和基于角色的访问控制。

设置

请按照以下步骤配置必要的环境变量：

1. 生成 Better Auth 密钥

BETTER_AUTH_SECRET 是用于加密和生成哈希的随机字符串，您可以使用 OpenSSL 命令生成密钥：

openssl rand -base64 32

生成密钥后，将其添加到 .env 文件中：

BETTER_AUTH_SECRET="your_generated_secret_key"

2. 配置 GitHub OAuth

要启用 GitHub 身份验证，您需要注册您的应用程序：

进入到 GitHub 开发者设置
点击 OAuth Apps，然后点击 New OAuth App
填写注册表单：
- 应用程序名称：您的应用程序名称（例如，MkSaaS）
- 主页网址：您的网站地址，例如，https://your-domain.com （或本地开发的 http://localhost:3000）
- 应用程序描述：您应用程序的简要描述
- 授权回调 URL：设置为 https://your-domain.com/api/auth/callback/github（或本地开发的 http://localhost:3000/api/auth/callback/github）
点击 Register application
注册后，您将看到 GitHub OAuth Client ID
点击 Generate a new client secret 创建 GitHub OAuth 客户端密钥
复制这两个值并将它们添加到 .env 文件中：

GITHUB_CLIENT_ID="your_github_client_id"
GITHUB_CLIENT_SECRET="your_github_client_secret"

确保 website.tsx 文件中 auth.enableGithubLogin 设置为 true

src/config/website.tsx

auth: {
  enableGithubLogin: true,
}

在 GitHub 中创建两个不同的 OAuth 应用程序：一个用于生产环境，一个用于开发环境。

永远不要在两个环境中使用相同的 OAuth 应用程序，因为它们需要不同的回调 URL。

3. 配置 Google OAuth

要启用 Google 身份验证，请按照以下步骤获取客户端凭据：

进入到 Google Cloud Console
创建新项目或选择现有项目
在左侧边栏中进入到 Credentials
点击 Create Credentials 并选择 OAuth client ID
如果这是您第一次，您可能需要配置 OAuth 同意屏幕：
- 用户类型：选择 External
- 填写必需信息（应用名称、用户支持电子邮件、开发者联系方式）
- 添加授权域，包括网站域名
- 在每个部分中点击 Save and Continue
返回 Credentials 并创建 OAuth Client ID：
- 应用程序类型：Web 应用程序
- 名称：您的网站名称
- 授权的 JavaScript 来源：添加您的域（例如，https://your-domain.com 或 http://localhost:3000）
- 授权的重定向 URI：添加 https://your-domain.com/api/auth/callback/google（或本地开发的 http://localhost:3000/api/auth/callback/google）
点击 Create，复制提供的客户端 ID 和客户端密钥，将它们添加到 .env 文件中：

GOOGLE_CLIENT_ID="your_google_client_id"
GOOGLE_CLIENT_SECRET="your_google_client_secret"

确保 website.tsx 文件中 auth.enableGoogleLogin 设置为 true

src/config/website.tsx

auth: {
  enableGoogleLogin: true,
}

推荐在 Google Cloud Console 中创建两个不同的 OAuth 应用程序：一个用于生产环境，一个用于开发环境。不要在两个环境中使用相同的 OAuth 应用程序，因为它们需要不同的回调 URL。
如果本地开发时 Google 登录失败，请检查梯子是否正常，并确保开启 TUN 模式 (建议使用 Clash Verge)。

4. 配置邮箱注册

要启用邮箱注册，请按照以下步骤获取客户端凭据：

按照邮件配置文档的要求配置邮件服务
更新 website.tsx 文件，设置开启邮箱注册，并设置邮件服务商和默认发送者邮箱地址，例如：

src/config/website.tsx

export const websiteConfig = {
  // ...其他配置
  auth: {
    enableCredentialLogin: true,
  },
  mail: {
    provider: 'resend', // 要使用的邮件提供商
    fromEmail: 'support@example.com', // 默认发送者邮箱地址
  },
  // ...其他配置
}

如果您正在设置环境，现在您可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。

环境配置

设置环境变量

身份验证系统架构

MkSaaS 中的身份验证系统设计有以下组件：

auth.ts

auth-types.ts

auth-client.ts

核心功能

邮箱密码身份验证（支持邮箱注册、邮箱登录、邮箱找回密码）
社交登录，默认支持 Google、GitHub 登录，可以扩展更多社交提供商，如 Twitter、Apple、Facebook 等
不同身份验证方法之间的账户绑定，例如将 GitHub 账户绑定到邮箱账户
用户和角色管理，包括管理员功能，例如封禁用户等
注册时自动订阅邮件列表（可配置）

客户端使用

访问会话数据

在客户端组件中，您可以使用 useSession hook 访问用户的会话数据：

'use client';

import { useSession } from '@/lib/auth-client';

export function ProfileButton() {
  const { data: session, isPending } = useSession();

  if (isPending) {
    return <div>加载中...</div>;
  }

  if (session) {
    return (
      <div>
        <p>欢迎，{session.user.name}！</p>
        <button onClick={() => signOut()}>退出登录</button>
      </div>
    );
  }

  return (
    <button onClick={() => signIn.social({ provider: 'google' })}>
      登录
    </button>
  );
}

身份验证操作

auth 客户端提供常见身份验证操作的方法：

import { signIn, signOut } from '@/lib/auth-client';

// 使用电子邮件和密码登录
signIn.emailAndPassword({
  email: 'user@example.com',
  password: 'password123',
});

// 使用社交提供商登录
signIn.social({
  provider: 'google',
});

// 退出登录
signOut();

服务器端使用

登录用户保护路由

在服务器组件中，您可以通过检查会话来保护路由：

import { auth } from '@/lib/auth';
import { redirect } from 'next/navigation';
import { headers } from 'next/headers';

export default async function ProtectedPage() {
  const session = await auth.api.getSession({ headers: await headers() });

  if (!session?.user) {
    redirect('/auth/login');
  }

  return <div>受保护的内容</div>;
}

管理员路由保护路由

对于仅限管理员的路由，您可以检查会话中的用户角色：

import { auth } from '@/lib/auth';
import { redirect } from 'next/navigation';
import { headers } from 'next/headers';

export default async function AdminPage() {
  const session = await auth.api.getSession({ headers: await headers() });

  if (!session?.user || session.user.role !== 'admin') {
    redirect('/auth/login');
  }

  return <div>管理员内容</div>;
}