iam-service/docs/jwt-rs256-keys-and-e2e.md

# iam-service：RS256 公私钥生成与认证链路配置（含 JWKS）

本文以 **RSA + RS256** 为主线，覆盖从密钥生成、配置、发布 JWKS、公钥验签、到端到端验证与故障排查的完整链路。文档中的代码路径、配置项与测试命令均已在本仓库中实际运行验证。

## 1. 密钥对生成（RSA/RS256）

### 1.1 技术规范（推荐）

- 算法：RSA
- JWT 签名算法：RS256（JWT header `alg=RS256`）
- 密钥长度：2048 位（推荐）；可选 3072/4096（性能会下降）
- 私钥格式：PKCS#8，PEM 编码（`-----BEGIN PRIVATE KEY-----`）
- 公钥格式：SubjectPublicKeyInfo（PKCS#8 公钥），PEM 编码（`-----BEGIN PUBLIC KEY-----`）
- Key ID：`kid`（用于密钥轮换与多 key 共存）

当前实现兼容：
- `JWT_PUBLIC_KEY_PEM`：PKCS#8 公钥 PEM 或 PKCS#1 RSA 公钥 PEM
- `JWT_PRIVATE_KEY_PEM`：RSA 私钥 PEM（建议 PKCS#8）

### 1.2 使用 OpenSSL 生成（已验证可用）

在安全目录生成（不要提交到仓库）：

```bash
mkdir -p ./keys && chmod 700 ./keys

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out ./keys/jwt_private_key.pem
openssl pkey -in ./keys/jwt_private_key.pem -pubout -out ./keys/jwt_public_key.pem

chmod 600 ./keys/jwt_private_key.pem
chmod 644 ./keys/jwt_public_key.pem
```

校验密钥可解析：

```bash
openssl pkey -in ./keys/jwt_private_key.pem -text -noout >/dev/null
openssl pkey -pubin -in ./keys/jwt_public_key.pem -text -noout >/dev/null
```

### 1.3 可选：生成 PKCS#1 RSA PUBLIC KEY（仅在部分生态需要）

```bash
openssl rsa -in ./keys/jwt_private_key.pem -RSAPublicKey_out -out ./keys/jwt_public_key_pkcs1.pem
chmod 644 ./keys/jwt_public_key_pkcs1.pem
```

## 2. 密钥管理生命周期（生成 → 存储 → 权限 → 轮换）

### 2.1 生成与分发原则

- 私钥仅用于 iam-service 签发令牌，严禁分发给其他服务
- 公钥用于验签，可通过 JWKS 端点按需分发
- 禁止在日志/错误信息中输出 PEM 内容

### 2.2 安全存储建议

- Kubernetes：用 Secret 存 PEM（多行字符串），挂载为文件或以 env 方式注入
- 传统部署：使用 Vault/KMS/主机密钥管理系统下发到主机，落盘权限 600
- CI/CD：密钥只在部署阶段注入，不进入镜像层与构建产物

### 2.3 文件权限（Linux 推荐）

- 目录：`chmod 700 /path/to/keys`
- 私钥文件：`chmod 600 jwt_private_key.pem`
- 公钥文件：`chmod 644 jwt_public_key.pem`
- 运行用户：仅运行用户可读私钥

### 2.4 密钥轮换（kid + JWKS 多 key 共存）

目标：启用新私钥签发，同时让旧 token 在 TTL 内仍可被验签。

1) 生成新密钥对，确定新 `kid`（如 `2026-02`）

2) iam-service 切换到新 key（签发使用新私钥）：

- `JWT_KEY_ID=2026-02`
- `JWT_PRIVATE_KEY_PEM`/`JWT_PUBLIC_KEY_PEM` 指向新密钥

3) 将旧公钥加入 JWKS 兼容列表（轮换窗口）：

- `JWT_JWKS_EXTRA_KEYS_JSON` 包含旧 `kid` + 旧公钥 PEM

```json
[
  {
    "kid": "2026-01",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
  }
]
```

4) 等待旧 token 最大有效期结束（当前 access token 默认 15 分钟）后，从 `JWT_JWKS_EXTRA_KEYS_JSON` 移除旧公钥

## 3. JWT 签名与验证方案（RS256 + JWKS）

### 3.1 服务端（iam-service）：私钥签名

- RS256 签名，header 自动携带 `kid`
- 代码： [jwt.rs](file:///home/shay/project/backend/iam-service/src/utils/jwt.rs)
- 私钥/公钥读取与兼容解析： [keys.rs](file:///home/shay/project/backend/iam-service/src/utils/keys.rs)

注意：
- `JWT_SECRET` 在本项目中用于 refresh token 指纹（HMAC pepper），不用于 JWT RS256 令牌签名

### 3.2 服务端（iam-service）：发布 JWKS

公开端点：

- `GET /.well-known/jwks.json`
- 代码： [jwks.rs](file:///home/shay/project/backend/iam-service/src/handlers/jwks.rs)

行为：
- 返回当前活动 key 的 JWK（`kty=RSA,use=sig,alg=RS256,n/e,kid`）
- 可选附加历史公钥（`JWT_JWKS_EXTRA_KEYS_JSON`）

### 3.3 客户端（微服务/网关）：公钥验签

本仓库内 cms-service 默认使用 JWKS 验签：

- 优先使用静态 `JWT_PUBLIC_KEY_PEM`（离线、公钥固定）
- 否则使用 `IAM_JWKS_URL`（未提供则默认 `IAM_BASE_URL + /.well-known/jwks.json`）
- 配置代码： [cms main.rs](file:///home/shay/project/backend/cms-service/src/main.rs#L33-L64)

## 4. 集成配置示例（服务端 & 客户端）

### 4.1 iam-service（服务端签名 + 发布 JWKS）

推荐以“文件 + 启动脚本注入”的方式运行（避免把多行 PEM 塞进 .env）：

```bash
export JWT_SECRET="change-me-refresh-token-pepper"
export JWT_KEY_ID="2026-02"
export JWT_PRIVATE_KEY_PEM="$(cat ./keys/jwt_private_key.pem)"
export JWT_PUBLIC_KEY_PEM="$(cat ./keys/jwt_public_key.pem)"

cargo run
```

### 4.2 cms-service（客户端验签）

方式 A（推荐）：只配置 IAM 地址，走默认 JWKS URL

```bash
IAM_BASE_URL=http://127.0.0.1:3000
```

方式 B：显式指定 JWKS URL

```bash
IAM_JWKS_URL=http://127.0.0.1:3000/.well-known/jwks.json
```

方式 C：静态公钥（不依赖网络）

```bash
JWT_PUBLIC_KEY_PEM="$(cat ./keys/jwt_public_key.pem)"
```

### 4.3 可选：客户端离线签发（仅用于测试/联调）

正常生产链路中，私钥应只由 iam-service 持有并用于签发；客户端应只携带 token 或使用公钥验签。若需要在联调/测试环境离线生成一个 RS256 token，可使用示例程序：

- 示例代码： [offline_issue_jwt.rs](file:///home/shay/project/backend/iam-service/examples/offline_issue_jwt.rs)

运行（会在 stdout 输出生成的 JWT）：

```bash
cd /home/shay/project/backend/iam-service
export JWT_KEY_ID="2026-02"
export JWT_ISSUER="iam-service"
export JWT_PRIVATE_KEY_PEM="$(cat ./keys/jwt_private_key.pem)"

cargo run --example offline_issue_jwt
```

## 5. 测试用例与端到端验证步骤（已验证）

### 5.1 自动化测试（推荐）

auth-kit：验证 RS256 + JWKS 拉取与验签：

```bash
cd /home/shay/project/backend/auth-kit
cargo test
```

覆盖用例： [jwks_verify.rs](file:///home/shay/project/backend/auth-kit/tests/jwks_verify.rs)

iam-service：验证 JWKS 端点返回的 key 能被 auth-kit 拉取并验签（端到端）：

```bash
cd /home/shay/project/backend/iam-service
cargo test jwks_endpoint_allows_rs256_verification_via_auth_kit
```

覆盖用例： [jwks_e2e.rs](file:///home/shay/project/backend/iam-service/tests/jwks_e2e.rs)

### 5.2 手工验证（HTTP + JWKS）

获取 JWKS：

```bash
curl -s http://127.0.0.1:3000/.well-known/jwks.json | jq .
```

检查：
- `keys[].kid` 是否为当前 `JWT_KEY_ID`
- `keys[].alg` 是否为 `RS256`

## 6. 安全配置要求（生产）

- 私钥不得进入镜像层、Git、日志、监控事件
- 私钥文件权限 600；目录权限 700；仅运行用户可读
- 使用 Secret 管理器下发（Vault/KMS/K8s Secret），避免人工分发
- 为 JWKS 设置合理缓存与降级（auth-kit 已带缓存与 stale-if-error）

### 6.1 Docker 部署示例（Secret 挂载为文件 + 启动脚本注入 env）

目标：

- 镜像中不包含任何密钥
- 宿主机/Secret 管理器以“文件”的方式把 PEM 提供给容器
- 容器启动脚本读取 PEM 文件并注入 `JWT_PRIVATE_KEY_PEM/JWT_PUBLIC_KEY_PEM`

#### 6.1.1 启动脚本（entrypoint.sh）

示例（容器内路径假定为 `/run/secrets/*`）：

```bash
#!/usr/bin/env sh
set -eu

JWT_PRIVATE_KEY_FILE="${JWT_PRIVATE_KEY_FILE:-/run/secrets/jwt_private_key.pem}"
JWT_PUBLIC_KEY_FILE="${JWT_PUBLIC_KEY_FILE:-/run/secrets/jwt_public_key.pem}"

if [ ! -r "$JWT_PRIVATE_KEY_FILE" ]; then
  echo "missing private key file: $JWT_PRIVATE_KEY_FILE" >&2
  exit 1
fi

if [ ! -r "$JWT_PUBLIC_KEY_FILE" ]; then
  echo "missing public key file: $JWT_PUBLIC_KEY_FILE" >&2
  exit 1
fi

export JWT_PRIVATE_KEY_PEM="$(cat "$JWT_PRIVATE_KEY_FILE")"
export JWT_PUBLIC_KEY_PEM="$(cat "$JWT_PUBLIC_KEY_FILE")"

exec /app/iam-service
```

说明：
- `export VAR="$(cat file)"` 会保留 PEM 的换行，适用于多行 env 注入
- 建议在运行时设置 `JWT_KEY_ID`（例如 `2026-02`）用于轮换

#### 6.1.2 Dockerfile（示例）

下面示例采用多阶段构建，并把二进制与启动脚本放入最终镜像（不写入任何 key）：

```dockerfile
# syntax=docker/dockerfile:1
FROM rust:1.93 AS builder
WORKDIR /work
COPY . .
RUN cargo build --release -p iam-service

FROM debian:bookworm-slim
WORKDIR /app
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*

COPY --from=builder /work/target/release/iam-service /app/iam-service
COPY ./docker/entrypoint.sh /app/entrypoint.sh
RUN chmod 755 /app/entrypoint.sh

EXPOSE 3000
ENTRYPOINT ["/app/entrypoint.sh"]
```

#### 6.1.3 docker run（示例）

假设宿主机上密钥位于 `./keys/`：

```bash
docker run --rm -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  -e SERVICE_NAME=iam-service \
  -e PORT=3000 \
  -e DATABASE_URL='postgres://iam_service_user:iam_service_password@host.docker.internal:5432/iam_service_db' \
  -e JWT_SECRET='change-me-refresh-token-pepper' \
  -e JWT_KEY_ID='2026-02' \
  --mount type=bind,source="$(pwd)/keys/jwt_private_key.pem",target=/run/secrets/jwt_private_key.pem,readonly \
  --mount type=bind,source="$(pwd)/keys/jwt_public_key.pem",target=/run/secrets/jwt_public_key.pem,readonly \
  iam-service:latest
```

#### 6.1.4 验证步骤（Docker 场景）

1) 拉取 JWKS（应返回当前 `JWT_KEY_ID` 对应 `kid`）：

```bash
curl -s http://127.0.0.1:3000/.well-known/jwks.json | jq .
```

2) 走业务登录获取 token，并在下游服务（如 cms-service）通过 JWKS 自动验签（详见本文第 4 节与第 5 节）。

## 7. 故障排查指南（常见失败场景）

### 7.1 `Missing kid in JWT header`

- 诊断：token header 未携带 `kid`
- 处理：确认签发方设置 `kid`（iam-service 已自动设置）

### 7.2 `jwks:kid_not_found`

- 诊断：token 的 `kid` 不在 JWKS 中（常见于轮换窗口未包含旧 key）
- 处理：将旧公钥加入 `JWT_JWKS_EXTRA_KEYS_JSON`，并等待旧 token 过期后移除

### 7.3 `Invalid JWT public key pem`

- 诊断：公钥 PEM 格式/换行错误或被转义
- 处理：使用文件注入：`export JWT_PUBLIC_KEY_PEM="$(cat file)"`；并用 openssl 校验

### 7.4 `Invalid issuer`

- 诊断：`iss` 不匹配（本项目默认 issuer 为 `iam-service`）
- 处理：确保验签端配置 issuer 为 `iam-service`

### 7.5 JWKS 拉取失败导致验签失败

- 诊断：IAM 不可用或网络不通
- 处理：依赖 auth-kit JWKS 缓存与 stale-if-error；生产上部署多副本 IAM 与 LB

## 8. ECDSA（ES256）路线说明

当前仓库实现为 RS256（RSA）。如需使用 ECDSA（ES256），需要在签发与验签侧同时切换算法（包括 auth-kit 的 JWKS 解析逻辑），并返回 `kty=EC` 的 JWK。