Supabase 合作伙伴集成指南

本指南假设你已经按照构建 Supabase 集成指南操作过，并且有一个可用的 OAuth 客户端。

🌐 This guide assumes you have already followed the Build a Supabase Integration guide and have a working OAuth client.

当 Supabase 用户在仪表板中点击 安装集成 按钮时，他们会被重定向到你的系统以开始 OAuth 流程。你可以通过两种方式实现这个重定向：

🌐 When a Supabase user clicks the Install Integration button in the Dashboard, they are redirected to your system to begin the OAuth flow. You can implement this redirect in one of two ways:

• 重定向：更容易构建，但你的系统无法验证传入用户是否由 Supabase 发送。
• 已签名重定向：需要更多工作来构建，但能通过加密方式验证重定向确实来自 Supabase。推荐用于生产环境集成。

选择符合你安全需求的方法，然后按照下面对应的部分操作。

🌐 Pick the method that fits your security requirements, then follow the matching section below.

方法一：重定向 #

🌐 Method 1: Redirect

在这个方法中，你只需要实现一个 GET 端点。当用户点击 安装集成 时，Supabase 会将用户重定向到这个端点，而你的端点会启动 OAuth 流程。

🌐 In this method, you implement a single GET endpoint. Supabase redirects the user to this endpoint when they click Install Integration, and your endpoint kicks off the OAuth flow.

用户在 Supabase 仪表板中点击 安装集成，这会把他们引导到合作伙伴的点击处理页面，然后再到 Supabase 授权页面。Supabase 会显示一个同意页面。一旦用户同意，Supabase 会带着授权码重定向回合作伙伴。合作伙伴用这个码换取一个令牌，然后用令牌请求管理 API 资源，最后向用户显示“集成已安装”的消息。

🌐 The user clicks Install Integration in the Supabase Dashboard, which routes them through the partner's click-handler page and on to the Supabase authorization page. Supabase shows a consent screen. Once the user consents, Supabase redirects back to the partner with an authorization code. The partner exchanges that code for a token, uses the token to request Management API resources, and finally shows the user an "Integration Installed" message.

第1步：实现重定向端点 #

🌐 Step 1: Implement the redirect endpoint

在你控制的任何网址上开放一个 GET 接口：

🌐 Expose a GET endpoint at any URL you control:

1
GET https://<your-host>/<optional-path>?project_id=<supabase-project_ref>&organization_slug=<supabase-org-slug>

Supabase 在重定向时会在 URL 后添加以下查询参数：

🌐 Supabase will append the following query parameters to the URL when redirecting:

将这些参数保存在你的系统中。一旦 OAuth 流程完成，你可以用它们来获取项目或组织的详情，或者在你的界面中预先选择一个项目或组织。

🌐 Save these parameters in your system. You can use them to fetch project or organization details, or to pre-select a project or organization in your UI once the OAuth flow is complete.

你的端点可能会要求用户在你的网站上注册、登录或完成其他设置任务。一旦这些完成，立即重定向到 Supabase 授权 URL，无需进一步的用户操作。这将启动 OAuth 流程。

🌐 Your endpoint may ask the user to sign up, sign in, or perform other setup tasks on your website. Once those are complete, immediately redirect to the Supabase authorization URL without further user interaction. This starts the OAuth flow.

步骤 2：把你的端点分享给 Supabase #

🌐 Step 2: Share your endpoint with Supabase

把你的端点 URL 发送给 Supabase，这样我们就可以配置 安装集成 按钮重定向到那里。

🌐 Send Supabase the URL of your endpoint so we can configure the Install Integration button to redirect there.

方法二：签名重定向 #

🌐 Method 2: Signed redirect

在这种方法中，Supabase 会在重定向用户之前签署一个 JWT。你需要验证这个签名，生成一次性重定向记录，并把它的 URL 返回给 Supabase。然后 Supabase 会把用户重定向到这个 URL。这就保证了你的系统处理的任何重定向都是来自 Supabase 的。

🌐 In this method, Supabase signs a JWT before redirecting the user. You verify the signature, generate a one-time redirect record, and return its URL to Supabase. Supabase then redirects the user to that URL. This guarantees that any redirect your system handles originated from Supabase.

你将实现两个端点：

🌐 You will implement two endpoints:

1. 一个 POST 端点，它会验证已签名的 JWT 并返回一个唯一的重定向 URL。
2. 一个 GET 端点，在用户被重定向到该 URL 后处理他们。

步骤走一遍：当用户点击 安装集成 时，Supabase 会向合作伙伴发送一个已签名的 JWT，并要求其生成一个重定向 URL。合作伙伴验证 JWT，生成一个唯一的重定向记录和 URL，然后返回给 Supabase。Supabase 会把用户重定向到该 URL；合作伙伴验证重定向记录，可选地让用户完成额外步骤，然后再把他们带到 Supabase 授权页面。从那里流程就和方法1一样：用户同意，Supabase 返回一个授权码，合作伙伴用它换取令牌，请求管理 API 资源，集成完成。

🌐 Walking through the sequence: when the user clicks Install Integration, Supabase sends the partner a signed JWT and asks it to generate a redirect URL. The partner validates the JWT, generates a unique redirect record and URL, and returns it. Supabase redirects the user to that URL; the partner validates the redirect record, optionally has the user complete extra steps, and then sends them to the Supabase authorization page. From there the flow matches Method 1: the user consents, Supabase returns an authorization code, the partner exchanges it for a token, requests Management API resources, and the integration completes.

第一步：和 Supabase 交换公钥 #

🌐 Step 1: Exchange public keys with Supabase

Supabase 会生成两对密钥，一对用于测试环境，一对用于生产环境，并会把公钥分享给你。把这两把公钥和它们的密钥 ID 存在你的系统里。这些密钥是 PEM 编码的 EC P-256。

🌐 Supabase generates two key-pairs, one for staging, one for production, and shares the public keys with you. Save both public keys and their key IDs in your system. The keys are PEM-encoded EC P-256.

示例：

🌐 Example:

1
===============Staging==================
2
3
Key ID: pik_3038669348a3ea75dbaf0655
4
Public Key:
5
-----BEGIN PUBLIC KEY-----
6
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnj3NmwrLPPH/3isvpS601ndQP9Mk
7
zqppdLDV9YfmoF4wavTyb9UTVE5pJ0fukpo5aOoNb4fBZgESsedIUoEn8Q==
8
-----END PUBLIC KEY-----
9
10
==============Production================
11
12
Key ID: pik_89e80ddbca9df41b97e28986
13
Public Key:
14
-----BEGIN PUBLIC KEY-----
15
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWCGhwtFWn4jpWZNeyZpTlaAdq/tD
16
/yBaN0gFPpS8LTFiCPFgnWKbVe3RfExXh7bEhcrEUdWycmYvwrNklWWHRA==
17
-----END PUBLIC KEY-----

通过 JWT 头部的 kid 字段查找正确的公钥。

🌐 Look up the correct public key by the kid field in the JWT header.

通过按 ID 存储密钥，可以实现零停机密钥轮换。当 Supabase 轮换密钥时，我们会共享新的密钥对，并开始使用新的密钥 ID 签署 JWT。你的系统会根据 kid 自动选择正确的密钥，无需任何代码更改。

🌐 Storing keys by ID enables zero-downtime key rotation. When Supabase rotates keys, we share new key-pairs and start signing JWTs with the new key ID. Your system picks the correct key based on kid without any code changes.

第二步：实现重定向记录端点 #

🌐 Step 2: Implement the redirect record endpoint

这个端点会接收来自 Supabase 的已签名 JWT，并返回一个一次性重定向网址。

🌐 This endpoint receives the signed JWT from Supabase and returns a one-time redirect URL.

在你控制的任何 URL 和路径上托管这个端点。不需要在这个端点上进行身份验证，但要应用速率限制以防止滥用。

🌐 Host the endpoint at any URL and path you control. Do not require authentication on this endpoint, but apply rate limiting to prevent abuse.

1
POST https://<your-api-host>/<your-api-path>
2
Content-Type: application/json

请求体 #

🌐 Request body

1
{
2
  "token": "<signed-jwt>"
3
}

JWT 字段 #

🌐 JWT fields

这个令牌是使用 ES256 私钥签名的 JWT。

🌐 The token is a JWT signed with the ES256 private key.

受保护的头部（JOSE 头部）

有效载荷（声明）

签名

头部和声明是用 EC P-256 私钥签名的。

🌐 The header and claims are signed with the EC P-256 private key.

验证 #

🌐 Validation

当你收到请求时：

🌐 When you receive a request:

1. 从 JWT 头部读取 kid 字段，然后查找匹配的公钥。
2. 用那个公钥验证 JWT 签名。
3. 确认 alg 是 ES256。
4. 确认 iss 是 supabase。
5. 确认 aud 是否与你和 Supabase 商定的值一致。
6. 确认当前时间是否在 iat 和 exp 之间。

如果有任何检查失败，就返回 401 Unauthorized。

🌐 If any check fails, return 401 Unauthorized.

如果验证成功，生成一个 UUID 来标识这个重定向记录（也叫集成记录），在你的系统中保存它并设置过期时间（通常是 1 小时），然后在响应中返回它。过期时间可以防止记录堆积，并限制泄露记录被使用的时间窗口。

🌐 If validation succeeds, generate a UUID to identify this redirect record (also called an integration record), save it in your system with an expiry (typically 1 hour), and return it in the response. The expiry prevents records from accumulating and limits the window in which a leaked record can be used.

响应体 #

🌐 Response body

1
{
2
  "integrationId": "<a unique uuid>",
3
  "redirectUrl": "https://<your-api-host>/<your-api-path>/<integration-id>",
4
  "expiresAt": "<timestamp>"
5
}

步骤 3：实现重定向处理端点 #

🌐 Step 3: Implement the redirect handler endpoint

这是你在上一步返回的 redirectUrl 上的 GET 端点。重定向记录的 UUID 必须在它的路径中。

🌐 This is the GET endpoint at the redirectUrl you returned in the previous step. The redirect record's UUID must be in its path.

当用户到达这个端点时：

🌐 When a user arrives at this endpoint:

1. 从 URL 路径中提取重定向记录 UUID。
2. 在你的系统里查一下。如果不存在或者已经过期，就返回 401 Unauthorized。
3. 可选地，引导用户完成你这边需要的任何设置——比如注册、登录，或配置你的系统以使集成正常工作。
4. 把用户重定向到 Supabase 授权网址 开始 OAuth 流程。

第4步：把你的信息分享给 Supabase #

🌐 Step 4: Share your details with Supabase

把以下内容发送给 Supabase，这样我们就可以配置 安装集成 按钮：

🌐 Send Supabase the following so we can configure the Install Integration button:

• 你的重定向记录端点的 URL（步骤 2）。
• 你的重定向处理端点的 URL 模式（步骤 3）。
• 你希望 Supabase 在签名的 JWT 中发送的 aud 声明值。

向 Supabase 询问测试和生产环境的公钥和密钥 ID。

🌐 Ask Supabase for the public keys and key IDs for the staging and production environments.