Securing Assets

Imgix recommends securing all URLs that are used to serve your assets. Although we don’t require that Amazon S3, Google Cloud Storage, Microsoft Azure, DigitalOcean, Cloudflare R2, Wasabi, Linode, and Web Folder Sources be secured, it is a requirement for Web Proxy Sources.

To secure an asset URL, we use a cryptographic hash function called “MD5” to combine the original URL with a unique token that we generate for each secure Source. The result of this hash function is then appended to the end of your unsigned URL with the s parameter, creating a signed URL.

If the path or parameters of your URL are altered after the s parameter has been set, the altered URL will return a “403 Forbidden” code instead of an asset. This prevents unauthorized parties from changing the parameters on your URLs, but it also means that if you need to change the parameters yourself, you’ll need to re-sign the new URL.

You can find your secure URL token by going to the Security section of your source and clicking on the button that says Show Token. This will only be available for Sources that have Secure URLs enabled, which will be explained in the following section.

To require that assets are only served over HTTPS, see Requiring HTTPS (HSTS).

Enabling Secure URLs

Before an asset URL can be signed, the Secure URL option must be enabled in your Source. Web Proxy Sources have this turned on automatically, and you can turn it on for your Amazon S3, Google Cloud Storage, Microsoft Azure, or Web Folder Sources by following these steps:

1. Go to the Sources page and click View for the Source you’d like to update.

2. In the Configuration section, click Edit.

3. In the Security subsection, check Secure URLs.

   
   

4. Click Review and Deploy at the bottom of the page.

5. Review your changes and click Deploy this Config to complete the changes to your Source.

Now that the Secure URL option is enabled in your Source, URLs served from that Source must be signed. The Tools tab contains the Sign Asset tool that will append the signature to the end of the query string. See the next section for instructions on using this tool.

Securing Assets on a Per-Asset Basis

Once Secure URLs are enabled, you can sign individual assets by clicking the Sign URLs button on your Source’s detail page.

Single Assets

1. Choose the subdomain for which you want to sign assets from the dropdown menu.
2. Set the path for your asset if it’s in a folder within your Source.
3. Assign any parameters with which you want to transform the asset.
4. Set the expiration date for the signature.
5. Click Sign Asset.
6. The form will be replaced with your signed URL, plus a button to copy the signed URL directly to your clipboard. Use the new signed URL to serve the asset.

Multiple Assets

1. Click the “Multiple” side of the button on the top right of the page.
2. Enter the full URLs for all of the assets you want to sign, including any parameters. You can enter up to 100 URLs.

Using Tools

You can also sign asset URLs in the Sign URLs section of the Tools view.

1. Enter the fully-qualified URL of your asset. If the asset is an image, include any parameters you want to transform the image with. See the Rendering API Documentation for instructions.
2. Set the expiration date for the signature.
3. Click Sign Asset.
4. The form will be replaced with your signed URL, plus a button to copy the signed URL directly to your clipboard. Use the new signed URL to serve the asset.

To sign another URL, just click Sign Another Asset.

Expiring URLs

URLs can be given an expiration date via an expires parameter that takes a UNIX timestamp in the query string. For example:

?expires=1477789261

This UNIX timestamp translates to 10/30/2016 1:01am (UTC time). Requests made to this URL after that time will output a 404 status code. When the request is made before the expiration date, the Cache-Control header of the image is replaced with the amount of time left until the expiration date, in seconds. With the same expires value, when the current time is 10/30/2016 1:00am (UTC time), the header will output Cache-Control: max-age=60.

Because the timestamp can be changed freely in the query string, we recommend signing assets that use the expires header to prohibit this behavior.

Requiring HTTPS (HSTS)

Secure URLs control which URLs can be requested. To control how they are requested, you can require HTTPS for every request to a Source with HTTP Strict Transport Security (HSTS).

When HSTS is enabled on a Source, Imgix does two things:

• Redirects HTTP to HTTPS at the CDN. Any request made over plain HTTP receives a 301 Moved Permanently response pointing to the same URL over HTTPS. This happens at the edge, before any browser HSTS policy applies, so it also covers first-time visitors and non-browser clients.
• Sends a Strict-Transport-Security header. Responses include Strict-Transport-Security: max-age=<seconds>, which tells browsers to use HTTPS for the Source’s domains for that duration without making an HTTP request first.

To enable HSTS for a Source:

1. Go to the Sources page and click View for the Source you’d like to update.
2. Click Edit Configuration, then scroll to the Asset Security section.
3. Check Require HTTPS (HSTS).
4. Enter a Policy Duration (seconds) greater than 0. One year is 31536000.
5. Click Save Changes. The new configuration is queued and deployed shortly after.

HSTS can also be set through the Management API with the hsts attribute on a Source, which takes an enabled boolean and a max_age value in seconds.

Keep the following in mind:

• The header only sets max-age. The includeSubDomains and preload directives are not supported.
• Browsers keep the policy after you turn it off. A browser that has received the header continues to require HTTPS for the full policy duration, even after HSTS is disabled on the Source.
• Cached images update gradually. Turning HSTS on or off, or changing the duration, reaches already-cached images as they expire from the CDN cache or are purged.

Securing Assets in Your Application

For securing assets within applications or websites at scale, we strongly recommend using one of the Imgix client libraries. This ensures that you will always be up to date with the latest issues in any given language. Although the rendering api is simple, there are a few corner cases that are not always apparent.

If a client library is not available in your language, please see the Securing URLs section of the Imgix library blueprint document.