| 1 |
.. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. |
| 2 |
|
| 3 |
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 |
| 4 |
International License (the "License"). You may not use this file except in compliance with the |
| 5 |
License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/. |
| 6 |
|
| 7 |
This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, |
| 8 |
either express or implied. See the License for the specific language governing permissions and |
| 9 |
limitations under the License. |
| 10 |
|
| 11 |
|
| 12 |
############## |
| 13 |
Presigned URLs |
| 14 |
############## |
| 15 |
|
| 16 |
A user who does not have AWS credentials or permission to access an S3 object |
| 17 |
can be granted temporary access by using a presigned URL. |
| 18 |
|
| 19 |
A presigned URL is generated by an AWS user who has access to the object. The |
| 20 |
generated URL is then given to the unauthorized user. The presigned URL can be |
| 21 |
entered in a browser or used by a program or HTML webpage. The credentials |
| 22 |
used by the presigned URL are those of the AWS user who generated the URL. |
| 23 |
|
| 24 |
A presigned URL remains valid for a limited period of time which is specified |
| 25 |
when the URL is generated. |
| 26 |
|
| 27 |
.. code-block:: python |
| 28 |
|
| 29 |
import logging |
| 30 |
import boto3 |
| 31 |
from botocore.exceptions import ClientError |
| 32 |
|
| 33 |
|
| 34 |
def create_presigned_url(bucket_name, object_name, expiration=3600): |
| 35 |
"""Generate a presigned URL to share an S3 object |
| 36 |
|
| 37 |
:param bucket_name: string |
| 38 |
:param object_name: string |
| 39 |
:param expiration: Time in seconds for the presigned URL to remain valid |
| 40 |
:return: Presigned URL as string. If error, returns None. |
| 41 |
""" |
| 42 |
|
| 43 |
# Generate a presigned URL for the S3 object |
| 44 |
s3_client = boto3.client('s3') |
| 45 |
try: |
| 46 |
response = s3_client.generate_presigned_url( |
| 47 |
'get_object', |
| 48 |
Params={'Bucket': bucket_name, 'Key': object_name}, |
| 49 |
ExpiresIn=expiration, |
| 50 |
) |
| 51 |
except ClientError as e: |
| 52 |
logging.error(e) |
| 53 |
return None |
| 54 |
|
| 55 |
# The response contains the presigned URL |
| 56 |
return response |
| 57 |
|
| 58 |
The user can download the S3 object by entering the presigned URL in a browser. |
| 59 |
A program or HTML page can download the S3 object by using the presigned URL |
| 60 |
as part of an HTTP GET request. |
| 61 |
|
| 62 |
The following code demonstrates using the Python ``requests`` package to |
| 63 |
perform a GET request. |
| 64 |
|
| 65 |
.. code-block:: python |
| 66 |
|
| 67 |
import requests # To install: pip install requests |
| 68 |
|
| 69 |
url = create_presigned_url('amzn-s3-demo-bucket', 'OBJECT_NAME') |
| 70 |
if url is not None: |
| 71 |
response = requests.get(url) |
| 72 |
|
| 73 |
|
| 74 |
Using presigned URLs to perform other S3 operations |
| 75 |
=================================================== |
| 76 |
|
| 77 |
The main purpose of presigned URLs is to grant a user temporary access to an |
| 78 |
S3 object. However, presigned URLs can be used to grant permission to perform |
| 79 |
additional operations on S3 buckets and objects. |
| 80 |
|
| 81 |
The ``create_presigned_url_expanded`` method shown below generates a presigned |
| 82 |
URL to perform a specified S3 operation. The method accepts the name of the S3 |
| 83 |
``Client`` method to perform, such as 'list_buckets' or 'get_bucket_location.' |
| 84 |
The parameters to pass to the method are specified in the |
| 85 |
``method_parameters`` dictionary argument. The HTTP method to use (GET, PUT, |
| 86 |
etc.) can be specified, but the AWS SDK for Python will automatically select |
| 87 |
the appropriate method so this argument is not normally required. |
| 88 |
|
| 89 |
.. code-block:: python |
| 90 |
|
| 91 |
import logging |
| 92 |
import boto3 |
| 93 |
from botocore.exceptions import ClientError |
| 94 |
|
| 95 |
|
| 96 |
def create_presigned_url_expanded( |
| 97 |
client_method_name, method_parameters=None, expiration=3600, http_method=None |
| 98 |
): |
| 99 |
"""Generate a presigned URL to invoke an S3.Client method |
| 100 |
|
| 101 |
Not all the client methods provided in the AWS Python SDK are supported. |
| 102 |
|
| 103 |
:param client_method_name: Name of the S3.Client method, e.g., 'list_buckets' |
| 104 |
:param method_parameters: Dictionary of parameters to send to the method |
| 105 |
:param expiration: Time in seconds for the presigned URL to remain valid |
| 106 |
:param http_method: HTTP method to use (GET, etc.) |
| 107 |
:return: Presigned URL as string. If error, returns None. |
| 108 |
""" |
| 109 |
|
| 110 |
# Generate a presigned URL for the S3 client method |
| 111 |
s3_client = boto3.client('s3') |
| 112 |
try: |
| 113 |
response = s3_client.generate_presigned_url( |
| 114 |
ClientMethod=client_method_name, |
| 115 |
Params=method_parameters, |
| 116 |
ExpiresIn=expiration, |
| 117 |
HttpMethod=http_method, |
| 118 |
) |
| 119 |
except ClientError as e: |
| 120 |
logging.error(e) |
| 121 |
return None |
| 122 |
|
| 123 |
# The response contains the presigned URL |
| 124 |
return response |
| 125 |
|
| 126 |
|
| 127 |
Generating a presigned URL to upload a file |
| 128 |
=========================================== |
| 129 |
|
| 130 |
A user who does not have AWS credentials to upload a file can use a |
| 131 |
presigned URL to perform the upload. The upload operation makes an HTTP POST |
| 132 |
request and requires additional parameters to be sent as part of the request. |
| 133 |
|
| 134 |
.. code-block:: python |
| 135 |
|
| 136 |
import logging |
| 137 |
import boto3 |
| 138 |
from botocore.exceptions import ClientError |
| 139 |
|
| 140 |
|
| 141 |
def create_presigned_post( |
| 142 |
bucket_name, object_name, fields=None, conditions=None, expiration=3600 |
| 143 |
): |
| 144 |
"""Generate a presigned URL S3 POST request to upload a file |
| 145 |
|
| 146 |
:param bucket_name: string |
| 147 |
:param object_name: string |
| 148 |
:param fields: Dictionary of prefilled form fields |
| 149 |
:param conditions: List of conditions to include in the policy |
| 150 |
:param expiration: Time in seconds for the presigned URL to remain valid |
| 151 |
:return: Dictionary with the following keys: |
| 152 |
url: URL to post to |
| 153 |
fields: Dictionary of form fields and values to submit with the POST |
| 154 |
:return: None if error. |
| 155 |
""" |
| 156 |
|
| 157 |
# Generate a presigned S3 POST URL |
| 158 |
s3_client = boto3.client('s3') |
| 159 |
try: |
| 160 |
response = s3_client.generate_presigned_post( |
| 161 |
bucket_name, |
| 162 |
object_name, |
| 163 |
Fields=fields, |
| 164 |
Conditions=conditions, |
| 165 |
ExpiresIn=expiration, |
| 166 |
) |
| 167 |
except ClientError as e: |
| 168 |
logging.error(e) |
| 169 |
return None |
| 170 |
|
| 171 |
# The response contains the presigned URL and required fields |
| 172 |
return response |
| 173 |
|
| 174 |
The generated presigned URL includes both a URL and additional fields that |
| 175 |
must be passed as part of the subsequent HTTP POST request. |
| 176 |
|
| 177 |
The following code demonstrates how to use the ``requests`` package with a |
| 178 |
presigned POST URL to perform a POST request to upload a file to S3. |
| 179 |
|
| 180 |
.. code-block:: python |
| 181 |
|
| 182 |
import requests # To install: pip install requests |
| 183 |
|
| 184 |
# Generate a presigned S3 POST URL |
| 185 |
object_name = 'OBJECT_NAME' |
| 186 |
response = create_presigned_post('amzn-s3-demo-bucket', object_name) |
| 187 |
if response is None: |
| 188 |
exit(1) |
| 189 |
|
| 190 |
# Demonstrate how another Python program can use the presigned URL to upload a file |
| 191 |
with open(object_name, 'rb') as f: |
| 192 |
files = {'file': (object_name, f)} |
| 193 |
http_response = requests.post(response['url'], data=response['fields'], files=files) |
| 194 |
# If successful, returns HTTP status code 204 |
| 195 |
logging.info(f'File upload HTTP status code: {http_response.status_code}') |
| 196 |
|
| 197 |
The presigned POST URL and fields values can also be used in an HTML page. |
| 198 |
|
| 199 |
.. code-block:: html |
| 200 |
|
| 201 |
<html> |
| 202 |
<head> |
| 203 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| 204 |
</head> |
| 205 |
<body> |
| 206 |
<!-- Copy the 'url' value returned by S3Client.generate_presigned_post() --> |
| 207 |
<form action="URL_VALUE" method="post" enctype="multipart/form-data"> |
| 208 |
<!-- Copy the 'fields' key:values returned by S3Client.generate_presigned_post() --> |
| 209 |
<input type="hidden" name="key" value="VALUE" /> |
| 210 |
<input type="hidden" name="AWSAccessKeyId" value="VALUE" /> |
| 211 |
<input type="hidden" name="policy" value="VALUE" /> |
| 212 |
<input type="hidden" name="signature" value="VALUE" /> |
| 213 |
File: |
| 214 |
<input type="file" name="file" /> <br /> |
| 215 |
<input type="submit" name="submit" value="Upload to Amazon S3" /> |
| 216 |
</form> |
| 217 |
</body> |
| 218 |
</html> |