S3 presigned URL-id: mis need on, kuidas töötavad, aegumise piirangud ja koodinäited

S3 presigned URL on ajutine link ühele privaatse bucketi objektile. Selle päringustringis on allkiri, nii et selle omanik saab objekti alla (või üles) laadida ilma AWS-i mandaatideta, kuni link aegub, ja bucket ei muutu kunagi avalikuks. Lood selle oma võtmetega, oma koodis või AWS CLI-st, ja see võib kesta 1 sekundist kuni 7 päevani. See juhend selgitab, kuidas see töötab, mida iga X-Amz-* parameeter tähendab, kui kaua see võib kesta, annab koodi alla- ja üleslaadimiseks ning kirjeldab vigu, millega kõige tõenäolisemalt kokku puutud. Piirangud on võetud AWS-i ja Cloudflare’i dokumentatsioonist 2026. aasta oktoobri seisuga.

S3 presigned URL-id lühidalt

Kuidas presigned URL töötab

1. Sinu kood (või CLI) võtab bucketi, objekti võtme, HTTP-meetodi ja aegumisaja.
2. SDK allkirjastab need väärtused sinu salajase ligipääsuvõtmega, kasutades AWS Signature Version 4. Selles etapis S3-le midagi ei saadeta.
3. Annad saadud URL-i kellelegi: brauserile, kolleegile, mobiilirakendusele.
4. Kui nad seda kasutavad, arvutab S3 allkirja uuesti salajase võtmega, mis kuulub URL-is olevale ligipääsuvõtmele. Kui see klapib, URL pole aegunud ja allkirjastajal on lubatud seda toimingut teha, läheb päring läbi.

URL kannab endas selle allkirjastaja õigusi. AWS ütleb seda selgelt: kui URL-i genereerinud IAM-kasutaja või roll ei saa objekti lugeda, tagastab URL 403, ükskõik kui kehtiv allkiri on.

Mida X-Amz parameetrid tähendavad

SigV4 presigned URL näeb välja selline (reavahetused lisatud):

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

Muuda ükskõik millist allkirjastatud osa (võtit, meetodit, aegumisaega või allkirjastatud päist) ja allkiri enam ei klapi. Pane tähele ka seda, mida URL avatekstina paljastab: bucketi nime, objekti täieliku võtme ja sinu ligipääsuvõtme ID. Salajast võtit URL-is kunagi pole.

Kui kaua presigned URL kestab

Piirang sõltub mandaatidest, millega see allkirjastatakse:

See selgitab kõige levinumat üllatust: küsid Lambda funktsioonist või EC2 instantsist 7 päeva ja link sureb tunni või mõne tunni pärast. URL elab vaid nii kaua kui selle taga olevad mandaadid. Kui vajad pikki linke, allkirjasta spetsiaalse IAM-kasutajaga, kellel on lugemisõigus ainult sellele bucketile.

S3 kontrollib aegumist päringu alguses. Suur allalaadimine, mis algab sekund enne tähtaega, lõpeb tavapäraselt, kuid uus katse pärast tähtaega ebaõnnestub veaga AccessDenied ja teatega „Request has expired“. Üle 604 800 sekundi küsimine lükatakse kohe tagasi.

Kuidas presigned URL-i genereerida

AWS CLI

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

Käsk allkirjastab allalaadimise (GET) URL-i. Vaikimisi on 3600 sekundit ja maksimum 604 800. Uuemad CLI versioonid kasutavad alati SigV4, seega veendu, et piirkond on seadistatud. Üleslaadimise URL-ide jaoks vajad SDK-d.

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

Määra signature_version='s3v4' selgesõnaliselt. Boto3 viide hoiatab, et tagasiühilduvuse huvides võib see muidu allkirjastada vanema Signature Version 2-ga piirkondades, mis seda veel aktsepteerivad, mis jätab vaikselt välja mõned parameetrid ja päised, näiteks Range. ResponseContentDisposition on valikuline: see paneb brauseri faili puhta nimega salvestama, selle asemel et seda brauseris avada.

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

Kui jätad expiresIn välja, kasutab JavaScripti presigner 900 sekundit (15 minutit).

Presigned üleslaadimise URL-id (PUT)

Sama idee töötab ka teises suunas. Allkirjastad ühe võtme jaoks PutObject toimingu ja URL-i omanik saab selle objekti kirjutada. Fail liigub otse tema seadmest bucketisse ja sinu server ei käsitle baite kunagi. Kui selle võtmega objekt on juba olemas, asendatakse see.

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 lisamine väljale signableHeaders seob URL-i selle tüübiga, nii et teistsuguse Content-Type’iga üleslaadimine lükatakse tagasi. Boto3-s on vaste generate_presigned_url('put_object', Params={'Bucket': ..., 'Key': ..., 'ContentType': 'application/pdf'}) ja klient peab saatma sama päise.

Kolm asja, mida enne brauserist üleslaadimist kontrollida:

• CORS. Bucket vajab CORS-reeglit, mis lubab sinu päritolu ja meetodit PUT. Multipart-üleslaadimiste jaoks peab see ka avaldama päise ETag, sest brauser peab selle igast osast lugema.
• Kindel võti. Genereeri serveris unikaalne võti (näiteks UUID-eesliitega), et külastaja ei saaks kellegi teise faili üle kirjutada.
• Kontrollsummad. Praegused AWS SDK-d lisavad üleslaadimistele vaikimisi CRC-kontrollsumma. Kui presigned üleslaadimised ebaõnnestuvad S3-ühilduva teenusepakkuja juures allkirja- või kontrollsummavigadega, määra kliendile requestChecksumCalculation: 'WHEN_REQUIRED'.

Presigned POST on eraldi mehhanism tavaliste HTML-vormide jaoks, poliitikaga, mis võib piirata suurust ja sisutüüpi. Kõik S3-ühilduvad teenusepakkujad seda ei toeta (R2 ei toeta), seega on presigned PUT paremini ülekantav valik.

Suured failid: presigned multipart-üleslaadimised

Üksik PUT S3-sse on piiratud 5 GB-ga ja AWS soovitab multipart-meetodit alates umbes 100 MB-st. Multipart jagab faili kuni 10 000 osaks, igaüks 5 MiB kuni 5 GiB, välja arvatud viimane, ning need laaditakse üles iseseisvalt, paralleelselt ja osapõhiste kordustega. Presigned allkirjastamine toimib osade kaupa: server alustab üleslaadimist, allkirjastab iga osa jaoks ühe UploadPart URL-i, brauser saadab iga tüki ja teatab tagasi selle ETag’i ning server lõpetab üleslaadimise.

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

Lisa elutsükli reegel, mis katkestab lõpetamata multipart-üleslaadimised mõne päeva pärast, muidu võtavad hüljatud osad jätkuvalt arveldatavat salvestusruumi.

Presigned URL-id R2-s, B2-s, Spacesis ja Wasabis

Teenusepakkujad, kes rakendavad S3 API-t koos SigV4-ga, aktsepteerivad sama koodi: muudad ainult lõpp-punkti, piirkonda ja võtmeid. Üksikasjad erinevad, seega kontrolli teenusepakkuja dokumentatsiooni:

• Cloudflare R2 toetab presigned GET-, HEAD-, PUT- ja DELETE-päringuid aegumisajaga 1 sekundist 7 päevani. See ei toeta presigned POST-i ja presigned URL-id töötavad ainult S3 API domeenil (<ACCOUNT_ID>.r2.cloudflarestorage.com), mitte kohandatud domeenidel. Kasuta region: 'auto'.
• Backblaze B2 teatab, et selle S3-ühilduv API toetab AWS CLI või SDK-dega genereeritud presigned URL-e.
• DigitalOcean Spaces ja Wasabi töötavad samade SDK päringutega, mis on suunatud nende lõpp-punktidele.

Iga teenusepakkuja hindade kohta vaata S3, R2, Spacesi, Wasabi ja B2 võrdlust.

Levinud presigned URL-i vead ja nende parandamine

Ettevõtete proksid, mis kirjutavad päiseid või päringustringe ümber, rikuvad samuti allkirju. Kui URL töötab ühest võrgust ja teisest mitte, testi ilma proksita.

Turvalisuse head tavad

AWS nimetab presigned URL-e kandjatõenditeks ja soovitab neid kaitsta. Praktikas:

• Hoia need lühikesed. Üleslaadimiste ja tundlike failide jaoks minutid, tavaliste allalaadimiste jaoks tunnid. Genereeri uus, kui keegi vajab faili uuesti.
• Allkirjasta kitsa identiteediga. Spetsiaalne IAM-kasutaja või roll, mis saab vaid lugeda (või vaid kirjutada) asjaomast prefiksit, piirab kahju, kui link lekib.
• Lisa bucketi poliitikasse kaitsepiirded. Tingimus s3:signatureAge lükkab tagasi määratud vanusest vanemad allkirjad ja aws:SourceIp piirab, millised võrgud saavad neid kasutada.
• Ära logi neid. Täielikud presigned URL-id rakenduse logides, analüütikas või vestlusajaloos on toimivad mandaadid, kuni need aeguvad.
• Arvesta sellega, mis neil puudub. Pole parooli, allalaadimiste loendurit ega lingipõhist tühistamist, seega pane ette rakendus, kui neid vajad.

Jagamise poole põhjalikumaks käsitluseks, koos valikutega, mis need kontrollid lisavad, vaata kuidas jagada S3 faile ilma bucketit avalikuks tegemata.

Kuidas Nubbo presigned URL-e kasutab

Nubbo on üles ehitatud sellele mustrile. Kui laadid failihalduris üles, allkirjastab server PUT-päringu (või alates 100 MB-st multipart-üleslaadimise kolme paralleelse osaga) ja sinu brauser saadab baidid otse sinu bucketisse. Üksikfailide allalaadimised kasutavad presigned GET URL-e, mis kehtivad ühe tunni. Sinu ligipääsuvõtmed salvestatakse AES-256-GCM-iga krüpteeritult ja neid kasutatakse ainult serveris allkirjastamiseks.

Jagamislingid lisavad selle, mis toorestest presigned URL-idest puudub: valikulise parooli, aegumiskuupäeva ja allalaadimiste piirangu, mida Nubbo kontrollib enne lühiajalise URL-i väljastamist, ning lingi saad igal ajal deaktiveerida. Mitme faili ZIP-allalaadimised koostatakse sinu brauseris, mis laadib iga faili otse sinu bucketist alla: Nubbo ei näe kunagi sisu. Üks aus erand: pisipildid kirjutatakse sinu enda bucketisse kausta .nubbo-thumbs/. See töötab samamoodi Amazon S3, Cloudflare R2, DigitalOcean Spacesi, Wasabi, Backblaze B2 ja avalike S3-ühilduvate lõpp-punktidega.