Pascal-在Delphi中实现现代身份验证：delphi-jose-jwt 深度解析与实战指南

icy 今天 6 抢沙发

默认

摘要： 什么是 delphi-jose-jwt？在现代的 Web 开发和 API 设计中，JWT (JSON Web Token) 已经成为了处理身份验证（Authentication）...

什么是 delphi-jose-jwt？

在现代的 Web 开发和 API 设计中，JWT (JSON Web Token) 已经成为了处理身份验证（Authentication）和信息交换（Information Exchange）的标准方案。无论是 OAuth2 还是 OpenID Connect，其核心都依赖于 JOSE (JSON Object Signing and Encryption) 规范。

delphi-jose-jwt 是一个为 Delphi 开发者量身定制的开源库，旨在为 Pascal 语言提供一套完整的 JOSE 规范实现。它允许开发者在 Delphi 应用程序中创建、签名、验证以及解密 JWT 令牌，而无需依赖复杂的外部 C++ 库或调用繁琐的命令行工具。

该项目不仅支持最常见的 HS256 (HMAC with SHA-256) 对称加密，还支持 RS256 (RSA Signature with SHA-256) 等非对称加密算法，使其能够无缝对接如 Auth0、Firebase、Azure AD 等主流身份验证平台。

核心功能特性

JWT 完整生命周期管理：支持 Token 的生成（Encoding）与解析（Decoding）。
多种签名算法：
- 对称加密：支持 HS256, HS384, HS512。
- 非对称加密：支持 RS256, RS384, RS512（基于 RSA 密钥对）。
标准 Claims 支持：内置对 iss (发行者), exp (过期时间), sub (主题) 等标准声明的处理。
轻量级依赖：设计简洁，易于集成到 VCL 或 FMX 项目中。
符合 RFC 标准：严格遵循 RFC 7519 (JWT) 和 RFC 7515 (JWS)。

快速上手实例

为了运行以下代码，请确保你已经将 delphi-jose-jwt 及其依赖项（如 JSON 处理库）添加到你的项目搜索路径中。

场景一：使用对称密钥生成与验证 JWT (HS256)

这是最简单的用法，适用于服务器内部验证或简单的 API Key 机制。

pascal

uses
  System.SysUtils,
  Jose.JWT, 
  Jose.JWT.Algorithm;

procedure TestHS256;
var
  JWT: TJWT;
  Token: string;
  Secret: string;
begin
  Secret := 'your-super-secret-key-12345'; // 必须足够复杂
  
  // 1. 创建 JWT 实例
  JWT := TJWT.Create;
  try
    // 2. 设置 Payload (载荷)
    JWT.Payload := TJSONObject.Create;
    JWT.Payload.AddPair('user_id', '1001');
    JWT.Payload.AddPair('role', 'admin');
    JWT.Payload.AddPair('exp', TJSONObject.ParseJSONValue(Format('%.0f', Now * 86400 + 3600)).AsType); // 设置1小时后过期

    // 3. 使用 HS256 算法签名并生成 Token
    Token := JWT.Encode(TJOSEAlgorithm.HS256, Secret);
    Writeln('Generated Token: ' + Token);

    // --- 验证阶段 ---
    
    // 4. 验证 Token 是否有效
    if JWT.Decode(Token, Secret) then
    begin
      Writeln('Token 验证成功！');
      Writeln('User ID: ' + JWT.Payload.GetValue('user_id').Value);
    end
    else
    begin
      Writeln('Token 验证失败或已过期！');
    end;
  finally
    JWT.Free;
  end;
end;

场景二：使用 RSA 非对称密钥签名 (RS256)

在企业级应用中，通常由认证服务器使用私钥签名，客户端或资源服务器使用公钥验证。

pascal

uses
  System.SysUtils,
  Jose.JWT, 
  Jose.JWT.Algorithm;

procedure TestRS256;
var
  JWT: TJWT;
  Token: string;
  PrivateKey, PublicKey: string;
begin
  // 假设你已经拥有 PEM 格式的密钥
  PrivateKey := TFile.ReadAllText('private_key.pem');
  PublicKey := TFile.ReadAllText('public_key.pem');

  JWT := TJWT.Create;
  try
    JWT.Payload := TJSONObject.Create;
    JWT.Payload.AddPair('sub', '1234567890');
    JWT.Payload.AddPair('name', 'Delphi Developer');

    // 使用 RS256 签名（需要私钥）
    Token := JWT.Encode(TJOSEAlgorithm.RS256, PrivateKey);
    Writeln('RS256 Token: ' + Token);

    // 使用公钥验证（不需要私钥，安全性更高）
    if JWT.Decode(Token, PublicKey) then
      Writeln('RSA 验证通过！')
    else
      Writeln('RSA 验证失败！');
  finally
    JWT.Free;
  end;
end;

关键技术细节解析

1. JWT 的结构

该库完美实现了 JWT 的三段式结构： * Header (头部)：定义了令牌的类型（JWT）和所使用的签名算法（如 HS256）。 * Payload (载荷)：包含实际传输的数据（Claims）。delphi-jose-jwt 将其映射为 TJSONObject，方便开发者动态增删字段。 * Signature (签名)：通过对 Header 和 Payload 进行 Base64Url 编码并使用密钥加密生成，确保数据在传输过程中未被篡改。

2. 安全性建议

在使用 delphi-jose-jwt 时，请务必注意以下几点： * 密钥存储：永远不要将 Secret 硬编码在源代码中。建议使用环境变量或加密的配置文件。 * 过期时间 (exp)：始终为 Token 设置过期时间。一个没有过期时间的 Token 相当于一个永久有效的密码，一旦泄露将导致严重安全漏洞。 * 算法选择：如果是在同一个服务内验证，HS256 足够；如果是跨服务验证，强烈建议使用 RS256。

为什么选择这个项目而不是自己写？

实现 JWT 看起来简单（只是 Base64 和 Hash），但实际开发中存在大量陷阱： 1. Base64Url 编码：标准的 Base64 与 Base64Url 不同（去掉了 =，将 + 和 / 替换），手动处理极易出错。 2. 时间戳处理：JWT 使用 Unix 时间戳，而 Delphi 的 TDateTime 是基于 1899 年的，转换逻辑需要精准。 3. RSA 兼容性：处理 PEM 格式的密钥并将其转换为加密库可识别的格式非常繁琐。

delphi-jose-jwt 将这些底层细节全部封装，让开发者可以专注于业务逻辑而非加密算法的实现。