@aws-sdk/s3-request-presigner

What is @aws-sdk/s3-request-presigner?

The @aws-sdk/s3-request-presigner package is part of the AWS SDK for JavaScript (v3) and is used to generate pre-signed URLs for AWS S3 objects. This allows clients to perform operations on S3 objects, such as GET or PUT, without requiring AWS credentials, by providing a URL that includes a signature. This is useful for providing temporary access to private objects, uploading files directly from a browser, or any other operation that you want to allow without giving out AWS credentials.

What are @aws-sdk/s3-request-presigner's main functionalities?

Generate pre-signed GET URL

This feature allows you to create a pre-signed URL for a GET request on an S3 object. The URL will be valid for the duration specified by 'expiresIn' (in seconds).

const { S3Client, GetObjectCommand } = require('@aws-sdk/client-s3');
const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');

const s3Client = new S3Client({ region: 'us-west-2' });
const getObjectParams = { Bucket: 'my-bucket', Key: 'my-object-key' };
const command = new GetObjectCommand(getObjectParams);

const signedUrl = await getSignedUrl(s3Client, command, { expiresIn: 3600 });
console.log('The signed URL is:', signedUrl);

Generate pre-signed PUT URL

This feature allows you to create a pre-signed URL for a PUT request to upload an object to S3. The URL will be valid for the duration specified by 'expiresIn' (in seconds).

const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');

const s3Client = new S3Client({ region: 'us-west-2' });
const putObjectParams = { Bucket: 'my-bucket', Key: 'my-object-key' };
const command = new PutObjectCommand(putObjectParams);

const signedUrl = await getSignedUrl(s3Client, command, { expiresIn: 3600 });
console.log('The signed URL is:', signedUrl);

Other packages similar to @aws-sdk/s3-request-presigner

aws-sdk

The 'aws-sdk' package is the previous version of the AWS SDK for JavaScript. It also supports generating pre-signed URLs for S3 objects, but it is not modular like the newer '@aws-sdk/s3-request-presigner' and includes the entire AWS SDK.

README

@aws-sdk/s3-request-presigner

This package provides a presigner based on signature V4 that will attempt to generate signed url for S3.

Get Presigned URL with Client and Command

You can generated presigned url from S3 client and command. Here's the example:

import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
const client = new S3Client(clientParams);
const command = new GetObjectCommand(getObjectParams);
const url = await getSignedUrl(client, command, { expiresIn: 3600 });

You can get signed URL for other S3 operations too, like PutObjectCommand. expiresIn config from the examples above is optional. If not set, it's default at 900.

If you already have a request, you can pre-sign the request following the section bellow.

Get Presigned URL from an Existing Request

import { S3RequestPresigner } from "@aws-sdk/s3-request-presigner";
import { Sha256 } from "@aws-crypto/sha256-browser";
import { Hash } from "@aws-sdk/hash-node";
const signer = new S3RequestPresigner({
  region: regionProvider,
  credentials: credentialsProvider,
  sha256: Hash.bind(null, "sha256"), // In Node.js
  //sha256: Sha256 // In browsers
});
const presigned = await signer.presign(request);

To avoid redundant construction parameters when instantiating the s3 presigner, you can simply spread the configuration of an existing s3 client and supply it to the presigner's constructor.

//s3 is instantiated from S3Client from @aws-sdk/client-s3-* packages
const signer = new S3RequestPresigner({
  ...s3.config,
});

Get Presigned URL with headers that cannot be signed

By using the getSignedUrl with a S3Client you are able to sign your headers, improving the security of presigned url. Importantly, if you want to sign any x-amz-* headers (like the ChecksumSHA256 header in this example), you need to provide those headers to the set of unhoistableHeaders in the getSignedUrl params which will force those headers to be present in the upload request.

import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const s3Client = new S3Client({ region: "us-east-1" });
const command = new PutObjectCommand({
  Bucket: bucket,
  Key: key,
  ChecksumSHA256: sha,
});

const presigned = getSignedUrl(s3Client, command, {
  expiresIn: expiration,
  // Set of all x-amz-* headers you wish to have signed
  unhoistableHeaders: new Set(["x-amz-checksum-sha256"]),
});

Get Presigned URL with headers that should be signed

For headers that are not x-amz-* you are able to add them to the set of signableHeaders to be enforced in the presigned urls request.

import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const s3Client = new S3Client({ region: "us-east-1" });
const command = new PutObjectCommand({
  Bucket: bucket,
  Key: key,
  ContentType: contentType,
});

const presigned = getSignedUrl(s3Client, command, {
  signableHeaders: new Set(["content-type"]),
  expiresIn: expiration,
});

PutObject with use of hoistableHeaders

hoistableHeaders overrides the default behavior of not hoisting any headers that begin with x-amz-*.

// example: Server Side Encryption headers
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const params = {
  Key: "...",
  Bucket: "...",
  ServerSideEncryption: "aws:kms",
  SSEKMSKeyId: "arn:aws:kms:us-west-2:0000:key/abcd-1234-abcd",
};
const s3Client = new S3Client();
const command = new PutObjectCommand(params);

const preSignedUrl = await getSignedUrl(s3Client, command, {
  hoistableHeaders: new Set(["x-amz-server-side-encryption", "x-amz-server-side-encryption-aws-kms-key-id"]),
});

Changelog

3.691.0 (2024-11-13)

Features

• client-accessanalyzer: This release adds support for policy validation and external access findings for resource control policies (RCP). IAM Access Analyzer helps you author functional and secure RCPs and awareness that a RCP may restrict external access. Updated service API, documentation, and paginators. (8ee2e53)
• client-application-signals: Amazon CloudWatch Application Signals now supports creating Service Level Objectives with burn rates. Users can now create or update SLOs with burn rate configurations to meet their specific business requirements. (e176892)
• client-b2bi: This release adds a GenerateMapping API to allow generation of JSONata or XSLT transformer code based on input and output samples. (79297bb)
• client-billing: Today, AWS announces the general availability of ListBillingViews API in the AWS SDKs, to enable AWS Billing Conductor (ABC) users to create proforma Cost and Usage Reports (CUR) programmatically. (b46415d)
• client-cloudtrail: This release adds a new API GenerateQuery that generates a query from a natural language prompt about the event data in your event data store. This operation uses generative artificial intelligence (generative AI) to produce a ready-to-use SQL query from the prompt. (93b16b2)
• client-dynamodb: This release includes supports the new WarmThroughput feature for DynamoDB. You can now provide an optional WarmThroughput attribute for CreateTable or UpdateTable APIs to pre-warm your table or global secondary index. You can also use DescribeTable to see the latest WarmThroughput value. (0ca3c21)
• client-ec2: This release adds the source AMI details in DescribeImages API (67fa666)
• client-internetmonitor: Add new query type Routing_Suggestions regarding querying interface (4f49de2)
• client-mediaconvert: This release adds support for ARN inputs in the Kantar credentials secrets name field and the MSPR field to the manifests for PlayReady DRM protected outputs. (6c46bda)
• client-organizations: Add support for policy operations on the Resource Control Polices. (d87a984)
• clients: update client endpoints as of 2024-11-13 (24e23f9)