认证

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