Presigned URL w S3: czym są, jak działają, limity ważności i przykłady kodu

Presigned URL w S3, czyli podpisany adres URL, to tymczasowy link do jednego obiektu w prywatnym buckecie. W query stringu ma podpis, więc każdy, kto go posiada, może pobrać (lub przesłać) ten obiekt bez danych uwierzytelniających AWS, dopóki link nie wygaśnie, a bucket nigdy nie staje się publiczny. Tworzysz go własnymi kluczami, w kodzie lub z AWS CLI, i może być ważny od 1 sekundy do 7 dni. Ten poradnik wyjaśnia, jak to działa, co oznacza każdy parametr X-Amz-*, jak długo link może być ważny, pokazuje kod do pobierania i przesyłania oraz błędy, na które najczęściej się trafia. Limity pochodzą z dokumentacji AWS i Cloudflare według stanu na październik 2026.

Presigned URL w S3 w skrócie

Jak działa presigned URL

1. Twój kod (lub CLI) przyjmuje bucket, klucz obiektu, metodę HTTP i czas ważności.
2. SDK podpisuje te wartości twoim secret access key za pomocą AWS Signature Version 4. Na tym etapie nic nie jest wysyłane do S3.
3. Przekazujesz wynikowy URL komuś: przeglądarce, współpracownikowi, aplikacji mobilnej.
4. Gdy ktoś go użyje, S3 ponownie oblicza podpis za pomocą secret należącego do klucza dostępu zawartego w URL. Jeśli podpis się zgadza, URL nie wygasł, a podpisujący ma uprawnienia do tej operacji, żądanie zostaje wykonane.

URL niesie uprawnienia tego, kto go podpisał. AWS mówi o tym wprost: jeśli użytkownik lub rola IAM, która wygenerowała URL, nie może odczytać obiektu, URL zwraca 403 bez względu na to, jak poprawny jest podpis.

Co oznaczają parametry X-Amz

Presigned URL w SigV4 wygląda tak (z dodanymi podziałami wierszy):

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

Zmień dowolną podpisaną część (klucz, metodę, ważność lub podpisany nagłówek), a podpis przestanie się zgadzać. Zwróć też uwagę, co URL ujawnia otwartym tekstem: nazwę bucketu, pełny klucz obiektu i identyfikator twojego klucza dostępu. Klucz tajny nigdy nie trafia do URL.

Jak długo ważny jest presigned URL

Limit zależy od danych uwierzytelniających, którymi go podpisano:

To wyjaśnia najczęstsze zaskoczenie: prosisz o 7 dni z funkcji Lambda lub instancji EC2, a link przestaje działać po godzinie lub kilku godzinach. URL żyje tylko tak długo jak dane uwierzytelniające, które za nim stoją. Jeśli potrzebujesz długich linków, podpisuj je osobnym użytkownikiem IAM z dostępem do odczytu tylko tego bucketu.

S3 sprawdza ważność w chwili rozpoczęcia żądania. Duże pobieranie, które zaczyna się sekundę przed terminem, kończy się normalnie, ale ponowna próba po terminie kończy się błędem AccessDenied z komunikatem „Request has expired”. Prośba o więcej niż 604 800 sekund jest od razu odrzucana.

Jak wygenerować presigned URL

AWS CLI

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

Polecenie podpisuje URL do pobierania (GET). Domyślnie to 3600 sekund, a maksymalnie 604 800. Nowsze wersje CLI zawsze używają SigV4, więc upewnij się, że masz skonfigurowany region. Do URL przesyłania potrzebujesz 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,
)

Ustaw jawnie signature_version='s3v4'. Dokumentacja boto3 ostrzega, że ze względu na zgodność wsteczną w przeciwnym razie może podpisywać starszą Signature Version 2 w regionach, które ją jeszcze akceptują, co po cichu pomija niektóre parametry i nagłówki, takie jak Range. ResponseContentDisposition jest opcjonalny: sprawia, że przeglądarka zapisuje plik pod czystą nazwą, zamiast otwierać go w oknie.

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 }
)

Jeśli pominiesz expiresIn, presigner JavaScript użyje 900 sekund (15 minut).

Presigned URL do przesyłania (PUT)

Ten sam pomysł działa w drugą stronę. Podpisujesz PutObject dla jednego klucza, a każdy, kto ma URL, może zapisać ten obiekt. Plik trafia prosto z jego urządzenia do bucketu, a twój serwer nigdy nie obsługuje tych bajtów. Jeśli obiekt o tym kluczu już istnieje, zostaje zastąpiony.

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

Dodanie content-type do signableHeaders wiąże URL z tym typem, więc przesłanie z innym Content-Type zostanie odrzucone. W boto3 odpowiednikiem jest generate_presigned_url('put_object', Params={'Bucket': ..., 'Key': ..., 'ContentType': 'application/pdf'}), a przesyłający musi wysłać ten sam nagłówek.

Trzy rzeczy do sprawdzenia przed przesyłaniem z przeglądarki:

• CORS. Bucket potrzebuje reguły CORS, która dopuszcza twój origin i metodę PUT. Przy przesyłaniu multipart musi też udostępniać nagłówek ETag, bo przeglądarka musi go odczytać z każdej części.
• Stały klucz. Generuj unikalny klucz na serwerze (na przykład z prefiksem UUID), aby odwiedzający nie mógł nadpisać cudzego pliku.
• Sumy kontrolne. Aktualne SDK AWS domyślnie dodają do przesyłanych plików sumę kontrolną CRC. Jeśli przesyłanie przez presigned URL do dostawcy zgodnego z S3 kończy się błędami podpisu lub sumy kontrolnej, ustaw w kliencie SDK requestChecksumCalculation: 'WHEN_REQUIRED'.

Presigned POST to osobny mechanizm dla zwykłych formularzy HTML, z polityką, która może ograniczać rozmiar i typ zawartości. Nie każdy dostawca zgodny z S3 go obsługuje (R2 nie), więc presigned PUT jest wyborem bardziej przenośnym.

Duże pliki: przesyłanie multipart przez presigned URL

Pojedynczy PUT do S3 jest ograniczony do 5 GB, a AWS zaleca multipart od około 100 MB. Multipart dzieli plik na maksymalnie 10 000 części, każdą od 5 MiB do 5 GiB z wyjątkiem ostatniej, które są przesyłane niezależnie, równolegle i z ponawianiem dla każdej części. Podpisywanie działa dla każdej części osobno: serwer rozpoczyna przesyłanie, podpisuje po jednym URL UploadPart na część, przeglądarka wysyła każdy fragment i odsyła jego ETag, a serwer kończy przesyłanie.

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 }] },
  })
)

Dodaj regułę cyklu życia, która przerywa niedokończone przesyłania multipart po kilku dniach, w przeciwnym razie porzucone części nadal zajmują płatną pamięć.

Presigned URL w R2, B2, Spaces i Wasabi

Dostawcy implementujący S3 API z SigV4 akceptują ten sam kod: zmieniasz tylko endpoint, region i klucze. Szczegóły się różnią, więc sprawdź dokumentację dostawcy:

• Cloudflare R2 obsługuje podpisane GET, HEAD, PUT i DELETE z ważnością od 1 sekundy do 7 dni. Nie obsługuje podpisanego POST, a presigned URL działają tylko w domenie S3 API (<ACCOUNT_ID>.r2.cloudflarestorage.com), a nie we własnych domenach. Użyj region: 'auto'.
• Backblaze B2 podaje, że jego API zgodne z S3 obsługuje presigned URL generowane za pomocą AWS CLI lub SDK.
• DigitalOcean Spaces i Wasabi działają z tymi samymi wywołaniami SDK skierowanymi na ich endpointy.

Ceny u każdego dostawcy znajdziesz w porównaniu S3, R2, Spaces, Wasabi i B2.

Typowe błędy presigned URL i jak je naprawić

Firmowe proxy, które przepisują nagłówki lub query stringi, również psują podpisy. Jeśli URL działa w jednej sieci, a w innej nie, przetestuj go bez proxy.

Dobre praktyki bezpieczeństwa

AWS nazywa presigned URL tokenami na okaziciela i zaleca ich ochronę. W praktyce:

• Ustawiaj krótką ważność. Minuty dla przesyłania i wrażliwych plików, godziny dla zwykłych pobrań. Generuj nowy, gdy ktoś znów potrzebuje pliku.
• Podpisuj tożsamością o wąskich uprawnieniach. Osobny użytkownik lub rola IAM, która może tylko odczytywać (lub tylko zapisywać) dany prefiks, ogranicza szkody, jeśli link wycieknie.
• Dodaj zabezpieczenia w polityce bucketu. Warunek s3:signatureAge odrzuca podpisy starsze niż ustalony wiek, a aws:SourceIp ogranicza, z jakich sieci można ich używać.
• Nie zapisuj ich w logach. Pełne presigned URL w logach aplikacji, analityce lub historii czatu są działającymi danymi dostępowymi aż do wygaśnięcia.
• Zaplanuj to, czego im brakuje. Nie mają hasła, licznika pobrań ani unieważniania pojedynczych linków, więc gdy tego potrzebujesz, postaw przed bucketem aplikację.

Więcej o udostępnianiu, z opcjami, które dodają te kontrole, przeczytasz w artykule jak udostępniać pliki S3 bez upubliczniania bucketu.

Jak Nubbo korzysta z presigned URL

Nubbo jest zbudowane na tym wzorcu. Gdy przesyłasz plik w eksploratorze, serwer podpisuje PUT (lub, od 100 MB, przesyłanie multipart z trzema częściami równolegle), a twoja przeglądarka wysyła bajty bezpośrednio do twojego bucketu. Pobieranie pojedynczych plików korzysta z podpisanych URL GET ważnych przez godzinę. Twoje klucze dostępu są przechowywane w postaci zaszyfrowanej algorytmem AES-256-GCM i są używane wyłącznie na serwerze do podpisywania.

Linki udostępniające dodają to, czego brakuje surowym presigned URL: opcjonalne hasło, datę wygaśnięcia i limit pobrań, które Nubbo sprawdza przed wydaniem krótkotrwałego URL, a link możesz w każdej chwili dezaktywować. Pobrania ZIP z wieloma plikami są składane w twojej przeglądarce, która pobiera każdy plik prosto z twojego bucketu: Nubbo nigdy nie widzi zawartości. Jeden uczciwy wyjątek: miniatury są zapisywane w twoim własnym buckecie w .nubbo-thumbs/. Wszystko działa tak samo w Amazon S3, Cloudflare R2, DigitalOcean Spaces, Wasabi, Backblaze B2 i publicznych endpointach zgodnych z S3.