AWS S3 with Authentication¶

Table of Contents

Using Webserver Directives for S3 authentication
Apache Configuration

When using Amazon S3 for remote storage, it might be required to secure access to the S3 buckets instead of using 'public' access. This means that the requests to the content in the bucket must be authenticated. See Using S3 storage regarding configuring Amazon S3 storage.

There are two ways to do this:

use the Authorization header

send a signature as a URL-encoded query-string parameter.

The mod_unified_s3_auth module supports both.

More information can be found in Amazon's Authenticating Requests documentation.

Using Webserver Directives for S3 authentication ¶

It is possible to use webserver directives and let USP sign the request automatically with the following webserver directives.

This covers one specific use case: both content (mp4/ismv) and server manifest (ism) are placed in the S3 bucket and the manifest references the content locally (no paths or URLs, just the filename).

The directives for Apache are the following:

Option	Description
S3SecretKey	The AWS secret key.
S3AccessKey	The AWS access key.
S3Region	Region of bucket where data is stored, added in 1.7.29. Required for AWS Signature v4.
S3UseHeaders	Set to 'on' to use HTTP headers for AWS authentication, instead of query parameters.

The keys can be created in the AWS IAM portal and managed there as well (active/inactive, delete).

AWS Signature v4¶

As of January 30, 2014, newer AWS regions such as eu-central-1 require the use of the AWS Signature v4 for authentication. To enable the use of v4 signatures the name of the S3 region must be set when configuring access to the bucket. If the region is set, v4 signatures will be used whether or not the region requires it. Not setting the S3 region will result in USP using the older v2 signature method that may not be supported by all regions.

Requirements for Amazon S3 authentication¶

To use Apache <Proxy> for Amazon S3 authentication:

The mod_unified_s3_auth module must be installed, see How to Install for further information.
Apache's subrequests must be enabled and <Proxy> sections configured for each S3 bucket.

Apache Configuration ¶

To secure access to Amazon S3 buckets, <Proxy> sections are the appropriate locations to specify the S3 authentication directives.

The directives can appear in two places:

In a <Proxy> section. This is the recommended location.
In a <Location> section, which is used in combination with the IsmProxyPass directive in a <Directory> or <Location> section. This is the traditional way of specifying the S3 parameters, and it is still supported for backwards compatibility.

Each Amazon S3 bucket must have its own <Proxy> section. These are then used automatically for each request sent to the Amazon S3 bucket.

An additional benefit for using <Proxy> sections is that performance is improved by keeping the connections to Amazon S3 bucket alive.

For example, if the bucket is called mybucket, and it is hosted in Amazon's eu-central-1 region, the section becomes:

<Proxy "http://mybucket.s3-eu-central-1.amazonaws.com/">
  S3SecretKey  SECRET_KEY
  S3AccessKey  ACCESS_KEY
  S3Region     eu-central-1
  S3UseHeaders on
  ProxySet connectiontimeout=5 enablereuse=on keepalive=on retry=0 timeout=30 ttl=300
</Proxy>

This can be used both when your manifests and/or media files are directly referring to Amazon S3 buckets, and when IsmProxyPass directives redirect requests to Amazon S3 buckets, see Cloud Storage for an outline of the different use cases.

In this case, there is no need to add any S3 parameters to the sections containing IsmProxyPass.

Schematically, it works like the following:

player --> cdn --> shield-cache --> origin (mod-smooth-streaming) --> signing (mod_unified_s3_auth) --> s3

The S3UseHeaders setting determines how the information is shared, either by adding a number of additional request headers, or otherwise by adding a number of additional query arguments.

Following is a complete example <VirtualHost>:

<VirtualHost *:80>
  ServerName www.example.com
  DocumentRoot /var/www/mysite

  # Enable just in time packaging for VOD and using subrequests for I/O backend requests.
  <Location "/">
    UspHandleIsm on
    UspEnableSubreq on
    IsmProxyPass https://mybucket.s3-eu-central-1.amazonaws.com/
  </Location>

  # If proxying to SSL hosts is desired, you must turn on SSLProxyEngine.
  SSLProxyEngine on

  <Proxy "https://mybucket.s3-eu-central-1.amazonaws.com/">
    S3SecretKey SECRET_KEY
    S3AccessKey ACCESS_KEY
    S3Region eu-central-1
    S3UseHeaders on
    ProxySet connectiontimeout=5 enablereuse=on keepalive=on retry=0 timeout=30 ttl=300
  </Proxy>
</VirtualHost>

Legacy IsmProxyPass Example¶

In previous versions of Origin, when subrequests were not available, S3 authentication parameters were typically placed in a <Location> section, with a corresponding <Directory> section containing an IsmProxyPass directive. E.g.:

<Location /s3/>
  S3SecretKey SECRET_KEY
  S3AccessKey ACCESS_KEY
  S3Region eu-west-1
</Location>

<Directory /var/www/mysite/s3/>
  IsmProxyPass https://mybucket.s3-eu-west-1.amazonaws.com/
</Directory>

Assuming the DocumentRoot of the site is /var/www/mysite, the URI path /s3/example.ism would be mapped by IsmProxyPass to https://mybucket.s3-eu-west-1.amazonaws.com/example.ism, and the S3SecretKey, S3AccessKey and S3Region parameters from the <Location> section would be used for authentication.