README.md
1# AWS proxy module
2
3[](https://travis-ci.com/anomalizer/ngx_aws_auth)
4 [](https://gitter.im/ngx_aws_auth/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link)
5
6This nginx module can proxy requests to authenticated S3 backends using Amazon's
7V4 authentication API. The first version of this module was written for the V2
8authentication protocol and can be found in the *AuthV2* branch.
9
10## License
11This project uses the same license as ngnix does i.e. the 2 clause BSD / simplified BSD / FreeBSD license
12
13## Usage example
14
15Implements proxying of authenticated requests to S3.
16
17```nginx
18 server {
19 listen 8000;
20
21 aws_access_key your_aws_access_key; # Example AKIDEXAMPLE
22 aws_key_scope scope_of_generated_signing_key; #Example 20150830/us-east-1/service/aws4_request
23 aws_signing_key signing_key_generated_using_script; #Example L4vRLWAO92X5L3Sqk5QydUSdB0nC9+1wfqLMOKLbRp4=
24 aws_s3_bucket your_s3_bucket;
25
26 location / {
27 aws_sign;
28 proxy_pass http://your_s3_bucket.s3.amazonaws.com;
29 }
30
31 # This is an example that does not use the server root for the proxy root
32 location /myfiles {
33
34 rewrite /myfiles/(.*) /$1 break;
35 proxy_pass http://your_s3_bucket.s3.amazonaws.com/$1;
36
37 aws_access_key your_aws_access_key;
38 aws_key_scope scope_of_generated_signing_key;
39 aws_signing_key signing_key_generated_using_script;
40 }
41
42 # This is an example that use specific s3 endpoint, default endpoint is s3.amazonaws.com
43 location /s3_beijing {
44
45 rewrite /s3_beijing/(.*) /$1 break;
46 proxy_pass http://your_s3_bucket.s3.cn-north-1.amazonaws.com.cn/$1;
47
48 aws_sign;
49 aws_endpoint "s3.cn-north-1.amazonaws.com.cn";
50 aws_access_key your_aws_access_key;
51 aws_key_scope scope_of_generated_signing_key;
52 aws_signing_key signing_key_generated_using_script;
53 }
54 }
55```
56
57## Security considerations
58The V4 protocol does not need access to the actual secret keys that one obtains
59from the IAM service. The correct way to use the IAM key is to actually generate
60a scoped signing key and use this signing key to access S3. This nginx module
61requires the signing key and not the actual secret key. It is an insecure practise
62to let the secret key reside on your nginx server.
63
64Note that signing keys have a validity of just one week. Hence, they need to
65be refreshed constantly. Please useyour favourite configuration management
66system such as saltstack, puppet, chef, etc. etc. to distribute the signing
67keys to your nginx clusters. Do not forget to HUP the server after placing the new
68signing key as nginx reads the configuration only at startup time.
69
70A standalone python script has been provided to generate the signing key
71```
72./generate_signing_key -h
73usage: generate_signing_key [-h] -k SECRET_KEY -r REGION [-s SERVICE]
74 [-d DATE] [--no-base64] [-v]
75
76Generate AWS S3 signing key in it's base64 encoded form
77
78optional arguments:
79 -h, --help show this help message and exit
80 -k SECRET_KEY, --secret-key SECRET_KEY
81 The secret key generated using AWS IAM. Do not confuse
82 this with the access key id
83 -r REGION, --region REGION
84 The AWS region where this key would be used. Example:
85 us-east-1
86 -s SERVICE, --service SERVICE
87 The AWS service for which this key would be used.
88 Example: s3
89 -d DATE, --date DATE The date on which this key is generated in yyyymmdd
90 format
91 --no-base64 Disable output as a base64 encoded string. This NOT
92 recommended
93 -v, --verbose Produce verbose output on stderr
94
95
96./generate_signing_key -k wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY -r us-east-1
97L4vRLWAO92X5L3Sqk5QydUSdB0nC9+1wfqLMOKLbRp4=
9820160902/us-east-1/s3/aws4_request
99
100```
101## Supported environments
102This plugin is tested against a variety of nginx versions, compilers, OS versions and hardware architectures. Take a look at the .travis.yml file or the latest travis build status to see the versions that the plugin has been tested against
103
104
105## Known limitations
106The 2.x version of the module currently only has support for GET and HEAD calls. This is because
107signing request body is complex and has not yet been implemented.
108
109
110
111## Credits
112Original idea based on http://nginx.org/pipermail/nginx/2010-February/018583.html and suggestion of moving to variables rather than patching the proxy module.
113
114Subsequent contributions can be found in the commit logs of the project.
115
){kind=link}
){kind=link}