身份验证

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

设置

要在 MkSaaS 中设置身份验证，请按照以下步骤配置必要的环境变量：

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）
- 主页 URL：您网站的 URL（例如，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 客户端 ID
点击 Generate a new client secret 创建 GitHub OAuth 客户端密钥
复制这两个值并将它们添加到 .env 文件中：

GITHUB_CLIENT_ID="your_github_client_id"
GITHUB_CLIENT_SECRET="your_github_client_secret"

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

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

3. 配置 Google OAuth

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

进入到 Google Cloud Console
创建新项目或选择现有项目
在左侧边栏中进入到 Credentials
点击 Create Credentials 并选择 OAuth client ID
如果这是您第一次，您可能需要配置 OAuth 同意屏幕：
- 用户类型：选择 External
- 填写必需信息（应用名称、用户支持电子邮件、开发者联系方式）
- 添加授权域，包括网站域名
- 在每个部分中点击 Save and Continue
返回 Credentials 并创建 OAuth 客户端 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"

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

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

环境配置

设置环境变量

身份验证系统架构

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

auth.ts

auth-client.ts

核心功能

邮箱密码身份验证
社交登录（例如 Google、GitHub）
密码重置功能（社媒注册用户支持设置密码，进而支持邮箱密码登录）
不同身份验证方法之间的账户绑定
用户管理（包括管理员功能）
基于 Cookie 的会话管理
注册时自动订阅邮件列表（可选）

客户端使用

访问会话数据

在客户端组件中，您可以使用 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>;
}

错误处理

Better Auth 支持错误处理和重定向：

onAPIError: {
  errorURL: '/auth/error',
  onError: (error, ctx) => {
    console.error('auth error:', error);
  },
},

最佳实践

要求电子邮件验证：始终要求新用户进行电子邮箱验证
提供多种身份验证方法：提供邮箱密码登录和社交媒体登录
使用安全会话设置：配置适当的会话超时和 Cookie 安全性
优雅地处理错误：提供用户友好的错误消息和回退
保护敏感路由：在客户端和服务器上实施适当的授权检查
考虑不同的用户角色：实施适当的基于角色的访问控制

视频教程

下一步

现在您了解了 MkSaaS 中身份验证的工作原理，您可能想要探索这些相关功能：

电子邮件

配置电子邮件服务

邮件订阅

设置邮件列表订阅

数据库

配置数据库

环境配置

配置环境变量

环境配置

电子邮件

邮件订阅

数据库

环境配置

目录