import { Steps } from '@astrojs/starlight/components' import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro' import UIFrameworkTabs from '/components/tabs/UIFrameworkTabs.astro' import ReadMore from '~/components/ReadMore.astro'

认证和授权是两种安全过程，用来管理对你的网站或应用的访问。身份认证用于验证访客的身份，而授权则允许访问受保护的区域和资源。

认证允许你为登录的个人定制你的网站的特定区域，并为个人或私人信息提供最大程度的保护。认证库（例如 Auth.js、Clerk）为多种认证方法提供了实用工具，如电子邮件登录和 OAuth 提供商。

:::tip Astro 没有官方的认证解决方案，但你可以在集成目录中找到 社区的“auth”集成。 :::

查看我们的专门指南，了解如何 使用 Supabase 添加认证 或 使用 Firebase 添加认证，以获取这些后端服务的详细信息。

Auth.js

Auth.js 是一个与框架无关的认证解决方案。社区框架适配器 auth-astro 可用于 Astro。

安装

使用你偏好的包管理器的 astro add 命令来添加 auth-astro 集成。

手动安装

要手动安装 auth-astro，请为你的包管理器安装所需的包：

然后，使用 integrations 属性将集成应用到你的 astro.config.* 文件中：

import { defineConfig } from 'astro/config';import auth from 'auth-astro';export default defineConfig({  // ...  integrations: [auth()],});

配置

在你的项目根目录中创建一个 auth.config.ts 文件。添加你希望支持的任何认证 提供商 或方法，以及它们所需的任何环境变量。

import GitHub from '@auth/core/providers/github';import { defineConfig } from 'auth-astro';export default defineConfig({	providers: [		GitHub({			clientId: import.meta.env.GITHUB_CLIENT_ID,			clientSecret: import.meta.env.GITHUB_CLIENT_SECRET,		}),	],});

如果你的项目根目录中还没有 .env 文件，请创建一个。添加以下两个环境变量。AUTH_SECRET 应该是一个至少包含 32 个字符的私有字符串。

AUTH_TRUST_HOST=trueAUTH_SECRET=<my-auth-secret>

使用方法

你可以使用 auth-astro/client 模块，在脚本标签或客户端框架组件中添加登录和登出按钮。

---import Layout from 'src/layouts/Base.astro';---<Layout>  <button id="login">Login</button>  <button id="logout">Logout</button>  <script>    const { signIn, signOut } = await import("auth-astro/client")    document.querySelector("#login").onclick = () => signIn("github")    document.querySelector("#logout").onclick = () => signOut()  </script></Layout>

你可以使用 getSession 方法获取用户的会话信息。

---import Layout from 'src/layouts/Base.astro';import { getSession } from 'auth-astro/server';export const prerender = false; // 'server' 模式下，无需配置const session = await getSession(Astro.request);---<Layout>  {    session ? (      <p>欢迎 {session.user?.name}</p>    ) : (      <p>未登录</p>    )  }</Layout>

下一步

• GitHub 上的 auth-astro
• Auth.js 文档

Better Auth

Better Auth 是一个与框架无关的 TypeScript 身份验证（和授权）框架。它提供了一套全面的开箱即用功能，并包含一个插件生态系统，可简化添加高级功能的过程。

它开箱即用地支持 Astro，你可以使用它为你的 astro 项目添加身份验证。

安装

有关详细的设置说明，请查看 Better Auth 安装指南。

配置

依照 Better Auth 安装指南 中所述，配置数据库表以存储用户数据和你的首选身份验证方法。然后，你需要在 Astro 项目中挂载 Better Auth 处理程序。

import { auth } from "../../../lib/auth"; // 导入你的 Better Auth 实例import type { APIRoute } from "astro";export const prerender = false; // 'server' 模式下，无需配置export const ALL: APIRoute = async (ctx) => {	return auth.handler(ctx.request);};

请参照 Better Auth Astro 指南 以了解更多信息。

使用方法

Better Auth 为各种框架提供了 createAuthClient 助手，包括 Vanilla JS、React、Vue、Svelte 和 Solid。

例如，要为 React 创建客户端，请从 better-auth/react 导入助手：

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

设置客户端后，你可以使用它来验证 Astro 组件或任何位于特定框架下的文件中的用户。以下示例添加了使用配置的 signIn() 和 signOut() 函数以验证登录或注销的功能。

---import Layout from 'src/layouts/Base.astro';---<Layout>  <button id="login">登录</button>  <button id="logout">注销</button>  <script>    const { signIn, signOut } = await import("./lib/auth-client")    document.querySelector("#login").onclick = () => signIn.social({      provider: "github",      callbackURL: "/dashboard",    })    document.querySelector("#logout").onclick = () => signOut()  </script></Layout>

然后，你可以使用 auth 对象以在服务器端代码中获取用户的会话数据。以下示例展示了一种个性化页面内容的方式，它通过显示经过了身份验证的用户名来实现：

---import { auth } from "../../../lib/auth"; // 导入你的 Better Auth 实例export const prerender = false; // 'server' 模式下，无需配置const session = await auth.api.getSession({	headers: Astro.request.headers,});---<p>{session.user?.name}</p>

你还可以使用 auth 对象来通过中间件以保护你的路由。以下示例检查了尝试访问登录仪表板路由的用户是否已通过身份验证，如果未通过身份验证，则将其重定向到主页。

import { auth } from "../../../auth"; // 导入你的 Better Auth 实例import { defineMiddleware } from "astro:middleware";export const onRequest = defineMiddleware(async (context, next) => {	const isAuthed = await auth.api		.getSession({			headers: context.request.headers,		})	if (context.url.pathname === "/dashboard" && !isAuthed) {		return context.redirect("/");	}	return next();});

下一步

• Better Auth Astro 指南
• Better Auth Astro 示例
• Better Auth 文档
• Better Auth 的 GitHub 仓库

Clerk

Clerk 是一套完整的系统，它拥有嵌入式 UI、灵活的 API 以及用于验证和管理用户的仪表盘。Clerk 的官方 Astro SDK 现已推出。

安装

使用你选择的包管理器安装 @clerk/astro。

配置

按照 Clerk 自己的 Astro 快速入门指南 在你的 Astro 项目中设置 Clerk 集成和中间件。

使用方法

Clerk 提供的组件允许你根据用户的身份验证状态控制页面的可见性。向已注销的用户显示登录按钮，而不是向已登录的用户显示可用的内容：

---import Layout from 'src/layouts/Base.astro';import { SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/astro/components';export const prerender = false; // 'server' 模式下，无需配置---<Layout>    <SignedIn>        <UserButton />    </SignedIn>    <SignedOut>        <SignInButton />    </SignedOut></Layout>

Clerk 还允许你使用中间件以保护服务器上的路由。指定受保护的路由，并提示未经身份验证的用户登录：

import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server';const isProtectedRoute = createRouteMatcher([  '/dashboard(.*)',  '/forum(.*)',]);export const onRequest = clerkMiddleware((auth, context) => {  if (!auth().userId && isProtectedRoute(context.request)) {    return auth().redirectToSignIn();  }});

下一步

• 阅读 官方 @clerk/astro 文档
• 从 Clerk + Astro 快速入门项目 的模板开始

Lucia

Lucia 是一个用于在许多框架（包括 Astro）中实现基于会话的身份验证的资源。

指南

1. 使用你选择的数据库创建一个 基本会话 API。
2. 使用端点和中间件添加 会话 cookie。
3. 使用你创建的 API 实现 GitHub OAuth。

示例

• Astro 中的 GitHub OAuth 示例
• Astro 中的 Google OAuth 示例
• 在 Astro 中使用 2FA 的电子邮件和密码的示例
• 在 Astro 中使用 2FA 和 WebAuthn 的电子邮件和密码的示例

社区资源

• 在 Astro 和 Azure 静态 Web 应用中使用 Microsoft Entra Id EasyAuth