Skip to content

Commit

Permalink
F - apply English corrections to readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@ianreidlangevin
ianreidlangevin committed Feb 22, 2022
1 parent 0bcf951 commit 1133395
Showing 1 changed file with 30 additions and 31 deletions.
61 changes: 30 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<p><img src="./src/icon.svg" width="100" height="100" alt="Cloudfront Signed Url icon"></p>
<p><img src="./src/icon.svg" width="100" height="100" alt="Cloudfront Signed URLs icon"></p>

<h1>Cloudfront Signed Urls for Craft CMS</h1>
<h1>Cloudfront Signed URLs for Craft CMS</h1>

This plugin provides AWS Cloudfront Signed Urls in Twig templates
This plugin provides AWS Cloudfront Signed URLs in Twig templates.

## Requirements

This plugin requires Craft CMS 3.4 or later.
This plugin requires Craft CMS 3.x



Expand All @@ -22,17 +22,17 @@ To install the plugin, follow these instructions.

composer require troisiemejoueur/cloudfront-signed-urls

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



## Overview

This plugin add a Twig function to sign URLs from a AWS Cloudfront distribution. The common usage is for a restricted section for logged in users only.
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 IAM access for the CMS. If not, you can read the documentation of the first-party plugin [AWS S3 plugin from Pixel & Tonic](https://plugins.craftcms.com/aws-s3) and this [article from Andrew Welch](https://nystudio107.com/blog/using-aws-s3-buckets-cloudfront-distribution-with-craft-cms).
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](https://plugins.craftcms.com/aws-s3) and this [article from Andrew Welch](https://nystudio107.com/blog/using-aws-s3-buckets-cloudfront-distribution-with-craft-cms).

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



Expand All @@ -42,22 +42,21 @@ You upload your assets to a non-public S3 bucket with a Cloudfront distribution

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

[Documentation for Cloudfront Signed Urls](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-signed-urls.html)
[Documentation for Cloudfront Signed URLs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-signed-urls.html)



## 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 get merged with the plugin defaults, so you only need to specify values for the settings you want to override.
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](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs).

#### 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_.

`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.
Expand All @@ -69,15 +68,15 @@ If you want to set your own values you should create a `cloudfront-signed-urls.p
`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 set__ as argument when using the Twig function. This is a fallback value. Default is 3600 (60 minutes).
`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`.
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')`
__Note:__ You can use values from your ENV file for all the configuration settings. Example: `App::env('YOUR_VARIABLE_NAME')`



## An Example Config File
## Example cloudfront-signed-urls.php Config File
```
<?php
Expand All @@ -100,29 +99,30 @@ return [
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](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html#private-content-creating-cloudfront-key-pairs).

When you install this plugin, a `cloudfront-signed-urls` folder will be create in your Craft CMS project `storage` folder. You need to copy your `private_key.pem` file in this folder.
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) is delete.__
__Note: When uninstalling the plugin, this folder (and your private key) will be deleted.__

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



## Usage in Twig


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

```
{{ signUrl(myAssetTest.filename, 300) }}
```

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

```
{{ signUrl(myAssetTest.filename) }}
```

##### Usage with a complete URL - this case only works if you do not provided a value to the _cloudfrontDistributionUrl_ setting in your config file.
##### 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.filename %}
Expand All @@ -134,23 +134,22 @@ This .pem file cannot be add as .env variable.
## S3 storage and Craft CMS Control Panel

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

#### Control Panel
1. Install the [AWS S3 plugin from Pixel & Tonic](https://plugins.craftcms.com/aws-s3)
1. Create a volume with the Amazon S3 `Volume Type`
1. Turn __off__ the lightswith for `Assets in this volume have public URLs`
1. Add your S3 bucket credentials and settings
1. Install the [AWS S3 plugin from Pixel & Tonic](https://plugins.craftcms.com/aws-s3).
1. Create a volume with the Amazon S3 `Volume Type`.
1. Turn __off__ the lightswith for `Assets in this volume have public URLs`.
1. Add your S3 bucket credentials and settings.

__Note: When a user(mostly the admin) is logged in in the Control Panel, he will be able to open / view the assets with the Download button, but not to preview it (as the assets have no public URLs).__
__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

1. Create your templates based on which user group is logged in (or any condition that you want).
2. Show assets with the Twig function.
3. No one from the "web" will be able to view the files. The URL will expires 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.

3. 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.



Expand Down

0 comments on commit 1133395

Please sign in to comment.