网站有页面,攻击面看得见;API 只有端点,出问题时往往是"某天早上发现订单表里多了几万条测试记录",或者"收到云厂商账单才发现接口被刷了几百万次"。API 是业务逻辑的直接入口,一旦防护缺失,损失是数据、资损和信誉,而不只是页面打不开。
本文只讲防护设计:怎么给 API 做身份认证、怎么防重放与篡改、怎么设计令牌生命周期、怎么做限流、怎么管理密钥。全文不涉及任何绕过或攻击手法,所有示例都是服务端校验与配置代码。
一、API 面临的风险画像
先明确要防什么,才能把力气用对地方:
- 凭据泄露:API Key 被硬编码在前端/App 里、被提交到公开代码仓库、被日志打印出来。
- 请求被篡改:参数在传输途中被改(金额、数量、用户 ID),服务端无法察觉。
- 请求被重放:一个合法请求被复制后反复提交(重复下单、重复领取)。
- 越权访问:改一下 URL 里的用户 ID 就能看到别人的数据(水平越权),或普通用户调用了管理员接口(垂直越权)。
- 资源被刷:短信接口被刷导致资损、查询接口被高频调用拖垮数据库。
- 信息过度返回:接口把整个数据库对象序列化返回,包含内部字段甚至哈希口令。
对应的五道防线:鉴权(你是谁)→ 签名(请求没被改)→ 时效与随机数(不是重放)→ 授权(你能不能访问这个资源)→ 限流(不能无限调用)。下面逐道展开。
二、身份认证:三种方案的取舍
| 方案 | 适用场景 | 优点 | 局限与注意 |
|---|---|---|---|
| API Key | 服务端到服务端(B2B 对接、内部微服务) | 实现简单、可精确吊销 | 本身不携带有效期,泄露即长期有效;必须配 HTTPS + 轮换 |
| JWT | 用户端会话(App、小程序、SPA) | 无状态、服务端不需存会话 | 签发后难以即时吊销,需要短有效期 + 黑名单配合 |
| OAuth 2.0 | 第三方授权登录、开放平台 | 标准成熟、支持细粒度 scope | 实现复杂,回调与 state 参数容易配错 |
| mTLS | 内部服务间高安全通信 | 双向证书校验,无口令传输 | 证书签发与轮换需要一整套 PKI 运维 |
实践中最常见的组合是:外部 B2B 对接用 API Key + HMAC 签名;用户登录后用 JWT;内部服务间用 mTLS 或网格方案。不要试图用一种方案覆盖所有场景。
2.1 API Key 的正确使用姿势
# 用 OpenSSL 生成高强度随机密钥(32 字节,Base64 后约 44 字符) openssl rand -base64 32 # 十六进制形式,适合放在配置里 openssl rand -hex 32 # 存储:服务端只保存哈希,不保存明文(与存口令同理) # 存储格式示例:key_id + 哈希 + 前缀(用于展示与检索) # ak_live_8f3a... | sha256(secret) | 前缀 ak_live_8f3a # # 校验流程: # 1. 从请求头取 key_id,查库得到记录(注意恒定时间比较) # 2. 对该记录的哈希与请求密钥做比对 # 3. 检查 key 的状态(启用/吊销)与 scope 是否包含本次操作 # 4. 更新 last_used_at,用于发现长期不用的僵尸密钥
三条硬性要求:密钥只在请求头中传递(如 X-API-Key),绝不放在 URL query 里(URL 会被网关、浏览器历史、各种访问日志记录);密钥必须带前缀标识环境与类型(ak_live_ / ak_test_),这样密钥扫描工具能识别、也能防止测试密钥被误用到生产;服务端只存哈希,数据库泄露时不会直接导致密钥可用。
三、请求签名:HMAC 防篡改与防重放
API Key 只解决"你是谁",不解决"请求被改了没有"。对资金、订单、对账类接口,必须加签名。
3.1 签名算法
# 待签串的构造:把会影响业务语义的要素都纳入,并用换行分隔
# METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY_SHA256
#
# 服务端按同样规则重建待签串,用同样密钥计算 HMAC,比对结果。
import hmac, hashlib, time, base64, secrets
def build_payload(method, path, timestamp, nonce, body: bytes) -> bytes:
return b"\n".join([
method.upper().encode(),
path.encode(),
str(timestamp).encode(),
nonce.encode(),
hashlib.sha256(body).hexdigest().encode(),
])
def sign(secret: str, payload: bytes) -> str:
return base64.b64encode(
hmac.new(secret.encode(), payload, hashlib.sha256).digest()
).decode()
# ---- 客户端 ----
timestamp = int(time.time())
nonce = secrets.token_hex(16)
sig = sign(API_SECRET, build_payload("POST", "/v1/orders", timestamp, nonce, body))
# 请求头:
# X-Api-Key: ak_live_xxxx
# X-Timestamp: 1717200000
# X-Nonce: a1b2c3...
# X-Signature: base64(...)
# ---- 服务端校验 ----
def verify(secret, method, path, headers, body):
ts = int(headers["X-Timestamp"])
nonce = headers["X-Nonce"]
sig = headers["X-Signature"]
# 1) 时间窗:与服务器时间差超过 300 秒直接拒绝(防重放的第一道)
if abs(int(time.time()) - ts) > 300:
return False, "timestamp expired"
# 2) nonce 去重:Redis SETNX,TTL 设为时间窗的 2 倍
# redis.set(f"nonce:{nonce}", 1, nx=True, ex=600) 返回 None 表示重复
if not redis.set(f"nonce:{ak_id}:{nonce}", 1, nx=True, ex=600):
return False, "nonce reused"
# 3) 恒定时间比较,避免时序侧信道
expected = sign(secret, build_payload(method, path, ts, nonce, body))
if not hmac.compare_digest(expected, sig):
return False, "bad signature"
return True, "ok"
3.2 签名设计的四个要点
- 待签串必须包含 body 的哈希,否则请求体可以被随意替换而签名仍有效。
- 必须包含完整路径,避免签名被挪用到其他接口。
- 时间窗与 nonce 缺一不可:只有时间窗,窗口内的重放挡不住;只有 nonce,存储会无限增长。
- 用
hmac.compare_digest而不是==,普通字符串比较会在第一个不同字符处返回,可能泄露信息。
四、令牌生命周期:有效期、刷新与吊销
JWT 的最大争议是"签发后无法即时吊销"。正确的应对不是放弃 JWT,而是用短有效期换取可接受的吊销延迟。
# JWT 结构:header.payload.signature,三段用点号分隔
# 推荐的 payload 声明(避免塞入敏感信息,payload 只是 Base64 编码,不是加密)
{
"iss": "api.example.com", # 签发者
"sub": "user_10086", # 用户标识
"aud": "mobile-app", # 受众,区分 App / 后台 / 第三方
"exp": 1717201800, # 过期时间
"iat": 1717200000, # 签发时间
"nbf": 1717200000, # 生效时间
"jti": "b3a1f2...", # 唯一 ID,用于黑名单与审计
"scope": ["order:read", "order:write"]
}
# 有效期建议(可按业务敏感度调整)
# access token:15-30 分钟
# refresh token:7-30 天,且只能使用一次(用后即换)
# 管理后台会话:更短,建议 15 分钟且绑定 IP 段
4.1 刷新与吊销设计
| 机制 | 吊销延迟 | 开销 | 适用 |
|---|---|---|---|
| 超短有效期(5-15 分钟) | ≤15 分钟 | 无额外存储 | 一般业务 |
| jti 黑名单(Redis) | 秒级 | 每次校验一次 Redis 查询 | 登出、风控封禁 |
| 令牌版本号(user 表 token_version) | 秒级 | 一次查询 | "下线所有设备" |
| 完全有状态会话(存 Redis) | 实时 | 每次请求一次查询 | 金融、后台管理 |
# 刷新令牌:单次有效,用后即换(检测到旧 refresh token 复用时立即吊销整条链)
def refresh(refresh_token):
rec = redis.get(f"rt:{sha256(refresh_token)}")
if not rec:
return 401, "invalid refresh token"
if rec.used:
# 复用意味着可能泄露,吊销该用户全部会话并告警
revoke_all_sessions(rec.user_id)
alert_security_team(rec.user_id)
return 401, "token reuse detected"
rec.used = True
new_rt = rotate_refresh_token(rec.user_id) # 签发新的并写入
new_at = issue_access_token(rec.user_id, ttl=1800)
return 200, {"access_token": new_at, "refresh_token": new_rt}
五、限流:令牌桶与漏桶
限流的目标有两个:防止资源被耗尽、防止接口被刷造成资损。选择算法前先明确要哪一种。
| 算法 | 原理 | 特点 | 适用 |
|---|---|---|---|
| 固定窗口计数 | 每个时间窗内计数 | 简单,但窗口边界可能通过 2 倍流量 | 粗粒度兜底 |
| 滑动窗口 | 按更小的时间片滚动统计 | 精度高,内存随精度上升 | API 网关通用 |
| 令牌桶 | 匀速生成令牌,请求取令牌,桶容量决定突发上限 | 允许可控突发,平均速率受限 | 大多数业务接口 |
| 漏桶 | 请求入桶,以恒定速率流出,超出丢弃 | 严格匀速,不允许突发 | 下游容量严格受限的场景 |
# Nginx 层限流(第一道,挡在应用之前)
# http 块中定义共享内存区:按客户端 IP,基准 10 请求/秒
limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;
# 按 API Key 限流,每分钟 100 次
limit_req_zone $http_x_api_key zone=perkey:10m rate=100r/m;
server {
location /api/ {
# burst=20 允许突发 20 个排队,nodelay 表示不延迟排队请求
limit_req zone=perip burst=20 nodelay;
limit_req zone=perkey burst=50 nodelay;
limit_req_status 429;
# 并发连接数限制
limit_conn_zone $binary_remote_addr zone=conn:10m;
limit_conn conn 20;
limit_conn_status 429;
proxy_pass http://api_backend;
}
# 短信/验证码这类高资损接口单独收紧
location /api/sms/send {
limit_req zone=perip burst=2 nodelay;
limit_req_status 429;
proxy_pass http://api_backend;
}
}
nginx -t && systemctl reload nginx
# 应用层:Redis + 令牌桶(需要按用户/接口精细控制时使用)
# KEYS[1]=桶key ARGV[1]=桶容量 ARGV[2]=令牌生成速率(个/秒) ARGV[3]=当前时间戳(秒) ARGV[4]=本次消耗
local capacity = tonumber(ARGV[1])
local rate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local cost = tonumber(ARGV[4])
local bucket = redis.call('HMGET', KEYS[1], 'tokens', 'ts')
local tokens = tonumber(bucket[1])
local ts = tonumber(bucket[2])
if tokens == nil then
tokens = capacity
ts = now
end
-- 先按时间差补充令牌,最多补到桶容量
tokens = math.min(capacity, tokens + (now - ts) * rate)
if tokens < cost then
redis.call('HMSET', KEYS[1], 'tokens', tokens, 'ts', now)
redis.call('EXPIRE', KEYS[1], 3600)
return {0, 0} -- 拒绝
end
tokens = tokens - cost
redis.call('HMSET', KEYS[1], 'tokens', tokens, 'ts', now)
redis.call('EXPIRE', KEYS[1], 3600)
return {1, math.floor(tokens)} -- 放行,返回剩余令牌
限流响应必须规范化:返回 429 Too Many Requests,并带 Retry-After 响应头,告诉客户端多久后重试。同时限流维度要叠加——只按 IP 限,会被分布式的来源绕过;只按 Key 限,无法防止单个 Key 被泄露后滥用。推荐 IP + Key + 接口三级叠加。
六、密钥与证书管理
# 生成 RSA 密钥对(JWT RS256 签名用,推荐 RS256 而非 HS256,便于密钥分离) openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out jwtRS256.key openssl rsa -in jwtRS256.key -pubout -out jwtRS256.key.pub # 生成 ECDSA 密钥对(更短、更快,P-256) openssl ecparam -genkey -name prime256v1 -noout -out ec256.key openssl ec -in ec256.key -pubout -out ec256.pub # 自建 CA 与服务端证书(用于内部服务 mTLS) openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt \ -days 3650 -subj "/CN=Internal-CA/O=Example" openssl req -newkey rsa:2048 -nodes -keyout server.key -out server.csr \ -subj "/CN=api.internal" openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \ -out server.crt -days 825 -sha256 # 检查证书有效期 openssl x509 -in server.crt -noout -dates -subject -issuer # 用 KMS / 密码库托管时的等价命令(以本地生成后导入为例) openssl rand -base64 32 | tr -d '\n' > master.key chmod 600 master.key
6.1 密钥管理规范
- 绝不硬编码:密钥放在密钥管理服务(云 KMS、Vault)或受控的环境变量中,不进代码仓库。CI 中加密钥扫描卡点。
- 一应用一密钥:不同对接方、不同环境使用不同的 Key,泄露时影响面可控,吊销也精准。
- 定期轮换:API Key 建议 90 天轮换一次,签名密钥 180 天,TLS 证书按有效期自动续签。
- 双密钥平滑过渡:轮换期间新旧密钥同时有效(如 7 天),给对接方留出切换窗口,到期后下线旧密钥。
- 最小权限 scope:Key 只授予必需的接口范围与读写权限,只读对接方不给写权限。
- 监控异常使用:对 Key 的调用频率、来源 IP、失败率设基线,异常时自动告警并支持一键吊销。
- 传输层强制 HTTPS:配置 HSTS,内部服务间也用 TLS,避免凭据在链路上明文。
七、日志、告警与审计
API 的日志是事后追溯的唯一依据,但绝不能记录密钥、令牌、完整请求体中的敏感字段。
# 推荐的 API 访问日志字段
# request_id、时间戳、来源 IP、User-Agent、key_id(不是密钥本身)、
# user_id、method、path、状态码、耗时、限流是否触发、签名校验结果
# 脱敏示例(Python 伪代码)
SENSITIVE = {'password', 'token', 'api_key', 'id_card', 'phone', 'cvv'}
def mask(obj):
if isinstance(obj, dict):
return {k: ('***' if k.lower() in SENSITIVE else mask(v)) for k, v in obj.items()}
if isinstance(obj, list):
return [mask(x) for x in obj]
return obj
# 告警规则示例
# 1. 单个 key_id 5 分钟内 401 次数 > 50 -> 疑似密钥枚举/泄露
# 2. 单个 IP 429 占比 > 30% -> 疑似刷接口
# 3. 某接口 P99 耗时突增 3 倍 -> 疑似被压测或攻击
# 4. 非白名单 IP 调用管理类接口 -> 立即告警
# 5. 某个 key 在 2 个地理位置间隔 1 小时出现 -> 疑似密钥泄露复制
八、上线前自检清单
- 所有接口强制 HTTPS,HTTP 请求 301 跳转到 HTTPS,配置 HSTS。
- 鉴权覆盖全部接口,不存在"漏掉某个路径"的情况(用中间件统一拦截,而不是逐接口手写)。
- 每个请求都做资源级授权校验:确认当前用户有权访问该资源 ID。
- 敏感接口启用 HMAC 签名,含时间戳与 nonce 去重。
- 令牌有效期:access ≤30 分钟,refresh 单次有效,登出走黑名单。
- 三级限流已配置(IP / Key / 接口),返回 429 带 Retry-After。
- 密钥不进代码仓库,CI 有密钥扫描卡点,服务端只存哈希。
- 日志脱敏,密钥与敏感字段不落日志。
- 响应体只返回必要字段,不返回内部对象全量序列化。
- 错误响应不暴露堆栈、SQL、内部路径等实现细节。
- 关键操作(改绑、提现、改密)有二次确认与风控审计。
- 已配置异常告警规则并做过一次模拟验证。
小结
API 防护不是加一个 token 就完事,而是五道防线的组合:鉴权确认身份、签名保证完整性、时间戳与 nonce 防重放、资源级授权防越权、分层限流防滥用。其中"资源级授权"最容易被忽略——很多团队做了登录校验就认为安全了,却没有校验"这条数据是不是你的"。
避坑清单:
- 不要把 API Key 放在 URL 参数里,它会被网关、浏览器历史和各类访问日志完整记录。
- 不要使用
==比较签名或令牌,用hmac.compare_digest做恒定时间比较。 - 不要把刷新令牌设计成可重复使用,单次有效 + 复用检测是关键。
- 不要只按 IP 限流,分布式来源会绕过;也不要只按 Key 限流,Key 泄露后无法约束。
- 不要把 JWT 有效期设成几天甚至永久,"无状态"的代价就是吊销延迟。
- 不要忽略 nonce 的 TTL,不设过期会让 Redis 无限膨胀;建议设为时间窗的 2 倍。
- 不要返回 500 或 200 来表示鉴权失败,用准确的 401(未认证)/ 403(无权限)/ 429(限流)。
- 不要在日志里打印完整请求头,
Authorization、X-Api-Key都要脱敏。 - 不要省略 HTTPS 校验的"证书验证"步骤,跳过校验的内网调用等于明文传输。
本文所有内容均为防护侧设计与配置,不涉及任何攻击、绕过或越权手法。
企业QQ咨询




