Integrazione con AWS CloudFront - Guida introduttiva

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.

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://support.crowdhandler.com

  1. Un account CrowdHandler attivo. Se non ti sei ancora registrato, puoi farlo qui.
  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
  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 (booleano) (impostazione predefinita: true)

Se il valore è falso, un utente che non riesca a effettuare il check-in tramite l'API di CrowdHandler verrà indirizzato a una sala d'attesa di sicurezza fino a quando CrowdHandler non sarà in grado di decidere come gestirlo.

Se vero, gli utenti che non effettuano il check-in tramite l'API di CrowdHandler saranno considerati affidabili.

safetyNetSlug (stringa) (valore predefinito: non definito)

Se definito e se failTrust è impostato su false, questo slug della sala d'attesa verrà utilizzato come sala di riserva.

**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
  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
  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:

  • Percorsi utilizzati per l'archiviazione di risorse statiche e file multimediali, ad esempio /wp-includes/*
  • URL di callback generati da fornitori di servizi di pagamento di terze parti.
  • Feed JSON e RSS.
  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. Introduzione (Puoi ignorare le parti relative all'installazione dell'integrazione JavaScript.)
  2. Sale d'attesa
  3. Configurazione del dominio