README

Cloudfront Signed URLs for Craft CMS

This plugin provides AWS Cloudfront Signed URLs in Twig templates.

Requirements

This plugin requires Craft CMS 3.x

Installation

To install the plugin, follow these instructions.

Open your terminal and go to your Craft project:
```
 cd /path/to/project
```

Then tell Composer to load the plugin:

 composer require troisiemejoueur/cloudfront-signed-urls

In the Control Panel, go to Settings → Plugins and click the “Install” button for Cloudfront Signed URLs.

Overview

This plugin adds a Twig function to sign URLs from an AWS Cloudfront distribution. The common usage is for a restricted section for logged-in users only.

In order to use this plugin, we assume that you already worked with AWS and that you know how to create a bucket, a Cloudfront distribution and an IAM access for the CMS. If not, you can read the documentation of the first-party plugin AWS S3 plugin from Pixel & Tonic and this article from Andrew Welch.

Please, do not open issues for AWS configuration problems or questions that are not related to this plugin.

How it works

You upload your assets to a non-public S3 bucket with a Cloudfront distribution with the Restrict Viewer Access setting to Yes. When you create URLs in your templates, these URLs are signed with a random key.

These URLs are created on page load and expires after the duration that you entered.

Documentation for Cloudfront Signed URLs

Configuration file

The plugin comes with a config.php file that defines some sensible defaults.

If you want to set your own values, you should create a cloudfront-signed-urls.php file in your Craft config directory. The contents of this file will be merged with the plugin defaults. You only need to specify the values of the settings you want to override.

keyPairId

keyPairId is where you define the value of the Key-Pair-Id field from your public–private key pair. See AWS documentation for creating public–private key pair.

cloudfrontDistributionUrl

cloudfrontDistributionUrl is where you define the base URL for your signed URLs. If you want to manage the base URL on a per-file basis, do not add this setting to your config file. If you are using a subfolder, you can append it to this URL. Trailing slash are not required.

profile

profile is where you define the profile of your Cloudfront client. default is the default value.

version

version is where you define the version of your Cloudfront client. 2020-05-31 is the default value.

region

region is where you define the regional endpoint for your Cloudfront client. ca-central-1 is the default value, you probably need to change it based on your project.

defaultExpires

defaultExpires is where you define in seconds the expiry delay for your signed URLs if not configured as an argument when using the Twig function. This is a fallback value. The default value is 3600 (60 minutes).

The expiry time is calculated like this: now time + defaultExpires.

Note: You can use values from your ENV file for all the configuration settings. Example: App::env('YOUR_VARIABLE_NAME')

Example cloudfront-signed-urls.php Config File

<?php

use craft\helpers\App;

return [
   'keyPairId' => App::env('SIGNED_URLS_KEYPAIR'),
   'cloudfrontDistributionUrl' => 'https://my-distribution.cloudfront.net',
   'profile' => 'default',
   'version' => '2020-05-31',
   'region' => 'ca-central-1',
   'defaultExpires' => 4200
];

Private Key (.pem file)

In order to sign your URLs, AWS needs to access the private key (the private_key.pem file). See AWS documentation for creating public–private key pair.

When you install this plugin, a cloudfront-signed-urls folder will be created in your Craft CMS project storage folder. You'll need to copy your private_key.pem file in this folder.

Note: When uninstalling the plugin, this folder (and your private key) will be deleted.

This .pem file cannot be added as an .env variable.

Usage in Twig

Basic usage with filename and an expiry delay of 300 seconds.

{{ signUrl(myAssetTest.getUrl(), 300) }}

Usage without expiry delay - it will use your fallback config value or the default one.

{{ signUrl(myAssetTest.getUrl()) }}

Usage with a complete URL - this use case only works if you did not provide a value to the cloudfrontDistributionUrl setting in your config file.

{% set myAssetUrl = 'https://my-distribution-url.cloudfront.net' ~  myAssetTest.getUrl() %}
{{ signUrl(myAssetUrl, 300) }}

S3 storage and Craft CMS Control Panel

AWS

Create a non-public S3 bucket on AWS (and an IAM user with a programmatically access for your Craft CMS).
Create a Cloudfront distribution with the Restrict Viewer Access setting to Yes.

Control Panel

Install the AWS S3 plugin from Pixel & Tonic.
Create a new filesystem in the Control Panel (settings/filesystems) with the Amazon S3 Filesystem Type.
Turn off the lightswith for Filesystem in this volume have public URLs.
Add your S3 bucket credentials, subfolder and settings.
Let empty the CloudFront Distribution ID and CloudFront Path Prefix fields.
Create a new volume (settings/assets) and choose your Private filesystem for Asset Filesystem

Note: When a user (mostly the admin) is logged in the Control Panel, he will be able to open / view the assets by clicking the download button, but he will not be able to preview them (as the assets have no public URLs).

Template restricted zone -> Example

Create your templates based on which user group is logged in (or any condition that you want).
Show assets with the Twig function.
No one from the "web" will be able to view the files. The URL will expire after the duration that you entered. A user can copy and share the URL to another, but that's the only way to share / access a signed URL.

Brought to you from Canada by 3e joueur

troisiemejoueur / cloudfront-signed-urls

Maintainers

Details