Terminate SSL on AWS Amazon Load Balancers (ALB)

Background

AWS ALB (and possibly other load balancers/reverse proxies) terminate SSL at the load balancer level and communicate with backend servers (Pyramid) over HTTP. The "X-Forwarded-Proto" header ensures that Pyramid correctly identifies requests as HTTPS and responds accordingly. For most reverse proxies / load balancers this setting is NOT needed as they know how to handle the SSL termination correctly. 

Prerequisites

• This guide applies only to Pyramid 2023.16.083 / 2024.01.013 and later .
• Earlier versions do not support the "X-Forwarded-Proto" header.

---

1. Enabling "X-Forwarded-Proto" in Pyramid

Pyramid must be configured to recognize HTTPS requests forwarded by the AWS Application Load Balancer (ALB). This is done using the "X-Forwarded-Proto" header.

Steps:

1. Log in to Pyramid Admin.
2. Navigate to:
   Services → Web Services → Web Settings.
3. Check the box for "Proxy SSL Handling (X-Forwarded-Proto)".
4. Click Apply.
5. Restart all Pyramid web servers for the change to take effect.

   

---

2. Configuring an AWS Application Load Balancer (ALB)

Note: AWS configurations may change over time. Always refer to the latest AWS documentation for updates.

Step 1: Create an Application Load Balancer

1. Open the AWS Console.
2. Go to EC2 → Load Balancers.
3. Click "Create Load Balancer" and select Application Load Balancer.

Basic Configuration:

Setting	Value
Load Balancer Name	Choose a name (e.g., Pyramid-ALB)
Scheme	Internet-facing (or Internal if needed)
IP Address Type	IPv4 (or Dualstack for IPv6 support)

Network Mapping:

Setting	Value
VPC	Select the VPC where Pyramid is running
Availability Zones & Subnets	Choose based on your infrastructure

Security Groups:

• Select or create a security group that allows inbound HTTPS (443) traffic.

---

Step 2: Configure Listeners & Routing

Setting	Value
Protocol	HTTPS
Port	443
Default Action	Forward requests to a target group (if none exists, create one in the next step).

---

Step 3: Create a Target Group

1. Click "Create Target Group".
2. Select "Instances" as the Target Type.
3. Configure the settings:

Setting	Value
Target Group Name	Pyramid
Protocol	HTTP
Port	8181 (default Pyramid web port)
IP Address Type	Choose based on your setup
VPC	Select the Pyramid VPC

Health Check Configuration:

Setting	Value
Health Check Path	/login/login.html
Protocol	HTTP
Port	Traffic port (or 8181)
Healthy Threshold	Default recommended
Unhealthy Threshold	Default recommended
Timeout	Default recommended
Interval	Default recommended

4. Click Next and register targets:
   • Select the EC2 instances running Pyramid.
   • Ensure the port is set to 8181.
   • Click "Include as pending below", then "Create Target Group".

---

Step 4: Assign the Target Group to the Load Balancer

1. Return to the "Listeners & Routing" section of the ALB setup.
2. Under Default Action, select "Forward to Target Group".
3. Choose the Pyramid target group created earlier.

---

Step 5: Configure SSL/TLS Certificate

1. Under Secure Listener Settings, select "Default SSL/TLS Certificate".
2. Upload or select an existing SSL certificate.
3. (Optional) Configure additional security settings based on your company's policies.

---

3. Final Configuration & Testing

Modify ALB Listener Rules (Optional)

If needed, edit the listener rules:

1. Go to EC2 → Load Balancers.
2. Select the ALB and navigate to Listeners → HTTPS:443 → Edit Default Rule.
3. Ensure the action is "Forward to Target Groups" and the correct Pyramid target group is selected.

---

1. Increase ALB Idle Timeout

Setting	Value
Default	60 seconds
Recommended	600 seconds

Steps:

1. Go to EC2 Dashboard → Load Balancers.
2. Select your Application Load Balancer (ALB).
3. Go to the Attributes tab.
4. Click Edit.
5. Set Idle Timeout to 600 seconds.
6. Click Save.

---

2. Adjust Target Group Health Check Settings

Increase timeout & interval to prevent premature failures.

Setting	Recommended Value
Timeout	10 seconds
Interval	30 seconds
Unhealthy Threshold	5
Healthy Threshold	3

Steps:

1. Go to EC2 Dashboard → Target Groups.
2. Select your Target Group.
3. Go to the Health Checks tab → Click Edit.
4. Apply the recommended values above.
5. Click Save.

---

Update Security & DNS Settings

• Security Group: Ensure inbound port 443 is open to allow user connections.
• DNS Configuration: Update external DNS records to point to the ALB DNS name.

---

4. Summary

Pyramid is now configured to recognize HTTPS requests using "X-Forwarded-Proto".

The AWS Load Balancer terminates SSL and forwards requests to Pyramid over HTTP.

Users can securely access Pyramid at https://your-domain.com via the ALB.

For further assistance, refer to the AWS Load Balancer Documentation or contact AWS Support.