一時認証情報

一時認証情報は、既存の R2 API トークン から派生する、有効期限付きでスコープを限定した S3 認証情報です。長寿命トークンと同じく AWS Signature Version 4 で認証しますが、セッショントークンを含み、自動的に期限切れになります。セッショントークンは、すべてのリクエストで X-Amz-Security-Token ヘッダーとして送信します。S3 互換クライアントは、これを標準のセッショントークン認証情報フィールドとして公開しています。

長寿命トークンを発行せずに、アクセスを委譲するために一時認証情報を使います。たとえば、モバイルクライアントに単一プレフィックスへの読み取りアクセスを 15 分間だけ付与する、または 1 オブジェクトにスコープしたアップロード用の認証情報をリクエストごとに発行する、といった使い方です。

R2 は、時間制限付きアクセス向けに 2 つのパターンに対応しています。重なる部分はありますが、トレードオフが異なります。

Temporary Credentials API は、親 API トークン、バケット名、任意のスコープパラメーターを受け取り、新しいアクセスキー ID、シークレットアクセスキー、セッショントークンを返します。Cloudflare がセッショントークンを代わりに署名します。

署名フローを Cloudflare に任せたい場合に、この方法を使います。

実行可能な手順は、一時認証情報で R2 に対して認証する を参照してください。

親 API トークンのシークレットアクセスキーで JWT に署名し、それをセッショントークンとして使うことで、一時認証情報をローカルで生成することもできます。

次の場合にこの方法を使います。

• 短寿命の認証情報を大量に発行し、発行ごとの API レイテンシを避けたい
• Cloudflare API に到達できない環境で認証情報を発行する必要がある
• S3 アクション単位で認証情報をスコープしたい（アクションでスコープする を参照）。現在はローカル署名でのみ対応しています

署名は次の 3 ステップです。

1. バケットとアクセス範囲を示す JWT ペイロードを組み立てます。
2. 親のシークレットアクセスキーを使い、HS256 で JWT に署名します。
3. 署名済み JWT の SHA-256 16 進ダイジェストを取り、一時シークレットアクセスキーを導出します。セッショントークンは base64("jwt/" + <signed-jwt>) としてエンコードします。

親のアクセスキー ID は、一時アクセスキー ID として再利用します。

完全な実行可能な例は、一時認証情報で R2 に対して認証する にあります。

一時認証情報は、必ず 1 つのバケットと、許可する操作の集合に紐づきます。さらに、バケット内の特定パスに制限することもできます。

一時認証情報は、親トークンの権限を超えることはできません。

一時認証情報は、名前で識別するちょうど 1 つのバケットに紐づきます。1 つの認証情報でクロスバケットアクセスはできません。

許可する操作は、scope（API には permission として渡す）または actions で指定します。少なくとも 1 つは指定する必要があります。

scope は、操作のプリセットカテゴリです。定義の全体は 権限 を参照してください。

actions は、許可する S3 操作の明示的なリストです。

たとえば、actions: ["GetObject", "HeadObject"] は個々のオブジェクトの読み取りを許可しますが、ListObjectsV2 は拒否します。より広い object-read-only スコープであれば一覧は許可されます。

有効なアクション:

バケット内の特定プレフィックスまたはオブジェクトにアクセスを制限します。これらのフィールドを省略すると、許可する操作の範囲でバケット全体にアクセスできます。

Temporary Credentials API: リクエスト本文のトップレベルフィールドとして prefixes と objects を渡します。

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

ローカル署名: JWT ペイロードの paths.prefixPaths と paths.objectPaths を設定します。

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

• prefixes / prefixPaths: 列挙したいずれかのプレフィックスで始まるキー
• objects / objectPaths: 完全一致するオブジェクトキー

セッショントークンに対応する S3 互換クライアントであれば、R2 の一時認証情報を受け取れます。アクセスキー ID、シークレットアクセスキー、セッショントークンの 3 つの値を、クライアントの標準の認証情報フィールドに渡します。

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>

一時認証情報はベアラートークンとして扱います。3 つの値をすべて持つ人は、認証情報の期限が切れるまで、許可された操作を実行できます。

• できるだけ狭くスコープします。 パスと権限スコープを設定し、呼び出し元が必要なことだけできるようにします。
• TTL は短くします。 ttlSeconds は、用途に合う最短の値にします。15 分で失効する認証情報は、1 日生きる認証情報より影響範囲が小さくなります。
• 一時認証情報は親を超えられません。 親 API トークンを失効させると、そこから派生した一時認証情報はすべて直ちに使えなくなります。
• 親のシークレットアクセスキーをクライアントへ出荷しないでください。 ローカル署名は、信頼できる環境（バックエンドや Worker など）で行う必要があります。