OAuth 2.1 服务器入门

本指南将带你一步步设置你的 Supabase 项目成为 OAuth 2.1 身份提供者，从启用该功能到注册你的第一个客户端应用。

🌐 This guide will walk you through setting up your Supabase project as an OAuth 2.1 identity provider, from enabling the feature to registering your first client application.

先决条件 #

🌐 Prerequisites

在开始之前，确保你有：

🌐 Before you begin, make sure you have:

• 一个 Supabase 项目（在 supabase.com 创建一个）
• 你项目的管理员权限
• (可选) 本地开发请使用 Supabase CLI v2.54.11 或更高版本

概览 #

🌐 Overview

在你的 Supabase 项目中设置 OAuth 2.1 包括以下步骤：

🌐 Setting up OAuth 2.1 in your Supabase project involves these steps:

1. 在你的项目中启用 OAuth 2.1 服务器功能
2. 配置你的授权路径
3. 搭建你的授权界面（前端）
4. 注册 OAuth 客户端应用

启用 OAuth 2.1 服务器 #

🌐 Enable OAuth 2.1 server

OAuth 2.1 服务器目前处于测试版，在测试期间，所有 Supabase 计划都可以免费使用。

🌐 OAuth 2.1 server is currently in beta and free to use during the beta period on all Supabase plans.

一旦启用，你的项目将会开放必要的 OAuth 端点：

🌐 Once enabled, your project will expose the necessary OAuth endpoints:

配置你的授权路径 #

🌐 Configure your authorization path

在注册客户之前，你需要先配置你的授权界面放在哪儿。

🌐 Before registering clients, you need to configure where your authorization UI will live.

1. 在你的项目仪表板中，导航到 身份验证 > OAuth 服务器
2. 设置授权路径（例如：/oauth/consent）

你的授权界面将在合并后的站点网址 + 授权路径。例如：

🌐 Your authorization UI will be at the combined Site URL + Authorization Path. For example:

• 站点网址：https://example.com（在 认证 > 网址配置 中）
• 授权路径：/oauth/consent（来自OAuth 服务器设置）
• 你的授权界面：https://example.com/oauth/consent

当 OAuth 客户端启动授权流程时，Supabase Auth 会将用户重定向到这个 URL，并附带一个 authorization_id 查询参数。你可以使用 Supabase JavaScript 库的 OAuth 方法 来处理授权：

🌐 When OAuth clients initiate the authorization flow, Supabase Auth will redirect users to this URL with an authorization_id query parameter. You'll use Supabase JavaScript library OAuth methods to handle the authorization:

• supabase.auth.oauth.getAuthorizationDetails(authorization_id) - 获取客户端和授权详情
• supabase.auth.oauth.approveAuthorization(authorization_id) - 批准授权请求
• supabase.auth.oauth.denyAuthorization(authorization_id) - 拒绝授权请求

搭建你的授权界面 #

🌐 Build your authorization UI

这里是你为授权流程构建前端的地方。当第三方应用启动 OAuth 时，用户会被重定向到你在上一步配置的授权路径，并带有一个 authorization_id 查询参数。

🌐 This is where you build the frontend for your authorization flow. When third-party apps initiate OAuth, users will be redirected to your authorization path (configured in the previous step) with an authorization_id query parameter.

你的授权界面应该：

🌐 Your authorization UI should:

1. 提取 authorization_id - 从 URL 查询参数中获取 authorization_id
2. 验证用户 - 如果尚未登录，请重定向到你的登录页面（保留 authorization_id）
3. 获取授权详细信息 - 使用 supabase.auth.oauth.getAuthorizationDetails(authorization_id) 获取客户端信息，包括请求的权限范围
4. 显示同意屏幕 - 向用户展示哪个应用在请求访问权限，以及正在请求哪些权限/范围
5. 处理用户决定 - 根据用户选择调用 approveAuthorization(authorization_id) 或 denyAuthorization(authorization_id)

授权详情包括一个 scope 字段（单数），其中包含客户端请求的以空格分隔的作用域字符串（例如，"openid email profile"）。你应该向用户显示这些作用域，这样他们就能明白会共享哪些信息。

🌐 The authorization details include a scope field (singular) containing a space-separated string of scopes requested by the client (e.g., "openid email profile"). You should display these scopes to the user so they understand what information will be shared.

示例授权界面 #

🌐 Example authorization UI

下面是如何在你配置的路径（例如 /oauth/consent）上创建一个最小化授权页面：

🌐 Here's how to build a minimal authorization page at your configured path (e.g., /oauth/consent):

1
// app/oauth/consent/page.tsx
2
import { createServerClient } from '@supabase/ssr'
3
import { cookies } from 'next/headers'
4
import { redirect } from 'next/navigation'
5
6
export default async function ConsentPage({
7
  searchParams,
8
}: {
9
  searchParams: { authorization_id?: string }
10
}) {
11
  const authorizationId = (await searchParams).authorization_id
12
13
  if (!authorizationId) {
14
    return <div>Error: Missing authorization_id</div>
15
  }
16
17
  const supabase = createServerClient(
18
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
19
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
20
    {
21
      cookies: {
22
        getAll: async () => (await cookies()).getAll(),
23
        setAll: async (cookiesToSet, _headers) => {
24
          const cookieStore = await cookies()
25
          cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options))
26
        },
27
      },
28
    }
29
  )
30
31
  // Check if user is authenticated
32
  const { data } = await supabase.auth.getClaims()
33
  const claims = data?.claims
34
35
  if (!claims) {
36
    // Redirect to login, preserving authorization_id
37
    redirect(`/login?redirect=/oauth/consent?authorization_id=${authorizationId}`)
38
  }
39
40
  // Get authorization details using the authorization_id
41
  const { data: authDetails, error } =
42
    await supabase.auth.oauth.getAuthorizationDetails(authorizationId)
43
44
  if (error || !authDetails) {
45
    return <div>Error: {error?.message || 'Invalid authorization request'}</div>
46
  }
47
48
  // if no authorization_id returned, user has previously consented, redirect them
49
  if (!('authorization_id' in authDetails)) {
50
    redirect(authDetails['redirect_url'])
51
  }
52
53
  return (
54
    <div>
55
      <h1>Authorize {authDetails.client.name}</h1>
56
      <p>This application wants to access your account.</p>
57
58
      <div>
59
        <p>
60
          <strong>Client:</strong> {authDetails.client.name}
61
        </p>
62
        <p>
63
          <strong>Redirect URI:</strong> {authDetails.redirect_uri}
64
        </p>
65
        {authDetails.scope && authDetails.scope.trim() && (
66
          <div>
67
            <strong>Requested permissions:</strong>
68
            <ul>
69
              {authDetails.scope.split(' ').map((scopeItem) => (
70
                <li key={scopeItem}>{scopeItem}</li>
71
              ))}
72
            </ul>
73
          </div>
74
        )}
75
      </div>
76
77
      <form action="/api/oauth/decision" method="POST">
78
        <input type="hidden" name="authorization_id" value={authorizationId} />
79
        <button type="submit" name="decision" value="approve">
80
          Approve
81
        </button>
82
        <button type="submit" name="decision" value="deny">
83
          Deny
84
        </button>
85
      </form>
86
    </div>
87
  )
88
}

1
// app/api/oauth/decision/route.ts
2
import { createServerClient } from '@supabase/ssr'
3
import { cookies } from 'next/headers'
4
import { NextResponse } from 'next/server'
5
6
export async function POST(request: Request) {
7
  const formData = await request.formData()
8
  const decision = formData.get('decision')
9
  const authorizationId = formData.get('authorization_id') as string
10
11
  if (!authorizationId) {
12
    return NextResponse.json({ error: 'Missing authorization_id' }, { status: 400 })
13
  }
14
15
  const supabase = createServerClient(
16
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
17
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
18
    {
19
      cookies: {
20
        getAll: async () => (await cookies()).getAll(),
21
        setAll: async (cookiesToSet, _headers) => {
22
          const cookieStore = await cookies()
23
          cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options))
24
        },
25
      },
26
    }
27
  )
28
29
  if (decision === 'approve') {
30
    const { data, error } = await supabase.auth.oauth.approveAuthorization(authorizationId)
31
32
    if (error) {
33
      return NextResponse.json({ error: error.message }, { status: 400 })
34
    }
35
36
    // Redirect back to the client with authorization code
37
    return NextResponse.redirect(data.redirect_url)
38
  } else {
39
    const { data, error } = await supabase.auth.oauth.denyAuthorization(authorizationId)
40
41
    if (error) {
42
      return NextResponse.json({ error: error.message }, { status: 400 })
43
    }
44
45
    // Redirect back to the client with error
46
    return NextResponse.redirect(data.redirect_url)
47
  }
48
}

它是怎么运作的 #

🌐 How it works

1. 用户导航到你的授权路径 - 当第三方应用启动 OAuth 时，Supabase Auth 会将用户重定向到你配置的授权路径（例如，https://example.com/oauth/consent?authorization_id=<id>）
2. 提取 authorization_id - 你的页面从 URL 查询参数中提取 authorization_id
3. 检查认证 - 你的页面会检查用户是否已登录，如果没有，会重定向到登录页（会保留 authorization_id）
4. 获取详情 - 调用 supabase.auth.oauth.getAuthorizationDetails(authorization_id) 来获取请求客户端的信息
5. 显示同意界面 - 显示一个界面，询问用户是否批准或拒绝访问
6. 处理决定 - 当用户点击批准/拒绝时：
   • 打电话给 supabase.auth.oauth.approveAuthorization(authorization_id) 或 denyAuthorization(authorization_id)
   • 这些方法会在内部处理所有 OAuth 逻辑（生成授权码等）
   • 它们返回一个 redirect_url URL
7. 重定向回去 - 将用户重定向到 redirect_url URL，这个 URL 会把他们带回第三方应用，并附带授权码（批准）或错误信息（拒绝）

注册一个 OAuth 客户端 #

🌐 Register an OAuth client

在第三方应用可以将你的项目作为身份提供者之前，你需要先把它们注册为 OAuth 客户端。

🌐 Before third-party applications can use your project as an identity provider, you need to register them as OAuth clients.

自定义令牌（可选） #

🌐 Customizing tokens (optional)

默认情况下，OAuth 访问令牌包含像 user_id、role 和 client_id 这样的标准声明。如果你需要自定义令牌——例如，为第三方验证设置特定的 audience 声明，或添加客户端特定的元数据——可以使用 自定义访问令牌钩子。

🌐 By default, OAuth access tokens include standard claims like user_id, role, and client_id. If you need to customize tokens—for example, to set a specific audience claim for third-party validation or add client-specific metadata—use Custom Access Token Hooks.

自定义访问令牌钩子会在所有令牌发放时触发，包括 OAuth 流程。你可以使用 client_id 参数根据请求令牌的 OAuth 客户端来自定义令牌。

🌐 Custom Access Token Hooks are triggered for all token issuance, including OAuth flows. You can use the client_id parameter to customize tokens based on which OAuth client is requesting them.

常见用例 #

🌐 Common use cases

• 自定义 audience 声明：将 aud 声明设置为第三方 API 端点，以便正确进行 JWT 验证
• 添加客户端特定权限：根据请求访问的OAuth客户端包含自定义声明
• 实现动态作用域：添加 RLS 策略可以使用的元数据，以进行精细化访问控制

更多示例，请参见 Token 安全与 RLS。

🌐 For more examples, see Token Security & RLS.

重定向 URI 配置 #

🌐 Redirect URI configuration

重定向 URI 对 OAuth 安全非常关键。Supabase Auth 只会重定向到客户端明确注册的 URI。

🌐 Redirect URIs are critical for OAuth security. Supabase Auth will only redirect to URIs that are explicitly registered with the client.

最佳实践 #

🌐 Best practices

• 在生产环境中使用 HTTPS - 在生产环境中，重定向 URI 始终使用 HTTPS
• 注册准确完整的 URL - 每个重定向 URI 必须是完整的 URL，包括协议、域名、路径以及必要时的端口
• 为每个环境使用不同的 OAuth 客户端 - 为开发、测试和生产环境创建独立的 OAuth 客户端。这样可以提供更好的安全隔离，允许独立更换密钥，并提升可审计性。如果你需要在不同环境中使用相同的客户端，可以注册多个重定向 URI，但还是建议使用独立的客户端。

下一步 #

🌐 Next steps

既然你已经注册了第一个 OAuth 客户端，你现在可以：

🌐 Now that you've registered your first OAuth client, you're ready to:

• 了解 OAuth 流程 - 学习授权码和刷新令牌流程是如何运作的
• 实现 MCP 身份验证 - 启用 AI 代理身份验证
• 使用 RLS 保护 - 控制 OAuth 客户端的数据访问