## 简介 pgjwt 是一款基于 PostgreSQL 的 JSON Web Token (JWT) 插件，它允许您在数据库内部直接生成和验证 JWT。该插件依赖 pgcrypto 扩展提供的加密函数，仅使用 HMAC 对称签名算法（如 HS256、HS384 和 HS512），整个过程无需借助任何外部服务，实现了安全、高效的身份验证令牌管理。 ## 适用场景 * **无服务器架构 (Serverless)：** 在函数计算等环境中，直接通过数据库进行用户认证，简化认证流程。 * **API 网关集成：** 与 PostgREST 等工具结合，在数据库层面处理请求认证，保护 API 接口安全。 * **简化应用逻辑：** 将 JWT 的生成与验证下沉到数据库，减少应用层的代码复杂度和依赖。 ## 前提条件使用 pgjwt 插件前，需确保您的数据库实例中已安装并启用了 pgcrypto 扩展。 ```SQL -- 检查 pgcrypto 是否已安装 SELECT * FROM pg_extension WHERE extname = 'pgcrypto'; -- 如果未安装，请执行以下命令创建 CREATE EXTENSION IF NOT EXISTS pgcrypto; ``` ## 创建与删除插件 ### 创建插件执行以下 SQL 命令以启用 pgjwt 插件。如果 pgcrypto 尚未启用，使用 `CASCADE` 会自动处理依赖。 ```SQL CREATE EXTENSION pgjwt; -- 或使用 CASCADE：CREATE EXTENSION pgjwt cascade; ``` ### 删除插件如果不再需要，可以执行以下命令将其卸载。 ```SQL DROP EXTENSION pgjwt; ``` ## 基础使用 ### 生成 JWT (`sign` 函数) `sign` 函数用于生成一个 JWT。它接受三个参数： * `payload` (json): 必需，一个有效的 JSON 对象，包含要编码的声明。 * `secret` (text): 必需，用于签名的密钥。 * `algorithm` (text): 可选，签名算法，支持 HS256 (默认)、HS384、HS512。 **示例：使用默认算法 (HS256) 生成 Token** ```SQL SELECT sign( '{"sub":"1234567890","name":"John Doe","admin":true}', 'your-super-secret-key' ); ``` **返回结果：** ```Plain Text eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ ``` **示例：使用 HS384 算法生成 Token** ```SQL SELECT sign( '{"sub":"1234567890","name":"John Doe","admin":true}', 'your-super-secret-key', 'HS384' ); ``` ### 验证 JWT (`verify` 函数) `verify` 函数用于验证 JWT 的有效性并解析其内容。它接受三个参数： * token (text): 必需，待验证的 JWT 字符串。 * `secret` (text): 必需，用于验证签名的密钥。 * `algorithm` (text): 可选，签名算法，必须与生成 Token 时使用的算法一致。函数返回一个包含 `header` (json)、`payload` (json) 和 `valid` (boolean) 三个字段的记录。 **示例：验证一个有效的 Token** ```SQL SELECT * FROM verify( 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ', 'your-super-secret-key' ); ``` **返回结果：** | | | | |---|---|---| | | | | **示例：验证一个使用错误密钥的 Token** 如果密钥不匹配，`valid` 字段将返回 `false`。 ```SQL SELECT * FROM verify( 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ', 'wrong-secret' ); ``` **返回结果：** `valid` 字段将为 `false`。 :::tip **说明** 在实际应用中，`secret` 应足够复杂，并通过安全的方式进行管理，例如使用环境变量或专门的密钥管理服务，避免硬编码在代码或数据库中。 :::

云数据库 PostgreSQL 版