AWS Application Load Balancer (ALB)

Deploy Centinel Analytica on AWS Application Load Balancer using Lambda middleware.

Overview

This guide shows you how to protect an AWS Application Load Balancer with Centinel. The Lambda middleware validates requests through the Centinel API before they reach your backend.

Prerequisites

Centinel secret key (from your dashboard)
AWS CLI configured with credentials
Backend service URL to protect
AWS permissions for Lambda, ALB, EC2, and IAM

Installation

Prepare the Lambda package

Download centinel-alb.js

Open the file and set:

const CENTINEL_SECRET_KEY = "sk_live_your_key_here";
const BACKEND_URL = "https://your-backend.com";

Zip the file:
```
zip centinel-alb.zip centinel-alb.js
```

Create the Lambda function

Using AWS Console:

Go to Lambda → Create function
Choose Author from scratch
Function name: centinel-alb
Runtime: Node.js 20.x
Create the function
Upload centinel-alb.zip via Code → Upload from → .zip file
Under Configuration → General configuration, set:
- Timeout: 30 seconds
- Memory: 256 MB

Using AWS CLI:

# Create execution role
aws iam create-role \
  --role-name centinel-alb-role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "lambda.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

# Attach basic execution policy
aws iam attach-role-policy \
  --role-name centinel-alb-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

# Create Lambda function
aws lambda create-function \
  --function-name centinel-alb \
  --runtime nodejs20.x \
  --role arn:aws:iam::YOUR_ACCOUNT_ID:role/centinel-alb-role \
  --handler centinel-alb.handler \
  --zip-file fileb://centinel-alb.zip \
  --timeout 30 \
  --memory-size 256 \
  --region eu-central-1

Create Application Load Balancer

Using AWS Console:

Go to EC2 → Load Balancers → Create Load Balancer
Choose Application Load Balancer
Name: centinel-alb
Scheme: Internet-facing
Select your VPC and at least 2 availability zones
Create or select a security group that allows HTTP (80) and HTTPS (443)
Create the load balancer

Using AWS CLI:

# Get VPC and subnets
VPC_ID=$(aws ec2 describe-vpcs \
  --filters "Name=is-default,Values=true" \
  --query 'Vpcs[0].VpcId' \
  --output text)

SUBNET_IDS=$(aws ec2 describe-subnets \
  --filters "Name=vpc-id,Values=$VPC_ID" \
  --query 'Subnets[0:2].SubnetId' \
  --output text)

# Create security group
SG_ID=$(aws ec2 create-security-group \
  --group-name centinel-alb-sg \
  --description "Security group for Centinel ALB" \
  --vpc-id $VPC_ID \
  --query 'GroupId' \
  --output text)

aws ec2 authorize-security-group-ingress \
  --group-id $SG_ID \
  --protocol tcp \
  --port 80 \
  --cidr 0.0.0.0/0

# Create ALB
aws elbv2 create-load-balancer \
  --name centinel-alb \
  --subnets $SUBNET_IDS \
  --security-groups $SG_ID \
  --region eu-central-1

Create target group

Using AWS Console:

Go to EC2 → Target Groups → Create target group
Target type: Lambda function
Target group name: centinel-lambda-tg
Select your Lambda function
Create the target group

Using AWS CLI:

# Create target group
TG_ARN=$(aws elbv2 create-target-group \
  --name centinel-lambda-tg \
  --target-type lambda \
  --region eu-central-1 \
  --query 'TargetGroups[0].TargetGroupArn' \
  --output text)

# Register Lambda as target
LAMBDA_ARN=$(aws lambda get-function \
  --function-name centinel-alb \
  --region eu-central-1 \
  --query 'Configuration.FunctionArn' \
  --output text)

aws elbv2 register-targets \
  --target-group-arn $TG_ARN \
  --targets Id=$LAMBDA_ARN \
  --region eu-central-1

Configure listener

Using AWS Console:

Go to your ALB's Listeners tab
Click Add listener
Protocol: HTTP, Port: 80
Default action: Forward to your target group
Create the listener

Using AWS CLI:

ALB_ARN=$(aws elbv2 describe-load-balancers \
  --names centinel-alb \
  --region eu-central-1 \
  --query 'LoadBalancers[0].LoadBalancerArn' \
  --output text)

aws elbv2 create-listener \
  --load-balancer-arn $ALB_ARN \
  --protocol HTTP \
  --port 80 \
  --default-actions Type=forward,TargetGroupArn=$TG_ARN \
  --region eu-central-1

Grant permissions

Allow the ALB to invoke your Lambda function:

aws lambda add-permission \
  --function-name centinel-alb \
  --statement-id alb-invoke \
  --action lambda:InvokeFunction \
  --principal elasticloadbalancing.amazonaws.com \
  --region eu-central-1

Test the setup

Get your ALB DNS name:

aws elbv2 describe-load-balancers \
  --names centinel-alb \
  --region eu-central-1 \
  --query 'LoadBalancers[0].DNSName' \
  --output text

Test it:

curl -v http://YOUR-ALB-DNS.eu-central-1.elb.amazonaws.com

How it works

Client → ALB → Lambda (Centinel) → Decision
                                       ↓
                          ┌────────────┴───────────┐
                          │                        │
                     Blocked (403)            Allowed
                          │                        │
                    Block page                Backend

Every request goes through Centinel validation:

Client sends request to your ALB
ALB invokes the Lambda function
Lambda validates with Centinel API
Based on the result:
- Block → Returns 403 error page
- Challenge → Returns verification page
- Allow → Forwards to your backend

If Centinel is unreachable, requests are allowed through (fail-open).

Configuration

The Lambda function has these settings in centinel-alb.js:

const CENTINEL_SECRET_KEY = "";           // Your API key (required)
const BACKEND_URL = "";                   // Your backend URL (required)
const CENTINEL_TIMEOUT_MS = 200;          // API timeout (optional)
const BACKEND_TIMEOUT_MS = 25000;         // Backend timeout (optional)

Lambda settings:

Runtime: Node.js 20.x
Memory: 256 MB
Timeout: 30 seconds

Troubleshooting

Target shows as unhealthy

Make sure the Lambda function has permission to be invoked by the ALB:

aws lambda add-permission \
  --function-name centinel-alb \
  --statement-id alb-invoke \
  --action lambda:InvokeFunction \
  --principal elasticloadbalancing.amazonaws.com \
  --region eu-central-1

All requests blocked

Check your API key and review the CloudWatch logs:

aws logs tail /aws/lambda/centinel-alb --follow --region eu-central-1

Common issues:

Wrong API key in centinel-alb.js
API key not activated in dashboard
Protection rules need adjustment

Cannot reach backend

If your backend is in a private VPC, configure the Lambda function to use that VPC:

aws lambda update-function-configuration \
  --function-name centinel-alb \
  --vpc-config SubnetIds=subnet-xxx,subnet-yyy,SecurityGroupIds=sg-xxx \
  --region eu-central-1

Also attach the VPC execution policy:

aws iam attach-role-policy \
  --role-name centinel-alb-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole

Slow response times

First requests after idle periods take longer (Lambda cold starts). For consistent performance, enable Provisioned Concurrency:

aws lambda put-provisioned-concurrency-config \
  --function-name centinel-alb \
  --provisioned-concurrent-executions 1 \
  --region eu-central-1

Changelog

1.2.0 - HTTP/2 support for validator connections
1.1.0 - Connection pooling improvements
1.0.0 - Initial release

AWS Application Load Balancer (ALB)

On this page