The aws4 npm package is a library that signs and prepares requests using AWS Signature Version 4. It is used to authenticate and send requests to AWS services that require signing, such as S3, EC2, SES, and others. It can be used both on the server side with Node.js and on the client side in browsers.
Signing HTTP requests
This feature allows you to sign an HTTP request with AWS Signature Version 4. The code sample demonstrates how to sign a GET request to an AWS service.
{"http": "require('http'), "aws4": "require('aws4'), "opts": { "host": "example.amazonaws.com", "path": "/path/to/resource", "method": "GET" }, "signedOpts": "aws4.sign(opts, { accessKeyId: 'YOURKEY', secretAccessKey: 'YOURSECRET' })", "request": "http.request(signedOpts, function(response) { /* handle response */ })"}Signing requests for AWS Elasticsearch
This feature is used to sign requests to AWS Elasticsearch service. The code sample shows how to sign a GET request to perform a search operation on an Elasticsearch index.
{"aws4": "require('aws4'), "https": "require('https'), "opts": { "host": "search-your-domain.region.es.amazonaws.com", "path": "/your-index/_search", "method": "GET" }, "signedOpts": "aws4.sign(opts, { accessKeyId: 'YOURKEY', secretAccessKey: 'YOURSECRET' })", "request": "https.request(signedOpts, function(response) { /* handle response */ })"}Signing requests for AWS S3
This feature is used to sign requests to AWS S3 service. The code sample illustrates how to sign a GET request to retrieve an object from an S3 bucket.
{"aws4": "require('aws4'), "https": "require('https'), "opts": { "host": "s3.amazonaws.com", "path": "/bucket/key", "method": "GET" }, "signedOpts": "aws4.sign(opts, { accessKeyId: 'YOURKEY', secretAccessKey: 'YOURSECRET' })", "request": "https.request(signedOpts, function(response) { /* handle response */ })"}The AWS SDK for JavaScript is a comprehensive library for working with AWS services. It provides a higher-level abstraction over the AWS API compared to aws4. It includes automatic signing of requests, handling of retries, and direct methods for calling AWS services.
This package is specifically designed to create AWS Signature Version 4 signed requests. It is similar to aws4 but may have different API design or additional features for signing requests.
This is another package for signing AWS requests with Signature Version 4. It offers functionality similar to aws4 but might have variations in its API or additional utilities for request signing.
A small utility to sign vanilla node.js http(s) request options using Amazon's AWS Signature Version 4.
Can also be used in the browser.
This signature is supported by nearly all Amazon services, including S3, EC2, DynamoDB, Kinesis, Lambda, SQS, SNS, IAM, STS, RDS, CloudWatch, CloudWatch Logs, CodeDeploy, CloudFront, CloudTrail, ElastiCache, EMR, Glacier, CloudSearch, Elastic Load Balancing, Elastic Transcoder, CloudFormation, Elastic Beanstalk, Storage Gateway, Data Pipeline, Direct Connect, Redshift, OpsWorks, SES, SWF, AutoScaling, Mobile Analytics, Cognito Identity, Cognito Sync, Container Service, AppStream, Key Management Service, Config, CloudHSM, Route53 and Route53 Domains.
Indeed, the only AWS services that don't support v4 as of 2014-12-30 are Import/Export and SimpleDB (they only support 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.
var http = require('http'),
https = require('https'),
aws4 = require('aws4')
// given an options object you could pass to http.request
var opts = {host: 'sqs.us-east-1.amazonaws.com', path: '/?Action=ListQueues'}
// alternatively (as aws4 can infer the host):
opts = {service: 'sqs', region: 'us-east-1', path: '/?Action=ListQueues'}
// alternatively (as us-east-1 is default):
opts = {service: 'sqs', path: '/?Action=ListQueues'}
aws4.sign(opts) // assumes AWS credentials are available in process.env
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 using the standard node.js http API
http.request(opts, function(res) { res.pipe(process.stdout) }).end()
/*
<?xml version="1.0"?>
<ListQueuesResponse xmlns="http://queue.amazonaws.com/doc/2012-11-05/">
...
*/
// you can also pass AWS credentials in explicitly (otherwise taken from process.env)
aws4.sign(opts, {accessKeyId: '', secretAccessKey: ''})
// can also add the signature to query strings
aws4.sign({service: 's3', path: '/my-bucket?X-Amz-Expires=12345', signQuery: true})
// create a utility function to pipe to stdout (with https this time)
function request(o) { https.request(o, function(res) { res.pipe(process.stdout) }).end(o.body || '') }
// 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/">
...
*/
// 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":[]}
...
*/
// works with all other services that support Signature Version 4
request(aws4.sign({service: 's3', path: '/', signQuery: true}))
/*
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
...
*/
request(aws4.sign({service: 'ec2', path: '/?Action=DescribeRegions&Version=2014-06-15'}))
/*
<DescribeRegionsResponse xmlns="http://ec2.amazonaws.com/doc/2014-06-15/">
...
*/
request(aws4.sign({service: 'sns', path: '/?Action=ListTopics&Version=2010-03-31'}))
/*
<ListTopicsResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
...
*/
request(aws4.sign({service: 'sts', path: '/?Action=GetSessionToken&Version=2011-06-15'}))
/*
<GetSessionTokenResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
...
*/
request(aws4.sign({service: 'cloudsearch', path: '/?Action=ListDomainNames&Version=2013-01-01'}))
/*
<ListDomainNamesResponse xmlns="http://cloudsearch.amazonaws.com/doc/2013-01-01/">
...
*/
request(aws4.sign({service: 'ses', path: '/?Action=ListIdentities&Version=2010-12-01'}))
/*
<ListIdentitiesResponse xmlns="http://ses.amazonaws.com/doc/2010-12-01/">
...
*/
request(aws4.sign({service: 'autoscaling', path: '/?Action=DescribeAutoScalingInstances&Version=2011-01-01'}))
/*
<DescribeAutoScalingInstancesResponse xmlns="http://autoscaling.amazonaws.com/doc/2011-01-01/">
...
*/
request(aws4.sign({service: 'elasticloadbalancing', path: '/?Action=DescribeLoadBalancers&Version=2012-06-01'}))
/*
<DescribeLoadBalancersResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2012-06-01/">
...
*/
request(aws4.sign({service: 'cloudformation', path: '/?Action=ListStacks&Version=2010-05-15'}))
/*
<ListStacksResponse xmlns="http://cloudformation.amazonaws.com/doc/2010-05-15/">
...
*/
request(aws4.sign({service: 'elasticbeanstalk', path: '/?Action=ListAvailableSolutionStacks&Version=2010-12-01'}))
/*
<ListAvailableSolutionStacksResponse xmlns="http://elasticbeanstalk.amazonaws.com/docs/2010-12-01/">
...
*/
request(aws4.sign({service: 'rds', path: '/?Action=DescribeDBInstances&Version=2012-09-17'}))
/*
<DescribeDBInstancesResponse xmlns="http://rds.amazonaws.com/doc/2012-09-17/">
...
*/
request(aws4.sign({service: 'monitoring', path: '/?Action=ListMetrics&Version=2010-08-01'}))
/*
<ListMetricsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
...
*/
request(aws4.sign({service: 'redshift', path: '/?Action=DescribeClusters&Version=2012-12-01'}))
/*
<DescribeClustersResponse xmlns="http://redshift.amazonaws.com/doc/2012-12-01/">
...
*/
request(aws4.sign({service: 'cloudfront', path: '/2014-05-31/distribution'}))
/*
<DistributionList xmlns="http://cloudfront.amazonaws.com/doc/2014-05-31/">
...
*/
request(aws4.sign({service: 'elasticache', path: '/?Action=DescribeCacheClusters&Version=2014-07-15'}))
/*
<DescribeCacheClustersResponse xmlns="http://elasticache.amazonaws.com/doc/2014-07-15/">
...
*/
request(aws4.sign({service: 'elasticmapreduce', path: '/?Action=DescribeJobFlows&Version=2009-03-31'}))
/*
<DescribeJobFlowsResponse xmlns="http://elasticmapreduce.amazonaws.com/doc/2009-03-31">
...
*/
request(aws4.sign({service: 'route53', path: '/2013-04-01/hostedzone'}))
/*
<ListHostedZonesResponse xmlns="https://route53.amazonaws.com/doc/2013-04-01/">
...
*/
request(aws4.sign({service: 'appstream', path: '/applications'}))
/*
{"_links":{"curie":[{"href":"http://docs.aws.amazon.com/appstream/latest/...
...
*/
request(aws4.sign({service: 'cognito-sync', path: '/identitypools'}))
/*
{"Count":0,"IdentityPoolUsages":[],"MaxResults":16,"NextToken":null}
...
*/
request(aws4.sign({service: 'elastictranscoder', path: '/2012-09-25/pipelines'}))
/*
{"NextPageToken":null,"Pipelines":[]}
...
*/
request(aws4.sign({service: 'lambda', path: '/2014-11-13/functions/'}))
/*
{"Functions":[],"NextMarker":null}
...
*/
request(aws4.sign({service: 'ecs', path: '/?Action=ListClusters&Version=2014-11-13'}))
/*
<ListClustersResponse xmlns="http://ecs.amazonaws.com/doc/2014-11-13/">
...
*/
request(aws4.sign({service: 'glacier', path: '/-/vaults', headers: {'X-Amz-Glacier-Version': '2012-06-01'}}))
/*
{"Marker":null,"VaultList":[]}
...
*/
request(aws4.sign({service: 'storagegateway', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'StorageGateway_20120630.ListGateways'
}}))
/*
{"Gateways":[]}
...
*/
request(aws4.sign({service: 'datapipeline', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'DataPipeline.ListPipelines'
}}))
/*
{"hasMoreResults":false,"pipelineIdList":[]}
...
*/
request(aws4.sign({service: 'opsworks', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'OpsWorks_20130218.DescribeStacks'
}}))
/*
{"Stacks":[]}
...
*/
request(aws4.sign({service: 'route53domains', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'Route53Domains_v20140515.ListDomains'
}}))
/*
{"Domains":[]}
...
*/
request(aws4.sign({service: 'kinesis', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'Kinesis_20131202.ListStreams'
}}))
/*
{"HasMoreStreams":false,"StreamNames":[]}
...
*/
request(aws4.sign({service: 'cloudtrail', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'CloudTrail_20131101.DescribeTrails'
}}))
/*
{"trailList":[]}
...
*/
request(aws4.sign({service: 'logs', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'Logs_20140328.DescribeLogGroups'
}}))
/*
{"logGroups":[]}
...
*/
request(aws4.sign({service: 'codedeploy', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'CodeDeploy_20141006.ListApplications'
}}))
/*
{"applications":[]}
...
*/
request(aws4.sign({service: 'directconnect', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'OvertureService.DescribeConnections'
}}))
/*
{"connections":[]}
...
*/
request(aws4.sign({service: 'kms', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'TrentService.ListKeys'
}}))
/*
{"Keys":[],"Truncated":false}
...
*/
request(aws4.sign({service: 'config', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'StarlingDoveService.DescribeDeliveryChannels'
}}))
/*
{"DeliveryChannels":[]}
...
*/
request(aws4.sign({service: 'cloudhsm', body: '{}', headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'CloudHsmFrontendService.ListAvailableZones'
}}))
/*
{"AZList":["us-east-1a","us-east-1b","us-east-1c"]}
...
*/
request(aws4.sign({
service: 'swf',
body: '{"registrationStatus":"REGISTERED"}',
headers: {
'Content-Type': 'application/x-amz-json-1.0',
'X-Amz-Target': 'SimpleWorkflowService.ListDomains'
}
}))
/*
{"domainInfos":[]}
...
*/
request(aws4.sign({
service: 'cognito-identity',
body: '{"MaxResults": 1}',
headers: {
'Content-Type': 'application/x-amz-json-1.1',
'X-Amz-Target': 'AWSCognitoIdentityService.ListIdentityPools'
}
}))
/*
{"IdentityPools":[]}
...
*/
request(aws4.sign({
service: 'mobileanalytics',
path: '/2014-06-05/events',
body: JSON.stringify({events:[{
eventType: 'a',
timestamp: new Date().toISOString(),
session: {},
}]}),
headers: {
'Content-Type': 'application/json',
'X-Amz-Client-Context': JSON.stringify({
client: {client_id: 'a', app_title: 'a'},
custom: {},
env: {platform: 'a'},
services: {},
}),
}
}))
/*
(HTTP 202, empty response)
*/
// Generate CodeCommit Git access password
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()
This calculates and populates the Authorization header of
requestOptions, and any other necessary AWS headers and/or request
options. 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 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 be calculated from hostname or host if not given)region (will be calculated from hostname or host or use 'us-east-1' if not given)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:
aws4.sign(requestOptions, {
secretAccessKey: "<your-secret-access-key>",
accessKeyId: "<your-access-key-id>",
sessionToken: "<your-session-token>"
})
process.env, such as this:export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
export AWS_ACCESS_KEY_ID="<your-access-key-id>"
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.
With npm do:
npm install aws4
Can also be used in the browser.
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.
FAQs
Signs and prepares requests using AWS Signature Version 4
We found that aws4 demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.