Skip to main content

​
Configure Keycloak

Configure Keycloak for HTTP access and import the ORISO realm. This step is critical for authentication to work properly. Keycloak is deployed via Helm as part of the oriso-platform umbrella chart.
This step is MANDATORY for authentication to work! Skipping this step will cause authentication failures across all services.
Keycloak is deployed as oriso-platform-keycloak service in the caritas namespace. Access it via:
  • Internal: http://oriso-platform-keycloak.caritas.svc.cluster.local:8080
  • External: https://auth.oriso-dev.site (via Ingress)
1

Configure HTTP Access

Disable SSL requirements for Keycloak realms to allow HTTP access. This is required for the authentication flow.
Wait for Keycloak pod to be fully ready (about 60 seconds after the pod shows as Running) before executing these commands.
Option A: Using Script (Recommended)
# Wait for Keycloak to be fully ready
kubectl wait --for=condition=ready pod -l app=keycloak -n caritas --timeout=300s
sleep 60  # Additional wait for Keycloak to fully initialize

# Run HTTP configuration script
cd ~/online-beratung/caritas-workspace/ORISO-Keycloak
chmod +x configure-http-access.sh
./configure-http-access.sh
If the script doesn’t exist, use Option B (Manual Configuration) below.
Option B: Manual Configuration
# Get Keycloak pod name
KEYCLOAK_POD=$(kubectl get pods -n caritas -l app=keycloak -o jsonpath="{.items[0].metadata.name}")

# Configure kcadm credentials
kubectl exec -n caritas $KEYCLOAK_POD -- \
  /opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin \
  --password admin

# Disable SSL for master realm
kubectl exec -n caritas $KEYCLOAK_POD -- \
  /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE

# Disable SSL for all realms
kubectl exec -n caritas $KEYCLOAK_POD -- bash -c '
/opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin
for r in $(/opt/keycloak/bin/kcadm.sh get realms --fields realm --format csv | tail -n +2); do
  echo "Processing realm: $r"
  /opt/keycloak/bin/kcadm.sh update realms/"$r" -s sslRequired=NONE
done'
Verify Configuration
# Verify SSL requirement is disabled
kubectl exec -n caritas $KEYCLOAK_POD -- \
  /opt/keycloak/bin/kcadm.sh get realms/master --fields sslRequired
The output should show sslRequired as NONE for the master realm.
2

Import Keycloak Realm

Import the ORISO realm configuration into Keycloak. You can do this via the admin console or command line.Get Server IP
# Get server IP
SERVER_IP=$(hostname -I | awk '{print $1}')
echo "Server IP: $SERVER_IP"
Option A: Using Admin Console (Recommended for Visual Verification)
  1. Open browser and navigate to: https://auth.oriso-dev.site/admin/ (or http://YOUR_SERVER_IP:8080/admin/ if Ingress not configured)
  2. Login with credentials: admin / admin (default, change in production)
  3. Select “Master” realm dropdown → Click “Add realm”
  4. Click “Select file”
  5. Navigate to: ~/online-beratung/caritas-workspace/ORISO-Keycloak/realm.json
  6. Upload and click “Create”
  7. Verify realm “online-beratung” is created
You should see the “online-beratung” realm in the realm dropdown menu.
Option B: Using Command Line
# Copy realm to Keycloak pod
KEYCLOAK_POD=$(kubectl get pods -n caritas -l app=keycloak -o jsonpath="{.items[0].metadata.name}")

kubectl cp ~/online-beratung/caritas-workspace/ORISO-Keycloak/realm.json \
  caritas/$KEYCLOAK_POD:/tmp/realm.json

# Import realm
kubectl exec -n caritas $KEYCLOAK_POD -- \
  /opt/keycloak/bin/kc.sh import --file /tmp/realm.json

# Restart Keycloak
kubectl rollout restart deployment/keycloak -n caritas
The Keycloak pod restart may take 1-2 minutes. Wait for the pod to be ready before proceeding.

​
Verification

After completing both steps, verify Keycloak is configured correctly: 
# Check Keycloak pod is running
kubectl get pods -n caritas | grep keycloak

# Check Keycloak is accessible (internal)
kubectl exec -n caritas deployment/oriso-platform-keycloak -- \
  curl -I http://localhost:8080

# Check realm is accessible (via Ingress)
curl -s https://auth.oriso-dev.site/realms/online-beratung/.well-known/openid-configuration | jq .realm

# Or check internally
kubectl exec -n caritas deployment/oriso-platform-keycloak -- \
  curl -s http://localhost:8080/realms/online-beratung/.well-known/openid-configuration | jq .realm
Expected output should show the realm name “online-beratung” in the JSON response.

​
Troubleshooting

​
HTTPS Required Error

If you see “HTTPS Required” errors:
This means HTTP access was not configured. Run the HTTP configuration step again.
cd ~/online-beratung/caritas-workspace/ORISO-Kubernetes
./scripts/configure-keycloak-http.sh

​
Cannot Login to Keycloak

Check Keycloak logs for errors: 
kubectl logs deployment/keycloak -n caritas --tail=100
Verify Keycloak is accessible: 
curl -I http://127.0.0.1:8080

​
Realm Not Found

Check if realm exists: 
KEYCLOAK_POD=$(kubectl get pods -n caritas -l app=keycloak -o jsonpath="{.items[0].metadata.name}")

kubectl exec -n caritas $KEYCLOAK_POD -- \
  /opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin \
  --password admin

kubectl exec -n caritas $KEYCLOAK_POD -- \
  /opt/keycloak/bin/kcadm.sh get realms --fields realm
If the realm is missing, re-import it using the steps above.

​
Next Steps