aws-lambda-edge-basic-auth-terraform

This is a Terraform module that creates AWS Lambda@Edge resources to protect CloudFront distributions with Basic Authentication.

The purpose of this module is to make it no-brainer to set up AWS resources required to perform Basic Authentication with AWS Lambda@Edge. If you don't want to take care of tedious jobs such as IAM role setup, this is a right module to go with.

The actual code to perform Basic Authentication is derived from lmakarov/lambda-basic-auth.js.

Usage

This is a Terraform module. You just need to include the module in one of your Terraform configuration files with some parameters and add lambda_function_association block to your aws_cloudfront_distribution resource. See examples/ for complete examples.

# If the parent module provider region is not us-east-1, define provider for us-east-1.
#
#provider "aws" {
#  alias  = "us-east-1"
#  region = "us-east-1"
#}

module "basic_auth" {
  source = "github.com/builtinnya/aws-lambda-edge-basic-auth-terraform/module"

  basic_auth_credentials = {
    user     = "your-username"
    password = "your-password"
  }

  # All Lambda@Edge functions must be put on us-east-1.
  # If the parent module provider region is not us-east-1, you have to
  # define and pass us-east-1 provider explicitly.
  # See https://www.terraform.io/docs/modules/usage.html#passing-providers-explicitly for detail.
  #
  #providers = {
  #  aws = "aws.us-east-1"
  #}
}

resource "aws_cloudfront_distribution" "your_distribution" {
  # ...

  # Add the following block to associate the Lambda function.
  lambda_function_association {
    event_type   = "viewer-request"
    lambda_arn   = "${module.basic_auth.lambda_arn}"
    include_body = false
  }
}

Inputs

Name	Description	Type	Default	Required
basic_auth_credentials	Credentials for Basic Authentication. Pass a map composed of 'user' and 'password'.	map	n/a	yes
function_name	Lambda function name	string	`"basicAuth"`	no

Outputs

Name	Description
lambda_arn	Lambda function ARN with version

Examples

Minimal

The minimal example is located at examples/minimal . It creates an S3 bucket, an S3 object (index.html), and a CloudFront distribution protected with Basic Authentication, enough to confirm that this module protects resources with Basic Authentication.

Building Resources

Move to examples/minimal directory.
```
$ cd examples/minimal
```

Copy terraform.tfvars.example to terraform.tfvars and fill in the values.

$ cp terraform.tfvars.example terraform.tfvars
$ # Edit terraform.tfvars with your favorite editor.

aws_access_key = "<your AWS access key>"
aws_secret_key = "<your AWS secret key>"
region = "<region>"
s3_bucket_name = "<S3 bucket name to create>"

basic_auth_credentials = {
  "user" = "<Basic Auth Username>"
  "password" = "<Basic Auth Password>"
}

Execute the following commands to build resources using Terraform.
```
$ terraform init
$ terraform plan
$ terraform apply
```

If building succeeded, it will show messages like the following:

Outputs:

url = https://<some-random-string>.cloudfront.net

You can access to the URL and check if Basic Authentication works once the CloudFront is ready (it takes some time to be ready.)

Destroying Resources

To destroy AWS resources created by the above steps, execute the following commands in examples/minimal directory.

$ terraform destroy

NOTICE: the above command probably ends up with error. See Deleting Lambda@Edge Functions and Replicas for detail.

Development

You just need to install Docker to develop this module.

Terraform configurations for this module is located at module/ directory.
Lambda@Edge function source code is located at src/basic-auth.js. It needs to be transpiled by Babel and minified by UglifyJS before zip-compressed by Terraform.

Updating Lambda Function Code

If you update the Lambda function source code, you also need to update the function code in the module. It can be done by running:

$ ./build.sh

Deleting Generated Lambda Function Code

If you want to delete Lambda function code generated by running ./build.sh, run the following:

$ ./clean.sh

You should rarely have to use the command.

Generating Inputs and Outputs Documentation

If you add or remove inputs or outputs of this module, you have to update the documentation.

You can generate inputs and ouputs documentation of this module by running:

$ ./docs.sh

It shows markdown table of inputs and outputs, same as included in this README.

Testing

Tests for the handler is located at test/ directory and executed in build.sh.

Diagrams

Diagrams are located at diagrams/ directory. You can import and edit XML files visually using draw.io.

License

Distributed under the MIT license. See the LICENSE file for full details.

s-maj/aws-lambda-edge-basic-auth-terraform