介绍 JWT 签名密钥

⚡️更多发布周信息

今天，我们将宣布 Supabase 一些期待已久的改动：

• 支持使用Supabase Auth 的非对称 JWT。
• 新的 API 密钥可帮助您过渡到非对称 JWT 并提高应用程序的安全性。

JWT 作为开源身份验证

在过去的十年里，JSON Web Tokens (JWT) 已成为业务逻辑和身份验证服务器之间的通用语言。

Supabase 自创立之初就采用了 JWT。它是 Postgres 行级安全 (RLS) 策略得以实现的基石。Supabase 身份验证会验证用户身份，并在用户使用应用程序期间颁发多个 JWT。这些 JWT 随后会被应用程序或其他 Supabase 产品（例如，数据 API、存储、实时数据）用于允许或拒绝访问应用程序的数据。

为了履行我们“规模可达数十亿”的承诺，我们正在改变项目中 JWT 的管理方式。

为什么对称 JWT 可能存在风险

此前，Supabase Auth 使用对称密钥对 JWT 进行签名。这意味着使用共享密钥来创建和验证令牌。这种方法简单快捷，但大规模应用时会带来严重的弊端：

• 您必须调用supabase.auth.getUser() 服务器来检查会话是否有效，因为只有认证服务器才能安全地验证令牌。这增加了网络延迟，并且对认证服务器的在线状态产生了依赖。
• 服务器端应用程序和自定义 API 依赖于身份验证服务器，这使得托管在边缘的应用程序速度更慢、更脆弱。
• 为了提升性能，您不得不手动管理共享密钥。如果密钥泄露，任何人都可以伪造令牌并绕过行级安全机制。这意味着您的应用程序很难符合 SOC2 等安全合规框架的要求。

更好的方法是利用公钥加密技术。它允许在使用 JWT 时使用两个独立的（因此是不对称的）密钥：

• 用于创建和签署 JWT 的私钥（仅 Supabase Auth 知道，不可提取）
• 用于验证和解码 JWT 的公钥（不可逆且可安全地发布在网络上）

此模型安全且可扩展。现在，您可以在应用程序的任何位置验证令牌，而无需依赖身份验证服务器。由于您可以从端点获取项目的公钥，因此密钥撤销和轮换也更加安全/auth/v1/.well-known/jwks.json。

我们的实现基于Web Crypto API，确保了广泛的兼容性和一流的安全标准。RSA 和椭圆曲线 (ECC) 签名算法均可使用。

我们花了一段时间，但今天我们正式向所有项目开放此功能！

立即开始使用非对称 JWT

非对称 JWT 支持现已作为一项可选功能提供。自 2025 年 10 月 1 日起，所有新项目将默认使用非对称 JWT。现有项目可随时选择启用此功能。除非您选择更改，否则无需更改 JWT 密钥。

我们已采取非常谨慎的措施，确保每一步都安全且可逆，从而保证关键部件轮换零停机时间。

1. 迁移开始

使用Supabase 控制面板将您现有的 JWT 密钥迁移到新的 JWT 签名密钥系统。

您的项目继续使用现有的对称 JWT 密钥，但 Supabase 已在底层为您的项目准备好了非对称 JWT。

1. 生成新的密钥对

Supabase 会生成一个新的备用密钥对：一个私钥（用于创建和签名）和一个公钥（用于验证令牌）。此时，该密钥可供发现，但尚未使用该密钥创建 JWT。

1. 旋转至非对称 JWT

准备就绪后，请轮换密钥。这将指示 Supabase Auth 开始颁发使用新私钥签名的 JWT。

但重要的是，，，anon以及service_role任何现有的未过期的身份验证 JWT仍然有效并被接受。

1. 撤销JWT的旧秘密

确认一切运行正常后，即可撤销旧版 JWT 密钥。从那时起：

• anon，，service_role任何使用旧密钥签署的 JWT 都将被拒绝。
• 只有使用新的非对称密钥签名的 JWT 才会被接受。

获得最大收益

我们为您提供了一个新的客户端库函数：

supabase.auth.getClaims()

这是一个速度更快的替代方案，getUser()您可以立即切换到它！如果使用对称 JWT，每次都会连接到身份验证服务器。但是，如果使用非对称密钥，则会使用 Web Crypto API 直接验证令牌。

它会自动发现并缓存边缘和内存中的公钥，从而显著提高应用程序的性能，同时保持安全，且不会带来额外的风险。

您也可以使用其他任何 JWT 库。以下是使用流行的 jose 库的示例：

import { createRemoteJWKSet, jwtVerify } from 'jose'

const SUPABASE_JWT_ISSUER = 'https://project.supabase.co/auth/v1'
const SUPABASE_JWT_KEYS = createRemoteJWKSet(
  new URL(SUPABASE_JWT_ISSUER + '/.well-known/jwks.json')
)

function verifySupabaseJWT(jwt: string) {
  return jwtVerify(token, SUPABASE_JWT_KEYS, { issuer: SUPABASE_JWT_ISSUER })
}

用于修复的 API 密钥anon和service_role

此外，anon我们service_role还将推出对以下功能的支持：

• 一把publishable钥匙，用来替换anon key。
• secret keys，更换service_role钥匙。

anon这些service_role是您项目的旧版 API 密钥。它们用于识别哪个应用程序（而不是哪个用户）正在访问您的数据。

遗憾的是，这些 JWT 会在您创建项目 10 年后过期。您可能已经猜到了，轮换并撤销旧版 JWT 密钥会导致它们失效。因此，我们也推出了改进后的 API 密钥。（这也是为什么这项工作耗时如此之久！）

即使您不使用新的 JWT 签名密钥功能，也应该切换到可发布密钥/私钥，因为它们根据过去几年收集的反馈信息提供了安全性方面的改进。此外，我们计划为这些密钥添加更多功能。

它们在大多数情况下可以替代 ` anonand`service_role键。请查阅文档，了解如何充分利用它们。

时间线

这两项功能目前均采用可选启用模式。我们非常希望收到您的反馈。在接下来的 12 个月里，我们将逐步要求您切换到新的 API 密钥，同时保留您是否使用非对称 JWT 的选择权。

发布周 15

主舞台

第一天 - JWT签名密钥介绍

构建阶段

• 01 - Supabase UI：平台套件

全球社区聚会