预签名URL 是把私有对象临时开放给浏览器下载、给客户端直传的常用手段,但它同时也是对象存储里最容易被做成越权入口的一环:签发时用的是管理员凭证、有效期给了七天、对象 key 直接取自 URL 参数、签完的链接又原样写进了访问日志。本文以 MinIO 为例,讲清预签名URL 的权限来源、四类典型越权路径,并给出最小权限策略、签发代码与逐条验证命令。
适用场景
以下业务形态几乎一定会用到预签名URL,也正是需要重点设防的地方:
- 图片站、下载站的私有对象不对外公开,但需要让已登录用户通过浏览器直接下载,不经过应用服务器中转;
- Web 端或 App 端直传文件到对象存储,应用只负责签发上传凭证,避免大文件占用应用带宽;
- 后台管理系统需要生成一次性分享链接,链接带过期时间与下载次数限制;
- 已有用户反馈「别人的订单附件被另一个账号下到了」,说明签发环节缺少对象归属校验;
- 安全审计要求所有临时访问凭证可追溯,需要知道谁在什么时间签发过哪个对象的链接。
前置条件
- MinIO 服务端版本不低于 RELEASE.2023-01-01,
mc客户端不低于 RELEASE.2023-01-01,低版本mc admin policy create子命令名称不一致; - 拥有
mc管理员别名,可执行mc admin user与mc admin policy; - 应用侧使用 boto3 1.28 以上,且显式指定
signature_version="s3v4",SigV4 是唯一支持过期时间的签名版本; - 桶策略为私有(无匿名
GetObject授权),否则预签名机制形同虚设; - 应用服务器与应用日志所在分区已开启访问日志留存,便于事后追溯签发记录。
原理说明
预签名URL 本质是一条带签名参数的普通 GET 或 PUT 请求。签名过程把请求方法、对象路径、过期时间(X-Amz-Expires)、参与签名的请求头(X-Amz-SignedHeaders)一起做 HMAC 计算,结果写进 X-Amz-Signature。服务端收到请求后用自己的密钥重算一遍,任何一项被改动都会导致签名不匹配。因此攻击者无法通过修改 URL 里的对象路径去读别的文件——这条路在签名层面就被封死了。
真正的风险不在篡改,而在签发的瞬间。预签名URL 的权限上限等于签发者凭证的权限上限:如果签发用的是 s3:* 的管理员账号,那么每一次签发都是把管理员能力切一小块递出去;如果对象 key 由前端传入而服务端不校验归属,攻击者只要把 order_id 换成别人的,服务端就会老老实实为别人的文件签出一条合法链接。前者是权限过大,后者是越权访问,两者叠加就形成了完整的横向读取链路。
此外还有两个常被忽略的暴露面。一是链接本身的流动性:预签名URL 会出现在浏览器历史、Referer 头、Nginx 访问日志、客服工单截图里,一旦泄露,在有效期内任何人拿到都能用,服务端无法区分「原用户」和「转发者」。二是过期时间的上限:SigV4 的 X-Amz-Expires 最大值为 604800 秒(7 天),超过会被服务端直接拒绝签名,而很多实现为了「用户体验」直接顶到上限,等于把临时凭证变成了周卡。
操作步骤
第一步:建立专用签发账号与最小权限策略
不要用管理员凭证签发。新建一个只具备「读指定前缀」能力的账号,把权限收敛到业务真正需要的范围:
# 写入签发专用策略:只允许读 uploads/ 与 orders/ 两个前缀
cat > app-signer-policy.json <<'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetObject"],
"Resource": [
"arn:aws:s3:::private-bucket/uploads/*",
"arn:aws:s3:::private-bucket/orders/*"
]
}
]
}
EOF
# 创建策略与账号,并完成绑定
mc admin policy create myminio app-signer-policy ./app-signer-policy.json
mc admin user add myminio app-signer 'R3place-With-Strong-Pass!'
mc admin policy attach myminio app-signer-policy --user app-signer
mc admin user info myminio app-signer
# 确认桶本身不对外匿名开放
mc anonymous get myminio/private-bucket
mc anonymous get 若返回 private 以外的内容,说明桶存在匿名读策略,必须先改回私有,否则预签名签得再严也没有意义。策略里的 Resource 一定要写到前缀粒度,写成 arn:aws:s3:::private-bucket/* 等于把整桶读权限交给签发账号。
第二步:服务端签发,key 必须过白名单
对象 key 绝不能直接透传前端参数。../、编码后的 %2e%2e%2f、以及不带用户维度前缀的裸文件名,都是常见越权手法。签发前用正则把 key 收敛到「固定前缀 + 32 位十六进制文件名 + 白名单后缀」:
# presign.py
import re
import boto3
from botocore.config import Config
ALLOWED_KEY = re.compile(r"^(uploads|orders)/\d{4}/[0-9a-f]{32}\.(jpg|png|webp|pdf)$")
s3 = boto3.client(
"s3",
endpoint_url="http://127.0.0.1:9000",
aws_access_key_id="app-signer",
aws_secret_access_key="R3place-With-Strong-Pass!",
config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
region_name="us-east-1",
)
def presign_download(bucket: str, key: str, ttl: int = 300) -> str:
if not ALLOWED_KEY.match(key):
raise ValueError(f"key rejected: {key}")
if not 60 <= ttl <= 900:
raise ValueError("ttl must be within 60-900 seconds")
return s3.generate_presigned_url(
"get_object",
Params={
"Bucket": bucket,
"Key": key,
"ResponseContentDisposition": "attachment",
},
ExpiresIn=ttl,
)
if __name__ == "__main__":
print(presign_download("private-bucket", "uploads/2026/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.jpg"))
三个约束同时生效才有意义:ttl 上限 900 秒限制泄露后的可用窗口,key 正则阻断路径穿越与任意对象选取,ResponseContentDisposition 让浏览器强制下载而不是内联渲染,避免对象里的 HTML 或 SVG 在站点域名下被当作页面执行。
第三步:给直传场景加内容约束
上传用的预签名URL 风险更高,因为它写的是数据。签发时必须把 Content-Type 与内容长度纳入签名,并配合桶策略里的 s3:PutObject + 前缀限制:
# upload_sign.py
import boto3
from botocore.config import Config
s3 = boto3.client(
"s3",
endpoint_url="http://127.0.0.1:9000",
aws_access_key_id="app-uploader",
aws_secret_access_key="An0ther-Strong-Pass!",
config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
region_name="us-east-1",
)
def presign_upload(key: str, content_type: str, ttl: int = 300) -> dict:
if content_type not in ("image/jpeg", "image/png", "image/webp"):
raise ValueError("content type not allowed")
url = s3.generate_presigned_url(
"put_object",
Params={"Bucket": "upload-bucket", "Key": key, "ContentType": content_type},
ExpiresIn=ttl,
)
return {"url": url, "headers": {"Content-Type": content_type}}
# 客户端必须原样带上返回的 Content-Type,否则签名不匹配
ContentType 进入 SignedHeaders 后,攻击者就无法把一张 JPEG 的签名挪去上传 HTML。这一步经常被省略,结果直传桶里堆满 .html 与 .svg,再配合一个错误的 Content-Type: text/html 就变成存储型 XSS 的落地点。同时桶策略需单独限制可写前缀,例如只允许写入 upload-bucket/incoming/*,禁止覆盖已归档对象。
第四步:用 mc 快速核对签发结果
排查线上问题时,先用 mc share 生成一条对照链接,确认服务端时间与时区正确,再比对应用签出的链接参数:
# 生成一条 1 小时有效的临时下载链接(仅用于排查,不要用于生产签发)
mc share download --expire 1h myminio/private-bucket/uploads/2026/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.jpg
# 把链接里的签名参数拆开看,重点核对 Expires 与 SignedHeaders
echo "$URL" | tr '&' '\n' | grep -E 'X-Amz-(Algorithm|Credential|Date|Expires|SignedHeaders|Signature)'
# 查看服务端时间,客户端与服务端偏差超过 15 分钟会直接签名失败
mc admin info myminio | grep -i time
date -u
配置验证
四条用例覆盖「能读、不能多读、不能续期、不能复用」四类判断,逐条执行并比对返回码:
URL='http://127.0.0.1:9000/private-bucket/uploads/2026/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.jpg?X-Amz-Algorithm=...'
# 1. 原始链接,期望 200
curl -s -o /dev/null -w "valid:%{http_code}\n" "$URL"
# 2. 篡改对象路径,期望 403 SignatureDoesNotMatch
TAMPER=$(echo "$URL" | sed 's/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/ffffffffffffffffffffffffffffffff/')
curl -s "$TAMPER" | head -c 200; echo
# 3. 把过期时间改成 7 天,期望 403 而非延长成功
LONGER=$(echo "$URL" | sed 's/X-Amz-Expires=[0-9]*/X-Amz-Expires=604800/')
curl -s "$LONGER" | head -c 200; echo
# 4. 越权读取别的前缀,期望 403 AccessDenied
curl -s -o /dev/null -w "cross-prefix:%{http_code}\n" \
"http://127.0.0.1:9000/private-bucket/secret/config.json"
# 5. 过期后再访问,期望 403 Request has expired
sleep 310 && curl -s -o /dev/null -w "expired:%{http_code}\n" "$URL"
第 2、3 条返回 SignatureDoesNotMatch 说明签名覆盖了路径与过期时间,符合预期;如果第 3 条返回 200,说明服务端把 X-Amz-Expires 当成了参考值而没有纳入验签,这种实现必须升级。第 4 条是对签发账号权限的复核,403 才正确,201 或 200 都意味着策略写得过宽。
签发记录也要留痕。应用侧至少记录 request_id、操作者 ID、对象 key、有效期、客户端 IP 五个字段,日志里不要落完整 URL——链接本身就是凭证,落盘等于二次泄露:
# 只记录签名指纹,不记录完整链接
import hashlib
def log_issue(uid, key, ttl, url, ip):
fp = hashlib.sha256(url.encode()).hexdigest()[:16]
logger.info(
"presign issue uid=%s key=%s ttl=%s fp=%s ip=%s", uid, key, ttl, fp, ip
)
# 事故排查时按指纹反查,避免日志中出现可直接使用的链接
grep 'presign issue' /var/log/app/presign.log | awk '{print $4, $5, $6}'
常见问题
预签名URL 会不会泄露 AccessKey 和 SecretKey?
链接里会带 X-Amz-Credential,其中包含 AccessKey 标识,但不包含 SecretKey,签名本身无法反推出密钥。风险不在密钥泄露,而在能力泄露:在有效期内,任何拿到链接的人都拥有该链接对应的那一次读写能力,且服务端无法区分原始用户与转发者。因此不要把预签名URL 当成身份凭证使用,也不要为了省事把有效期设成几天。
有效期最长能设多久,为什么建议 5 到 15 分钟?
SigV4 的硬上限是 604800 秒(7 天),超过这个值服务端直接拒绝。业务上建议 300 到 900 秒:一是缩短泄露窗口,二是让「链接被转发到群里」这类事件自然失效,三是配合下载次数限制时更容易统计。确需长时间访问的场景,应改为每次访问时由应用重新签发,而不是签一条长效链接。
预签名URL 放在 CDN 后面还能用吗?
能用,但有两个前提。一是 CDN 回源必须完整保留 query string,任何丢弃或重排查询参数的配置都会导致签名失效;二是私有内容不要走公共缓存,否则首次成功响应会被缓存下来,后续不带签名的请求也能命中缓存拿到文件。正确做法是给私有对象单独配置一条不缓存的回源规则,或在缓存键中加入签名参数并设置极短 TTL。
总结
预签名URL 的安全模型可以用一句话概括:签名保护传输,策略保护边界,代码保护归属。签名机制保证链接不可篡改,桶策略与账号权限决定这条链接最多能碰到什么,而服务端的 key 白名单与归属校验决定它到底该碰什么。三者里最容易失守的是第三个——因为前两个有服务端兜底,第三个只能靠业务代码自己守住。落地时按「专用低权账号 → 前缀白名单 → 短有效期 → 签发留痕 → 定期审计策略」的顺序推进,一次改完一个环节,比一次性重写签发逻辑更可控。