 | Feedback |  |
Topics
Amazon Simple Storage Service users can give direct third-party access to their private Amazon S3 data, without proxying the request. They do this by constructing a pre-signed request and encoding it as a URL that can be used in a browser. This feature is commonly referred to as query string authentication or pre-signed URLs. This section describes the special work your Amazon DevPay web product must do to use this feature.
We assume that you are familiar with using Amazon S3 query string authentication. If you're not, go to the REST authentication section of the Amazon Simple Storage Service Developer Guide and read about it, and then come back to this section.
Query string authentication is designed for use with DevPay web products and not DevPay desktop products. If you currently have a desktop product and want to use query string authentication, we recommend you enable a server to run a web (hosted) interface to your product, set up the server to handle query string authentication, and have your customers use the web interface. Thereafter, to use your product, the customers can either use the desktop client or the web interface (their subscription covers both). In this case, you need to activate the customer's use of the product twice: once with ActivateDesktopProduct (for use with the desktop client) and once with ActivateHostedProduct (for use with the web interface).
The primary use case for query string authentication is for GETs in a web browser, although you can also use it programmatically with GETs, PUTs, or DELETEs.
Your web product can make the pre-signed URL available to one person, multiple people, or the entire public. The person clicking the URL does not need to be subscribed to your DevPay product or use the URL through your DevPay web product. Anyone can click a pre-signed URL to download data from the customer's Amazon S3 bucket. This is an exception to the Amazon DevPay data sharing policy (for more information about data sharing, see Customer Access to Data Stored by Your Amazon S3 Product).
Pre-signed URLs are just another way to download data from the customer's bucket. It might be the customer, or someone else, who uses the pre-signed URL to download data. However, the customer pays the price you specify for downloading objects with your DevPay product. Likewise, you pay AWS for the corresponding Amazon S3 costs that you would for downloading objects for the customer. If your web product makes the pre-signed URL available to the general public (for example), millions of people could click the URL and download the object, causing you and your customer to incur the corresponding costs, which could be significant. Keep this in mind when deciding who your web product gives the pre-signed URL to and how long the URL will be valid.
Downloads that originate with a pre-signed URL are included in the download usage statistics and dollar amount the customer sees on the Application Billing page.
The following table describes the basic process to use a pre-signed URL with your DevPay web product.
Process for Using a Pre-Signed URL
1 | Make sure your web product has the required version of the user token. For more information, see The Required Version of the User Token. |
2 | Create the URL according to the instructions in the Amazon Simple Storage Service Developer Guide, with the specific changes required for DevPay products. For more information, see Changes to the URL. |
To make query string authentication work with your web product, you must use a particular version of the web product user token, which ActivateHostedProduct began returning after May 15, 2008. This version of the user token lets you omit the product token from the request, which is desirable because it's a security risk to send the product token in clear text in the URL. Use the RefreshUserToken action to ensure your web product has the required version of the user token.
Your web product can still use the original version of the user token in requests that don't use query string authentication. In that case, the web product must continue to include the product token in the request. The newer user token is compatible with older requests so you don't have to reconstruct them. That is, if you have refreshed the user token, you can still send it together with the product token even though the product token is no longer required.
When creating a pre-signed URL for a DevPay bucket, you must add the query parameter x-amz-security-token to pass the user token and include the user token when creating the signature. The example that follows shows the x-amz-security-token parameter in the request.
The instructions for creating a signature for query string authentication tell you to include any headers that start with x-amz. When creating the string to sign, you treat the x-amz-security-token query parameter as if it were a header, so that the signature includes the user token. Your web product also must use your Access Key ID and Secret Access Key to create the signature, as it does for all Amazon S3 requests it makes on behalf of the customer.
![[Important]](images/important.png) | Important |
|---|---|
Remember to URL encode the user token when including it as a query parameter in the URL, but not to URL encode it when including it in the string to sign. |
Example Request
The following example shows an example pre-signed URL that you would use in a web browser. This URL gets the /photos/puppy.jpg object from the customer's bucket. The presence of the user token enables AWS to bill the customer for the GET request. Line breaks have been added and the user token has been shortened to make the URL easier to read.
http://johnsmith.s3.amazonaws.com/photos/puppy.jpg
?x-amz-security-token={UserToken}BA4PXRKl...Kczg==
&AWSAccessKeyId=0PN5J17HBGZEXAMPLE
&Signature=vjbyPxybdZaNmGa%2ByEXAMPLE%3D
&Expires=1141889120
The following example shows the same request in the format that you would use with a programmatic GET.
GET /photos/puppy.jpg?x-amz-security-token={UserToken}BA4PXRKl...Kczg==&
AWSAccessKeyId=0PN5J17HBGZEXAMPLE&
Signature=vjbyPxybdZaNmGa%2ByEXAMPLE%3D&
Expires=1141889120 HTTP/1.1
Host: johnsmith.s3.amazonaws.com
