← Cloudflare R2 / r2 / api / s3

Dočasné přihlašovací údaje

Dočasné přihlašovací údaje jsou krátkodobé přihlašovací údaje S3 s omezeným rozsahem, odvozené z existujícího Token R2 API. Autentizují se pomocí AWS Signature Version 4, stejně jako dlouhodobě platný token, ale navíc obsahují session token a automaticky vyprší. Session token se odesílá s každým požadavkem prostřednictvím X-Amz-Security-Token hlavička; všichni klienti kompatibilní s S3 ji vystavují jako standardní pole přihlašovacích údajů pro token relace.

Pomocí dočasných přihlašovacích údajů delegujte přístup, aniž byste museli vydávat dlouhodobý token. Můžete tak například udělit mobilnímu klientovi přístup pro čtení k jedinému prefixu na 15 minut, nebo vydávat přihlašovací údaje pro nahrávání platné jen pro jeden konkrétní požadavek a omezené na jeden objekt.

R2 podporuje dva vzory časově omezeného přístupu. Částečně se překrývají, ale mají odlišné kompromisy:

Temporary Credentials API přijímá nadřazený token API, název bucketu a volitelné parametry rozsahu a vrací nový access key ID, secret access key a session token. Cloudflare podepíše session token vaším jménem.

Tuto metodu použijte, pokud chcete, aby proces podepisování řídil Cloudflare za vás.

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

Dočasné přihlašovací údaje můžete také vygenerovat lokálně podepsáním JWT pomocí secret access key nadřazeného API tokenu a jeho použitím jako session tokenu.

Tuto metodu použijte, pokud:

• Vydáváte mnoho krátkodobých přihlašovacích údajů a chcete se vyhnout latenci API při každém vytvoření.
• Přihlašovací údaje potřebujete vytvářet v prostředí, které se nemůže připojit k Cloudflare API.
• Chcete omezit rozsah přihlašovacích údajů podle akce S3 (viz Rozsah podle akce), což je v současnosti podporováno pouze místním podepisováním.

Podepisování probíhá ve třech krocích:

1. Vytvořte payload JWT, který identifikuje bucket a rozsah přístupu.
2. Podepište JWT algoritmem HS256 pomocí svého nadřazeného secret access key.
3. Dočasný tajný přístupový klíč odvoďte jako hexadecimální otisk SHA-256 podepsaného JWT. Token relace zakódujte jako base64("jwt/" + <signed-jwt>).

ID nadřazeného přístupového klíče se znovu použije jako ID dočasného přístupového klíče.

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

Každý dočasný přihlašovací údaj je vázán na jeden bucket a sadu povolených operací. Volitelně můžete přístup dále omezit na konkrétní cesty uvnitř bucketu.

Dočasný token nemůže přesáhnout oprávnění svého nadřazeného tokenu.

Dočasný token je vázán vždy přesně na jeden bucket, identifikovaný názvem. Přístup napříč více buckety není v rámci jednoho tokenu podporován.

Zadejte povolené operace pomocí scope (předáno jako permission k API) nebo actions. Musíte zadat alespoň jeden.

scope je předdefinovaná kategorie operací. Viz Oprávnění pro úplné definice.

actions je explicitní seznam povolených operací S3.

Například actions: ["GetObject", "HeadObject"] uděluje oprávnění ke čtení jednotlivých objektů, ale odepírá ListObjectsV2, i když širší object-read-only rozsah by umožňoval výpis.

Platné akce:

Omezte přístup na konkrétní prefixy nebo objekty v bucketu. Pokud tato pole vynecháte, získáte přístup k celému bucketu, a to v rozsahu povolených operací.

Temporary Credentials API: předat prefixes a objects jako pole nejvyšší úrovně v těle požadavku.

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

Lokální podepisování: nastaveno paths.prefixPaths a paths.objectPaths na payloadu JWT.

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

• prefixes / prefixPaths: klíče začínající libovolným uvedeným prefixem.
• objects / objectPaths: přesné klíče objektů.

Jakýkoli klient kompatibilní s S3, který podporuje tokeny relace, přijme dočasné přihlašovací údaje R2. Všechny tři hodnoty (access key ID, secret access key, session token) předejte pomocí standardních polí pro přihlašovací údaje daného klienta.

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>

Dočasné přihlašovací údaje považujte za bearer tokeny. Kdokoli, kdo má všechny tři hodnoty, může provádět povolené operace, dokud platnost přihlašovacích údajů nevyprší.

• Nastavte rozsah co nejúžeji. Nastavte cesty a rozsah oprávnění tak, aby přihlašovací údaje umožňovaly pouze to, co volající potřebuje.
• Používejte krátké TTL. Nastavte ttlSeconds na nejkratší hodnotu, která vyhovuje vašemu případu použití. Přihlašovací údaj platný 15 minut představuje menší riziko než ten, který platí celý den.
• Dočasný token nemůže přesáhnout svůj nadřazený token. Pokud zrušíte nadřazený token API, všechny dočasné přihlašovací údaje z něj odvozené okamžitě přestanou fungovat.
• Nikdy neposílejte klientovi svůj nadřazený tajný přístupový klíč. Lokální podepisování musí probíhat v důvěryhodném prostředí (například na vašem backendu nebo ve Workeru).