Presigned URL в S3: что это, как они работают, лимиты срока действия и примеры кода

Presigned URL в S3 это временная ссылка на один объект в приватном bucket. В строке запроса у неё есть подпись, поэтому её владелец может скачать (или загрузить) этот объект без учётных данных AWS, пока ссылка не истечёт, а bucket при этом никогда не становится публичным. Вы создаёте её своими ключами, в коде или через AWS CLI, и она может действовать от 1 секунды до 7 дней. В этом руководстве разобрано, как она работает, что означает каждый параметр X-Amz-*, сколько она может действовать, код для скачивания и загрузки и ошибки, с которыми вы вероятнее всего столкнётесь. Лимиты взяты из документации AWS и Cloudflare на октябрь 2026 года.

Presigned URL в S3 вкратце

Как работает presigned URL

1. Ваш код (или CLI) берёт bucket, ключ объекта, HTTP-метод и срок действия.
2. SDK подписывает эти значения вашим secret access key с помощью AWS Signature Version 4. На этом этапе в S3 ничего не отправляется.
3. Вы передаёте полученный URL кому-то: браузеру, коллеге, мобильному приложению.
4. Когда им пользуются, S3 заново вычисляет подпись с secret, принадлежащим ключу доступа из URL. Если подпись совпадает, срок URL не истёк и подписавшему разрешена эта операция, запрос выполняется.

URL несёт права того, кто его подписал. AWS прямо об этом говорит: если пользователь или роль IAM, создавшие URL, не могут читать объект, URL вернёт 403, какой бы действительной ни была подпись.

Что означают параметры X-Amz

Presigned URL с SigV4 выглядит так (переносы строк добавлены):

https://my-bucket.s3.eu-west-1.amazonaws.com/reports/q3.pdf
  ?X-Amz-Algorithm=AWS4-HMAC-SHA256
  &X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20261017%2Feu-west-1%2Fs3%2Faws4_request
  &X-Amz-Date=20261017T093000Z
  &X-Amz-Expires=3600
  &X-Amz-SignedHeaders=host
  &X-Amz-Signature=5f2c...e91a

Измените любую подписанную часть (ключ, метод, срок или подписанный заголовок), и подпись перестанет совпадать. Обратите внимание и на то, что URL раскрывает открытым текстом: имя bucket, полный ключ объекта и ID вашего ключа доступа. Секретного ключа в URL никогда нет.

Сколько действует presigned URL

Лимит зависит от учётных данных, которыми он подписан:

Это объясняет самый частый сюрприз: вы просите 7 дней из функции Lambda или инстанса EC2, а ссылка умирает через час или несколько часов. URL живёт ровно столько, сколько стоящие за ним учётные данные. Если нужны долгие ссылки, подписывайте их отдельным пользователем IAM, у которого есть доступ на чтение только к этому bucket.

S3 проверяет срок в момент начала запроса. Большое скачивание, начатое за секунду до крайнего срока, завершится нормально, но повторная попытка после него завершится ошибкой AccessDenied с сообщением «Request has expired». Запрос больше 604 800 секунд сразу отклоняется.

Как создать presigned URL

AWS CLI

aws s3 presign s3://my-bucket/reports/q3.pdf --expires-in 3600

Команда подписывает URL для скачивания (GET). По умолчанию 3 600 секунд, максимум 604 800. Свежие версии CLI всегда используют SigV4, поэтому убедитесь, что регион настроен. Для URL загрузки нужен SDK.

Python (boto3)

import boto3
from botocore.config import Config

s3 = boto3.client('s3', region_name='eu-west-1', config=Config(signature_version='s3v4'))

url = s3.generate_presigned_url(
    ClientMethod='get_object',
    Params={
        'Bucket': 'my-bucket',
        'Key': 'reports/q3.pdf',
        'ResponseContentDisposition': 'attachment; filename="q3.pdf"',
    },
    ExpiresIn=3600,
)

Укажите signature_version='s3v4' явно. Справочник boto3 предупреждает, что ради обратной совместимости иначе он может подписывать устаревшей Signature Version 2 в регионах, которые её ещё принимают, а она молча отбрасывает некоторые параметры и заголовки, например Range. ResponseContentDisposition необязателен: он заставляет браузер сохранить файл с аккуратным именем, а не открывать его во вкладке.

JavaScript (AWS SDK v3)

import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3'
import { getSignedUrl } from '@aws-sdk/s3-request-presigner'

const client = new S3Client({ region: 'eu-west-1' })

const url = await getSignedUrl(
  client,
  new GetObjectCommand({ Bucket: 'my-bucket', Key: 'reports/q3.pdf' }),
  { expiresIn: 3600 }
)

Если не указать expiresIn, presigner для JavaScript использует 900 секунд (15 минут).

Presigned URL для загрузки (PUT)

Та же идея работает и в обратную сторону. Вы подписываете PutObject для одного ключа, и владелец URL может записать этот объект. Файл идёт прямо с его устройства в bucket, а ваш сервер никогда не обрабатывает байты. Если объект с таким ключом уже существует, он заменяется.

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
import { getSignedUrl } from '@aws-sdk/s3-request-presigner'

const client = new S3Client({ region: 'eu-west-1' })

const url = await getSignedUrl(
  client,
  new PutObjectCommand({
    Bucket: 'my-bucket',
    Key: 'incoming/brief.pdf',
    ContentType: 'application/pdf',
  }),
  { expiresIn: 900, signableHeaders: new Set(['content-type']) }
)

await fetch(url, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/pdf' },
  body: file,
})

Добавление content-type в signableHeaders привязывает URL к этому типу, поэтому загрузка с другим Content-Type отклоняется. В boto3 аналог это generate_presigned_url('put_object', Params={'Bucket': ..., 'Key': ..., 'ContentType': 'application/pdf'}), и клиент должен отправить тот же заголовок.

Три вещи, которые стоит проверить перед загрузкой из браузера:

• CORS. В bucket нужно правило CORS, разрешающее ваш источник и метод PUT. Для загрузок multipart оно также должно открывать заголовок ETag, потому что браузеру нужно прочитать его из каждой части.
• Фиксированный ключ. Генерируйте уникальный ключ на сервере (например, с префиксом UUID), чтобы посетитель не мог перезаписать чужой файл.
• Контрольные суммы. Современные AWS SDK по умолчанию добавляют к загрузкам контрольную сумму CRC. Если presigned-загрузки к S3-совместимому провайдеру падают с ошибками подписи или контрольной суммы, задайте в клиенте requestChecksumCalculation: 'WHEN_REQUIRED'.

Presigned POST это отдельный механизм для обычных HTML-форм с политикой, которая может ограничивать размер и тип содержимого. Его поддерживают не все S3-совместимые провайдеры (R2 не поддерживает), поэтому presigned PUT более переносимый вариант.

Большие файлы: presigned-загрузки multipart

Одиночный PUT в S3 ограничен 5 ГБ, и AWS советует multipart примерно от 100 МБ. Multipart разбивает файл на части, до 10 000 штук, каждая от 5 МиБ до 5 ГиБ, кроме последней, и они загружаются независимо, параллельно и с повторами для каждой части. Подпись работает по частям: сервер начинает загрузку, подписывает один URL UploadPart на каждую часть, браузер отправляет каждый фрагмент и возвращает его ETag, а сервер завершает загрузку.

import {
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand,
} from '@aws-sdk/client-s3'

const { UploadId } = await client.send(
  new CreateMultipartUploadCommand({ Bucket: 'my-bucket', Key: 'video/raw.mov' })
)

const partUrl = await getSignedUrl(
  client,
  new UploadPartCommand({ Bucket: 'my-bucket', Key: 'video/raw.mov', UploadId, PartNumber: 1 }),
  { expiresIn: 3600 }
)

await client.send(
  new CompleteMultipartUploadCommand({
    Bucket: 'my-bucket',
    Key: 'video/raw.mov',
    UploadId,
    MultipartUpload: { Parts: [{ PartNumber: 1, ETag: etagFromPartResponse }] },
  })
)

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

Presigned URL в R2, B2, Spaces и Wasabi

Провайдеры, реализующие API S3 с SigV4, принимают тот же код: вы меняете только endpoint, регион и ключи. Детали различаются, поэтому сверяйтесь с документацией провайдера:

• Cloudflare R2 поддерживает presigned GET, HEAD, PUT и DELETE со сроком от 1 секунды до 7 дней. Он не поддерживает presigned POST, а presigned URL работают только на домене API S3 (<ACCOUNT_ID>.r2.cloudflarestorage.com), а не на собственных доменах. Используйте region: 'auto'.
• Backblaze B2 заявляет, что его S3-совместимый API поддерживает presigned URL, созданные через AWS CLI или SDK.
• DigitalOcean Spaces и Wasabi работают с теми же вызовами SDK, направленными на их endpoint.

Цены каждого провайдера смотрите в сравнении S3, R2, Spaces, Wasabi и B2.

Частые ошибки presigned URL и как их исправить

Корпоративные прокси, которые переписывают заголовки или строки запроса, тоже ломают подписи. Если URL работает из одной сети и не работает из другой, проверьте без прокси.

Лучшие практики безопасности

AWS называет presigned URL токенами на предъявителя и рекомендует их защищать. На практике:

• Делайте их короткими. Минуты для загрузок и чувствительных файлов, часы для обычных скачиваний. Создавайте новый, когда файл снова кому-то понадобится.
• Подписывайте узкой учётной записью. Отдельный пользователь или роль IAM, которые могут только читать (или только писать) нужный префикс, ограничивают ущерб, если ссылка утечёт.
• Добавьте ограничения в политику bucket. Условие s3:signatureAge отклоняет подписи старше заданного возраста, а aws:SourceIp ограничивает, из каких сетей ими можно пользоваться.
• Не пишите их в логи. Полные presigned URL в логах приложения, аналитике или истории чатов это рабочие учётные данные, пока не истечёт их срок.
• Учитывайте, чего у них нет. Нет пароля, счётчика скачиваний и отзыва отдельной ссылки, поэтому, если всё это нужно, поставьте перед хранилищем приложение.

Подробнее о стороне обмена, с вариантами, которые добавляют эти механизмы контроля, читайте в статье как делиться файлами S3, не делая bucket публичным.

Как Nubbo использует presigned URL

Nubbo построен на этом принципе. Когда вы загружаете файл в проводнике, сервер подписывает PUT (или, начиная со 100 МБ, загрузку multipart с тремя частями параллельно), и ваш браузер отправляет байты прямо в ваш bucket. Скачивания отдельных файлов используют presigned URL GET, действующие один час. Ваши ключи доступа хранятся в зашифрованном виде (AES-256-GCM) и используются только на сервере для подписи.

Ссылки для доступа добавляют то, чего нет у голых presigned URL: пароль, срок действия и лимит скачиваний по желанию, которые Nubbo проверяет, прежде чем выдать короткоживущий URL, а ссылку можно отключить в любой момент. ZIP-архивы с несколькими файлами собираются в вашем браузере, который скачивает каждый файл прямо из вашего bucket: Nubbo никогда не видит их содержимого. Одно честное исключение: миниатюры записываются в ваш собственный bucket в .nubbo-thumbs/. Всё работает одинаково с Amazon S3, Cloudflare R2, DigitalOcean Spaces, Wasabi, Backblaze B2 и публичными S3-совместимыми endpoint.