How to Install Keycloak on an AWS EC2 Instance for Production

Hosting Keycloak on an AWS EC2 Instance for Production

Hosting Keycloak on an AWS EC2 instance is a great way to manage authentication and authorization in a production environment. This guide will walk you through the steps to install and configure Keycloak version 25.x on an Ubuntu server using AWS EC2. We will also set up HTTPS using a self-signed SSL certificate.

Step 1: Choose a Server Provider

To host Keycloak, select a reliable cloud provider such as AWS, DigitalOcean, Azure, or Google Cloud. In this guide, we will use AWS EC2 as an example.

Step 2: Create an EC2 Instance

1. Log in to AWS Management Console.
2. Navigate to EC2 Dashboard.
3. Launch a New Instance:
   • Choose an Amazon Machine Image (AMI): Use a Linux distribution like Ubuntu Server.
   • Select an Instance Type: For small to medium workloads, choose t2.small or higher.
   • Configure Instance Details: Set up network settings and storage as per your requirements.
   • Configure Security Group:
     • Allow the following inbound rules:
     • HTTP (port 80)
     • HTTPS (port 443)
     • Custom TCP (port 8080) - if you plan to run Keycloak on the default port.
     • SSH (port 22) - for remote access.
   • Review and Launch the instance.

Step 3: Connect to Your EC2 Instance

After launching, go to the EC2 Dashboard and select your instance. Click Connect to get the SSH command.

Use SSH to connect to your instance:

ssh -i "your-key.pem" ubuntu@your-ec2-instance-public-dns

Replace your-key.pem with the path to your private key file and your-ec2-instance-public-dns with the Public DNS of your EC2 instance.

Step 4: Install Java (OpenJDK)

Keycloak requires Java to run. Install OpenJDK 17 by running:

sudo apt update
sudo apt install -y openjdk-17-jdk

Step 5: Download and Install Keycloak

Download Keycloak version 25.x:

wget https://github.com/keycloak/keycloak/releases/download/25.0.2/keycloak-25.0.2.zip

Step 6: Unzip Keycloak

Install unzip and unzip the downloaded Keycloak package:

sudo apt install unzip
unzip keycloak-25.0.2.zip

Step 7: Move Keycloak to the Desired Directory

Move the Keycloak folder to /opt:

sudo mv keycloak-25.0.2 /opt/keycloak

Step 8: Configure Keycloak for Production

Create a dedicated user to run Keycloak:

sudo useradd -r -s /bin/false keycloak

Assign ownership of the Keycloak directory:

sudo chown -R keycloak:keycloak /opt/keycloak

Switch to the Keycloak directory:

cd /opt/keycloak

Step 9: Install a Self-Signed SSL Certificate

To run Keycloak securely over HTTPS, we'll set up a self-signed SSL certificate. This is sufficient for testing purposes, but for production, use a trusted CA.

Update the Package List:

sudo apt update

Install OpenSSL and Nginx:

sudo apt install openssl nginx -y

Generate a Self-Signed SSL Certificate:

Create a directory to store the SSL certificate:

sudo mkdir -p /etc/ssl/private

Generate the SSL certificate and private key:

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/keycloak-selfsigned.key -out /etc/ssl/certs/keycloak-selfsigned.crt

When prompted, enter your server's IP address or domain name for the Common Name (CN). Other fields are optional.

Step 10: Configure Nginx to Use the Self-Signed SSL Certificate

Create a new Nginx configuration file for Keycloak:

sudo nano /etc/nginx/sites-available/keycloak

Add the following configuration:

server {
    listen 80;
    server_name <your-ec2-ip>;  # Replace with your domain or IP if needed
    
    # Redirect all HTTP requests to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name <your-ec2-ip>;  # Replace with your domain or IP if needed

    ssl_certificate /etc/ssl/certs/keycloak-selfsigned.crt;
    ssl_certificate_key /etc/ssl/private/keycloak-selfsigned.key;

    location / {
        proxy_pass http://localhost:8080;  # Forward to Keycloak
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the Nginx configuration and restart Nginx:

sudo ln -s /etc/nginx/sites-available/keycloak /etc/nginx/sites-enabled/
sudo nginx -t  # Test the configuration for errors
sudo systemctl restart nginx

Step 11: Configure Keycloak to Work Behind Nginx with HTTPS

Edit the Keycloak configuration file:

sudo nano /opt/keycloak/conf/keycloak.conf

Add the following lines to configure Keycloak for HTTPS:

hostname=<Your-Domain-Or-IP>  # Replace with your actual domain or IP
hostname-strict-https=false
proxy=edge

Step 12: Start Keycloak Normally

Make sure Keycloak is running without start-dev mode:

sudo -u keycloak KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=admin /opt/keycloak/bin/kc.sh start

Step 13: Access Keycloak via HTTPS

Open your browser and navigate to:

https://<Your-Domain-Or-IP>

Replace <Your-Domain-Or-IP> with your EC2 instance's public IP or domain.

Step 14: Configure Keycloak to Use the External Database

Keycloak should not use the default embedded H2 database in production. Instead, set up a production-grade database like PostgreSQL or MySQL.

Edit the keycloak.conf file in the /opt/keycloak/conf directory to include your database settings (Using postgres here):

db=postgres
db-url=jdbc:postgresql://localhost:5432/keycloakdb
db-username=keycloakuser
db-password=yourpassword

Note on Browser Security Warnings:

Since the SSL certificate is self-signed, any machine trying to access the Keycloak Admin Console will see a security warning indicating that the certificate is not from a trusted Certificate Authority (CA). Manually accept the risk or add an exception in the browser for each machine accessing Keycloak.