AWS Installation: Using a Load Balancer for SSL Termination

Last modified on January 19, 2023

After deploying SwaggerHub On-Premise to AWS, you may want to enable HTTPS access to the instance. There are two ways to set up HTTPS for SwaggerHub On-Premise:

  • Install an SSL certificate directly on your SwaggerHub EC2 instance. This approach is straightforward and is explained here.

-- OR --

  • Configure a load balancer for SSL termination (also known as SSL offloading). The users will connect to the load balancer using HTTPS, and the load balancer will forward the requests to your SwaggerHub EC2 instance through HTTP. You may want to use this approach if you use AWS Certificate Manager (ACM) to manage your SSL certificates.

This guide explains how to configure a load balancer with an SSL certificate and how to route inbound traffic to your SwaggerHub EC2 instance through this load balancer.

1. Get an SSL certificate

This guide assumes you already have an SSL certificate with a matching private key. You can get an SSL certificate from a certificate authority (CA) of your choice, request a certificate from AWS Certificate Manager (ACM), or use a self-signed certificate. Make sure your certificate meets the AWS requirements.

The certificate common name (CN) must match the domain name you will use for SwaggerHub, such as swaggerhub.MyCompany.com. You can also use a wildcard certificate for the base domain (*.MyCompany.com).

2. Create a security group for the load balancer

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2.

  2. Switch to the AWS region where your SwaggerHub On-Premise instance is deployed.

  3. On the left, select Security Groups.

  4. Click Create Security Group.

  5. Give this group a unique name (for example, SwaggerHub-OnPremise-LB) and enter a description.

  6. Select the VPC where the instance is deployed.

  7. Add the following Inbound rules:

    Type Protocol Port Range Source Description
    HTTP TCP 80 Anywhere Port 80 will be redirected to port 443 (HTTPS)
    HTTPS TCP 443 Anywhere HTTPS access to SwaggerHub
    Note: Anywhere or 0.0.0.0/0, ::/0 means inbound access from all IP addresses. You may want to restrict access to specific IP addresses and ranges instead.

3. Configure target groups

In this guide, we will use an Application Load Balancer (ALB). Application Load Balancers use target groups to route requests to a specific port of the target EC2 instance. Target group configuration also includes health checks.

To create a target group:

  1. Make sure you are still in the same AWS region where your SwaggerHub On-Premise instance is.

  2. In the left part of the EC2 console, under Load Balancing, select Target Groups.

  3. Click Create target group.

  4. Specify the following values:

    Option Target group 1
    Target group name SwaggerHub-OnPrem-Frontend
    Target type instance
    Protocol HTTP
    Port 80
    VPC Select the VPC used by your SwaggerHub EC2 instance
    Health check settings (see below)
    Protocol HTTP
    Path /_health
    Advanced health check settings (see below)
    Port traffic port
    Healthy threshold * 5 *
    Unhealthy threshold * 2 *
    Timeout * 5 *
    Interval * 30 *
    Success codes 200

    * You may use other values for the thresholds, timeout and interval based on your requirements.

  5. Click Create.

  6. Select the created target group and switch to the Targets tab at the bottom.

  7. Click Edit.

  8. In the list at the bottom, select your SwaggerHub EC2 instance, and click Add to registered.

    Note: If your SwaggerHub EC2 instance is not on the list, make sure it is running.
    Add to registered

    Click the image to enlarge it.

  9. Click Save.

4. Create a load balancer

  1. Make sure you are still in the same AWS region where your SwaggerHub On-Premise instance is.

  2. In the EC2 console, select Load Balancers on the left.

  3. Click Create Load Balancer.

  4. Choose to create an Application Load Balancer.

    Creating an Application Load Balancer

    Click the image to enlarge it.

  5. Configure the load balancer:

    Option Value
    Name Give this load balancer a name, for example, SwaggerHub-OnPrem-LB.
    Scheme internal or internet-facing depending on your needs.
    IP address type ipv4
    Listeners Add a listener for HTTPS port 443 (we will add a port 80 listener later).
    VPC Select the same VPC as the one used by your SwaggerHub EC2 instance.
    Availability Zones Select at least two availability zones.
  6. Click Next: Configure Security Settings.

  7. Specify the SSL certificate the load balancer will use to negotiate SSL connections with the clients. You can upload your certificate, or if it is already stored in AWS Certificate Manager (ACM), select it from the list.

    Note: This should be the certificate issued for your SwaggerHub On-Premise domain, such as swaggerhub.MyCompany.com, or a wildcard certificate, such as *.MyCompany.com.
  8. Click Next: Configure Security Groups.

  9. Select the security group you created earlier for the load balancer.

  10. Click Next: Configure Routing.

  11. Change Target group to Existing target group, and select the group named SwaggerHub-OnPrem-Frontend. Leave the other settings unchanged.

  12. Click Next until you get to the Review page, then click Create.

  13. Click Close.

  14. Now, we will add a rule to redirect inbound HTTP connections to HTTPS. In the load balancer details, switch to the Listeners tab and click Add listener.

  15. Make sure the protocol and port are set to HTTP : 80.

  16. Click Add action and select Redirect to.

  17. Specify HTTPS port 443 as the target port. Leave other values as is and click the check mark icon.

    Listener configuration to redirect HTTP to HTTPS
  18. Click Save at the top of the page.

  19. Your load balancer configuration should now look like this:

    Port listener roles for AWS load balancer

    Click the image to enlarge it.

  20. On the Description tab, note down the DNS name of your load balancer.

    DNS name of the load balancer

    Click the image to enlarge it.

  21. To verify that the load balancer works, wait until its state becomes active, then navigate to https://Load.Balancer.DNS.Name in your browser. Choose to ignore the certificate error (it occurs because you access the site using a different DNS name, not the one the certificate is issued for). You should see the SwaggerHub home page.

  22. To test that HTTP is redirected to HTTPS, navigate to HTTP://Load.Balancer.DNS.Name and confirm that the redirect occurs.

 

Once your load balancer is set up, use your DNS service to create a CNAME record that will point your desired SwaggerHub domain (such as swaggerhub.MyCompany.com) to the load balancer DNS name. For more information on how to create CNAME records, refer to the documentation of your DNS service. If you use Route 53, the steps are provided below.

5. Register a domain name in Route 53 (optional)

If you use Amazon Route 53 as the DNS service for your domain, you can use it to register a domain name for your SwaggerHub On-Premise instance.

This guide assumes that you already have a hosted zone in Route 53. To learn how to create hosted zones, refer to the Route 53 documentation:

To create a DNS entry for SwaggerHub:

  1. Open the Amazon Route 53 console at https://console.aws.amazon.com/route53/.

  2. On the left, select Hosted Zones.

  3. Click your hosted zone in the list.

    Hosted zone in Route 53

    Click the image to enlarge it.

  4. Click Create Record Set.

  5. Specify the following:

    Option Value
    Name The desired domain name for your SwaggerHub instance. For example, swaggerhub.MyCompany.com. This domain name must match the Common Name (CN) of the SSL certificate used by the load balancer.
    Type A - IPv4 Address
    Alias Yes
    Alias Target Select your load balancer from the list
    Routing Policy Simple
    Evaluate Target Health Select Yes or No based on your needs
  6. Click Create.

6. Configure SwaggerHub for HTTPS access

Once you have a domain name pointing to your load balancer, you need to specify this domain name in the SwaggerHub system settings, and indicate that SSL offloading is in place:

  1. Navigate to http://VM_IP_address/ui to open the Admin Center.

  2. Select Settings on the left.

  3. In the DNS name for this instance field, enter the domain name you registered for SwaggerHub, such as swaggerhub.MyCompany.com. This domain name must point to the load balancer.

  4. In the Privacy section, change the SSL Termination setting to Use SSL with termination on external load balancer.

    Enabling HTTPS in SwaggerHub On-Premise

    Click the image to enlarge it.

  5. If your SSL certificate is self-signed or issued by a private CA:

    • Upload your trusted CA root and any intermediate certificates in the PEM format to the Certificate Manager.

    • In Settings > Privacy, add your custom certificates to the SSL certificate trust chain list.

  6. Click Save Changes and Restart. Wait a few minutes for the system to restart completely.

Now you can access SwaggerHub at https://Your.SwaggerHub.Domain, and the Admin Center at https://Your.SwaggerHub.Domain/ui.

See Also

Installing SwaggerHub On-Premise on AWS
Configuring SwaggerHub On-Premise

Highlight search results