Install the Akamai EdgeWorker Enforcer v4

If your organization uses Akamai, you can use HUMAN's Akamai EdgeWorker Enforcer to protect against malicious behavior. The Enforcer is installed using an Akamai EdgeWorker and deployed to your content delivery network (CDN). The Enforcer dictates how traffic should be handled per your organization's standards.

You can learn how to install the Akamai EdgeWorker Enforcer with this article.

🚧

Warning

This process only works if you do not have an existing Enforcer integrated with your application. If you do, see our article on manual installation.

Prerequisites

• An Akamai account with editor access to the following:
  • NetStorage services
  • EdgeWorkers
  • Property Manager
• Depending on your preferred deployment method, the following tools:
  • Docker method:
    • Docker. See how to install Docker with their documentation.
  • Script method:
    • Node.js 18.x or later and npm 10.x or later. See how to install both with npm’s documentation.
    • Git CLI. You can download it directly from Git.
    • GNU Wget. See how to install with their documentation.
• Your unique HUMAN information:
  • Your Application ID. You can find this under Platform Settings > Applications > Overview in the HUMAN console. If you have multiple environments, you will also have multiple Application IDs, so be sure to choose the correct ID for the environment you want to install on.
  • Your Server Token. You can find this under Platform Settings > Applications, then selecting an application and navigating to Application settings > Server token.
  • Your Risk Cookie Key. You can find this under Bot Defender > Policies > Policy Settings > Policy Information.
• Other HUMAN information provided by your Solutions Engineer:
  • Your logger authentication token.
  • Your remote configuration authentication token.
  • Your remote configuration ID.
  • An Enforcer configuration file, enforcerConfig.json. Be sure to save it in a directory you’ll remember (like /deploy).

Akamai setup

The Akamai setup consists of three parts. Be sure to complete each part in order.

1. Create an API client
2. If you do not have one already, create a NetStorage storage group
3. If you do not have one already, create a NetStorage upload account

📘

Note

We recommend letting HUMAN set up your Akamai EdgeWorker, Property Manager, and NetStorage due to the manual nature of the process. This requires creating an API token so that the HUMAN CDN Enforcer Deploy Tool can access your Akamai environment.

Create an API client

The deploy tool must send API requests to Akamai to configure the EdgeWorker and the Property Manager. To send these requests, you must create a personal API client.

1. Log in to the Akamai Control Center.
2. From the main menu, select Account Admin > Identity and Access.
3. Under Users and API Clients, click Create API client.
4. Click Advanced.
5. Update the following fields as specified below. Otherwise, you can complete fields as appropriate for your organization or leave them as their defaults.
   1. For the APIs selection, click Select APIs.
   2. Grant READ-WRITE access to the following:
      1. Property Manager (PAPI)
      2. EdgeWorkers
      3. NetStorage
   3. Click Submit
   4. For the Group selection, choose Same group as <user account name>.
6. Click Create API Client.
7. Save the generated API client credentials, including the host, client token, client secret, and access token, in a secure location. The deploy tool uses these credentials later on.

🚧

Warning

This will be the only time you’ll see your credentials, so be sure to save them before closing the page.

Create a NetStorage storage group

📘

Note

These steps are optional and only necessary if you do not already have a storage group. If you do, you can move on to Upload accounts.

1. From your Akamai account’s main menu, navigate to Origin Services > NetStorage > Storage Groups.
2. Select the + to Create a new storage group.
3. Update the following fields as specified below. If not specified, you can complete fields as appropriate for your organization or leave them as their defaults.
   1. In Step 1, Basic Information:
      1. Set the storage group name as human-storage-group
      2. Set the domain name prefix as human-storage-group
   2. In Step 4, Upload Directories:
      1. Click Create a new upload directory
      2. Keep the default values and click Add. Then, click Next.
   3. In Step 6, Summary, review your settings and click Create.

The storage group will start to propagate, which may take up to two hours. Meanwhile, you can move on to creating an upload account.

Create a NetStorage upload account

📘

Note

These steps are optional and only necessary if you have not uploaded accounts yet. If you have, you can move on to Deploy the Enforcer.

1. Navigate to Origin Services > NetStorage > Upload Accounts.
2. Select the + to create a new upload account.
3. Update the following fields as specified below. Otherwise, you can complete fields as appropriate for your organization or leave them as their defaults.
   1. In Step 1, Basic Information:
      1. Enter human-upload-account as the Upload Account ID.
      2. Provide a name and contact information for your account.
   2. In Step 2, Access Methods:
      1. Click the File Manager tab
      2. Enable File Manager access.
   3. In Step 3, Upload Directory Association, select the group you made in Create a storage group, human-storage-group.
   4. In Step 5, Summary, review your settings and click Create.
4. Navigate to NetStorage > Storage Groups. Select the group you created, human-storage-group. Then, select File Manager.
5. In File Manager Access, locate your user account. Then, locate the human-upload-account upload account and click the checkbox to select it.
6. Click Save to apply changes.

The upload account will start to propagate, which may take up to two hours. Afterwards, you can move on to updating the configuration file.

Update the configuration file

1. Update the Enforcer configuration file, enforcerConfig.json, with your unique HUMAN information if it hasn’t been already.

{
  "px_app_id": "<APP_ID>",
  "px_auth_token": "<AUTH_TOKEN>",
  "px_cookie_secret": "<COOKIE_SECRET>",
  "px_logger_auth_token": "<LOGGER_AUTH_TOKEN>",
  "px_remote_config_auth_token": "<REMOTE_CONFIG_AUTH_TOKEN>",
  "px_remote_config_id": "<REMOTE_CONFIG_ID>"
}

2. Save your file and select your preferred method to run the Deploy Tool.
   1. Docker method
   2. Script method

Run the Deploy Tool

Docker method

📘

Note for Windows users

Windows users also need to complete additional setup for Docker:

1. In your Windows search bar, search for and open “Turn Windows features on or off”.
2. Find the Windows Hypervisor Platform feature and enable it.
3. Click OK to save your changes.
4. Open Windows Powershell as an Administrator.
5. Copy and paste in C:\Windows\System32\wsl.exe --update --web-download, then hit Enter.

1. Pull the Docker Image by running:

docker pull us-docker.pkg.dev/hmn-registry/docker-public/cdn-enforcer-deploy-tool

2. Navigate to the directory where you created enforcerConfig.json. Based on our example from above, this would be the /deploy directory.
3. Run the deploy tool with the following:

docker run --rm -v $PWD:/app/local -it us-docker.pkg.dev/hmn-registry/docker-public/cdn-enforcer-deploy-tool

Script method

1. Navigate to the directory where you created enforcerConfig.json. Based on our example from above, this would be your /deploy directory.
2. Pull the HUMAN Deploy Tool zip from Google Artifact Registry using:

wget 'https://artifactregistry.googleapis.com/v1/projects/hmn-registry/locations/us/repositories/enforcers-public/files/cdn-enforcer-deploy-tool_win:1.1.0:cdn-enforcer-deploy-tool_win.zip:download?alt=media' -O cdn-enforcer-deploy-tool.zip

wget 'https://artifactregistry.googleapis.com/v1/projects/hmn-registry/locations/us/repositories/enforcers-public/files/cdn-enforcer-deploy-tool_unix:1.1.0:cdn-enforcer-deploy-tool_unix.zip:download?alt=media' -O cdn-enforcer-deploy-tool.zip

3. Unzip cdn-enforcer-deploy-tool.zip to the same directory (e.g., /deploy)
4. Run the tool by opening the cdn-enforcer-deploy-tool.bat script for Windows or cdn-enforcer-deploy-tool.command for Mac or Linux.

Deploy the Enforcer

1. When prompted, select Akamai EdgeWorker and hit Enter.

🚀 HUMAN CDN Enforcer Deploy Tool 🚀
? Which platform do you want to deploy to? (Use arrow keys)
  ...
  Cloudflare Workers
❯ Akamai EdgeWorker
  ...

2. Continue to follow the steps that appear to complete your deployment.
3. When you finish the setup, confirm that the displayed details are correct, then enter y to deploy the Enforcer.