Skip to content

Secure Web App with Keycloak on Ubuntu 22.04

Note: This guide documents the oauth2-proxy authentication architecture. As of TQ-51 (2026-02-19), TQPro supports native OIDC authentication where the frontend (tqweb-adm) acts as an OIDC client directly, eliminating the need for oauth2-proxy. The backend validates JWT tokens using Nimbus JOSE+JWT against Keycloak's public keys. See the OIDC Migration Implementation Plan for migration details and the auth-mode property in tlinqapi.properties for configuration.

This guide walks you through a non-production setup using:

📦 1. Install Amazon Corretto 21

sudo apt update
sudo apt install -y wget gnupg apt-transport-https

# Import Amazon Corretto GPG key
wget -O- https://apt.corretto.aws/corretto.key | sudo gpg --dearmor -o /usr/share/keyrings/corretto-keyring.gpg

# Add repository to APT sources
echo "deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main" | sudo tee /etc/apt/sources.list.d/corretto.list

# Install Corretto 21
sudo apt update
sudo apt install -y java-21-amazon-corretto-jdk

# Verify
java -version

🔧 2. Install Keycloak (Bare-Metal, Dev Mode)

Create Keycloak System User

sudo adduser --system --no-create-home --group keycloak
sudo mkdir -p /opt/keycloak
sudo chown keycloak:keycloak /opt/keycloak
cd /opt/keycloak

Download and Extract Keycloak

sudo -u keycloak bash -c '
cd /opt/keycloak
wget https://github.com/keycloak/keycloak/releases/download/26.4.0/keycloak-26.4.0.tar.gz
tar -xzf keycloak-26.4.0.tar.gz --strip-components=1
rm keycloak-26.4.0.tar.gz
'

Create Admin User and Start

sudo -u keycloak /opt/keycloak/bin/kc.sh build

sudo -u keycloak /opt/keycloak/bin/kc.sh bootstrap-admin user
# [Enter the admin username and password]

# Start in development mode
sudo -u keycloak /opt/keycloak/bin/kc.sh start-dev

Keycloak is now accessible at: http://localhost:8080

🔐 3. Install and Configure oauth2-proxy

Download Binary

OAUTH2_VERSION="v7.12.0"
wget https://github.com/oauth2-proxy/oauth2-proxy/releases/download/${OAUTH2_VERSION}/oauth2-proxy-${OAUTH2_VERSION}.linux-amd64.tar.gz
tar -xzf oauth2-proxy-${OAUTH2_VERSION}.linux-amd64.tar.gz
sudo cp oauth2-proxy-${OAUTH2_VERSION}.linux-amd64/oauth2-proxy /usr/local/bin/

Or, for ARM-64 processors (for example AWS Graviton): 

OAUTH2_VERSION="v7.12.0"
wget https://github.com/oauth2-proxy/oauth2-proxy/releases/download/${OAUTH2_VERSION}/oauth2-proxy-${OAUTH2_VERSION}.linux-arm64.tar.gz
tar -xzf oauth2-proxy-${OAUTH2_VERSION}.linux-arm64.tar.gz
sudo cp oauth2-proxy-${OAUTH2_VERSION}.linux-arm64/oauth2-proxy /usr/local/bin/

Create Config File

sudo mkdir -p /etc/oauth2-proxy

cat <<EOF | sudo tee /etc/oauth2-proxy/oauth2-proxy.cfg
provider = "keycloak-oidc"
oidc_issuer_url = "http://localhost:8080/realms/myrealm"
client_id = "myapp"
client_secret = "myapp-secret"
redirect_url = "https://your-app.example.com/oauth2/callback"
cookie_secret = "0123456789abcdef0123456789abcdef"
cookie_secure = false
email_domains = ["*"]
http_address = "127.0.0.1:4180"
upstreams = ["http://127.0.0.1:8081/"]
EOF

Start oauth2-proxy

oauth2-proxy --config /etc/oauth2-proxy/oauth2-proxy.cfg

🌐 4. Configure NGINX Reverse Proxy

Install NGINX if not already:

sudo apt install -y nginx

Edit or create your site config (e.g., /etc/nginx/sites-available/myapp):

server {
    listen 443 ssl;
    server_name your-app.example.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    location = /oauth2/auth {
        internal;
        proxy_pass       http://127.0.0.1:4180;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
    }

    location /oauth2/ {
        proxy_pass       http://127.0.0.1:4180;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
    }

    location / {
        auth_request /oauth2/auth;
        error_page 401 = /oauth2/start;

        proxy_pass http://127.0.0.1:8081; # Your backend app
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Auth-Request-User $remote_user;
    }
}

Enable the site and restart NGINX:

sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl restart nginx

🎯 Done!

  • Visit https://your-app.example.com
  • You will be redirected to Keycloak for login
  • On successful login, you’ll access your app via oauth2-proxy

🔒 Notes

  • This is not production ready: no HTTPS auto-renewal, limited security
  • For production:
    • Use PostgreSQL for Keycloak
    • Deploy behind a load balancer
    • Enable HTTPS with Let's Encrypt or a real cert
    • Run oauth2-proxy and Keycloak as services
    • Secure secrets (use .env, Vault, etc.)