Amazon CloudFront
Developer Guide (API Version 2014-08-31)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Overview of Signed URLs

Now that you've configured CloudFront to require that end users access your objects using special signed URLs, you can create the signed URLs (either manually or programmatically) and distribute them to the users that you want to have access to the objects.

A signed URL includes additional information, for example, an expiration date and time, that gives you more control over access to your content. This additional information appears in a policy statement, which is based on either a canned policy or a custom policy. The differences between canned and custom policies are explained in the next two sections.

Note

You can create some signed URLs using canned policies and create some signed URLs using custom policies for the same distribution.

Signed URLs that You Create Using a Canned Policy

Use a canned policy to create a CloudFront signed URL if you want to:

  • Restrict access to a single object.

  • Control access to your objects based only on the date and time that you want users to stop having access.

You don't include the policy in the URL, so a canned policy results in a shorter URL. You do include a signature, for which you hash and sign the policy.

When a user requests an object using a signed URL that you created using a canned policy, CloudFront reconstructs the canned policy statement based on information in the URL. CloudFront then compares the reconstructed policy statement with the policy statement in the signature to determine whether to allow the end user to access to the content. If the two statements don't match exactly, CloudFront denies access to the content.

For information about creating signed URLs using a canned policy, see Creating a Signed URL Using a Canned Policy.

Signed URLs that You Create Using a Custom Policy

Use a custom policy to create a CloudFront signed URL if you want to:

  • Restrict access to one or more objects, for example, all of the .pdf files in an annual-report directory. This allows you to use a single policy statement for the signed URLs for multiple objects.

  • Control access to your objects based on:

    • The date and time that you want users to stop having access.

    • The date and time that you want users to begin having access. (Optional)

    • The IP address or range of IP addresses of the users who you want to have access to the object or objects. (Optional)

For a signed URL that you create using a custom policy, you hash and sign the policy and include the signature, as you do with a signed URL that you create using a canned policy. In addition, you include a Base64-encoded version of the policy in the URL, which provides URL-safe compression. As a result, using a custom policy results in a longer URL than a canned policy.

When a user requests an object using a signed URL that you created using a canned policy, CloudFront compares the custom policy statement in the signed URL with the policy statement in the signature to determine whether to allow the end user to access to the content. If the two statements don't match exactly, CloudFront denies access to the content.

For information about creating signed URLs using a custom policy, see Creating a Signed URL Using a Custom Policy.

The Parts of a Signed URL

CloudFront signed URLs include the following components.

Base URL

The base URL is the CloudFront URL that you would use to access the object if you were not using signed URLs, including your own query string parameters, if any. For more information about the format of URLs for web distributions, see Format of URLs for CloudFront Objects.

The following examples show values that you specify for web distributions.

  • The following CloudFront URL is for an object in a web distribution (using the CloudFront domain name). Note that image.jpg is in an images directory. The path to the object in the URL must match the path to the object on your HTTP server or in your Amazon S3 bucket.

    http://d111111abcdef8.cloudfront.net/images/image.jpg

  • The following CloudFront URL includes a query string:

    http://d111111abcdef8.cloudfront.net/images/image.jpg?size=large

  • The following CloudFront URLs are for objects in a web distribution. Both use an alternate domain name; the second one includes a query string:

    http://www.example.com/images/image.jpg

    http://www.example.com/images/image.jpg?color=red

  • The following CloudFront URL is for an objects in a web distribution that uses an alternate domain name and the HTTPS protocol:

    https://www.example.com/images/image.jpg

For RTMP distributions, the following examples are for objects in two different video formats, MP4 and FLV:

  • MP4: mp4:sydney-vacation.mp4

  • FLV: sydney-vacation

  • FLV: sydney-vacation.flv

Note

For .flv files, whether you include the .flv filename extension depends on your player. To serve MP3 audio files or H.264/MPEG-4 video files, you might need to prefix the file name with mp3: or mp4:. Some media players can be configured to add the prefix automatically. The media player might also require you to specify the file name without the file extension (for example, sydney-vacation instead of sydney-vacation.mp4).

Expiration Date and Time (Canned Policies Only)

The date and time, in Unix time format (in seconds) and Coordinated Universal Time (UTC), that you want the URL to stop allowing access to the object. For example, January 1, 2013 10:00 am UTC converts to 1357034400 in Unix time format. For information about UTC, see RFC 3339, Date and Time on the Internet: Timestamps, http://tools.ietf.org/html/rfc3339.

If you're using a custom policy, you can still specify the date and time that you want a signed URL to stop allowing access to the object, but the date and time is included in the policy statement instead of appearing as a separate query string parameter in the signed URL.

Policy Statement

A policy statement is a text string in JSON format that determines the characteristics of the signed URL. For both canned policies and custom policies, the policy statement includes the URL of the object (for web distributions) or the stream name (for RTMP distributions), and an expiration date and time. Note the following:

  • Canned policy: You don't include the policy statement in the signed URL—you only create a policy statement so you can hash and sign it, and include the signature in the URL. See Signature.

  • Custom policy: You can also optionally include a date and time that the URL becomes valid and/or an IP address or range of IP addresses that are allowed to access the object. Then you Base64-encode the policy statement, and you include the encoded policy statement in the signed URL.

Signature

The signature is a hashed and signed version of the policy statement.

CloudFront Key Pair ID for the AWS Account that Is Creating the Signed URL

The CloudFront key pair ID tells CloudFront which public key to use to validate the signed URL. CloudFront compares the information in the signature with the information in the policy statement to verify that the URL has not been tampered with.

The key pair ID that you include in CloudFront signed URLs must be the ID of an active key pair for one of your trusted signers. For more information, see Specifying the AWS Accounts That Can Create Signed URLs (Trusted Signers).

If you make a key pair inactive while rotating CloudFront key pairs, and if you're generating signed URLs programmatically, you must update your application to use a new active key pair for one of your trusted signers. If you're generating signed URLs manually, you must create new signed URLs. For more information about rotating key pairs, see Rotating CloudFront Key Pairs.

When Does CloudFront Check the Expiration Date and Time in a Signed URL?

When CloudFront checks the expiration date and time in a signed URL to determine whether the URL is still valid depends on whether the URL is for a web distribution or an RTMP distribution:

  • Web distributions: CloudFront checks the expiration date and time in a signed URL at the time of the HTTP request. If a client begins to download a large object immediately before the expiration time, the download should complete even if the expiration time passes during the download. If the TCP connection drops and the client tries to restart the download after the expiration time passes, the download will fail.

    If a client uses Range GETs to get an object in smaller pieces, any GET request that occurs after the expiration time passes will fail. For more information about Range GETs, see How CloudFront Processes Partial Requests for an Object (Range GETs).

  • RTMP distributions: CloudFront checks the expiration time in a signed URL at the start of a play event. If a client starts to play a media file before the expiration time passes, CloudFront allows the entire media file to play. However, depending on the media player, pausing and restarting might trigger another play event. Skipping to another position in the media file will trigger another play event. If the subsequent play event occurs after the expiration time passes, CloudFront won't serve the media file.