INTEGRITY Dokumentace

← Cloudflare R2 / r2 / examples

Ověřování vůči R2 pomocí dočasných přihlašovacích údajů

Následující příklady ukazují, jak vygenerovat R2 dočasné přihlašovací údaje pomocí Temporary Credentials API i lokálního podepisování na straně klienta, a jak výsledné přihlašovací údaje použít s klientem S3.

Předpoklady

Generování přes Temporary Credentials API

Zavolejte Temporary Credentials API z důvěryhodného serveru a poté použijte vrácené přihlašovací údaje s libovolným klientem S3.

curl https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/r2/temp-access-credentials \
  --header "Authorization: Bearer <PARENT_API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "bucket": "my-bucket",
    "parentAccessKeyId": "<PARENT_ACCESS_KEY_ID>",
    "permission": "object-read-only",
    "ttlSeconds": 900,
    "objects": ["reports/2026-q1.pdf"]
  }'

Odpověď zabaluje přihlašovací údaje do result objekt:

{
  "result": {
    "accessKeyId": "<accessKeyId>",
    "secretAccessKey": "<secretAccessKey>",
    "sessionToken": "<sessionToken>"
  },
  "errors": [],
  "messages": [],
  "success": true
}

Generování lokálně (podepisování na straně klienta)

Tento příklad používá jose ↗ k podepsání JWT a aws4fetch ↗ k vytváření podepsaných požadavků.

npm i jose aws4fetch

Následující pomocná funkce podepíše JWT vaším nadřazeným tajným přístupovým klíčem a odvodí dočasný tajný přístupový klíč a token relace:

temp-credentials.ts
import { SignJWT } from "jose";

type R2Scope =
  | "object-read-only"
  | "object-read-write"
  | "admin-read-only"
  | "admin-read-write";

export interface TempCredentialOptions {
  scope: R2Scope;
  // Optional: narrow the credential to specific S3 operations.
  actions?: string[];
  // Time-to-live in seconds. Defaults to 1 hour.
  ttlSeconds?: number;
  // Optional: restrict access to specific prefixes or objects.
  paths?: { prefixPaths?: string[]; objectPaths?: string[] };
}

export async function createTempCredentials(
  endpoint: string,
  accountId: string,
  parentAccessKeyId: string,
  parentSecretAccessKey: string,
  bucket: string,
  opts: TempCredentialOptions,
): Promise<{
  accessKeyId: string;
  secretAccessKey: string;
  sessionToken: string;
}> {
  const ttl = opts.ttlSeconds ?? 3600;

  const claims: Record<string, unknown> = {
    bucket,
    scope: opts.scope,
  };

  if (opts.actions !== undefined && opts.actions.length > 0) {
    claims.actions = opts.actions;
  }

  if (opts.paths !== undefined) {
    claims.paths = {
      prefixPaths: opts.paths.prefixPaths ?? [],
      objectPaths: opts.paths.objectPaths ?? [],
    };
  }

  // Sign the JWT with the parent secret access key. R2 validates this signature.
  const jwt = await new SignJWT(claims)
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setSubject(accountId)
    .setIssuer(parentAccessKeyId)
    .setAudience(new URL(endpoint).host)
    .setIssuedAt()
    .setExpirationTime(`${ttl}s`)
    .sign(new TextEncoder().encode(parentSecretAccessKey));

  // The temporary secret access key is the SHA-256 hex digest of the signed JWT.
  const digest = await crypto.subtle.digest(
    "SHA-256",
    new TextEncoder().encode(jwt),
  );
  const secretAccessKey = Array.from(new Uint8Array(digest))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");

  return {
    // Reuse the parent access key ID as the temporary access key ID.
    accessKeyId: parentAccessKeyId,
    secretAccessKey,
    // The session token is base64("jwt/" + signed JWT).
    sessionToken: btoa(`jwt/${jwt}`),
  };
}

Následující příklad vrací přihlašovací údaj platný po dobu 15 minut, který může pouze GetObject a HeadObject v části data/ prefix:

import { createTempCredentials } from "./temp-credentials";

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

const creds = await createTempCredentials(
  R2_URL,
  ACCOUNT_ID,
  PARENT_ACCESS_KEY_ID,
  PARENT_SECRET_ACCESS_KEY,
  "my-bucket",
  {
    scope: "object-read-only",
    actions: ["GetObject", "HeadObject"],
    ttlSeconds: 900,
    paths: { prefixPaths: ["data/"] },
  },
);

Použijte přihlašovací údaje

Jakmile máte dočasné přihlašovací údaje, použití je stejné bez ohledu na to, jak byly vygenerovány. Předejte tyto tři hodnoty svému S3 klientovi a odešlete požadavky. Následující příklad používá přihlašovací údaje omezené na data/ prefix pro demonstraci jednoho povoleného a jednoho zamítnutého požadavku:

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",
});

// Allowed: object under the data/ prefix.
const ok = await client.fetch(`${R2_URL}/my-bucket/data/file.bin`);
console.log(ok.status); // 200

// Rejected with 403 AccessDenied because the object is outside the data/ prefix.
const denied = await client.fetch(`${R2_URL}/my-bucket/other/file.bin`);
console.log(denied.status); // 403