服务器API接口如何防护?访问鉴权、限流与密钥管理方法

网站有页面,攻击面看得见;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 签名设计的四个要点

  1. 待签串必须包含 body 的哈希,否则请求体可以被随意替换而签名仍有效。
  2. 必须包含完整路径,避免签名被挪用到其他接口。
  3. 时间窗与 nonce 缺一不可:只有时间窗,窗口内的重放挡不住;只有 nonce,存储会无限增长。
  4. 用 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 密钥管理规范

  1. 绝不硬编码:密钥放在密钥管理服务(云 KMS、Vault)或受控的环境变量中,不进代码仓库。CI 中加密钥扫描卡点。
  2. 一应用一密钥:不同对接方、不同环境使用不同的 Key,泄露时影响面可控,吊销也精准。
  3. 定期轮换:API Key 建议 90 天轮换一次,签名密钥 180 天,TLS 证书按有效期自动续签。
  4. 双密钥平滑过渡:轮换期间新旧密钥同时有效(如 7 天),给对接方留出切换窗口,到期后下线旧密钥。
  5. 最小权限 scope:Key 只授予必需的接口范围与读写权限,只读对接方不给写权限。
  6. 监控异常使用:对 Key 的调用频率、来源 IP、失败率设基线,异常时自动告警并支持一键吊销。
  7. 传输层强制 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 小时出现 -> 疑似密钥泄露复制

八、上线前自检清单

  1. 所有接口强制 HTTPS,HTTP 请求 301 跳转到 HTTPS,配置 HSTS。
  2. 鉴权覆盖全部接口,不存在"漏掉某个路径"的情况(用中间件统一拦截,而不是逐接口手写)。
  3. 每个请求都做资源级授权校验:确认当前用户有权访问该资源 ID。
  4. 敏感接口启用 HMAC 签名,含时间戳与 nonce 去重。
  5. 令牌有效期:access ≤30 分钟,refresh 单次有效,登出走黑名单。
  6. 三级限流已配置(IP / Key / 接口),返回 429 带 Retry-After。
  7. 密钥不进代码仓库,CI 有密钥扫描卡点,服务端只存哈希。
  8. 日志脱敏,密钥与敏感字段不落日志。
  9. 响应体只返回必要字段,不返回内部对象全量序列化。
  10. 错误响应不暴露堆栈、SQL、内部路径等实现细节。
  11. 关键操作(改绑、提现、改密)有二次确认与风控审计。
  12. 已配置异常告警规则并做过一次模拟验证。

小结

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 校验的"证书验证"步骤,跳过校验的内网调用等于明文传输。

本文所有内容均为防护侧设计与配置,不涉及任何攻击、绕过或越权手法。