README.md

S3 Secure Downloads plugin for Craft CMS

This plugin will return a pre-signed URL used to allow temporary access to private objects with an expiring URL. You can optionally allow file downloads only for logged in users and force file downloads (useful for PDF files).

From the original developer, Jonathan Melville:

This plugin was originally developed for a client in the financial services industry who wanted to make sure only logged in users had access to downloads of financial reports, and download links couldn’t be shared. … Now you can keep your S3 objects private but grant temporary access to them with an expiring link.

Installation

# Require the plugin with composer
composer require kennethormandy/craft-s3securedownloads

Then, install the plugin:

# Install the plugin via the Control Panel, or by running:
./craft plugin/install s3securedownloads

Usage

Pass in an asset's entry id and it will return a pre-signed URL for that asset:

{% set asset = entry.myAssetField.one() %}
<a href="{{ getSignedUrl(asset.id) }}">{{ asset }}</a>

By default, only users logged in will be able to generate the pre-signed URL. This can be changed within the plugin settings.

The generated a pre-signed AWS S3 URL will expire after 24 hours, or however long you have configured in the plugin settings.

Options

filename

By default, the download will use the same filename as the Craft CMS asset. Alternatively, a custom filename can be passed to AWS instead. For example:

{% set asset = entry.myAssetField.one() %}
<a href="{{ getSignedUrl(asset.id, { filename: 'my-new-filename.png' }) }}">{{ asset }}</a>

Events

• kennethormandy\s3securedownloads\services\SignUrl
  • SignUrl::EVENT_BEFORE_SIGN_URL
  • SignUrl::EVENT_AFTER_SIGN_URL

use Craft;
use yii\base\Event;
use kennethormandy\s3securedownloads\events\SignUrlEvent;
use kennethormandy\s3securedownloads\services\SignUrl;

// …

Event::on(
    SignUrl::class,
    SignUrl::EVENT_BEFORE_SIGN_URL,
    function (SignUrlEvent $event) {
        $asset = $event->asset;
        Craft::info("Handle EVENT_BEFORE_SIGN_URL event here", __METHOD__);
    }
);

Event::on(
    SignUrl::class,
    SignUrl::EVENT_AFTER_SIGN_URL,
    function (SignUrlEvent $event) {
        $asset = $event->asset;
        Craft::info("Handle EVENT_AFTER_SIGN_URL event here", __METHOD__);
    }
);

Earlier versions

S3 Secure Downloads is available for Craft 3, 4, and 5. For a version that runs on Craft v2.5.x, see the original plugin. Note that as of June 24, 2020 all new AWS S3 buckets require URLs to be signed using Signature Version 4, and the original plugin (understandably) only signs URLs using Signature Version 2.

License

The MIT License (MIT)

Copyright © 2016–2019 Jonathan Melville
Copyright © 2019–2024 Kenneth Ormandy Inc.