Our CloudFront integration utilizes Amazon's edge code solution Lambda@Edge to provide you with a waiting room service that works directly from your CDN without the need for you to make any changes to your application code or web servers.

Introduction


This article will take you through the steps required to integrate CrowdHandler with your CloudFront distribution. As this integration involves provisioning infrastructure into your AWS account, standard AWS usage fees will apply.


If at any point of working your way through the guide you get stuck or have questions then feel free to reach out to us via https://www.crowdhandler.com

Prerequisites

  1. An active CrowdHandler account. If you haven't signed up already you can do so here.
  2. Access to the AWS console that your CloudFront distribution is located in and permission to:
    1. Make alterations to the CloudFront Distribution
    2. Publish Lambda functions
    3. Edit IAM roles.


As with all of our server-side integrations, we recommend integrating against your UAT/Staging environment prior to integrating against your production domain. 


Step 1: Download the Integration Code.


  1. Go to the CloudFront integration GitHub repository.
  2. Enter the dist directory.
  3. Download the zip files contained within.


Step 2: Create the viewerRequest Lambda Function.



AWS require that lambda@edge functions are created in the US-East-1 region (N.Virgina). 

Lambda@Edge functions are distributed globally, but they must originate from this geographic location.


  1. Log into your AWS console.
  2. Navigate to the AWS Lambda service. 
  3. Create a new function.
  4. Leave the function creation options set to "Author from scratch".
  5. Name the function crowdhandler-viewerRequest
  6. Set the Runtime to Node.js 14.x
  7. Expand the execution role dropdown and make note of the execution role that Lambda will create. 
  8. Create the function.


In the example below the execution role is named crowdhandler-viewerRequest-role-28dhheno



Step 3: Configure Execution Role Permissions.


  1. Open a new browser tab and navigate to the AWS IAM management console.
  2. Select Roles.
  3. Select the execution role that was created in step 2. 
  4. Select the trust relationships tab.
  5. Click the "edit trust relationship" button. 
  6. Update the Trust Policy to include the edgelambda.amazonaws.com service and save it. 



Step 4a: Configure the viewerRequest Lambda function.


  1. Switch back to the browser tab where you created the viewerRequest function in step 2.
  2. Upload the viewerRequest.zip file that you downloaded in Step 1.


  3. Double click handlerViewerRequest.js file to display the source code.
  4. Search for CROWDHANDLER_API_DOMAIN in the source code and replace it with api.crowdhandler.com.


  5. Search for CROWDHANDLER_PUBLIC_KEY and replace it with your CrowdHandler public key value (Can be found in the Account -> API section of the CrowdHandler administration control panel.)


  6. Scroll down to runtime settings.
  7. Click edit.
  8. Change Handler name to handlerViewerRequest.viewerRequest.
  9. Update the Lambda function by clicking the deploy button.



Step 4b: (Optional) Configure Advanced Settings.



failTrust (boolean) (default true)

If false, a user that fails to check-in with CrowdHandler's API will be sent to a safety net waiting room until CrowdHandler is able to make a decision on what to do with them. 

If true, users that fail to check-in with CrowdHandler's API will be trusted.

safetyNetSlug (string) (default undefined)

If defined and if failTrust is set to false, this waiting room slug will be used as the safety net room. 

whitelabel (boolean) (default false)

By default, users will be queued on CrowdHandler's wait.crowdhandler.com domain. If whitelabel is set to true, users will be queued on the domain CrowdHandler is protecting. For example, if CrowdHandler has been set up to protect www.example.com, users will be queued on the www.example.com/ch/ path. The /ch/ route does not need to exist in your application. 

Read more about whitelabel waiting rooms here.


  1. If any alterations to the advanced settings have been made, update the Lambda function by clicking the deploy button.

Step 5: Deploy the viewerRequest Lambda function to CloudFront.


  1. Refresh the page (AWS Lambda caches IAM execution role configurations). 
  2. Select Deploy to Lambda@Edge from the actions dropdown.


  3. Select your CloudFront distribution from the Distribution dropdown.
  4. Select the behavior that you would like CrowdHandler to trigger on. We recommend selecting *.

The * pattern will trigger the CrowdHandler function for all routes on your site except for any routes excluded in CloudFront behaviours (see section 13). We recommend starting off with this pattern unless you're confident that your site won't be flooded with traffic to unprotected routes and will not be vulnerable to the redirect gotcha outlined here. 

You can do further, more granular waiting room route configurations through the CrowdHandler admin console.


5. Change the CloudFront event to viewer request.

6. Select the acknowledgment.

7. Deploy.



Step 6: Create the viewerResponse Lambda function.


  1. Navigate to the AWS Lambda service. 
  2. Create a new function.
  3. Leave the function creation options set to "Author from scratch".
  4. Name the function crowdhandler-viewerResponse
  5. Set the Runtime to Node.js 14.x
  6. Expand the execution role dropdown and select the execution role that you took note of in step 2. 
  7. Create the function.



Step 7: Configure the viewerResponse Lambda function.


  1. Upload the viewerResponse.zip file that you downloaded in Step 1.


  2. Scroll down to runtime settings.
  3. Click edit.
  4. Change Handler name to handlerViewerResponse.viewerResponse.



Step 8: Deploy the viewerResponse Lambda function to CloudFront.


  1. Select Deploy to Lambda@Edge from the actions dropdown.



  2. Select your CloudFront distribution from the Distribution dropdown.
  3. Select the same behavior that you chose in step 5.
  4. Change the CloudFront event to viewer response.
  5. Select the acknowledgment.
  6. Deploy




Steps 9-12 can be skipped if you didn't set whitelabel to true in step 4b.

Step 9: Create the originOverride Lambda function (Whitelabel configuration only).


  1. Navigate to the AWS Lambda service. 
  2. Create a new function.
  3. Leave the function creation options set to "Author from scratch".
  4. Name the function crowdhandler-originOverride.
  5. Set the Runtime to Node.js 14.x
  6. Expand the execution role dropdown and select the execution role that you took note of in step 2. 
  7. Create the function.



Step 10: Configure the originOverride Lambda function (Whitelabel configuration only).


  1. Upload the originOverride.zip file that you downloaded in Step 1.


  2. Scroll down to runtime settings.
  3. Click edit.
  4. Change Handler name to handlerOriginOverride.originOverride, save, then increase the function timeout to 10 seconds.




Step 11: Add whitelabel CloudFront support (Whitelabel configuration only).


  1. Open a new browser tab and navigate to the AWS CloudFront console.
  2. Find your CloudFront distribution and click the distribution ID to go into configuration mode. 
  3. Select the behaviours tab.
  4. Add a new behavior for path pattern /ch/* as shown in the screenshot below, altering the origin to match your own.


!!! IMPORTANT !!!

It's critical when completing this step that CloudFront caching is enabled by selecting the cache policy shown in the screenshot. Failure to do so may cause AWS to throttle your traffic in high traffic situations.


Step 12: Deploy Whitelabel Route (Whitelabel configuration only).

  1. Switch back to the browser tab where you created the originOverride function in step 9.
  2. Refresh the page.
  3. Select Deploy to Lambda@Edge from the actions dropdown.

  4. Select your CloudFront distribution from the Distribution dropdown.
  5. Select the /ch/* behavior.
  6. Change the CloudFront event to origin request
  7. Select the acknowledgment.
  8. Deploy.

Step 13: Add CrowdHandler Exclusion Routes.


Out of the box CrowdHandler will automatically not attempt to queue routes with the following file extensions. 

"avi","css","csv","eot","gif","ico","jpg","js","json","map","mov","mp4","mpeg","mpg","ogg","ogv","ott","pdf","png","svg","ttf","webmanifest","wmv","woff","woff2","xml".

It is your responsibility to ommit patterns and routes that should not be queued. 

Common examples are:

* Paths used for storing static assets and media i.e. /wp-includes/*
* Callback URLs made by third party payment providers. 
* JSON and RSS feeds.
  1. Navigate to the AWS CloudFront console.
  2. Find your CloudFront distribution and click the distribution ID to go into configuration mode.
  3. Select the behaviors tab.
  4. Add new behaviors for any routes that should not be subject to Crowdhandler protection.
An example configuration for a static assets directory show below.

Step 14: (Optional) Add x-ch-no-bypass Header.


The x-ch-no-bypass header can be configured to be sent to your origin server in CloudFront. You can check for this header in your application to verify that the request has traversed through CrowdHandler. Implementation examples can be found in the "Integration Examples" section of this article.


  1. Navigate to the AWS CloudFront console.
  2. Find your CloudFront distribution and click the distribution ID to go into configuration mode.
  3. Select the origins tab.
  4. Select your origin and click edit.
  5. Add a custom header.


  6. Set the header name to x-ch-no-bypass.
  7. Set the value to a secret string (consider using a password generator).
  8. This header/value will now be sent to your origin on every request.

Step 15: Finalise your configuration.

CrowdHandler is integrated with your CloudFront distribution and now it's over to you to customize your CrowdHandler setup through the CrowdHandler administration console. Here are some recommended support articles that cover the basics:

  1. Getting Started (You can disregard the bits about installing the Javascript integration.)
  2. Waiting Rooms
  3. Domain Configuration