Repository files navigation

This repository contains a collection of Bash scripts and a choice of either a Terraform module or a set of CloudFormation templates that build a serverless infrastructure in AWS to host a static website protected withBasic Authentication.The static website is published on a subdomain registered in Route 53.

A live example can be found athttps://serverless-static-website-with-basic-auth.dumrauf.uk/ using the demo usernameguest and passwordletmein.Note that access to the underlyingS3 bucket hosting the static website is denied.

The master branch in this repository is compliant withTerraform v0.12; a legacy version that is compatible withTerraform v0.11 is available on branchterraform@0.11.

Before you can use the tools in this repository out of the box, you need

• anAWS account
• anAWS CLI configured to work with your AWS account
• adomain registered with Route 53
• anACM certificate for the subdomain you want to publish your static website at
• alog bucket which can be used to storeCloudFront access logs (use the Terraform module provided inhttps://github.com/dumrauf/aws_log_bucket to create a log bucket if needed)

If Terraform is the tool of choice then you also need

• aTerraform CLI

After creating the serverless infrastructure in AWS you get

• aprice class 100 CloudFront distribution which serves your static website using HTTPS (including redirect) and the ACM certificate provided in the input
• a private S3 bucket which contains the static website and serves as the origin for the CloudFront distribution
• a Lambda@Edge function which runs in the CloudFront distribution and performs the Basic Authentication for all requests
• a private S3 bucket acting as a serverless code repository
• potentially significant cost savings over using a dedicated EC2 instance, depending on your traffic
• the whole thing in one go while getting another coffee

Using the tools in this repository helps you avoid having

• the static website run on a dedicated EC2 instance or ECS container
• the static website to be hosted by S3 directly where it is publicly available to the whole world

All entry points are Bash scrips located in thescripts folder.

Unless you are happy with the demo usernameguest and passwordletmein,swap out the username-credentials dictionaryconst credentials in filelambda-at-edge-code/index.js with your own.

See the FAQs section about updating passwords at a later time in case changes are not reflected.

The entire serverless infrastructure can be created via

scripts/create_static_serverless_website.sh <parameter_1> ... <parameter_n>

where the parameters differ between CloudFormation and Terraform and additional setup may be required.

As for CloudFormation, the entire serverless infrastructure can be created via

scripts/create_static_serverless_website.sh <website-directory> <subdomain> <domain> <hosted-zone-id> <acm-certificate-arn> <profile>

An example invocation may look like

scripts/create_static_serverless_website.sh  static-website-content/  static-website mydomain.uk  Z23ABC4XYZL05B  "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"  default

Note that you need to replace the example values with yours in order for the script to work.

Under the bonnet, the script calls

1. bootstrap_serverless_repo.sh
2. create_serverless_infrastructure.sh.sh
3. upload_website_to_s3_bucket.sh

creating and uploaded the resources as indicated by the corresponding name.

As for Terraform, the input variables for the example websitestatic-website.example.com are definied inTerraform/settings/static-website.example.com.tfvars as

region="us-east-1"shared_credentials_file="/path/to/.aws/credentials"profile="default"hosted_zone_id="Z23ABC4XYZL05B"subdomain_name="static"domain_name="example.com"acm_certificate_arn="arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"log_bucket_domain_name="<your-log-bucket-domain>"

Note that you need to replace the example values with yours in order for Terraform to work.

With the Terraform configuration done, the entire serverless infrastructure can be created via

scripts/create_static_serverless_website.sh  <website-directory>  <profile>  <workspace-name>

Here, the<workspace-name> has to match the name of the input variables file insettings/ when neglecting the.tfvars extension (in this casestatic-website.example.com)

An example invocation may look like

scripts/create_static_serverless_website.sh  static-website-content/  default  static-website.example.com

Note that you need to replace the example values with yours in order for the script to work.

Under the bonnet, the script calls

1. create_serverless_infrastructure.sh.sh
2. upload_website_to_s3_bucket.sh

The local static website contents can be synced with the corresponding S3 bucket serving as the CloudFront origin via

scripts/upload_website_to_s3_bucket.sh <website-directory> <profile>

If your static website is located at../static-website-content/, sync it with the corresponding S3 bucket using profiledefault via

scripts/upload_website_to_s3_bucket.sh  "../static-website-content/"  default

creating and uploaded the resources as indicated by the corresponding name.

By default, an IAM user is also created who isonly allowed to

1. modify objects in the bucket hosting the website and
2. create CloudFront invalidations

Using this least-privileged user's access keys minimises your potential attack surface and is highly recommended.Note that APIaccess keys are not generated by default but can easily be obtained from the AWS console.

After syncing the static website with the S3 bucket, the CloudFront distribution will most likely keep a cached copy of the old static website until it expires.

This process can be expedited by invalidating the cache via

scripts/invalidate_cloudfront_chache.sh <profile> <paths>

The entire CloudFront distribution can be invalidated using profiledefault via

scripts/invalidate_cloudfront_chache.sh default '/*'

Here, note the single quotes around'/*' in order to avoid parameter expansion in Bash.Note that invalidations can incurcosts.

Again, the details differ when it comes to CloudFormation versus Terraform. Here, Terraform seems to simplify things a little.

In the case of CloudFormation, the Bash scripts essentially kick off two CloudFormation templates, namely

1. bootstrap_serverless_code_repository.yaml and
2. serverless_static_website_with_basic_auth.yaml

In the case of Terraform, the Bash scripts first switches to the workspace provided in the input or creates it if it doesn't exist. Afterwards, the Bash scripts essentially kick off a simple Terraform configuration inmain.tf which utilises theserverless-static-website-with-basic-auth module.

The Serverless Code Repository template is a CloudFormation specific implementation. Here, thebootstrap_serverless_code_repository.yaml creates a private S3 bucket which enforces encryption and acts as a serverless code repository. Another option would be to provide the code inline in the CloudFormation template but no matter how the code editor is set up, a good chunk of the template is always being marked as either plain text or plain wrong.

Theserverless_static_website_with_basic_auth.yaml template as well as theserverless-static-website-with-basic-auth module creates

1. A Lambda@Edge function version which runs the Basic Authentication code
2. A role to execute the Lambda@Edge function
3. A CloudFront origin access identity
4. A private S3 bucket which enforces encryption and permits the CloudFront origin access identity to read from the S3 bucket
5. A CloudFront distribution which uses the S3 bucket previously created as the origin and has a CNAME entry for the subdomain to be registered in the next step
6. A Route 53 RecordSetGroup which adds an A record for the subdomain to be registered and points to the CloudFront distribution URL created in the previous step

When using Route 53 as the domain registrar, a default hosted zone is usually created. This hosted zone contains four dedicated name servers.As of December 2017, creating a new hosted zone which uses specific name servers (namely the ones from the default hosted zone) is currently not possible via CloudFormation.

As of December 2017, CloudFormation only allows email validation for ACM certificates it issues; DNS validation is not an option even if the domain is registered via Route 53.Moreover, theentire stack remains in theCREATE_IN_PROGRESS state until the certificate has been validated which can introduce long delays.However, the AWS console allows to create an ACM certificate and add a record set to the corresponding hosted zone in Route 53 with one click.

Here, the problem is that new versions are not automagically published even if the underlying code has changed. For this, the name of the version has to changed in the corresponding CloudFormation template.Manually change the name of theBasicAuthAtEdgeLambdaVersion and all its uses. Another redeploy should fix the problem.

As of December 2017, CloudFront can only reference aversion in Lambda@Edge.Yup, it seems like yearly days here. Oh, and good luck deleting that Lambda@Edge via CloudFormation...

The default root document isindex.html.This value can be changed by updating theDefaultRootObject: index.html in theserverless_static_website_with_basic_auth.yaml template.

As of January 2018, CloudFront does not seem to provide fine grained access control for distributions on thecloudfront:CreateInvalidation permission. So much for true least privileged then...

Splendid! Open a pull request and let's make things better for everyone!

The code in this repository builds upon agreat article by Leonid Makarov describing the underlying idea as well as providing a Node.js implementation of Basic Authentication.