Presigned URL-ji S3: kaj so, kako delujejo, omejitve veljavnosti in primeri kode

Presigned URL S3 je začasna povezava do enega objekta v zasebnem bucketu. V nizu poizvedbe nosi podpis, zato lahko kdor jo ima, ta objekt prenese (ali naloži) brez poverilnic AWS, dokler povezava ne poteče, bucket pa nikoli ne postane javen. Ustvariš ga s svojimi ključi, v svoji kodi ali iz AWS CLI, veljavnost pa ima lahko od 1 sekunde do 7 dni. Ta vodnik razloži, kako deluje, kaj pomeni vsak parameter X-Amz-*, kako dolgo lahko velja, kodo za prenose in nalaganja ter napake, na katere boš najverjetneje naletel. Omejitve so povzete po dokumentaciji AWS in Cloudflare, stanje oktobra 2026.

Presigned URL-ji S3 na kratko

Kako deluje presigned URL

1. Tvoja koda (ali CLI) vzame bucket, ključ objekta, metodo HTTP in čas veljavnosti.
2. SDK te vrednosti podpiše s tvojim skrivnim dostopnim ključem z AWS Signature Version 4. Na tej točki se v S3 ne pošlje nič.
3. Nastali URL daš nekomu: brskalniku, sodelavcu, mobilni aplikaciji.
4. Ko ga uporabi, S3 podpis izračuna znova s skrivnostjo, ki pripada dostopnemu ključu v URL-ju. Če se ujema, URL ni potekel in podpisnik sme izvesti to operacijo, zahteva uspe.

URL nosi dovoljenja tistega, ki ga je podpisal. AWS je pri tem jasen: če uporabnik ali vloga IAM, ki je ustvaril URL, objekta ne more brati, URL vrne 403, ne glede na to, kako veljaven je podpis.

Kaj pomenijo parametri X-Amz

Presigned URL SigV4 je videti takole (prelomi vrstic dodani):

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

Če spremeniš kateri koli podpisan del (ključ, metodo, veljavnost ali podpisano glavo), se podpis ne ujema več. Upoštevaj tudi, kaj URL razkrije v navadnem besedilu: ime bucketa, celoten ključ objekta in ID tvojega dostopnega ključa. Skrivnega ključa v URL-ju nikoli ni.

Kako dolgo velja presigned URL

Omejitev je odvisna od poverilnic, ki ga podpišejo:

To pojasni najpogostejše presenečenje: iz funkcije Lambda ali instance EC2 zahtevaš 7 dni, povezava pa ugasne po eni uri ali nekaj urah. URL živi le toliko časa kot poverilnice za njim. Če potrebuješ dolge povezave, podpisuj z namenskim uporabnikom IAM, ki ima dostop za branje samo do tega bucketa.

S3 veljavnost preveri ob začetku zahteve. Velik prenos, ki se začne sekundo pred rokom, se normalno konča, ponovni poskus po roku pa ne uspe z AccessDenied in sporočilom »Request has expired«. Zahteva za več kot 604.800 sekund je takoj zavrnjena.

Kako ustvariti presigned URL

AWS CLI

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

Ukaz podpiše URL za prenos (GET). Privzeto je 3.600 sekund, največ 604.800. Novejše različice CLI vedno uporabljajo SigV4, zato poskrbi, da je regija nastavljena. Za URL-je za nalaganje potrebuješ 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' nastavi izrecno. Referenca boto3 opozarja, da lahko zaradi združljivosti za nazaj sicer podpiše s starejšim Signature Version 2 v regijah, ki ga še sprejemajo, kar tiho izpusti nekatere parametre in glave, kot je Range. ResponseContentDisposition ni obvezen: brskalnik z njim datoteko shrani s čistim imenom, namesto da bi jo odprl neposredno.

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

Če expiresIn izpustiš, presigner za JavaScript uporabi 900 sekund (15 minut).

Presigned URL-ji za nalaganje (PUT)

Ista zamisel deluje v drugo smer. Podpišeš PutObject za en ključ in kdor ima URL, lahko zapiše ta objekt. Datoteka gre neposredno iz njegove naprave v bucket, tvoj strežnik pa bajtov nikoli ne obdeluje. Če objekt s tem ključem že obstaja, se zamenja.

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

Ko content-type dodaš v signableHeaders, URL vežeš na to vrsto, zato je nalaganje z drugačnim Content-Type zavrnjeno. V boto3 je enakovredno generate_presigned_url('put_object', Params={'Bucket': ..., 'Key': ..., 'ContentType': 'application/pdf'}), odjemalec pa mora poslati isto glavo.

Tri stvari, ki jih preveri pred nalaganjem iz brskalnika:

• CORS. Bucket potrebuje pravilo CORS, ki dovoljuje tvoj izvor in metodo PUT. Za nalaganje po delih mora razkriti tudi glavo ETag, ker jo mora brskalnik prebrati iz vsakega dela.
• Fiksen ključ. Edinstven ključ ustvari na strežniku (na primer s predpono UUID), da obiskovalec ne more prepisati tuje datoteke.
• Kontrolne vsote. Trenutni SDK-ji AWS nalaganjem privzeto dodajo kontrolno vsoto CRC. Če presigned nalaganja pri S3-združljivem ponudniku ne uspejo z napakami podpisa ali kontrolne vsote, na odjemalcu nastavi requestChecksumCalculation: 'WHEN_REQUIRED'.

Presigned POST je ločen mehanizem za navadne obrazce HTML, s pravilnikom, ki lahko omeji velikost in vrsto vsebine. Ne podpirajo ga vsi S3-združljivi ponudniki (R2 ga ne), zato je presigned PUT bolj prenosljiva izbira.

Velike datoteke: presigned nalaganje po delih

Posamezen PUT v S3 je omejen na 5 GB, AWS pa nalaganje po delih (multipart) predlaga od približno 100 MB naprej. Nalaganje po delih datoteko razdeli na do 10.000 delov, vsak od 5 MiB do 5 GiB razen zadnjega, ki se nalagajo neodvisno, vzporedno in s ponovnimi poskusi za vsak del. Predpodpisovanje deluje po delih: strežnik začne nalaganje, podpiše en URL UploadPart na del, brskalnik pošlje vsak kos in sporoči njegov ETag, strežnik pa nalaganje dokonča.

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 pravilo življenjskega cikla, ki nedokončana nalaganja po delih prekine po nekaj dneh, sicer zapuščeni deli še naprej zasedajo obračunljivo shrambo.

Presigned URL-ji pri R2, B2, Spaces in Wasabi

Ponudniki, ki implementirajo API S3 s SigV4, sprejmejo isto kodo: spremeniš samo endpoint, regijo in ključe. Podrobnosti se razlikujejo, zato preveri dokumentacijo ponudnika:

• Cloudflare R2 podpira presigned GET, HEAD, PUT in DELETE z veljavnostjo od 1 sekunde do 7 dni. Ne podpira presigned POST, presigned URL-ji pa delujejo samo na domeni API-ja S3 (<ACCOUNT_ID>.r2.cloudflarestorage.com), ne na domenah po meri. Uporabi region: 'auto'.
• Backblaze B2 navaja, da njegov S3-združljivi API podpira presigned URL-je, ustvarjene z AWS CLI ali SDK-ji.
• DigitalOcean Spaces in Wasabi delujeta z istimi klici SDK, usmerjenimi na njune endpointe.

Za cene pri posameznem ponudniku glej primerjavo S3, R2, Spaces, Wasabi in B2.

Pogoste napake pri presigned URL-jih in kako jih odpraviti

Podpise pokvarijo tudi korporativni posredniški strežniki, ki prepisujejo glave ali nize poizvedb. Če URL deluje iz enega omrežja in iz drugega ne, ga preizkusi brez posrednika.

Dobre varnostne prakse

AWS presigned URL-je imenuje žetoni prinosnika in jih priporoča zaščititi. V praksi:

• Naj bodo kratki. Minute za nalaganja in občutljive datoteke, ure za običajne prenose. Ko nekdo datoteko spet potrebuje, ustvari novega.
• Podpisuj z ozko identiteto. Namenski uporabnik ali vloga IAM, ki lahko samo bere (ali samo piše) v zadevno predpono, omeji škodo, če povezava uide.
• Dodaj varovala v pravilnik bucketa. Pogoj s3:signatureAge zavrne podpise, starejše od določene starosti, aws:SourceIp pa omeji, katera omrežja jih lahko uporabljajo.
• Ne beleži jih. Celotni presigned URL-ji v dnevnikih aplikacij, analitiki ali zgodovini klepeta so delujoče poverilnice, dokler ne potečejo.
• Upoštevaj, česa nimajo. Nimajo gesla, števca prenosov in preklica posamezne povezave, zato pred bucket postavi aplikacijo, ko to potrebuješ.

Za poglobljen pogled na deljenje, z možnostmi, ki dodajo ta nadzor, glej kako deliti datoteke S3, ne da bi bucket naredil javen.

Kako Nubbo uporablja presigned URL-je

Nubbo temelji na tem vzorcu. Ko nalagaš v raziskovalcu, strežnik podpiše PUT (ali, od 100 MB naprej, nalaganje po delih s tremi deli vzporedno), tvoj brskalnik pa bajte pošlje neposredno v tvoj bucket. Prenosi posameznih datotek uporabljajo presigned URL-je GET, veljavne eno uro. Tvoji dostopni ključi so shranjeni šifrirani z AES-256-GCM in se na strežniku uporabljajo samo za podpisovanje.

Povezave za deljenje dodajo, česar surovi presigned URL-ji nimajo: neobvezno geslo, datum poteka in omejitev prenosov, ki jih Nubbo preveri, preden izda kratkotrajen URL, povezavo pa lahko kadar koli deaktiviraš. Prenosi ZIP z več datotekami se sestavijo v tvojem brskalniku, ki vsako datoteko prenese neposredno iz tvojega bucketa: Nubbo vsebine nikoli ne vidi. Ena iskrena izjema: sličice se zapišejo v tvoj lastni bucket pod .nubbo-thumbs/. Enako deluje na Amazon S3, Cloudflare R2, DigitalOcean Spaces, Wasabi, Backblaze B2 in javnih S3-združljivih endpointih.