aws4

A small utility to sign vanilla Node.js http(s) request options using Amazon's AWS Signature Version 4.

If you want to sign and send AWS requests in a modern browser, or an environment like Cloudflare Workers, then check out aws4fetch – otherwise you can also bundle this library for use in older browsers.

The only AWS service that doesn't support v4 as of 2020-05-22 is SimpleDB (it only supports AWS Signature Version 2).

It also provides defaults for a number of core AWS headers and request parameters, making it very easy to query AWS services, or build out a fully-featured AWS library.

# Example

var https = require('https')
var aws4 = require('aws4')
// to illustrate usage, we'll create a utility function to request and pipe to stdout
function request(opts) { https.request(opts, function(res) { res.pipe(process.stdout) }).end(opts.body || '') }
// aws4 will sign an options object as you'd pass to http.request, with an AWS service and region
var opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object', service: 's3', region: 'us-west-1' }
// aws4.sign() will sign and modify these options, ready to pass to http.request
aws4.sign(opts, { accessKeyId: '', secretAccessKey: '' })
// or it can get credentials from process.env.AWS_ACCESS_KEY_ID, etc
aws4.sign(opts)
// for most AWS services, aws4 can figure out the service and region if you pass a host
opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object' }
// usually it will add/modify request headers, but you can also sign the query:
opts = { host: 'my-bucket.s3.amazonaws.com', path: '/?X-Amz-Expires=12345', signQuery: true }
// and for services with simple hosts, aws4 can infer the host from service and region:
opts = { service: 'sqs', region: 'us-east-1', path: '/?Action=ListQueues' }
// and if you're using us-east-1, it's the default:
opts = { service: 'sqs', path: '/?Action=ListQueues' }
aws4.sign(opts)
console.log(opts)
/*
{
host: 'sqs.us-east-1.amazonaws.com',
path: '/?Action=ListQueues',
headers: {
Host: 'sqs.us-east-1.amazonaws.com',
'X-Amz-Date': '20121226T061030Z',
Authorization: 'AWS4-HMAC-SHA256 Credential=ABCDEF/20121226/us-east-1/sqs/aws4_request, ...'
}
}
*/
// we can now use this to query AWS
request(opts)
/*
<?xml version="1.0"?>
<ListQueuesResponse xmlns="https://queue.amazonaws.com/doc/2012-11-05/">
...
*/
// aws4 can infer the HTTP method if a body is passed in
// method will be POST and Content-Type: 'application/x-www-form-urlencoded; charset=utf-8'
request(aws4.sign({ service: 'iam', body: 'Action=ListGroups&Version=2010-05-08' }))
/*
<ListGroupsResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
...
*/
// you can specify any custom option or header as per usual
request(aws4.sign({
service: 'dynamodb',
region: 'ap-southeast-2',
method: 'POST',
path: '/',
headers: {
'Content-Type': 'application/x-amz-json-1.0',
'X-Amz-Target': 'DynamoDB_20120810.ListTables'
},
body: '{}'
}))
/*
{"TableNames":[]}
...
*/
// The raw RequestSigner can be used to generate CodeCommit Git passwords
var signer = new aws4.RequestSigner({
service: 'codecommit',
host: 'git-codecommit.us-east-1.amazonaws.com',
method: 'GIT',
path: '/v1/repos/MyAwesomeRepo',
})
var password = signer.getDateTime() + 'Z' + signer.signature()
// see example.js for examples with other services

# API

## aws4.sign(requestOptions, [credentials])

Calculates and populates any necessary AWS headers and/or request options on `requestOptions`. Returns `requestOptions` as a convenience for chaining.

`requestOptions` is an object holding the same options that the Node.js http.request function takes.

The following properties of `requestOptions` are used in the signing or populated if they don't already exist:

- `hostname` or `host` (will try to be determined from `service` and `region` if not given)
- `method` (will use ‘'GET’`if not given or`'POST'`if there is a`body`) -`path`(will use`'/'`if not given) -`body`(will use`''`if not given) -`service`(will try to be calculated from`hostname`or`host`if not given) -`region`(will try to be calculated from`hostname`or`host`or use`'us-east-1'`if not given) -`signQuery`(to sign the query instead of adding an`Authorization`header, defaults to false) -`headers['Host']`(will use`hostname`or`host`or be calculated if not given) -`headers['Content-Type']`(will use`'application/x-www-form-urlencoded; charset=utf-8'`if not given and there is a`body`) -`headers['Date']`(used to calculate the signature date if given, otherwise`new Date` is used)

Your AWS credentials (which can be found in your AWS console) can be specified in one of two ways:

- As the second argument, like this:

aws4.sign(requestOptions, {
secretAccessKey: "<your-secret-access-key>",
accessKeyId: "<your-access-key-id>",
sessionToken: "<your-session-token>"
})

- From `process.env`, such as this:

export AWS_ACCESS_KEY_ID="<your-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
export AWS_SESSION_TOKEN="<your-session-token>"

(will also use `AWS_ACCESS_KEY` and `AWS_SECRET_KEY` if available)

The `sessionToken` property and `AWS_SESSION_TOKEN` environment variable are optional for signing with IAM STS temporary credentials.

# Installation

With npm do:

npm install aws4

Can also be used in the browser.

# Thanks

Thanks to @jed for his dynamo-client lib where I first committed and subsequently extracted this code.

Also thanks to the official Node.js AWS SDK for giving me a start on implementing the v4 signature.