JWT (RFC 7519) 之所以能成为事实标准, 一半功劳归于它的形状极其简单—— 三段 base64url 用 . 拼起来, 一行字符串能传 HTTP Header 也能塞 Cookie。 理解 JWT 的第一件事不是密码学, 而是"这串字符到底是什么"。

真实例子拆解

两种序列化形式

手撕一个 JWT (不用任何库)

// 30 行用标准库手撕 HS256 — 看清"签名前签名后"
package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "encoding/json"
    "fmt"
)

func main() {
    key := []byte("my-secret-key-at-least-32-bytes!!")

    // 1) 构造 Header 和 Payload (任何 JSON 对象都行)
    header  := map[string]any{"alg": "HS256", "typ": "JWT"}
    payload := map[string]any{"sub": "42", "exp": 1727340800}

    hJSON, _ := json.Marshal(header)
    pJSON, _ := json.Marshal(payload)

    // 2) base64url 编码 — RawURLEncoding 去掉 = 填充
    h64 := base64.RawURLEncoding.EncodeToString(hJSON)
    p64 := base64.RawURLEncoding.EncodeToString(pJSON)

    // 3) 签名: 对 "H64.P64" 整段做 HMAC-SHA256
    signingInput := h64 + "." + p64
    mac := hmac.New(sha256.New, key)
    mac.Write([]byte(signingInput))
    s64 := base64.RawURLEncoding.EncodeToString(mac.Sum(nil))

    // 4) 拼起来就是 JWT
    token := signingInput + "." + s64
    fmt.Println(token)
    // → eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MjczNDA4MDAsInN1YiI6IjQyIn0.xxx
}

"JWT"这个词其实是个容器—— 它真正的实质是 JWS(签名形态)或 JWE(加密形态)。 绝大多数我们日常说的 JWT, 都是 JWS; 另外两条 RFC JWK / JWKS(密钥分发)和 JWA(算法标识) 是它们的支撑设施。这四条 RFC 一起构成 "JOSE" (JavaScript Object Signing and Encryption)。

JWS vs JWE

四条 RFC 的分工

JWK 与 JWKS

JWK (JSON Web Key) 是一种 用 JSON 表达密钥 的格式; JWKS (JWK Set) 是 JWK 的数组——OIDC / OAuth 服务器在 /.well-known/jwks.json 暴露这个, 客户端拉过来就能用对应 kid 验证 JWT 签名。Day 18 OIDC Discovery 会展开。

# 一个公开的 RSA 公钥 (JWK 形态)
{
  "kty": "RSA",                // 密钥类型: RSA / EC / OKP
  "use": "sig",                // 用途: sig 签名 / enc 加密
  "alg": "RS256",              // 使用的 JWA 算法
  "kid": "2024-01-rsa-key",    // key id — JWT Header 通过这个找钥匙
  "n":   "sXch...(modulus)...",
  "e":   "AQAB"                // 公钥指数 (65537)
}

# JWKS = JWK 的数组, 一个端点里可以同时有"当前 key"和"上一把 key"
{
  "keys": [
    { "kid": "2024-01", "kty": "RSA", "alg": "RS256", ... },
    { "kid": "2023-12", "kty": "RSA", "alg": "RS256", ... }
  ]
}

Day 02 已经讲过 HMAC、RSA、ECDSA、Ed25519 各自的底层取舍。 这一节专门看这些算法在 JWT 里怎么命名、怎么挑—— 不同算法的安全模型完全不同, 选错一个比不签名还危险。

JWA 算法标识对照

五种算法的体积与速度

Go 实战 · 用 golang-jwt 签发与验证

// HS256 — 自签自验
$ go get github.com/golang-jwt/jwt/v5

import "github.com/golang-jwt/jwt/v5"

var secret = []byte("my-secret-at-least-32-bytes-long!!")

func signHS256() string {
    claims := jwt.MapClaims{
        "iss": "my-service",
        "sub": "42",
        "aud": "api.example.com",
        "exp": time.Now().Add(15 * time.Minute).Unix(),
        "iat": time.Now().Unix(),
        "jti": uuid.NewString(),
    }
    tok := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    signed, _ := tok.SignedString(secret)
    return signed
}

func verifyHS256(s string) (jwt.MapClaims, error) {
    tok, err := jwt.Parse(s, func(t *jwt.Token) (any, error) {
        // 关键: 显式锁死算法, 不要"兼容多算法"
        if t.Method.Alg() != "HS256" {
            return nil, errors.New("unexpected alg")
        }
        return secret, nil
    },
        jwt.WithIssuer("my-service"),
        jwt.WithAudience("api.example.com"),
        jwt.WithExpirationRequired(),
    )
    if err != nil || !tok.Valid {
        return nil, err
    }
    return tok.Claims.(jwt.MapClaims), nil
}

// RS256 — 私钥签发 / 公钥验证
import (
    "crypto/rsa"
    "github.com/golang-jwt/jwt/v5"
)

var (
    privateKey *rsa.PrivateKey  // 从 PEM 加载, openssl genrsa -out k.pem 2048
    publicKey  *rsa.PublicKey   // 同一密钥对的公钥
)

func signRS256() string {
    claims := jwt.MapClaims{"sub": "42", "exp": time.Now().Add(1 * time.Hour).Unix()}
    tok := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
    // 加 kid, 验证方据此到 JWKS 里查公钥
    tok.Header["kid"] = "2026-05-key"
    signed, _ := tok.SignedString(privateKey)
    return signed
}

func verifyRS256(s string) (jwt.MapClaims, error) {
    tok, err := jwt.Parse(s, func(t *jwt.Token) (any, error) {
        if _, ok := t.Method.(*jwt.SigningMethodRSA); !ok {
            return nil, errors.New("unexpected alg")
        }
        // 实际场景: 根据 t.Header["kid"] 从 JWKS 里取对应公钥
        return publicKey, nil
    })
    if err != nil || !tok.Valid {
        return nil, err
    }
    return tok.Claims.(jwt.MapClaims), nil
}

JWT 的 Payload 是 任意 JSON, 但 RFC 7519 §4.1 预定义了 七个"标准声明"—— 这些字段被业界一致约定语义, 库和服务都默认认得。 用对它们, 你的 JWT 跟全世界互通; 用错或不用, 验证时各种边界 case 自己重新发明轮子。

七个标准声明

完整 Payload 范例

{
  // === 七个标准声明 ===
  "iss": "https://auth.example.com",
  "sub": "user_42",
  "aud": ["api.example.com", "open-api.example.com"],  // 可以多值
  "exp": 1727340800,
  "nbf": 1727340000,
  "iat": 1727340000,
  "jti": "7f3c4a98-9b3a-4a32-9...",

  // === OIDC / OAuth 常见扩展 ===
  "scope": "openid profile contact:read",
  "client_id": "app_3rd_party_abc",
  "acr": "urn:mace:incommon:iap:silver",    // MFA 强度等级 (Day 05)
  "amr": ["pwd", "otp"],                     // 用了哪些认证方法

  // === 私有声明 — 业务自定义 ===
  "tenant": "acme-corp",
  "plan": "pro"
}

私有声明的命名约定

Payload 是任意 JSON, 但 不要 用 user_id / email 这种"裸名"——可能与未来标准化的声明冲突。 RFC 7519 §4.3 推荐用命名空间式 URI 作 key, 避免碰撞:

{
  // ✗ 反例 — 裸名易冲突
  "role": "admin",
  "team": "backend",

  // ✓ 推荐 — URL 命名空间
  "https://example.com/role": "admin",
  "https://example.com/team": "backend",

  // ✓ 简化 — 命名空间前缀
  "ex:role": "admin",
  "ex:team": "backend"
}

验证时机清单

拿到一个 JWT 后, "验证"远不止"签名对不对"——以下七步缺一不可:

1. 解析 Header, 取出 alg 和 kid。
2. 校验 alg 在允许的白名单内(显式列出, 不要"接受任何算法")。
3. 根据 kid 取对应公钥 / 密钥, 验证签名——签名错了立刻 reject。
4. 校验 exp: now < exp(允许 30-60 秒时钟偏移)。
5. 校验 nbf(如果有): now >= nbf。
6. 校验 iss: 必须匹配预期的签发者。
7. 校验 aud: 必须包含本服务的标识。

1. 用 30 秒讲清 JWT 三段结构, 以及为什么用 base64url 而不是标准 base64。
2. RFC 7515 / 7516 / 7517 / 7518 / 7519 各自定义什么? "JOSE" 是什么意思?
3. HS256 / RS256 / ES256 / EdDSA 四种算法的关键区别——密钥模型、体积、何时该选?
4. 七个标准声明分别是什么? 资源服务器收到 JWT 必须校验哪几个?
5. 动手用标准库 (不要用 golang-jwt) 写一段代码: 输入 header / payload / secret, 输出一个合法的 HS256 JWT。验证: 用 jwt.io 能解码成功。