URL prefirmada de S3: qué es, cómo funciona, cuánto dura y ejemplos de código

Una URL prefirmada de S3 es un enlace temporal a un objeto de un bucket privado. Lleva una firma en la query string, así que quien la tiene puede descargar (o subir) ese objeto sin credenciales de AWS hasta que caduca, y el bucket nunca se hace público. La generas con tus propias claves, desde tu código o desde la AWS CLI, y puede durar desde 1 segundo hasta 7 días. En esta guía verás cómo funciona, qué significa cada parámetro X-Amz-*, cuánto puede durar, código para descargas y subidas y los errores que más te vas a encontrar. Los límites salen de la documentación de AWS y Cloudflare a octubre de 2026.

URLs prefirmadas de S3 en resumen

Cómo funciona una URL prefirmada

1. Tu código (o la CLI) toma el bucket, la clave del objeto, el método HTTP y un tiempo de caducidad.
2. El SDK firma esos valores con tu secret access key usando AWS Signature Version 4. En este paso no se envía nada a S3.
3. Entregas la URL resultante a quien la necesite: un navegador, un compañero, una app móvil.
4. Cuando la usan, S3 recalcula la firma con el secreto de la access key que aparece en la URL. Si coincide, no ha caducado y quien firmó tiene permiso para esa operación, la petición pasa.

La URL lleva los permisos de quien la firmó. AWS lo deja claro: si el usuario o rol IAM que generó la URL no puede leer el objeto, la URL devuelve 403 por muy válida que sea la firma.

Qué significan los parámetros X-Amz

Una URL prefirmada con SigV4 tiene este aspecto (con saltos de línea añadidos):

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

Si cambias cualquier parte firmada (la clave, el método, la caducidad o una cabecera firmada), la firma deja de coincidir. Fíjate también en lo que la URL deja ver en claro: el nombre del bucket, la clave completa del objeto y tu access key ID. La clave secreta nunca va en la URL.

Cuánto dura una URL prefirmada

El límite depende de las credenciales con que la firmas:

Esto explica la sorpresa más común: pides 7 días desde una función Lambda o una instancia EC2 y el enlace muere en una hora o unas pocas horas. La URL dura lo que duran las credenciales que hay detrás. Si necesitas enlaces largos, fírmalos con un usuario IAM dedicado que solo tenga acceso de lectura a ese bucket.

S3 comprueba la caducidad al empezar cada petición. Una descarga grande que arranca un segundo antes del límite termina con normalidad, pero un reintento después del límite falla con AccessDenied y el mensaje “Request has expired”. Si pides más de 604.800 segundos, la petición se rechaza directamente.

Cómo generar una URL prefirmada

AWS CLI

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

El comando firma una URL de descarga (GET). Por defecto dura 3.600 segundos y como máximo 604.800. Las versiones actuales de la CLI usan siempre SigV4, así que asegúrate de tener una región configurada. Para URLs de subida necesitas un 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,
)

Indica signature_version='s3v4' de forma explícita. La referencia de boto3 avisa de que, por compatibilidad, si no lo haces puede firmar con la antigua Signature Version 2 en las regiones que aún la aceptan, y eso descarta sin avisar algunos parámetros y cabeceras como Range. ResponseContentDisposition es opcional: hace que el navegador guarde el archivo con un nombre limpio en vez de abrirlo.

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

Si no pasas expiresIn, el presigner de JavaScript usa 900 segundos (15 minutos).

URLs prefirmadas de subida (PUT)

La misma idea funciona en sentido contrario. Firmas un PutObject para una clave y quien tenga la URL puede escribir ese objeto. El archivo va directo de su dispositivo al bucket y tu servidor nunca toca los bytes. Si ya existe un objeto con esa clave, se sustituye.

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

Añadir content-type a signableHeaders ata la URL a ese tipo, así que una subida con otro Content-Type se rechaza. En boto3 el equivalente es generate_presigned_url('put_object', Params={'Bucket': ..., 'Key': ..., 'ContentType': 'application/pdf'}), y el cliente tiene que enviar la misma cabecera.

Tres cosas que revisar antes de subir desde un navegador:

• CORS. El bucket necesita una regla CORS que permita tu origen y el método PUT. Para subidas multiparte también debe exponer la cabecera ETag, porque el navegador tiene que leerla de cada parte.
• Clave fija. Genera en el servidor una clave única (por ejemplo, con un prefijo UUID) para que nadie pueda sobrescribir el archivo de otra persona.
• Checksums. Los SDK actuales de AWS añaden por defecto un checksum CRC a las subidas. Si las subidas prefirmadas fallan contra un proveedor compatible con S3 con errores de firma o de checksum, configura requestChecksumCalculation: 'WHEN_REQUIRED' en el cliente.

El POST prefirmado es otro mecanismo, pensado para formularios HTML, con una política que puede limitar tamaño y tipo. No todos los proveedores compatibles con S3 lo admiten (R2 no), así que el PUT prefirmado es la opción más portable.

Archivos grandes: subidas multiparte prefirmadas

Un único PUT a S3 tiene un límite de 5 GB, y AWS recomienda multiparte a partir de unos 100 MB. La subida multiparte divide el archivo en hasta 10.000 partes, de 5 MiB a 5 GiB cada una salvo la última, que se suben por separado, en paralelo y con reintentos por parte. La firma va por parte: el servidor inicia la subida, firma una URL UploadPart por cada parte, el navegador envía cada trozo y devuelve su ETag, y el servidor completa la subida.

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

Añade una regla de ciclo de vida que aborte las subidas multiparte incompletas pasados unos días; si no, las partes abandonadas siguen ocupando almacenamiento facturable.

URLs prefirmadas en R2, B2, Spaces y Wasabi

Los proveedores que implementan la API de S3 con SigV4 aceptan el mismo código: solo cambias el endpoint, la región y las claves. Los detalles varían, así que revisa la documentación de cada uno:

• Cloudflare R2 admite GET, HEAD, PUT y DELETE prefirmados, con una caducidad de 1 segundo a 7 días. No admite POST prefirmado, y las URLs prefirmadas solo funcionan en el dominio de la API S3 (<ACCOUNT_ID>.r2.cloudflarestorage.com), no en dominios personalizados. Usa region: 'auto'.
• Backblaze B2 indica que su API compatible con S3 admite URLs prefirmadas generadas con la AWS CLI o los SDK.
• DigitalOcean Spaces y Wasabi funcionan con las mismas llamadas del SDK apuntando a sus endpoints.

Para comparar lo que cuesta cada proveedor, mira la comparativa de S3, R2, Spaces, Wasabi y B2.

Errores comunes con URLs prefirmadas y cómo resolverlos

Los proxies corporativos que reescriben cabeceras o la query string también rompen las firmas. Si una URL funciona desde una red y no desde otra, prueba sin el proxy.

Buenas prácticas de seguridad

AWS llama a las URLs prefirmadas tokens al portador y recomienda protegerlas. En la práctica:

• Que duren poco. Minutos para subidas y archivos sensibles, horas para descargas normales. Genera una nueva cuando alguien vuelva a necesitar el archivo.
• Firma con una identidad acotada. Un usuario o rol IAM dedicado que solo pueda leer (o solo escribir) en el prefijo en cuestión limita el daño si se filtra un enlace.
• Añade límites en la política del bucket. La condición s3:signatureAge rechaza firmas más antiguas de cierta edad y aws:SourceIp restringe desde qué redes se pueden usar.
• No las guardes en logs. Una URL prefirmada completa en logs, analítica o un chat es una credencial válida hasta que caduca.
• Ten en cuenta lo que no tienen. No hay contraseña, ni contador de descargas, ni revocación por enlace, así que pon una aplicación delante si necesitas eso.

Para la parte de compartir en detalle, con opciones que añaden esos controles, lee cómo compartir archivos de S3 sin hacer público el bucket.

Cómo usa Nubbo las URLs prefirmadas

Nubbo se basa en este patrón. Cuando subes un archivo en el explorador, el servidor firma un PUT (o, a partir de 100 MB, una subida multiparte con tres partes en paralelo) y tu navegador envía los bytes directamente a tu bucket. Las descargas de un solo archivo usan URLs GET prefirmadas válidas durante una hora. Tus claves de acceso se guardan cifradas con AES-256-GCM y solo se usan en el servidor para firmar.

Los enlaces para compartir añaden lo que les falta a las URLs prefirmadas: contraseña, fecha de caducidad y límite de descargas opcionales que Nubbo comprueba antes de emitir una URL de vida corta, y puedes desactivar un enlace cuando quieras. Las descargas en ZIP de varios archivos las monta tu navegador, que descarga cada archivo directamente de tu bucket: Nubbo no ve el contenido. Una excepción, para ser claros: las miniaturas se guardan en tu propio bucket, en .nubbo-thumbs/. Funciona igual con Amazon S3, Cloudflare R2, DigitalOcean Spaces, Wasabi, Backblaze B2 y endpoints compatibles con S3 accesibles públicamente.