临时凭据

临时凭据是从现有 R2 API 令牌派生的短期、范围限定的 S3 凭据。它们使用 AWS Signature Version 4 进行身份验证，与长期令牌相同，但包含会话令牌并自动过期。会话令牌通过 X-Amz-Security-Token 请求头随每个请求发送；所有 S3 兼容客户端将其作为标准会话令牌凭据字段公开。

使用临时凭据可在不签发长期令牌的情况下委派访问。例如，授予移动客户端对单个前缀 15 分钟的读取访问，或签发范围限定于单个对象的上传凭据。

R2 支持两种限时访问模式。它们有重叠，但权衡不同：

Temporary Credentials API 接受父 API 令牌、存储桶名称和可选的范围参数，返回新的 access key ID、secret access key 和 session token。Cloudflare 代表您签署会话令牌。

当您希望 Cloudflare 管理签名流程时使用此方法。

可运行的演练请参阅 使用临时凭据对 R2 进行身份验证。

您也可以在本地生成临时凭据，使用父 API 令牌的 secret access key 签署 JWT 并将其用作 session token。

在以下情况下使用此方法：

• 您需要签发大量短期凭据，希望避免每次 mint 的 API 延迟。
• 您需要在无法访问 Cloudflare API 的环境中 mint 凭据。
• 您需要按 S3 操作限定凭据范围（请参阅按操作限定范围），目前仅支持本地签名。

签名分三步进行：

1. 构建标识存储桶和访问范围的 JWT payload。
2. 使用父 secret access key 以 HS256 签署 JWT。
3. 通过取已签署 JWT 的 SHA-256 十六进制摘要派生临时 secret access key。将 session token 编码为 base64("jwt/" + <signed-jwt>)。

父 access key ID 复用作临时 access key ID。

完整可运行示例请参阅 使用临时凭据对 R2 进行身份验证。

每个临时凭据绑定到单个存储桶和一组允许的操作。您可进一步将凭据限制为存储桶内的特定路径。

临时凭据不能超过其父令牌的权限。

临时凭据精确绑定到一个存储桶，通过名称标识。单个凭据不支持跨存储桶访问。

使用 scope（作为 permission 传递给 API）或 actions 指定允许的操作。必须至少提供一项。

scope 是操作的预设类别。完整定义请参阅权限。

actions 是允许的 S3 操作的显式列表。

例如，actions: ["GetObject", "HeadObject"] 授予单个对象的读取权限，但拒绝 ListObjectsV2，尽管更广泛的 object-read-only scope 允许列出。

有效 actions：

将访问限制为存储桶内的特定前缀或对象。省略这些字段可在允许的操作范围内授予对整个存储桶的访问。

Temporary Credentials API： 在请求体顶层传递 prefixes 和 objects。

{
  "prefixes": ["uploads/user-123/"],
  "objects": ["shared/manifest.json"]
}

本地签名： 在 JWT payload 上设置 paths.prefixPaths 和 paths.objectPaths。

{
  "paths": {
    "prefixPaths": ["uploads/user-123/"],
    "objectPaths": ["shared/manifest.json"]
  }
}

• prefixes / prefixPaths：以任一列出前缀开头的键。
• objects / objectPaths：精确的对象键。

任何支持 session token 的 S3 兼容客户端都接受 R2 临时凭据。使用客户端的标准凭据字段传递全部三个值（access key ID、secret access key、session token）。

import { AwsClient } from "aws4fetch";

const R2_URL = `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`;

const client = new AwsClient({
	accessKeyId: ACCESS_KEY_ID,
	secretAccessKey: SECRET_ACCESS_KEY,
	sessionToken: SESSION_TOKEN,
	service: "s3",
});

const response = await client.fetch(`${R2_URL}/my-bucket/image.png`);

import boto3

s3 = boto3.client(
    service_name="s3",
    endpoint_url="https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
    aws_access_key_id="<ACCESS_KEY_ID>",
    aws_secret_access_key="<SECRET_ACCESS_KEY>",
    aws_session_token="<SESSION_TOKEN>",
    region_name="auto",
)

AWS_ACCESS_KEY_ID=<ACCESS_KEY_ID>
AWS_SECRET_ACCESS_KEY=<SECRET_ACCESS_KEY>
AWS_SESSION_TOKEN=<SESSION_TOKEN>

将临时凭据视为 bearer token。任何拥有全部三个值的人可在凭据过期前执行允许的操作。

• 尽可能缩小范围。 设置路径和权限 scope，使凭据只能执行调用方需要的操作。
• 使用短 TTL。 将 ttlSeconds 设为适合用例的最短值。存活 15 分钟的凭据比存活一天的爆炸半径更小。
• 临时凭据不能超过其父令牌。 若撤销父 API 令牌，从中派生的所有临时凭据立即停止工作。
• 切勿将父 secret access key 发送到客户端。 本地签名必须在受信任的环境（例如后端或 Worker）中进行。