Presigned URL v S3: čo sú, ako fungujú, limity platnosti a príklady kódu

Presigned URL v S3 je dočasný odkaz na jeden objekt v súkromnom buckete. V query stringu nesie podpis, takže ktokoľvek, kto ho má, môže tento objekt stiahnuť (alebo nahrať) bez prihlasovacích údajov AWS, kým odkaz nevyprší, a bucket sa nikdy nestane verejným. Vytvoríte ju vlastnými kľúčmi, vo svojom kóde alebo z AWS CLI, a môže platiť od 1 sekundy do 7 dní. Tento návod vysvetľuje, ako funguje, čo znamená každý parameter X-Amz-*, ako dlho môže platiť, kód na sťahovanie a nahrávanie a chyby, na ktoré pravdepodobne narazíte. Limity pochádzajú z dokumentácie AWS a Cloudflare k októbru 2026.

Presigned URL v S3 v skratke

Ako presigned URL funguje

1. Váš kód (alebo CLI) vezme bucket, kľúč objektu, metódu HTTP a dobu platnosti.
2. SDK tieto hodnoty podpíše vaším tajným prístupovým kľúčom pomocou AWS Signature Version 4. V tomto bode sa do S3 nič neposiela.
3. Výslednú URL niekomu dáte: prehliadaču, kolegovi, mobilnej aplikácii.
4. Keď ju použije, S3 prepočíta podpis s tajným kľúčom, ktorý patrí prístupovému kľúču v URL. Ak sa zhoduje, URL nevypršala a podpisujúci smie danú operáciu vykonať, požiadavka prejde.

URL nesie oprávnenia toho, kto ju podpísal. AWS to hovorí jasne: ak používateľ alebo rola IAM, ktorá URL vygenerovala, nemôže objekt čítať, URL vráti 403 bez ohľadu na to, aký platný je podpis.

Čo znamenajú parametre X-Amz

Presigned URL so SigV4 vyzerá takto (zalomenia riadkov pridané):

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

Ak zmeníte akúkoľvek podpísanú časť (kľúč, metódu, platnosť alebo podpísanú hlavičku), podpis sa už nezhoduje. Všimnite si aj to, čo URL prezrádza v čitateľnej podobe: názov bucketu, celý kľúč objektu a ID vášho prístupového kľúča. Tajný kľúč v URL nikdy nie je.

Ako dlho presigned URL platí

Limit závisí od prihlasovacích údajov, ktoré ju podpisujú:

To vysvetľuje najčastejšie prekvapenie: z funkcie Lambda alebo inštancie EC2 požiadate o 7 dní a odkaz po hodine či niekoľkých hodinách prestane fungovať. URL žije len tak dlho ako prihlasovacie údaje za ňou. Ak potrebujete dlhé odkazy, podpisujte vyhradeným používateľom IAM, ktorý má prístup na čítanie len k tomuto bucketu.

S3 kontroluje platnosť pri začiatku požiadavky. Veľké sťahovanie, ktoré začne sekundu pred termínom, normálne dobehne, ale opakovaný pokus po termíne zlyhá s AccessDenied a správou „Request has expired“. Požiadavka na viac ako 604 800 sekúnd sa rovno odmietne.

Ako vygenerovať presigned URL

AWS CLI

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

Príkaz podpíše URL na stiahnutie (GET). Predvolená hodnota je 3 600 sekúnd a maximum 604 800. Novšie verzie CLI vždy používajú SigV4, preto sa uistite, že máte nastavený región. Na URL pre nahrávanie potrebujete 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,
)

Nastavte signature_version='s3v4' výslovne. Referencia boto3 upozorňuje, že kvôli spätnej kompatibilite môže inak podpisovať staršou Signature Version 2 v regiónoch, ktoré ju ešte prijímajú, čo potichu vynechá niektoré parametre a hlavičky ako Range. ResponseContentDisposition je voliteľný: prehliadač vďaka nemu súbor uloží s čistým názvom, namiesto toho, aby ho otvoril priamo.

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

Ak vynecháte expiresIn, presigner v JavaScripte použije 900 sekúnd (15 minút).

Presigned URL na nahrávanie (PUT)

Rovnaký princíp funguje aj opačným smerom. Podpíšete PutObject pre jeden kľúč a ktokoľvek, kto má URL, môže tento objekt zapísať. Súbor ide priamo z jeho zariadenia do bucketu a váš server sa bajtov nikdy nedotkne. Ak objekt s týmto kľúčom už existuje, nahradí sa.

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

Pridanie content-type do signableHeaders viaže URL na tento typ, takže nahratie s iným Content-Type sa odmietne. V boto3 je ekvivalentom generate_presigned_url('put_object', Params={'Bucket': ..., 'Key': ..., 'ContentType': 'application/pdf'}) a klient musí poslať rovnakú hlavičku.

Tri veci, ktoré treba skontrolovať pred nahrávaním z prehliadača:

• CORS. Bucket potrebuje pravidlo CORS, ktoré povoľuje váš pôvod a metódu PUT. Pri multipart nahrávaní musí sprístupniť aj hlavičku ETag, pretože prehliadač ju musí prečítať z každej časti.
• Pevný kľúč. Generujte jedinečný kľúč na serveri (napríklad s prefixom UUID), aby návštevník nemohol prepísať súbor niekoho iného.
• Kontrolné súčty. Súčasné SDK AWS predvolene pridávajú k nahratiam kontrolný súčet CRC. Ak presigned nahrávanie u S3 kompatibilného poskytovateľa zlyháva s chybami podpisu alebo kontrolného súčtu, nastavte na klientovi requestChecksumCalculation: 'WHEN_REQUIRED'.

Presigned POST je samostatný mechanizmus pre bežné HTML formuláre s politikou, ktorá môže obmedziť veľkosť a typ obsahu. Nie každý S3 kompatibilný poskytovateľ ho podporuje (R2 nie), takže presigned PUT je prenosnejšia voľba.

Veľké súbory: presigned multipart nahrávanie

Jeden PUT do S3 je obmedzený na 5 GB a AWS odporúča multipart približne od 100 MB. Multipart rozdelí súbor až na 10 000 častí, každú od 5 MiB do 5 GiB okrem poslednej, ktoré sa nahrávajú nezávisle, paralelne a s opakovaním pre každú časť. Podpisovanie funguje po častiach: server začne nahrávanie, podpíše jednu URL UploadPart pre každú časť, prehliadač pošle každý kus a vráti jeho ETag a server nahrávanie dokončí.

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

Pridajte pravidlo životného cyklu, ktoré po niekoľkých dňoch zruší nedokončené multipart nahrávania, inak opustené časti naďalej zaberajú účtované úložisko.

Presigned URL v R2, B2, Spaces a Wasabi

Poskytovatelia, ktorí implementujú S3 API so SigV4, prijímajú rovnaký kód: meníte len endpoint, región a kľúče. Detaily sa líšia, preto si overte dokumentáciu poskytovateľa:

• Cloudflare R2 podporuje presigned GET, HEAD, PUT a DELETE s platnosťou od 1 sekundy do 7 dní. Nepodporuje presigned POST a presigned URL fungujú len na doméne S3 API (<ACCOUNT_ID>.r2.cloudflarestorage.com), nie na vlastných doménach. Použite region: 'auto'.
• Backblaze B2 uvádza, že jeho S3 kompatibilné API podporuje presigned URL vygenerované cez AWS CLI alebo SDK.
• DigitalOcean Spaces a Wasabi fungujú s rovnakými volaniami SDK nasmerovanými na ich endpointy.

Ceny jednotlivých poskytovateľov nájdete v porovnaní S3, R2, Spaces, Wasabi a B2.

Časté chyby presigned URL a ich riešenie

Podpisy rozbíjajú aj firemné proxy, ktoré prepisujú hlavičky alebo query stringy. Ak URL funguje z jednej siete a z inej nie, otestujte ju bez proxy.

Osvedčené bezpečnostné postupy

AWS nazýva presigned URL bearer tokenmi a odporúča ich chrániť. V praxi:

• Držte ich krátke. Minúty pri nahrávaní a citlivých súboroch, hodiny pri bežnom sťahovaní. Keď niekto súbor potrebuje znova, vygenerujte novú.
• Podpisujte úzkou identitou. Vyhradený používateľ alebo rola IAM, ktorá môže daný prefix len čítať (alebo len zapisovať), obmedzí škody, ak odkaz unikne.
• Pridajte poistky do bucket policy. Podmienka s3:signatureAge odmieta podpisy staršie ako určený vek a aws:SourceIp obmedzuje, z ktorých sietí sa dajú použiť.
• Nezapisujte ich do logov. Úplné presigned URL v logoch aplikácie, analytike alebo histórii chatu sú funkčné prihlasovacie údaje, kým nevyprší ich platnosť.
• Počítajte s tým, čo im chýba. Nemajú heslo, počet stiahnutí ani zrušenie jednotlivých odkazov, takže keď to potrebujete, dajte pred ne aplikáciu.

Zdieľanie do hĺbky, s možnosťami, ktoré tieto kontroly pridávajú, nájdete v článku ako zdieľať súbory S3 bez zverejnenia bucketu.

Ako Nubbo používa presigned URL

Nubbo je postavené na tomto vzore. Keď nahrávate v prehliadači súborov, server podpíše PUT (alebo od 100 MB multipart nahrávanie s tromi časťami paralelne) a váš prehliadač pošle bajty priamo do vášho bucketu. Sťahovanie jednotlivých súborov používa presigned URL GET s platnosťou jednu hodinu. Vaše prístupové kľúče sú uložené zašifrované pomocou AES-256-GCM a používajú sa len na serveri na podpisovanie.

Odkazy na zdieľanie pridávajú to, čo samotným presigned URL chýba: voliteľné heslo, dátum vypršania a limit stiahnutí, ktoré Nubbo skontroluje predtým, ako vydá URL s krátkou platnosťou, a odkaz môžete kedykoľvek deaktivovať. ZIP s viacerými súbormi sa zostavuje vo vašom prehliadači, ktorý stiahne každý súbor priamo z vášho bucketu: Nubbo obsah nikdy nevidí. Jedna úprimná výnimka: náhľady sa zapisujú do vášho vlastného bucketu pod .nubbo-thumbs/. Funguje to rovnako v Amazon S3, Cloudflare R2, DigitalOcean Spaces, Wasabi, Backblaze B2 a na verejných S3 kompatibilných endpointoch.