Keycloak Installation and OIDC Configuration

Brief description: Install Keycloak 26.5.5 and set up OIDC for SSO.

What You'll Learn

• How to install Keycloak 26.5.5
• How to create OIDC clients for SSO
• How to integrate with Rocket.Chat and Nextcloud

Prerequisites

• [ ] VM-106 created and Ubuntu 24.04 LTS installed
• [ ] OpenJDK 17 installed on Keycloak VM
• [ ] IP addresses documented
• [ ] Nginx reverse proxy configured

Estimated Time

2-3 hours

Part 1: Keycloak Installation

Step 1: Update System and Install Java

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

Verify:

java -version   # Should show openjdk 17.x

Step 2: Download and Install Keycloak (Standalone Tarball Method)

No official APT package exists from Keycloak project → use the recommended tar.gz distribution.

cd /tmp
wget https://github.com/keycloak/keycloak/releases/download/26.5.5/keycloak-26.5.5.tar.gz
sudo tar -xzf keycloak-26.5.5.tar.gz -C /opt/
sudo mv /opt/keycloak-26.5.5 /opt/keycloak

Step 3: Create Dedicated Keycloak User/Group and Set Permissions

sudo groupadd keycloak
sudo useradd -r -g keycloak -d /opt/keycloak -s /sbin/nologin keycloak

sudo chown -R keycloak:keycloak /opt/keycloak
sudo chmod -R u+rwX /opt/keycloak

sudo mkdir -p /opt/keycloak/data /var/log/keycloak
sudo chown -R keycloak:keycloak /opt/keycloak/data /var/log/keycloak

Step 4: Build Optimized Image (Production Recommendation)

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

Step 5: Create Systemd Service File

sudo nano /etc/systemd/system/keycloak.service

Paste (customize hostname, password, and internal listening):

[Unit]
Description=Keycloak Identity and Access Management
After=network.target

[Service]
Type=simple
User=keycloak
Group=keycloak
WorkingDirectory=/opt/keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --optimized \
  --hostname=auth.example.com \
  --http-port=8080 \
  --http-host=0.0.0.0 \
  --proxy-headers=xforwarded \
  --log=console,file --log-file=/var/log/keycloak/keycloak.log

Restart=always
RestartSec=10

Environment="JAVA_OPTS=-Xms1024m -Xmx2048m -Djava.security.egd=file:/dev/./urandom"

# ONLY for FIRST start – remove these lines after initial setup!
Environment="KC_BOOTSTRAP_ADMIN_USERNAME=admin"
Environment="KC_BOOTSTRAP_ADMIN_PASSWORD=<very-strong-password-here>"

[Install]
WantedBy=multi-user.target

• --hostname=...: Your public domain (Keycloak enforces redirects/URIs).
• --proxy-headers=xforwarded: Trusts headers from Nginx proxy.

Remove the two KC_BOOTSTRAP_ADMIN_* lines after first successful start (edit file → sudo systemctl daemon-reload → restart).

Step 6: Start and Enable Service

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

Check:

sudo systemctl status keycloak
sudo journalctl -u keycloak -f   # Wait for "Listening on: http://0.0.0.0:8080"

Step 7: Initial Access & Admin Console (Temporary – via Internal)

From another internal VM (or Proxmox console forwarding):

http://<keycloak-internal-ip>:8080/admin

Login: admin /

After first login → remove bootstrap env vars from service file, reload & restart.

Part 2: OIDC Client Configuration

This section covers connecting Keycloak to your OpenLDAP directory and creating OIDC clients for single sign-on.

Step 1: Connect Keycloak to OpenLDAP

Keycloak can authenticate users against your existing LDAP directory.

1. Open the Keycloak Admin Console: https://auth.example.com
2. Login with your admin credentials
3. Select the example realm
4. Navigate to User Federation → Add provider → ldap

Configure the LDAP federation settings:

Under Sync Settings, enable: - Import Users: ON - Edit Mode: READ_ONLY

1. Click Save
2. Click Test connection to verify connectivity
3. Click Test authentication to verify bind credentials
4. Click Synchronize all users to import existing users

Verify users appear under Users → View all users.

Step 2: Create OIDC Clients

OIDC clients allow applications to authenticate users through Keycloak.

Rocket.Chat

1. Go to Clients → Create client
2. Configure:

1. Click Next
2. Enable capability config:

1. Click Next
2. Configure login settings:

1. Click Save

Nextcloud

1. Go to Clients → Create client
2. Configure:

1. Click Next
2. Use default capability config
3. Configure login settings:

1. Click Save

LDAP Admin UI

1. Go to Clients → Create client
2. Configure:

1. Click Next
2. Configure login settings:

1. Click Save

Step 3: Retrieve Client Secrets

Each OIDC client requires a secret for authentication.

1. Go to Clients → select client → Credentials tab
2. Copy the Client Secret

Store secrets in a password manager:

• Rocket.Chat: <generated-in-keycloak>
• Nextcloud: <generated-in-keycloak>

Authentication Flow

User → Application (Rocket.Chat/Nextcloud) → Keycloak (OIDC) → OpenLDAP