认证

Clerk

在Supabase项目中使用Clerk


Clerk 可以作为第三方认证提供者与 Supabase Auth 配合使用,也可以独立用于您的 Supabase 项目。

开始使用

入门非常简单。首先访问 Clerk 的 Connect with Supabase 页面 配置您的 Clerk 实例以兼容 Supabase。

最后在 Supabase 仪表盘中 添加一个新的 Clerk 第三方认证集成

配置本地开发或自托管环境

当使用 Supabase CLI 进行本地开发或自托管时,将以下配置添加到您的 supabase/config.toml 文件中:

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

您仍然需要配置 Clerk 实例以兼容 Supabase。

手动配置 Clerk 实例

如果无法使用 Clerk 的 Connect with Supabase 页面 来配置 Clerk 实例以与 Supabase 协同工作,请按照以下步骤操作。

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

设置 Supabase 客户端库

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

使用 RLS 策略

配置 Supabase 客户端库使用 Clerk 会话令牌后,您可以使用 RLS (行级安全) 策略来保护对项目数据库、存储对象和实时通道的访问。

与 Clerk 配合设计 RLS 策略的推荐方式是使用 Clerk 会话令牌中的声明(claims)来控制对项目数据的访问权限。请查阅 Clerk 文档了解可用的 JWT 声明及其值。

示例:检查用户组织角色

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

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

通过这种方式,只有组织管理员才能为他们所属的组织向表中添加行。

示例:检查用户是否通过二次因素验证

1
2
3
4
5
6
7
8
create policy "Only users that have passed second factor verification can read from table"on secured_tableas restrictivefor selectto authenticatedusing ( ((select auth.jwt()->'fva'->>1) != '-1'));
View source

此示例使用严格的RLS策略检查fva声明中的二次因素验证年龄元素是否为'-1',表明用户已通过二次因素验证。

已弃用的JWT模板集成

自2025年4月1日起,先前提供的Clerk与Supabase集成被视为已弃用,不再推荐使用。所有使用已弃用集成的项目在至少2026年1月1日前将免除第三方月活跃用户(TP-MAU)费用。

该集成使用了Supabase和Clerk中仍可用的底层原语,例如可配置的JWT密钥Clerk的JWT模板。这使得您可以非正式地继续使用它,但Supabase仅提供有限支持。

弃用原因如下:

  • 与第三方共享项目的JWT密钥存在安全隐患
  • 在这种情况下轮换项目的JWT密钥几乎总会导致应用程序显著停机
  • 相比使用Clerk的会话令牌,需要额外延迟来生成新的JWT以用于Supabase