职员

Clerk 可以和 Supabase Auth 一起用作第三方认证提供商，也可以单独用在你的 Supabase 项目中。

🌐 Clerk can be used as a third-party authentication provider alongside Supabase Auth, or standalone, with your Supabase project.

入门 #

🌐 Getting started

入门非常简单。首先访问Clerk 的 Supabase 连接页面来配置你的 Clerk 实例以兼容 Supabase。

🌐 Getting started is incredibly easy. Start off by visiting Clerk's Connect with Supabase page to configure your Clerk instance for Supabase compatibility.

最后在 Supabase 仪表板中添加一个 新的第三方身份验证集成与 Clerk。

🌐 Finally add a new Third-Party Auth integration with Clerk in the Supabase dashboard.

为本地开发或自托管配置 #

🌐 Configure for local development or self-hosting

在本地开发或使用 Supabase CLI 自行托管时，向你的 supabase/config.toml 文件添加以下配置：

🌐 When developing locally or self-hosting with the Supabase CLI, add the following config to your supabase/config.toml file:

1
[auth.third_party.clerk]
2
enabled = true
3
domain = "example.clerk.accounts.dev"

你仍然需要为 Supabase 兼容性配置你的 Clerk 实例。

🌐 You will still need to configure your Clerk instance for Supabase compatibility.

手动配置你的 Clerk 实例 #

🌐 Manually configuring your Clerk instance

如果你无法使用 Clerk 的 Supabase 连接页面 来配置你的 Clerk 实例以与 Supabase 配合使用，请按照以下步骤操作。

🌐 If you are not able to use Clerk's Connect with Supabase page to configure your Clerk instance for working with Supabase, follow these steps.

1. 通过自定义它们将 role 声明添加到Clerk 会话令牌中。已经认证的终端用户应该在该声明中拥有 authenticated 值。如果你有一个高级的 Postgres 设置，认证的终端用户使用不同的 Postgres 角色访问数据库，请调整该值以使用正确的角色名。
2. 一旦你实例的所有 Clerk 会话令牌都包含 role 权限声明，就在 Supabase 仪表板中添加一个 新的 Clerk 第三方认证集成，或者按照上面说明在 CLI 中注册它。

设置 Supabase 客户端库 #

🌐 Setup the Supabase client library

1
const supabaseClient = createClient(
2
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
3
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
4
    {
5
      // Session accessed from Clerk SDK, either as Clerk.session (vanilla
6
      // JavaScript) or useSession (React)
7
      accessToken: async () => session?.getToken() ?? null,
8
    }
9
  )

使用 RLS 策略 #

🌐 Using RLS policies

一旦你将 Supabase 客户端库配置为使用 Clerk 会话令牌，你就可以使用 RLS 策略来保护你的项目数据库、存储对象和实时通道的访问。

🌐 Once you've configured the Supabase client library to use Clerk session tokens, you can use RLS policies to secure access to your project's database, Storage objects and Realtime channels.

使用 Clerk 设计 RLS 策略的推荐方式是利用你 Clerk 会话令牌中的声明来允许或拒绝访问你项目的数据。查看 Clerk 的文档 了解可用的 JWT 声明及其值。

🌐 The recommended way to design RLS policies with Clerk is to use claims present in your Clerk session token to allow or reject access to your project's data. Check Clerk's docs on the available JWT claims and their values.

示例：检查用户组织角色 #

🌐 Example: Check user organization role

1
create policy "Only organization admins can insert in table"
2
on secured_table
3
for insert
4
to authenticated
5
with check (
6
  (((select auth.jwt()->>'org_role') = 'org:admin') or ((select auth.jwt()->'o'->>'rol') = 'admin'))
7
    and
8
  (organization_id = (select coalesce(auth.jwt()->>'org_id', auth.jwt()->'o'->>'id')))
9
);

这个 RLS 策略会检查表中新插入的行的 organization_id 列是否包含用户声明的组织 ID。此外，它还确保他们是一个 org:admin。

🌐 This RLS policy checks that the newly inserted row in the table has the user's declared organization ID in the organization_id column. Additionally it ensures that they're an org:admin.

这样只有组织管理员才能为他们所属的组织向表格中添加行。

🌐 This way only organization admins can add rows to the table, for organizations they're a member of.

示例：检查用户是否已通过第二步验证 #

🌐 Example: Check user has passed second factor verification

1
create policy "Only users that have passed second factor verification can read from table"
2
on secured_table
3
as restrictive
4
for select
5
to authenticated
6
using (
7
  ((select auth.jwt()->'fva'->>1) != '-1')
8
);

这个示例使用了限制性的 RLS 策略，检查 fva 声明中的二次验证年龄元素不是 '-1'，表示用户已经通过了二次验证。

🌐 This example uses a restrictive RLS policy checks that the second factor verification age element in the fva claim is not '-1' indicating the user has passed through second factor verification.

已弃用的 JWT 模板集成 #

🌐 Deprecated integration with JWT templates

截至2025年4月1日，之前提供的 Clerk 与 Supabase 集成 已被视为弃用，不再推荐使用。所有使用该弃用集成的项目将在至少2026年1月1日之前免除第三方月活跃用户（TP-MAU）收费。

🌐 As of 1st April 2025 the previously available Clerk Integration with Supabase is considered deprecated and is no longer recommended for use. All projects using the deprecated integration will be excluded from Third-Party Monthly Active User (TP-MAU) charges until at least 1st January 2026.

这个集成使用了低级原语，这些原语在 Supabase 和 Clerk 中仍然可用，比如 可配置的 JWT 密钥 和 Clerk 的 JWT 模板。这让你可以以非官方方式继续使用它，不过 Supabase 只能提供有限的支持。

🌐 This integration used low-level primitives that are still available in Supabase and Clerk, such as a configurable JWT secret and JWT templates from Clerk. This enables you to keep using it in an unofficial manner, though only limited support will be provided from Supabase.

弃用是出于以下原因：

🌐 Deprecation is done for the following reasons:

• 把你项目的 JWT 密钥分享给第三方是一种有问题的安全做法
• 在这种情况下，旋转项目的 JWT 密钥几乎总是会导致你的应用出现较长的停机时间
• 生成一个新的 JWT 用于 Supabase 会增加额外延迟，而不是使用 Clerk 的会话令牌