[dependencies] jsonwebtoken = "9" serde = { version = "1", features = ["derive"] } uuid = { version = "1", features = ["v4", "serde"] } time = { version = "0.3", features = ["serde"] }

// src/auth/claims.rs use serde::{Deserialize, Serialize}; #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Claims { // ---- 标准声明 ---- pub iss: String, // "https://api.example.com" pub sub: String, // user_id，注意是 String pub aud: String, // "example-api" pub exp: usize, // 过期时间戳（秒） pub nbf: usize, // 生效时间戳 pub iat: usize, // 签发时间戳 // ---- 自定义声明 ---- // jti 让 token 可以被单独撤销，refresh 轮换也靠它 pub jti: String, // 只放"粗粒度"角色，细粒度权限每次查缓存，避免改权限要等 token 过期 pub roles: Vec<String>, // 用于"改密码后旧 token 全部失效"：与 user.pwd_changed_at 比较 pub pwd_at: i64, }

use jsonwebtoken::{encode, Algorithm, EncodingKey, Header}; use uuid::Uuid; const ISSUER: &str = "https://api.example.com"; const AUDIENCE: &str = "example-api"; const ACCESS_TTL_SECS: usize = 15 * 60; // 15 分钟，越短越安全 pub fn issue_access_token( user_id: &str, roles: Vec<String>, pwd_at: i64, secret: &[u8], ) -> Result<String, jsonwebtoken::errors::Error> { // get_current_timestamp() 返回秒级 Unix 时间戳，别自己算错时区 let now = jsonwebtoken::get_current_timestamp() as usize; let claims = Claims { iss: ISSUER.into(), sub: user_id.into(), aud: AUDIENCE.into(), exp: now + ACCESS_TTL_SECS, // nbf 故意往前留 30 秒，容忍签发机与被验机之间的时钟偏移 nbf: now.saturating_sub(30), iat: now, jti: Uuid::new_v4().to_string(), roles, pwd_at, }; // Header::new(Algorithm::HS256) 会把 alg 写进 JWT 头部；typ 自动填 JWT encode( &Header::new(Algorithm::HS256), &claims, &EncodingKey::from_secret(secret), ) }

// src/config.rs —— 密钥来源优先级：环境变量 > 密钥管理服务 > 配置文件 #[derive(Debug, Clone)] pub struct AuthConfig { pub jwt_secret: Vec<u8>, pub access_ttl: std::time::Duration, pub refresh_ttl: std::time::Duration, } impl AuthConfig { pub fn from_env() -> anyhow::Result<Self> { let secret = std::env::var("JWT_SECRET") .map_err(|_| anyhow::anyhow!("必须设置 JWT_SECRET 环境变量"))?; // HS256 的安全下限是"密钥熵不小于哈希输出"，32 字节起步 if secret.len() < 32 { anyhow::bail!("JWT_SECRET 太短，至少 32 字节，建议 openssl rand -base64 48 生成"); } Ok(Self { jwt_secret: secret.into_bytes(), access_ttl: std::time::Duration::from_secs(15 * 60), refresh_ttl: std::time::Duration::from_secs(7 * 24 * 3600), }) } }

// 危险：先解析 header 看 alg，再决定怎么验 —— 攻击者说 none 你就放行 let header = jsonwebtoken::decode_header(token)?; match header.alg { Algorithm::HS256 => { /* 用密钥验 */ } // 一旦这里写了"其他算法就不验签名"，直接沦陷 _ => { /* 放行 */ } }

use jsonwebtoken::{decode, Algorithm, DecodingKey, Validation}; pub fn verify_access_token(token: &str, secret: &[u8]) -> Result<Claims, AuthError> { // 关键 1：Validation::new(Algorithm::HS256) —— 算法在这里就被钉死 // 库内部会把 header.alg 与这里指定的算法比对，alg=none 的 token 直接被拒 let mut validation = Validation::new(Algorithm::HS256); // 关键 2：iss / aud 必须校验，否则跨服务 token 可以互相冒用 validation.set_issuer(&[ISSUER]); validation.set_audience(&[AUDIENCE]); // 关键 3：时钟偏移容忍。服务器之间差 30 秒是常态，默认 60 秒 buffer 别关掉 validation.leeway = 60; // 关键 4：显式声明哪些声明"必须存在"，缺失就报错 // 默认只有 exp 是必需的，iss/aud 不写进这里就可能被"缺失即跳过" validation.required_spec_claims.insert("iss".into()); validation.required_spec_claims.insert("aud".into()); validation.required_spec_claims.insert("sub".into()); // 关键 5：过期必须校验（默认 true，显式写出来让 Review 的人放心） validation.validate_exp = true; // nbf 与 iat 的校验按需；校验 iat 能挡住"把 exp 改到很久以后"的旧 token 复用 validation.validate_nbf = true; let data = decode::<Claims>( token, &DecodingKey::from_secret(secret), &validation, ) .map_err(|e| match e.kind() { jsonwebtoken::errors::ErrorKind::ExpiredSignature => AuthError::Expired, jsonwebtoken::errors::ErrorKind::InvalidSignature => AuthError::BadSignature, jsonwebtoken::errors::ErrorKind::ImmatureSignature => AuthError::NotYetValid, _ => AuthError::Invalid, })?; // data.header 是 token 头部，data.claims 才是我们关心的内容 Ok(data.claims) } // 只在"确实要看 payload 内容但不需要信任它"时才用（例如日志、路由） pub fn peek_unverified(token: &str) -> Result<Claims, AuthError> { // dangerous::insecure_decode 明确标了 dangerous，看到它就该警觉 jsonwebtoken::dangerous::insecure_decode::<Claims>(token) .map(|d| d.claims) .map_err(|_| AuthError::Invalid) }

// 对称：HS256 —— 同一把密钥既签名又验签 let enc = EncodingKey::from_secret(secret); let dec = DecodingKey::from_secret(secret); // 优点：快、实现简单。缺点：所有验签方都拿到密钥 = 都能签发 // 适用：单体服务、内部服务之间（且能保证密钥不外泄） // 非对称：RS256 / ES256 —— 私钥签名，公钥验签 let enc = EncodingKey::from_rsa_pem(include_bytes!("keys/private.pem"))?; let dec = DecodingKey::from_rsa_pem(include_bytes!("keys/public.pem"))?; // 优点：验签方只有公钥，无法伪造 token（可安全下发给网关、其他团队） // 缺点：RSA 验签比 HMAC 慢一个量级；密钥管理更重（要处理轮换） // 适用：多服务共享登录态、需要把公钥暴露给第三方、OIDC 场景 // ECDSA（ES256）比 RS256 快、签名更短，但并非所有 JWT 库都完整支持 let dec = DecodingKey::from_ec_pem(public_pem)?;

use jsonwebtoken::jwk::{Jwk, JwkSet}; use std::collections::HashMap; // 典型 JWKS 文档结构（https://idp.example.com/.well-known/jwks.json） // { "keys": [ { "kty": "RSA", "kid": "abc123", "use": "sig", "n": "...", "e": "AQAB" } ] } pub struct JwksCache { // kid -> 已解析好的 DecodingKey，避免每次请求都重新解析模数 keys: tokio::sync::RwLock<HashMap<String, DecodingKey>>, fetched_at: std::sync::atomic::AtomicU64, url: String, http: reqwest::Client, } impl JwksCache { pub async fn get(&self, kid: &str) -> anyhow::Result<DecodingKey> { { let guard = self.keys.read().await; if let Some(k) = guard.get(kid) { return Ok(k.clone()); } } // 缓存没命中：可能是 IdP 轮换了密钥，重新拉一次再查 let set: JwkSet = self.http.get(&self.url).send().await?.json().await?; let mut map = HashMap::new(); for jwk in &set.keys { if let Some(kid) = &jwk.common.key_id { // from_jwk 直接把 JWK 转成 DecodingKey，不用自己拼模数 map.insert(kid.clone(), DecodingKey::from_jwk(jwk)?); } } let key = map.get(kid).cloned().ok_or_else(|| anyhow::anyhow!("未知 kid: {kid}"))?; *self.keys.write().await = map; Ok(key) } } // 验签时：先取 header 的 kid（不验签，只看头部），再从缓存取公钥 let header = jsonwebtoken::decode_header(token)?; let key = jwks.get(header.kid.as_deref().ok_or(AuthError::Invalid)?).await?; let mut v = Validation::new(Algorithm::RS256); // 仍然要钉死算法 let data = decode::<Claims>(token, &key, &v)?;

# refresh 白名单：只存"当前有效"的 refresh token 的 jti # 值里带上 user_id 与"这一代的 jti"，TTL 就等于 refresh 有效期 SET refresh:{jti} "user:42|gen:7" EX 604800 # 用户级会话索引：用于"一键登出所有设备" SADD user:42:refresh_jtis {jti1} {jti2} # access token 黑名单（只在"提前撤销"时需要，TTL 设成 access 剩余寿命即可） SET revoked:access:{jti} "1" EX 900 # 关键点：黑名单的 TTL 千万不要设成永久，否则 Redis 会被慢慢撑爆 # 设成"access token 的自然过期时间"就够，过期后 JWT 自己会失效

use redis::AsyncCommands; /// 用 refresh token 换一套新的 (access, refresh) pub async fn rotate( old_refresh: &str, redis: &redis::aio::ConnectionManager, cfg: &AuthConfig, ) -> Result<(String, String), AuthError> { // 1) 先校验签名与 exp（refresh token 也要签名，别用不透明字符串硬查库） let claims = verify_refresh_token(old_refresh, &cfg.jwt_secret)?; // 2) 原子地"取出并删除"旧 jti —— GETDEL 保证并发下只有一个请求能成功 // 用 GET + DEL 两步会在并发续期时出现两个请求都成功的竞态 let key = format!("refresh:{}", claims.jti); let mut conn = redis.clone(); let stored: Option<String> = conn.get_del(&key).await.map_err(AuthError::internal)?; match stored { // 3a) 正常路径：旧 token 确实在我们这，删除成功，发新一代 Some(_) => { let new_access = issue_access_token(&claims.sub, claims.roles.clone(), claims.pwd_at, &cfg.jwt_secret)?; let new_refresh = issue_refresh_token(&claims.sub, &cfg)?; // 把新的 refresh jti 写回白名单 let new_claims = peek_unverified(&new_refresh)?; let _: () = conn .set_ex(format!("refresh:{}", new_claims.jti), &claims.sub, cfg.refresh_ttl.as_secs()) .await .map_err(AuthError::internal)?; Ok((new_access, new_refresh)) } // 3b) 签名合法但 jti 不在白名单 —— 典型的【重放】： // 这个 refresh 已经用过一次，现在被人拿着旧副本再次使用。 // 说明凭证可能已泄露，必须把该用户的所有会话全部踢掉。 None => { revoke_all_sessions(&claims.sub, &mut conn).await; Err(AuthError::RefreshReused) } } } /// 踢掉某用户全部会话：遍历索引里的 jti 逐个删白名单 + 加 access 黑名单 async fn revoke_all_sessions(user_id: &str, conn: &mut redis::aio::ConnectionManager) { let idx = format!("user:{user_id}:refresh_jtis"); let jtis: Vec<String> = conn.smembers(&idx).await.unwrap_or_default(); for jti in jtis { let _: Result<(), _> = conn.del(format!("refresh:{jti}")).await; } let _: Result<(), _> = conn.del(&idx).await; }

1. 前端生成 code_verifier（43~128 位随机串） └─ 算出 code_challenge = BASE64URL( SHA256(code_verifier) ) 2. 浏览器跳转到授权端点： GET https://idp.example.com/authorize ?response_type=code &client_id=my-app &redirect_uri=https://app.example.com/callback &scope=openid profile email &state=RANDOM_CSRF_TOKEN &code_challenge=XXXX &code_challenge_method=S256 3. 用户在 IdP 登录并授权 → 浏览器被重定向回： https://app.example.com/callback?code=CODE&state=RANDOM_CSRF_TOKEN └─ 前端【必须比对 state】，防止 CSRF 4. 后端拿 code 换 token（这一步在服务端做，client_secret 不下发浏览器）： POST https://idp.example.com/token grant_type=authorization_code &code=CODE &redirect_uri=... &client_id=my-app &code_verifier=原始随机串 ← 回放给 IdP，它自己算 hash 比对 5. 响应里拿到： { "access_token": "...", "refresh_token": "...", "id_token": "eyJ...", ← OIDC 才有，JWT 格式，含身份 "expires_in": 3600 } 6. 用 access_token 调 /userinfo 拿详细资料，或用 id_token 里的 claims └─ 调业务 API 时不需要再带 IdP 的 token，换成你自己签发的 JWT

// src/auth/oidc.rs —— 用 reqwest 走标准的 token 端点交换 #[derive(serde::Deserialize)] struct TokenResponse { access_token: String, id_token: Option<String>, refresh_token: Option<String>, expires_in: u64, } pub async fn exchange_code( http: &reqwest::Client, issuer: &str, client_id: &str, client_secret: &str, code: &str, redirect_uri: &str, code_verifier: &str, ) -> anyhow::Result<TokenResponse> { // 端点地址从 discovery 文档拿，别硬编码 // GET {issuer}/.well-known/openid-configuration -> token_endpoint / jwks_uri let disc: serde_json::Value = http .get(format!("{issuer}/.well-known/openid-configuration")) .send().await?.json().await?; let token_endpoint = disc["token_endpoint"].as_str().unwrap(); let resp = http .post(token_endpoint) .form(&[ ("grant_type", "authorization_code"), ("code", code), ("redirect_uri", redirect_uri), ("client_id", client_id), ("client_secret", client_secret), // PKCE 的唯一作用就是回放这个原串给 IdP ("code_verifier", code_verifier), ]) .send().await? .error_for_status()? .json::<TokenResponse>().await?; Ok(resp) } /// 校验 OIDC 的 id_token（本质就是一个 JWT） pub fn verify_id_token( id_token: &str, key: &DecodingKey, issuer: &str, client_id: &str, ) -> anyhow::Result<IdClaims> { // id_token 的 aud 必须等于你的 client_id —— 这一步常被漏掉 let mut v = Validation::new(Algorithm::RS256); // 仍然钉死算法 v.set_issuer(&[issuer]); v.set_audience(&[client_id]); v.leeway = 60; let data = decode::<IdClaims>(id_token, key, &v)?; Ok(data.claims) }

// src/auth/extractor.rs use axum::{ extract::FromRequestParts, http::{header, request::Parts, StatusCode}, Json, }; use std::sync::Arc; #[derive(Debug, Clone)] pub struct AuthUser { pub user_id: String, pub roles: Vec<String>, pub jti: String, pub pwd_at: i64, } // 把依赖（密钥、redis）放进 AppState，提取器通过 State 拿到 pub struct AppState { pub auth: Arc<AuthConfig>, pub redis: redis::aio::ConnectionManager, pub db: sqlx::PgPool, } // axum 0.8 的 FromRequestParts 用的是原生 async fn（Rust 1.75+）， // 不再需要 #[async_trait]，写起来和普通函数一样 impl FromRequestParts<AppState> for AuthUser { // Rejection 决定鉴权失败时的响应。用一个自定义错误类型比元组更清晰 type Rejection = (StatusCode, Json<ApiError>); async fn from_request_parts( parts: &mut Parts, state: &AppState, ) -> Result<Self, Self::Rejection> { // 1) 取头。大小写不敏感，用 header::AUTHORIZATION 常量而不是手写字符串 let raw = parts .headers .get(header::AUTHORIZATION) .and_then(|v| v.to_str().ok()) .ok_or_else(|| unauthorized("缺少 Authorization 头"))?; // 2) 严格按 "Bearer " 前缀解析，大小写差异按 RFC 应当忽略 let token = raw .strip_prefix("Bearer ") .or_else(|| raw.strip_prefix("bearer ")) .ok_or_else(|| unauthorized("Authorization 头格式必须是 Bearer <token>"))? .trim(); // 3) 验签 + 校验声明 let claims = verify_access_token(token, &state.auth.jwt_secret) .map_err(|e| unauthorized(&format!("token 无效: {e}")))?; // 4) 黑名单检查：被撤销的 access token 要立刻失效 // 注意这里查 Redis 是每次请求都做的，所以键的 TTL 必须是有界的 let mut conn = state.redis.clone(); let revoked: Option<String> = redis::AsyncCommands::get( &mut conn, format!("revoked:access:{}", claims.jti), ) .await .map_err(|_| unauthorized("鉴权服务暂不可用"))?; if revoked.is_some() { return Err(unauthorized("token 已被撤销")); } // 5) 关键的安全设计：roles 不信任 token 里的值，而是查库/查缓存 // 这样管理员改了权限立刻生效，不用等 token 过期 let roles: Vec<String> = sqlx::query_scalar( "SELECT role FROM user_roles WHERE user_id = $1", ) .bind(&claims.sub) .fetch_all(&state.db) .await .unwrap_or_default(); // 6) 密码修改时间比对：改过密码后，更早签发的 token 一律失效 let pwd_at: i64 = sqlx::query_scalar("SELECT pwd_changed_at FROM users WHERE id = $1") .bind(&claims.sub) .fetch_one(&state.db) .await .map_err(|_| unauthorized("用户不存在"))?; if claims.pwd_at < pwd_at { return Err(unauthorized("密码已变更，请重新登录")); } Ok(AuthUser { user_id: claims.sub, roles, jti: claims.jti, pwd_at, }) } }

// 1) 只要"已登录"：把 AuthUser 当普通参数写进去即可 async fn me(user: AuthUser) -> Json<serde_json::Value> { Json(serde_json::json!({ "user_id": user.user_id, "roles": user.roles })) } // 2) 只要某个角色：提取器实现了"角色守卫"，用类型把它们区分开 pub struct AdminUser(pub AuthUser); impl FromRequestParts<AppState> for AdminUser { type Rejection = (StatusCode, Json<ApiError>); async fn from_request_parts(parts: &mut Parts, state: &AppState) -> Result<Self, Self::Rejection> { // 复用基础提取器的全部逻辑，再叠加角色检查 let user = AuthUser::from_request_parts(parts, state).await?; if !user.roles.iter().any(|r| r == "admin") { // 注意语义：已认证但无权限应当是 403，不是 401 return Err((StatusCode::FORBIDDEN, Json(ApiError::new("需要管理员权限")))); } Ok(AdminUser(user)) } } // 3) 资源级校验必须写在业务逻辑里，提取器管不了 async fn delete_order( user: AuthUser, axum::extract::Path(order_id): axum::extract::Path<i64>, axum::extract::State(state): axum::extract::State<AppState>, ) -> Result<StatusCode, AppError> { let owner: String = sqlx::query_scalar("SELECT owner_id FROM orders WHERE id = $1") .bind(order_id).fetch_one(&state.db).await?; // 只能删自己的，或者是管理员。这条规则无法用"角色"表达，必须查数据 if owner != user.user_id && !user.roles.iter().any(|r| r == "admin") { return Err(AppError::Forbidden); } sqlx::query("DELETE FROM orders WHERE id = $1").bind(order_id).execute(&state.db).await?; Ok(StatusCode::NO_CONTENT) } // 4) 路由装配：把 AuthUser 写在参数里，就自动要求鉴权 let app = axum::Router::new() .route("/me", axum::routing::get(me)) .route("/admin/users", axum::routing::get(list_users)) // handler 参数是 AdminUser .route("/login", axum::routing::post(login)) .with_state(state);

use tower_http::cors::{Any, CorsLayer}; use axum::http::{header, Method}; let cors = CorsLayer::new() // 注意：allow_credentials(true) 与 allow_origin(Any) 不能同时用 // 浏览器规范禁止 "Access-Control-Allow-Origin: *" 携带凭证 .allow_origin("https://app.example.com".parse::<axum::http::HeaderValue>().unwrap()) .allow_methods([Method::GET, Method::POST, Method::DELETE]) // 必须显式列出 AUTHORIZATION，否则浏览器预检请求会失败 .allow_headers([header::AUTHORIZATION, header::CONTENT_TYPE]) .allow_credentials(true);