AI 原生 BaaS 平台 Supabase 版
AI 原生 BaaS 平台 Supabase 版
文档指南
请输入
- 文档首页
AI 原生 BaaS 平台 Supabase 版用户指南Supabase 引擎用户指南使用 Supabase 控制台使用 Authentication设置 Third-Party 登录
复制全文
下载 pdf设置 Third-Party 登录
文档反馈
问问助手Third-Party Auth（第三方认证）允许 Supabase 信任由外部身份认证服务签发的 JWT，并将其用于访问 Supabase 的 Database、Storage、Realtime、Edge Function 等服务。本文介绍如何通过 Supabase 控制台和 Admin API 为应用配置 Third-Party Auth 登录能力。
前提条件
- 已创建使用 Supabase 引擎的 Workspace，且 Workspace 状态为运行中。关于创建 Workspace 的更多详细信息，请参见创建 Workspace。
- 已通过目标 Workspace 成功登录 Supabase 控制台。关于登录控制台的详细信息，请参见登录 Supabase 控制台。
- 已获取 SUPABASE_BASE_URL、SERVICE_ROLE_KEY 和 SUPABASE_ANON_KEY。关于获取变量的详细信息，请参见获取变量。
- 已在第三方身份认证平台完成应用创建，并能获取对应的 Issuer URL 或 Provider 配置信息。
- 第三方身份认证平台签发的 JWT 需要满足以下要求：
- 使用非对称签名算法，推荐 RS256。
- JWT Header 中包含 kid。
- JWT Payload 中包含 role Claim，推荐值为 authenticated。如第三方 Token 默认不包含该 Claim，可通过 JWT Template、Trigger 或 Action 等方式补齐。
- JWT 的 iss、aud 等字段与第三方 Provider 配置保持一致。
- 已根据业务访问策略，为数据表、Storage 或 Realtime 配置对应的 RLS 策略，确保鉴权后的访问权限受控。
使用流程
Third-Party Auth 用于将 Supabase 的用户认证能力委托给第三方身份认证服务。整体流程如下：
- 用户在第三方认证平台（如 Clerk、Firebase Auth）完成登录。
- 业务应用获取第三方平台签发的 JWT。
- 业务应用访问 Supabase 时，将该 JWT 作为 Authorization: Bearer <JWT> 传入。
- Supabase 根据已配置的 Third-Party Auth 信息，拉取并校验第三方 Provider 的 JWKS 公钥。
- 校验通过后，请求可访问 Supabase 的 Database、Storage、Realtime、Edge Function 等服务。
支持的 Provider：
当前支持以下主流身份认证服务，您可根据业务实际使用的认证平台选择对应配置方式：
通过 Supabase 控制台配置
通用步骤：添加 Third-Party Auth 配置
- 在左侧导航栏中选择 Authentication。
- 进入 Sign In / Providers 页面。
- 在页面中找到 Third-Party Auth 配置区域。
- 单击新增配置。
- 选择需要接入的 Provider（如 Firebase Auth、Clerk 等）。
- 填写对应 Provider 的 Issuer URL 或配置参数（详见下文各 Provider 子章节）。
- 单击保存。
保存后，系统会根据配置自动解析 Provider 类型，并拉取对应的 JWKS 公钥。配置成功后，页面或接口返回值会展示以下信息：
- 配置 ID
- Provider 类型
- OIDC Issuer URL
- 最近一次成功解析时间
- 已解析的公钥信息
Firebase Auth 的 Issuer URL 格式如下：
其中 {project_id} 为 Firebase 项目的 Project ID。
主要配置项说明：
Firebase 端配置要求：需在 Firebase 中为用户 Token 增加自定义 Claim：
需要在 Firebase 中为用户 Token 增加自定义 Claim：
可通过 Firebase Cloud Functions 或 Admin SDK 设置该 Claim。
Clerk 的 Issuer URL 通常为 Clerk 实例域名，例如：
主要配置项说明：
Clerk 端配置要求：需确保 Session Token 包含以下 Claim：
需要在 Clerk 中确保 Session Token 包含以下 Claim：
可通过 Clerk 的 JWT Template 或 Supabase 集成配置补齐该 Claim。业务应用初始化 Supabase Client 时，需要通过 accessToken 回调传入 Clerk 签发的 Token。
WorkOS 的 Issuer URL 格式如下：
其中 {client_id} 为 WorkOS 应用的 Client ID。
主要配置项说明：
WorkOS 端配置要求：需在 WorkOS JWT Template 中增加 role Claim，例如：
需要在 WorkOS JWT Template 中增加 role Claim，例如：
Auth0 的 Issuer URL 格式如下：
如果 Auth0 租户不使用区域域名，则以实际 Auth0 控制台展示的 Domain 为准。
主要配置项说明：
Auth0 端配置要求：需通过 Auth0 Action 为 Token 增加 role Claim，例如：
需要通过 Auth0 Action 为 Token 增加 role Claim，例如：
AWS Cognito 的 Issuer URL 格式如下：
主要配置项说明：
AWS Cognito 端配置要求：需通过 Pre Token Generation Trigger 为 Token 增加 role Claim，例如：
需要通过 Pre Token Generation Trigger 为 Token 增加 role Claim，例如：
配置自定义 JWKS（Custom JWKS）认证
除了标准的 OIDC Issuer，您还可以使用自定义 JWKS。该方式适用于使用固定 kid 和 JWKS 公钥进行认证的应用，配置格式如下：
主要配置项说明：
通过 Admin API 配置
您也可以通过 Auth 模块的 Admin API /auth/v1/config/third-party-auth 接口管理 Third-Party Auth 配置，便于自动化部署或集成到 CI/CD 流程。
查询配置列表
返回示例：
新增配置
返回示例：
删除配置
其中 {resource_id} 为查询配置列表或新增配置时返回的 id。
手动同步 Third-Party 公钥
系统会每隔 30 分钟自动刷新第三方 Provider 的公钥。如需在 JWKS 轮转后立即生效，可调用以下接口手动同步：
在业务应用中使用 Third-Party Token
配置完成后，业务应用需要在初始化 Supabase Client 时传入第三方认证服务签发的 JWT。
说明
以下示例中的 thirdPartyAuthClient 代表业务应用中使用的第三方认证 Client，不是 Supabase Client 的 Auth 对象。在实际接入时，请替换为业务应用使用的 Clerk、Firebase Auth、Auth0、WorkOS、AWS Cognito 或自定义的第三方认证 SDK Client。关键点是 accessToken 回调函数必须返回第三方 Provider 签发的有效 JWT。
JavaScript / TypeScript 示例
之后访问 Supabase 时，客户端会自动携带：
接入示例
场景一：通过 Firebase Auth 接入
场景二：通过 Clerk 接入
场景三：通过 WorkOS 接入
场景四：通过 Auth0 接入
场景五：通过 AWS Cognito 接入
场景六：通过自定义 JWKS 接入
步骤 1：准备 JWKS（私钥和公钥）。如尚未生成，可参考以下示例：
安全提示
请谨慎保管您的私钥，切勿上传至公网或任何可能泄漏的位置。
步骤 2：在 Supabase 控制台配置自定义 JWK Provider，填入 kid、algorithm、public_key：
-
-
步骤 3：生成业务侧 JWT。注意 KID / ALG 必须与第二步配置保持一致，且 ROLE 不能为 service_role：
步骤 4：在业务应用中使用该 JWT 访问 Supabase 服务。
注意事项与限制
- 配额限制：每个 Supabase Branch 最多可配置 10 个 Third-Party Auth Provider。
- 公钥刷新：Supabase 后台每 30 分钟自动刷新一次 Third-Party Auth Provider 的公钥。
- JWKS 轮转：如果 Third-Party Auth Provider 的 JWKS 已发生轮转，建议立即调用手动同步公钥接口，确保新的 JWKS 尽快生效。
- 客户端凭据：不建议使用 SERVICE_ROLE_KEY 作为客户端访问凭据。客户端应使用 SUPABASE_ANON_KEY 初始化 Supabase Client，并通过 accessToken 回调传入第三方 JWT。
- role Claim 校验：Third-Party JWT Payload 中必须包含 role Claim，推荐值为 authenticated。如果 role 的值为 service_role，请求会被直接拒绝。
- 删除影响：删除某个 Third-Party Auth Provider 后，使用该 Provider JWT 的请求将立即被 Supabase 拒绝。
- 创建参数互斥：在创建单个 Provider 时，参数 oidc_issuer_url 和 custom_jwt_secret 只能选择其中一种。前者创建支持自动轮转的标准三方 JWKS，后者创建自定义 JWKS。
- 自定义 JWKS 安全建议：建议定期轮转自定义 JWKS 私钥，降低由于私钥泄漏带来的安全风险。Supabase 不会自动刷新自定义 JWKS 的公钥，请由业务方自行管理其有有效期。
最近更新时间：2026.05.22 15:40:10
这个页面对您有帮助吗？
有用
有用
无用
无用