S3:n presigned URL -osoitteet: mitä ne ovat, miten ne toimivat, voimassaolon rajat ja koodiesimerkit

S3:n presigned URL on väliaikainen linkki yksityisen bucketin yhteen objektiin. Sen kyselymerkkijonossa on allekirjoitus, joten linkin haltija voi ladata (tai lähettää) objektin ilman AWS-tunnuksia, kunnes linkki vanhenee, eikä bucketista koskaan tule julkista. Luot sen omilla avaimillasi koodissasi tai AWS CLI:llä, ja se voi olla voimassa 1 sekunnista 7 päivään. Tämä opas käy läpi, miten se toimii, mitä jokainen X-Amz-*-parametri tarkoittaa, kuinka kauan se voi olla voimassa, koodin latauksiin ja lähetyksiin sekä virheet, joihin todennäköisimmin törmäät. Rajat on otettu AWS:n ja Cloudflaren dokumentaatiosta lokakuulta 2026.

S3:n presigned URL:t lyhyesti

Miten presigned URL toimii

1. Koodisi (tai CLI) ottaa bucketin, objektin avaimen, HTTP-metodin ja voimassaoloajan.
2. SDK allekirjoittaa nämä arvot salaisella käyttöavaimellasi käyttäen AWS Signature Version 4:ää. Tässä vaiheessa S3:lle ei lähetetä mitään.
3. Annat tuloksena saadun URL:n jollekin: selaimelle, kollegalle, mobiilisovellukselle.
4. Kun sitä käytetään, S3 laskee allekirjoituksen uudelleen sillä salaisella avaimella, joka kuuluu URL:ssä olevaan käyttöavaimeen. Jos se täsmää, URL ei ole vanhentunut ja allekirjoittajalla on oikeus kyseiseen toimintoon, pyyntö menee läpi.

URL kantaa allekirjoittajansa käyttöoikeudet. AWS sanoo tämän suoraan: jos URL:n luonut IAM-käyttäjä tai -rooli ei voi lukea objektia, URL palauttaa 403, oli allekirjoitus kuinka kelvollinen tahansa.

Mitä X-Amz-parametrit tarkoittavat

SigV4:n presigned URL näyttää tältä (rivinvaihdot lisätty):

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

Jos muutat mitä tahansa allekirjoitettua osaa (avainta, metodia, voimassaoloa tai allekirjoitettua otsaketta), allekirjoitus ei enää täsmää. Huomaa myös, mitä URL paljastaa selväkielisenä: bucketin nimen, objektin koko avaimen ja käyttöavaimesi tunnuksen. Salainen avain ei ole koskaan URL:ssä.

Kuinka kauan presigned URL on voimassa

Raja riippuu tunnuksista, joilla se allekirjoitetaan:

Tämä selittää yleisimmän yllätyksen: pyydät Lambda-funktiosta tai EC2-instanssista 7 päivää, ja linkki kuolee tunnin tai muutaman tunnin kuluttua. URL elää vain yhtä kauan kuin sen takana olevat tunnukset. Jos tarvitset pitkiä linkkejä, allekirjoita erillisellä IAM-käyttäjällä, jolla on lukuoikeus vain kyseiseen bucketiin.

S3 tarkistaa voimassaolon pyynnön alkaessa. Suuri lataus, joka alkaa sekuntia ennen määräaikaa, valmistuu normaalisti, mutta määräajan jälkeinen uusintayritys epäonnistuu virheellä AccessDenied ja viestillä “Request has expired”. Yli 604 800 sekunnin pyyntö hylätään suoraan.

Miten presigned URL luodaan

AWS CLI

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

Komento allekirjoittaa latausosoitteen (GET). Oletus on 3 600 sekuntia ja enimmäisarvo 604 800. Uusimmat CLI-versiot käyttävät aina SigV4:ää, joten varmista, että alue on määritetty. Lähetysosoitteisiin tarvitset SDK:n.

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

Aseta signature_version='s3v4' erikseen. Boto3-viite varoittaa, että taaksepäin yhteensopivuuden vuoksi se voi muuten allekirjoittaa vanhemmalla Signature Version 2:lla alueilla, jotka sitä yhä hyväksyvät, mikä pudottaa huomaamatta joitakin parametreja ja otsakkeita, kuten Range. ResponseContentDisposition on valinnainen: sen ansiosta selain tallentaa tiedoston siistillä nimellä sen sijaan, että avaisi sen suoraan.

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

Jos jätät expiresIn:n pois, JavaScriptin presigner käyttää 900 sekuntia (15 minuuttia).

Presigned-lähetysosoitteet (PUT)

Sama ajatus toimii toiseen suuntaan. Allekirjoitat PutObject-pyynnön yhdelle avaimelle, ja URL:n haltija voi kirjoittaa kyseisen objektin. Tiedosto kulkee suoraan hänen laitteeltaan bucketiin, eikä palvelimesi koskaan käsittele tavuja. Jos samalla avaimella on jo objekti, se korvataan.

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

Kun lisäät content-type:n signableHeaders-joukkoon, URL sidotaan kyseiseen tyyppiin, joten lähetys eri Content-Type:llä hylätään. Boto3:ssa vastine on generate_presigned_url('put_object', Params={'Bucket': ..., 'Key': ..., 'ContentType': 'application/pdf'}), ja asiakkaan on lähetettävä sama otsake.

Kolme asiaa tarkistettavaksi ennen lähettämistä selaimesta:

• CORS. Bucket tarvitsee CORS-säännön, joka sallii originisi ja PUT-metodin. Moniosaisia lähetyksiä varten sen on myös paljastettava ETag-otsake, koska selaimen on luettava se jokaisesta osasta.
• Kiinteä avain. Luo yksilöllinen avain palvelimella (esimerkiksi UUID-etuliitteellä), jotta vierailija ei voi korvata jonkun toisen tiedostoa.
• Tarkistussummat. Nykyiset AWS SDK:t lisäävät lähetyksiin oletuksena CRC-tarkistussumman. Jos presigned-lähetykset epäonnistuvat S3-yhteensopivalla palveluntarjoajalla allekirjoitus- tai tarkistussummavirheisiin, aseta asiakkaalle requestChecksumCalculation: 'WHEN_REQUIRED'.

Presigned POST on erillinen mekanismi tavallisille HTML-lomakkeille, ja siinä on käytäntö, joka voi rajoittaa kokoa ja sisältötyyppiä. Kaikki S3-yhteensopivat palveluntarjoajat eivät tue sitä (R2 ei tue), joten presigned PUT on siirrettävämpi valinta.

Suuret tiedostot: presigned-moniosaiset lähetykset

Yksittäinen PUT S3:een on rajattu 5 GB:hen, ja AWS suosittelee moniosaista lähetystä noin 100 MB:stä alkaen. Moniosainen lähetys jakaa tiedoston enintään 10 000 osaan, joista kukin on 5 MiB:n ja 5 GiB:n välillä viimeistä lukuun ottamatta, ja osat lähetetään toisistaan riippumatta, rinnakkain ja osakohtaisin uusintayrityksin. Allekirjoitus toimii osittain: palvelin aloittaa lähetyksen, allekirjoittaa yhden UploadPart-URL:n osaa kohden, selain lähettää jokaisen palan ja palauttaa sen ETag:n, ja palvelin viimeistelee lähetyksen.

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

Lisää elinkaarisääntö, joka keskeyttää keskeneräiset moniosaiset lähetykset muutaman päivän kuluttua, tai hylätyt osat vievät edelleen laskutettavaa tallennustilaa.

Presigned URL:t R2:ssa, B2:ssa, Spacesissa ja Wasabissa

Palveluntarjoajat, jotka toteuttavat S3-rajapinnan SigV4:llä, hyväksyvät saman koodin: vaihdat vain endpointin, alueen ja avaimet. Yksityiskohdat vaihtelevat, joten tarkista palveluntarjoajan dokumentaatio:

• Cloudflare R2 tukee presigned GET-, HEAD-, PUT- ja DELETE-pyyntöjä 1 sekunnin ja 7 päivän välisellä voimassaololla. Se ei tue presigned POST-pyyntöjä, ja presigned URL:t toimivat vain S3-rajapinnan verkkotunnuksessa (<ACCOUNT_ID>.r2.cloudflarestorage.com), eivät omissa verkkotunnuksissa. Käytä region: 'auto'.
• Backblaze B2:n mukaan sen S3-yhteensopiva rajapinta tukee AWS CLI:llä tai SDK:illa luotuja presigned URL -osoitteita.
• DigitalOcean Spaces ja Wasabi toimivat samoilla SDK-kutsuilla, kun ne osoitetaan niiden endpointeihin.

Kunkin palveluntarjoajan hinnoista katso S3:n, R2:n, Spacesin, Wasabin ja B2:n vertailu.

Presigned URL:ien yleiset virheet ja niiden korjaus

Myös yritysten välityspalvelimet, jotka kirjoittavat otsakkeita tai kyselymerkkijonoja uudelleen, rikkovat allekirjoituksia. Jos URL toimii yhdestä verkosta mutta ei toisesta, testaa ilman välityspalvelinta.

Hyvät tietoturvakäytännöt

AWS kutsuu presigned URL:iä haltijatunnisteiksi ja suosittelee niiden suojaamista. Käytännössä:

• Pidä ne lyhyinä. Minuutteja lähetyksille ja arkaluonteisille tiedostoille, tunteja tavallisille latauksille. Luo uusi, kun joku tarvitsee tiedoston uudelleen.
• Allekirjoita kapealla identiteetillä. Erillinen IAM-käyttäjä tai -rooli, joka voi vain lukea (tai vain kirjoittaa) kyseistä etuliitettä, rajoittaa vahinkoa, jos linkki vuotaa.
• Lisää suojakaiteita bucket policyyn. Ehto s3:signatureAge hylkää tiettyä ikää vanhemmat allekirjoitukset, ja aws:SourceIp rajoittaa, mistä verkoista niitä voi käyttää.
• Älä kirjaa niitä lokeihin. Täydet presigned URL:t sovelluslokeissa, analytiikassa tai keskusteluhistoriassa ovat toimivia tunnuksia, kunnes ne vanhenevat.
• Varaudu siihen, mitä niistä puuttuu. Niissä ei ole salasanaa, latausmäärää eikä linkkikohtaista perumista, joten laita eteen sovellus, kun tarvitset niitä.

Jakamisesta perusteellisemmin, vaihtoehdoilla, jotka lisäävät nämä hallintakeinot, kertoo artikkeli miten jaat S3-tiedostoja tekemättä bucketista julkista.

Miten Nubbo käyttää presigned URL -osoitteita

Nubbo on rakennettu tämän mallin varaan. Kun lähetät tiedostoja selaimessa, palvelin allekirjoittaa PUT-pyynnön (tai 100 MB:stä alkaen moniosaisen lähetyksen kolmella rinnakkaisella osalla), ja selaimesi lähettää tavut suoraan bucketiisi. Yksittäisten tiedostojen lataukset käyttävät presigned GET -osoitteita, jotka ovat voimassa tunnin. Käyttöavaimesi tallennetaan AES-256-GCM-salattuina, ja niitä käytetään vain palvelimella allekirjoittamiseen.

Jakolinkit lisäävät sen, mitä pelkistä presigned URL:istä puuttuu: valinnaisen salasanan, vanhenemispäivän ja latausrajan, jotka Nubbo tarkistaa ennen lyhytikäisen URL:n antamista, ja voit poistaa linkin käytöstä milloin tahansa. Usean tiedoston ZIP-lataukset kootaan selaimessasi, joka lataa jokaisen tiedoston suoraan bucketistasi: Nubbo ei koskaan näe sisältöä. Yksi rehellinen poikkeus: pikkukuvat kirjoitetaan omaan bucketiisi kansioon .nubbo-thumbs/. Se toimii samoin Amazon S3:ssa, Cloudflare R2:ssa, DigitalOcean Spacesissa, Wasabissa, Backblaze B2:ssa ja julkisissa S3-yhteensopivissa endpointeissa.