How to Deploy Keycloak on Ubuntu VPS

Here’s a clear and detailed how-to guide for how to deploy Keycloak on Ubuntu VPS. This guide uses Keycloak in standalone mode with PostgreSQL as the database and NGINX as a reverse proxy with SSL.

What is Keycloak?

Keycloak is an open-source identity and access management (IAM) solution developed by Red Hat. It provides authentication, authorization, and user management features for modern applications and services. Essentially, Keycloak helps developers and organizations manage user identities and secure their applications without having to build these systems from scratch.

Key Features of Keycloak:

• Single Sign-On (SSO): Users can log in once and access multiple applications.
• Identity Brokering and Social Login: Integrates with identity providers like Google, Facebook, GitHub, etc.
• User Federation: Connects to external user databases like LDAP or Active Directory.
• OAuth2, OpenID Connect, and SAML Support: Standards-based authentication protocols.
• Multifactor Authentication (MFA): Adds an extra layer of security.
• Admin Console: Web-based UI for managing realms, users, roles, etc.
• Customizable Login Pages: Easily branded and themed.
• Token-based Authentication: Issues JWT tokens for secure communication between services.

Common Use Cases:

• Centralized authentication across multiple apps and services.
• Securing REST APIs and microservices.
• Enabling SSO for enterprise applications.
• Delegating identity management for mobile and web apps.

🔧 Prerequisites

• Ubuntu VPS (20.04 or later)
• Root or sudo access
• Domain name (e.g., auth.example.com)
• PostgreSQL installed or access to a PostgreSQL server
• Open ports: 80, 443

How to Deploy Keycloak on Ubuntu VPS

To deploy Keycloak on Ubuntu VPS, follow the steps below:

1. 🧱 System Preparation

   sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget unzip gnupg2 software-properties-common

2. 🐘 Install and Configure PostgreSQL

   If you don’t have PostgreSQL installed:

   sudo apt install -y postgresql postgresql-contrib

   Create Keycloak DB & User

   sudo -u postgres psql

   CREATE DATABASE keycloak; CREATE USER keycloakuser WITH PASSWORD 'your_strong_password'; GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloakuser; \q

3. ☕ Install Java (OpenJDK 21)

   Keycloak requires Java 21+.

   sudo apt install -y openjdk-21-jdk java -version

4. 📦 Download and Extract Keycloak

   wget https://github.com/keycloak/keycloak/releases/latest/download/keycloak-.zip unzip keycloak-.zip -d /opt/ sudo mv /opt/keycloak- /opt/keycloak cd /opt/keycloak

   Replace with the latest release tag (e.g., 24.0.1).

5. ⚙️ Set Up Keycloak Configuration

   1. Create a System User

      sudo useradd -r -d /opt/keycloak -s /sbin/nologin keycloak sudo chown -R keycloak:keycloak /opt/keycloak

   2. Create the Admin User

      cd /opt/keycloak/bin sudo -u keycloak ./kc.sh create admin --user admin --password StrongAdminPassword

   3. Configure the Database

      Create a file: /opt/keycloak/conf/keycloak.conf

      db=postgres db-url=jdbc:postgresql://localhost/keycloak db-username=keycloakuser db-password=your_strong_password hostname=auth.example.com https-port=8443

6. 🚀 Start Keycloak in Production Mode

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

   At this point, Keycloak will be running on port 8080.

7. 🌐 Set Up NGINX as Reverse Proxy (with SSL)

   1. Install Nginx

      sudo apt install nginx sudo ufw allow 'Nginx Full'

   2. Install Certbot for SSL

      sudo apt install certbot python3-certbot-nginx

   3. NGINX Config

      Create /etc/nginx/sites-available/keycloak

      server { listen 80; server_name auth.example.com; location / { proxy_pass http://localhost:8080/; 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 and test:

      sudo ln -s /etc/nginx/sites-available/keycloak /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx

   4. Get SSL Certificate

      sudo certbot --nginx -d auth.example.com

      Certbot will modify your config to use HTTPS.

8. 🔁 Enable Keycloak as a Service

   Create /etc/systemd/system/keycloak.service

   [Unit] Description=Keycloak Server After=network.target [Service] Type=simple User=keycloak Group=keycloak ExecStart=/opt/keycloak/bin/kc.sh start Restart=on-failure LimitNOFILE=10240 [Install] WantedBy=multi-user.target

   sudo systemctl daemon-reexec sudo systemctl daemon-reload sudo systemctl enable keycloak sudo systemctl start keycloak

9. ✅ Access Keycloak

   Go to: https://auth.example.com
   Log in with the admin credentials you set.

10. 🛡️ (Optional) Secure with Firewall

    sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' sudo ufw enable

✅ Final Notes

• You now have a fully-functional Keycloak instance running behind NGINX with HTTPS.
• All configuration lives in /opt/keycloak.
• Consider setting up backups for your PostgreSQL DB and Keycloak config.
• To upgrade Keycloak, back up data, download the new version, and follow upgrade notes.

Conclusion

You now know how to deploy Keycloak on Ubuntu VPS.