4. JWT Header详解

JWT（JSON Web Token）的 Header（头部）是令牌的第一部分，通常是一个 Base64URL 编码的 JSON 对象。它承载了令牌的元数据，包括签名算法、令牌类型等关键信息。服务端在验证 JWT 时，首先解析 Header 以确定使用何种算法进行签名校验。理解 Header 的结构与字段，是正确实现 JWT 鉴权的基础。

4.1 Header 标准字段

JWT 规范（RFC 7519）定义了两个标准字段，所有 JWT 实现都应支持：

4.1.1 alg 字段详解

alg 是 Header 中唯一必须存在的字段。它告诉验证方该 JWT 使用了哪种签名或加密算法。常见的 alg 取值包括：

• HS256：HMAC with SHA-256，对称签名算法。
• HS384：HMAC with SHA-384。
• HS512：HMAC with SHA-512。
• RS256：RSA with SHA-256，非对称签名算法。
• RS384：RSA with SHA-384。
• RS512：RSA with SHA-512。
• ES256：ECDSA with P-256 and SHA-256。
• none：不签名（仅用于调试，生产环境禁止使用）。

4.1.2 typ 字段详解

typ 字段用于声明令牌的媒体类型。根据 RFC 7519，其值应设置为 "JWT"。在某些复合结构中（如 JWE 嵌套 JWS），typ 可以帮助解析器区分内部令牌类型。一个典型的 Header 示例：

{
  "alg": "HS256",
  "typ": "JWT"
}

4.2 常见签名算法：HS256 与 RS256

在 Web 接口安全中，HS256 和 RS256 是最广泛使用的两种签名算法。它们分别代表对称与非对称签名体系，在密钥管理、性能、安全性方面有显著差异。

4.3 自定义 Header

除了标准字段，JWT Header 允许添加自定义字段，用于携带与令牌处理相关的元数据。自定义字段通常以 非冲突命名 为原则，避免与标准字段或未来扩展冲突。常见做法是使用前缀或特定命名空间。

4.3.1 常见自定义字段示例

4.3.2 自定义 Header 的 Go 实现示例

在 Go 中使用 github.com/golang-jwt/jwt/v5 库时，可以通过自定义结构体扩展 Header：

package main

import (
    "fmt"
    "github.com/golang-jwt/jwt/v5"
)

// 自定义 Claims 结构体
type CustomClaims struct {
    UserID   string `json:"user_id"`
    Role     string `json:"role"`
    jwt.RegisteredClaims
}

// 自定义 Header 字段
type CustomHeader struct {
    jwt.Header
    KeyID string `json:"kid,omitempty"`
    AppID string `json:"app_id,omitempty"`
}

func main() {
    // 创建自定义 Header
    header := CustomHeader{
        Header: jwt.Header{
            Algorithm: "RS256",
            Type:      "JWT",
        },
        KeyID: "my-rsa-key-2024",
        AppID: "gateway-v3",
    }

    // 创建 Claims
    claims := CustomClaims{
        UserID: "u-10086",
        Role:   "admin",
        RegisteredClaims: jwt.RegisteredClaims{
            Issuer: "auth-service",
        },
    }

    // 使用自定义 Header 和 Claims 生成 Token
    token := jwt.NewWithClaims(header, claims)
    tokenString, err := token.SignedString(privateKey)
    if err != nil {
        panic(err)
    }
    fmt.Println(tokenString)
}

4.4 JWT Header 结构总览

下图展示了 JWT Header 的标准字段、常见算法选择以及自定义扩展的整体结构：

4.5 算法选择决策流程

在实际项目中，选择 HS256 还是 RS256 需要根据架构和安全需求权衡。以下决策流程可以帮助你做出选择：

4.6 安全最佳实践

• 算法白名单验证： 在验证 JWT 时，必须检查 alg 字段是否在服务端允许的算法列表中。防止攻击者将 alg 改为 none 或弱算法绕过签名验证。
• 避免算法混淆攻击： 如果服务端支持 RS256，但攻击者将 alg 改为 HS256 并使用公钥作为 HMAC 密钥签名，可能导致验证通过。解决方案：始终根据 alg 字段选择对应的验证方法，不要混用。
• 使用 kid 支持密钥轮换： 在 Header 中包含 kid 字段，服务端根据 kid 查找对应的密钥进行验证。这允许在不中断服务的情况下轮换密钥。
• 最小化自定义字段： 只在 Header 中放置与令牌处理直接相关的元数据。业务数据应放在 Payload 中，而非 Header。