← Cloudflare R2 / r2 / api / s3

Временные учётные данные

Временные учётные данные представляют собой краткосрочные учётные данные S3 с ограниченной областью действия, производные от существующего R2 API-токен. Они проходят аутентификацию с помощью AWS Signature Version 4, как и долгоживущий токен, но включают токен сессии и истекают автоматически. Токен сессии отправляется с каждым запросом через X-Amz-Security-Token заголовок; все S3-совместимые клиенты предоставляют его как стандартное поле учётных данных для токена сессии.

Используйте временные учётные данные, чтобы делегировать доступ без выдачи долгоживущего токена. Например, предоставьте мобильному клиенту доступ на чтение к одному префиксу на 15 минут или выдавайте учётные данные для загрузки, ограниченные одним объектом, для каждого запроса.

R2 поддерживает два подхода к ограниченному по времени доступу. Они пересекаются по функциям, но имеют разные компромиссы:

Temporary Credentials API принимает родительский API-токен, имя бакета и необязательные параметры области действия, а затем возвращает новый идентификатор ключа доступа, секретный ключ доступа и токен сессии. Cloudflare подписывает токен сессии от вашего имени.

Используйте этот метод, если хотите, чтобы Cloudflare сам управлял процессом подписи.

Готовый к запуску пример см. в Аутентификация в R2 с помощью временных учётных данных.

Вы также можете локально создавать временные учётные данные, подписав JWT секретным ключом доступа родительского API-токена и использовав его в качестве токена сессии.

Используйте этот метод в следующих случаях:

• Вы выпускаете множество краткоживущих учётных данных и хотите избежать задержки API при каждой генерации.
• Вам нужно создавать учётные данные в среде, у которой нет доступа к API Cloudflare.
• Вы хотите ограничить область действия учётных данных по действиям S3 (см. Область действия по операциям), что в настоящее время поддерживается только через локальную подпись.

Подписание происходит в три этапа:

1. Сформируйте JWT-payload, который определяет бакет и область действия доступа.
2. Подпишите JWT алгоритмом HS256, используя ваш родительский секретный ключ доступа.
3. Получите временный секретный ключ доступа, вычислив хеш SHA-256 подписанного JWT в шестнадцатеричном представлении. Закодируйте токен сеанса как base64("jwt/" + <signed-jwt>).

Родительский идентификатор ключа доступа используется повторно в качестве временного идентификатора ключа доступа.

Полный рабочий пример доступен в Аутентификация в R2 с помощью временных учётных данных.

Каждые временные учётные данные привязаны к одному бакету и определённому набору разрешённых операций. При необходимости доступ можно дополнительно ограничить конкретными путями внутри бакета.

Временные учётные данные не могут превышать разрешения родительского токена.

Временные учётные данные привязаны ровно к одному бакету, указанному по имени. Доступ к нескольким бакетам в рамках одних учётных данных не поддерживается.

Укажите разрешённые операции с помощью scope (передаётся как permission к API) или actions. Необходимо указать хотя бы один.

scope представляет собой заданную категорию операций. См. Разрешения для полных определений.

actions представляет собой явный список разрешённых операций S3.

Например, actions: ["GetObject", "HeadObject"] предоставляет доступ на чтение отдельных объектов, но запрещает ListObjectsV2, хотя более широкий object-read-only область действия позволит выполнять листинг.

Допустимые действия:

Ограничьте доступ к определённым префиксам или объектам в бакете. Чтобы предоставить доступ ко всему бакету в рамках разрешённых операций, оставьте эти поля пустыми.

Temporary Credentials API: передать prefixes и objects как поля верхнего уровня в теле запроса.

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

Локальное подписание: задать paths.prefixPaths и paths.objectPaths в payload JWT.

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

• prefixes / prefixPaths: ключи, начинающиеся с любого из указанных префиксов.
• objects / objectPaths: точные ключи объектов.

Любой 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-токенам. Пока срок действия учетных данных не истек, любой, у кого есть все три значения, может выполнять разрешенные операции.

• Ограничивайте область действия максимально узко. Задайте пути и область разрешений так, чтобы учётные данные позволяли выполнять только то, что нужно вызывающей стороне.
• Используйте короткие значения TTL. Установите ttlSeconds до минимального значения, подходящего для вашего сценария использования. Учётные данные со сроком действия 15 минут представляют меньший риск в случае утечки, чем те, что действуют сутки.
• Временные учётные данные не могут превышать уровень родительских учётных данных. Если вы отзовёте родительский API-токен, все временные учётные данные, созданные на его основе, немедленно перестанут работать.
• Никогда не передавайте родительский секретный ключ доступа клиенту. Локальное подписание должно выполняться в доверенной среде (например, на вашем бэкенде или в Worker).