1 | aws4
|
2 | ----
|
3 |
|
4 | [![Build Status](https://api.travis-ci.org/mhart/aws4.png?branch=master)](https://travis-ci.org/github/mhart/aws4)
|
5 |
|
6 | A small utility to sign vanilla Node.js http(s) request options using Amazon's
|
7 | [AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
|
8 |
|
9 | If you want to sign and send AWS requests in a modern browser, or an environment like [Cloudflare Workers](https://developers.cloudflare.com/workers/), then check out [aws4fetch](https://github.com/mhart/aws4fetch) – otherwise you can also bundle this library for use [in older browsers](./browser).
|
10 |
|
11 | The only AWS service that *doesn't* support v4 as of 2020-05-22 is
|
12 | [SimpleDB](https://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/SDB_API.html)
|
13 | (it only supports [AWS Signature Version 2](https://github.com/mhart/aws2)).
|
14 |
|
15 | It also provides defaults for a number of core AWS headers and
|
16 | request parameters, making it very easy to query AWS services, or
|
17 | build out a fully-featured AWS library.
|
18 |
|
19 | Example
|
20 | -------
|
21 |
|
22 | ```javascript
|
23 | var http = require('https')
|
24 | var aws4 = require('aws4')
|
25 |
|
26 | // to illustrate usage, we'll create a utility function to request and pipe to stdout
|
27 | function request(opts) { http.request(opts, function(res) { res.pipe(process.stdout) }).end(opts.body || '') }
|
28 |
|
29 | // aws4 will sign an options object as you'd pass to http.request, with an AWS service and region
|
30 | var opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object', service: 's3', region: 'us-west-1' }
|
31 |
|
32 | // aws4.sign() will sign and modify these options, ready to pass to http.request
|
33 | aws4.sign(opts, { accessKeyId: '', secretAccessKey: '' })
|
34 |
|
35 | // or it can get credentials from process.env.AWS_ACCESS_KEY_ID, etc
|
36 | aws4.sign(opts)
|
37 |
|
38 | // for most AWS services, aws4 can figure out the service and region if you pass a host
|
39 | opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object' }
|
40 |
|
41 | // usually it will add/modify request headers, but you can also sign the query:
|
42 | opts = { host: 'my-bucket.s3.amazonaws.com', path: '/?X-Amz-Expires=12345', signQuery: true }
|
43 |
|
44 | // and for services with simple hosts, aws4 can infer the host from service and region:
|
45 | opts = { service: 'sqs', region: 'us-east-1', path: '/?Action=ListQueues' }
|
46 |
|
47 | // and if you're using us-east-1, it's the default:
|
48 | opts = { service: 'sqs', path: '/?Action=ListQueues' }
|
49 |
|
50 | aws4.sign(opts)
|
51 | console.log(opts)
|
52 | /*
|
53 | {
|
54 | host: 'sqs.us-east-1.amazonaws.com',
|
55 | path: '/?Action=ListQueues',
|
56 | headers: {
|
57 | Host: 'sqs.us-east-1.amazonaws.com',
|
58 | 'X-Amz-Date': '20121226T061030Z',
|
59 | Authorization: 'AWS4-HMAC-SHA256 Credential=ABCDEF/20121226/us-east-1/sqs/aws4_request, ...'
|
60 | }
|
61 | }
|
62 | */
|
63 |
|
64 | // we can now use this to query AWS
|
65 | request(opts)
|
66 | /*
|
67 | <?xml version="1.0"?>
|
68 | <ListQueuesResponse xmlns="https://queue.amazonaws.com/doc/2012-11-05/">
|
69 | ...
|
70 | */
|
71 |
|
72 | // aws4 can infer the HTTP method if a body is passed in
|
73 | // method will be POST and Content-Type: 'application/x-www-form-urlencoded; charset=utf-8'
|
74 | request(aws4.sign({ service: 'iam', body: 'Action=ListGroups&Version=2010-05-08' }))
|
75 | /*
|
76 | <ListGroupsResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
|
77 | ...
|
78 | */
|
79 |
|
80 | // you can specify any custom option or header as per usual
|
81 | request(aws4.sign({
|
82 | service: 'dynamodb',
|
83 | region: 'ap-southeast-2',
|
84 | method: 'POST',
|
85 | path: '/',
|
86 | headers: {
|
87 | 'Content-Type': 'application/x-amz-json-1.0',
|
88 | 'X-Amz-Target': 'DynamoDB_20120810.ListTables'
|
89 | },
|
90 | body: '{}'
|
91 | }))
|
92 | /*
|
93 | {"TableNames":[]}
|
94 | ...
|
95 | */
|
96 |
|
97 | // see example.js for examples with other services
|
98 | ```
|
99 |
|
100 | API
|
101 | ---
|
102 |
|
103 | ### aws4.sign(requestOptions, [credentials])
|
104 |
|
105 | This calculates and populates the `Authorization` header of
|
106 | `requestOptions`, and any other necessary AWS headers and/or request
|
107 | options. Returns `requestOptions` as a convenience for chaining.
|
108 |
|
109 | `requestOptions` is an object holding the same options that the node.js
|
110 | [http.request](https://nodejs.org/docs/latest/api/http.html#http_http_request_options_callback)
|
111 | function takes.
|
112 |
|
113 | The following properties of `requestOptions` are used in the signing or
|
114 | populated if they don't already exist:
|
115 |
|
116 | - `hostname` or `host` (will try to be determined from `service` and `region` if not given)
|
117 | - `method` (will use `'GET'` if not given or `'POST'` if there is a `body`)
|
118 | - `path` (will use `'/'` if not given)
|
119 | - `body` (will use `''` if not given)
|
120 | - `service` (will try to be calculated from `hostname` or `host` if not given)
|
121 | - `region` (will try to be calculated from `hostname` or `host` or use `'us-east-1'` if not given)
|
122 | - `headers['Host']` (will use `hostname` or `host` or be calculated if not given)
|
123 | - `headers['Content-Type']` (will use `'application/x-www-form-urlencoded; charset=utf-8'`
|
124 | if not given and there is a `body`)
|
125 | - `headers['Date']` (used to calculate the signature date if given, otherwise `new Date` is used)
|
126 |
|
127 | Your AWS credentials (which can be found in your
|
128 | [AWS console](https://portal.aws.amazon.com/gp/aws/securityCredentials))
|
129 | can be specified in one of two ways:
|
130 |
|
131 | - As the second argument, like this:
|
132 |
|
133 | ```javascript
|
134 | aws4.sign(requestOptions, {
|
135 | secretAccessKey: "<your-secret-access-key>",
|
136 | accessKeyId: "<your-access-key-id>",
|
137 | sessionToken: "<your-session-token>"
|
138 | })
|
139 | ```
|
140 |
|
141 | - From `process.env`, such as this:
|
142 |
|
143 | ```
|
144 | export AWS_ACCESS_KEY_ID="<your-access-key-id>"
|
145 | export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
|
146 | export AWS_SESSION_TOKEN="<your-session-token>"
|
147 | ```
|
148 |
|
149 | (will also use `AWS_ACCESS_KEY` and `AWS_SECRET_KEY` if available)
|
150 |
|
151 | The `sessionToken` property and `AWS_SESSION_TOKEN` environment variable are optional for signing
|
152 | with [IAM STS temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html).
|
153 |
|
154 | Installation
|
155 | ------------
|
156 |
|
157 | With [npm](https://www.npmjs.com/) do:
|
158 |
|
159 | ```
|
160 | npm install aws4
|
161 | ```
|
162 |
|
163 | Can also be used [in the browser](./browser).
|
164 |
|
165 | Thanks
|
166 | ------
|
167 |
|
168 | Thanks to [@jed](https://github.com/jed) for his
|
169 | [dynamo-client](https://github.com/jed/dynamo-client) lib where I first
|
170 | committed and subsequently extracted this code.
|
171 |
|
172 | Also thanks to the
|
173 | [official node.js AWS SDK](https://github.com/aws/aws-sdk-js) for giving
|
174 | me a start on implementing the v4 signature.
|