🚀 How to Deploy Keycloak on Ubuntu VPS (5 Minute Quick-Start Guide)

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.