S3 presigned URL-ek: mik ezek, hogyan működnek, lejárati korlátok és kódpéldák

Az S3 presigned URL (előre aláírt URL) egy ideiglenes link egy privát bucket egyetlen objektumára. A lekérdezési karakterláncában aláírást hordoz, így aki birtokolja, AWS-hitelesítő adatok nélkül letöltheti (vagy feltöltheti) azt az objektumot a link lejártáig, a bucket pedig soha nem válik nyilvánossá. A saját kulcsaiddal hozod létre, a kódodban vagy az AWS CLI-ből, és 1 másodperctől 7 napig tarthat. Ez az útmutató bemutatja, hogyan működik, mit jelent minden X-Amz-* paraméter, meddig tarthat, kódot ad letöltéshez és feltöltéshez, és sorra veszi a leggyakoribb hibákat. A korlátok az AWS és a Cloudflare 2026 októberi dokumentációjából származnak.

S3 presigned URL-ek egy pillantással

Hogyan működik egy presigned URL

1. A kódod (vagy a CLI) veszi a bucketet, az objektumkulcsot, a HTTP-metódust és egy lejárati időt.
2. Az SDK ezeket az értékeket a secret access key-ed segítségével, AWS Signature Version 4-gyel írja alá. Ekkor még semmi sem megy az S3 felé.
3. Az így kapott URL-t odaadod valakinek: egy böngészőnek, egy kollégának, egy mobilalkalmazásnak.
4. Amikor használják, az S3 újraszámolja az aláírást az URL-ben lévő access key-hez tartozó secrettel. Ha egyezik, az URL nem járt le, és az aláíró jogosult az adott műveletre, a kérés átmegy.

Az URL annak a jogosultságait hordozza, aki aláírta. Az AWS ezt egyértelműen kimondja: ha az URL-t létrehozó IAM-felhasználó vagy szerep nem olvashatja az objektumot, az URL 403-at ad, bármennyire érvényes is az aláírás.

Mit jelentenek az X-Amz paraméterek

Egy SigV4 presigned URL így néz ki (sortörésekkel):

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

Ha bármelyik aláírt részt (a kulcsot, a metódust, a lejáratot vagy egy aláírt fejlécet) megváltoztatod, az aláírás már nem egyezik. Figyelj arra is, mit árul el az URL nyílt szövegben: a bucket nevét, a teljes objektumkulcsot és az access key ID-det. A secret key soha nincs az URL-ben.

Meddig tart egy presigned URL

A korlát az aláíró hitelesítő adatoktól függ:

Ez magyarázza a leggyakoribb meglepetést: egy Lambda-függvényből vagy EC2-példányból 7 napot kérsz, és a link egy vagy néhány óra után megszűnik. Az URL csak addig él, amíg a mögötte lévő hitelesítő adatok. Ha hosszú linkekre van szükséged, egy dedikált IAM-felhasználóval írj alá, amely csak az adott bucketet olvashatja.

Az S3 a kérés indulásakor ellenőrzi a lejáratot. Egy nagy letöltés, amely egy másodperccel a határidő előtt indul, rendben befejeződik, de a határidő utáni újrapróbálkozás AccessDenied hibával és „Request has expired” üzenettel meghiúsul. A 604 800 másodpercnél hosszabb kérést azonnal elutasítja.

Hogyan hozz létre presigned URL-t

AWS CLI

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

A parancs egy letöltési (GET) URL-t ír alá. Az alapértelmezés 3600 másodperc, a maximum 604 800. A friss CLI-verziók mindig SigV4-et használnak, ezért gondoskodj róla, hogy legyen beállított régió. Feltöltési URL-ekhez SDK kell.

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

Állítsd be kifejezetten a signature_version='s3v4' értéket. A boto3 referenciája figyelmeztet, hogy a visszafelé kompatibilitás miatt egyébként a régebbi Signature Version 2-vel is aláírhat azokban a régiókban, amelyek még elfogadják, ami csendben elhagy néhány paramétert és fejlécet, például a Range-et. A ResponseContentDisposition opcionális: hatására a böngésző tiszta néven menti el a fájlt ahelyett, hogy megnyitná.

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

Ha kihagyod az expiresIn értéket, a JavaScript presigner 900 másodpercet (15 percet) használ.

Presigned feltöltési URL-ek (PUT)

Ugyanez az elv a másik irányban is működik. Egy PutObject műveletet írsz alá egy kulcsra, és aki birtokolja az URL-t, megírhatja azt az objektumot. A fájl közvetlenül az eszközéről megy a bucketbe, a szervered soha nem kezeli a bájtokat. Ha már létezik ilyen kulcsú objektum, lecserélődik.

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

Ha a content-type értéket hozzáadod a signableHeaders listához, az URL ehhez a típushoz kötődik, így egy eltérő Content-Type-pal küldött feltöltést elutasít. A boto3-ban ennek megfelelője a generate_presigned_url('put_object', Params={'Bucket': ..., 'Key': ..., 'ContentType': 'application/pdf'}), és a kliensnek ugyanazt a fejlécet kell küldenie.

Három dolog, amit böngészőből való feltöltés előtt ellenőrizz:

• CORS. A bucketnek olyan CORS-szabály kell, amely engedélyezi az originodat és a PUT metódust. Multipart feltöltésnél az ETag fejlécet is elérhetővé kell tennie, mert a böngészőnek minden részből ki kell olvasnia.
• Rögzített kulcs. A szerveren generálj egyedi kulcsot (például UUID-előtaggal), hogy egy látogató ne írhassa felül más fájlját.
• Ellenőrzőösszegek. A jelenlegi AWS SDK-k alapból CRC-ellenőrzőösszeget adnak a feltöltésekhez. Ha a presigned feltöltések egy S3-kompatibilis szolgáltatónál aláírási vagy ellenőrzőösszeg-hibával meghiúsulnak, állítsd be a kliensen a requestChecksumCalculation: 'WHEN_REQUIRED' értéket.

A presigned POST egy külön mechanizmus egyszerű HTML-űrlapokhoz, olyan policyvel, amely korlátozhatja a méretet és a tartalomtípust. Nem minden S3-kompatibilis szolgáltató támogatja (az R2 nem), ezért a presigned PUT a jobban hordozható választás.

Nagy fájlok: presigned multipart feltöltések

Egyetlen PUT az S3-ba 5 GB-ra korlátozott, és az AWS nagyjából 100 MB-tól javasolja a multipartot. A multipart a fájlt legfeljebb 10 000 részre bontja, mindegyik 5 MiB és 5 GiB közötti (az utolsó kivételével), amelyek egymástól függetlenül, párhuzamosan és részenkénti újrapróbálkozással töltődnek fel. Az előaláírás részenként működik: a szerver elindítja a feltöltést, részenként aláír egy UploadPart URL-t, a böngésző elküldi az egyes darabokat, és visszajelzi az ETag értéküket, a szerver pedig befejezi a feltöltést.

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

Adj hozzá egy életciklus-szabályt, amely néhány nap után megszakítja a befejezetlen multipart feltöltéseket, különben az elhagyott részek továbbra is számlázott tárhelyet foglalnak.

Presigned URL-ek az R2-n, a B2-n, a Spaces-en és a Wasabin

Azok a szolgáltatók, amelyek SigV4-gyel valósítják meg az S3 API-t, ugyanazt a kódot fogadják el: csak az endpointot, a régiót és a kulcsokat cseréled. A részletek eltérnek, ezért nézd meg a szolgáltató dokumentációját:

• A Cloudflare R2 támogatja a presigned GET, HEAD, PUT és DELETE műveletet 1 másodperc és 7 nap közötti lejárattal. A presigned POST-ot nem támogatja, és a presigned URL-ek csak az S3 API domainjén (<ACCOUNT_ID>.r2.cloudflarestorage.com) működnek, egyéni domaineken nem. Használd a region: 'auto' értéket.
• A Backblaze B2 szerint az S3-kompatibilis API-ja támogatja az AWS CLI-vel vagy SDK-kkal generált presigned URL-eket.
• A DigitalOcean Spaces és a Wasabi ugyanazokkal az SDK-hívásokkal működik, az ő endpointjukra irányítva.

Az egyes szolgáltatók áraiért lásd az S3, R2, Spaces, Wasabi és B2 összehasonlítását.

Gyakori presigned URL-hibák és javításuk

A fejléceket vagy lekérdezési karakterláncokat átíró vállalati proxyk is tönkreteszik az aláírásokat. Ha egy URL az egyik hálózatról működik, a másikról nem, teszteld proxy nélkül.

Biztonsági bevált gyakorlatok

Az AWS bearer tokennek nevezi a presigned URL-eket, és azt javasolja, hogy védd őket. A gyakorlatban:

• Tartsd őket rövidre. Feltöltésekhez és érzékeny fájlokhoz perceket, hétköznapi letöltésekhez órákat. Generálj újat, ha valakinek ismét szüksége van a fájlra.
• Szűk identitással írj alá. Egy dedikált IAM-felhasználó vagy szerep, amely csak olvashatja (vagy csak írhatja) az adott prefixet, korlátozza a kárt, ha egy link kiszivárog.
• Építs be korlátokat a bucket policybe. Az s3:signatureAge feltétel elutasítja a megadott kornál régebbi aláírásokat, az aws:SourceIp pedig korlátozza, mely hálózatokról használhatók.
• Ne naplózd őket. Az alkalmazásnaplókban, analitikában vagy csevegési előzményekben szereplő teljes presigned URL-ek a lejáratukig működő hitelesítő adatok.
• Számolj azzal, ami hiányzik belőlük. Nincs jelszó, nincs letöltésszámláló és nincs linkenkénti visszavonás, ezért tegyél eléjük egy alkalmazást, ha ezekre szükséged van.

A megosztási oldalról részletesen, olyan lehetőségekkel, amelyek ezeket az ellenőrzéseket is hozzáadják: hogyan oszthatsz meg S3-fájlokat a bucket nyilvánossá tétele nélkül.

Hogyan használja a Nubbo a presigned URL-eket

A Nubbo erre a mintára épül. Amikor a fájlkezelőben feltöltesz, a szerver aláír egy PUT műveletet (vagy 100 MB-tól egy multipart feltöltést három párhuzamos résszel), a böngésződ pedig közvetlenül a bucketedbe küldi a bájtokat. Az egyes fájlok letöltése egy óráig érvényes presigned GET URL-ekkel történik. A hozzáférési kulcsaidat AES-256-GCM titkosítással tároljuk, és csak a szerveren használjuk őket aláírásra.

A megosztási linkek azt adják hozzá, ami a nyers presigned URL-ekből hiányzik: opcionális jelszót, lejárati dátumot és letöltési korlátot, amelyeket a Nubbo ellenőriz, mielőtt rövid élettartamú URL-t ad ki, és bármikor kikapcsolhatsz egy linket. A több fájlt tartalmazó ZIP-letöltéseket a böngésződ állítja össze, minden fájlt közvetlenül a bucketedből letöltve: a Nubbo soha nem látja a tartalmat. Egy őszinte kivétel: az előnézeti képek a saját bucketedbe kerülnek a .nubbo-thumbs/ alá. Ugyanígy működik az Amazon S3, a Cloudflare R2, a DigitalOcean Spaces, a Wasabi, a Backblaze B2 és a nyilvános S3-kompatibilis endpointok esetén.