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
toterraform.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
Copyright © 2019 Naoto Yokoyama
Distributed under the MIT license. See the LICENSE file for full details.