Keycloak SSO Installation und Einrichtung auf Ubuntu

Was ist Keycloak?

Keycloak ist ein Open-Source Identity and Access Management (IAM) Server, entwickelt von Red Hat. Mit Keycloak können Sie Single Sign-On (SSO) für mehrere Anwendungen zentral verwalten. Benutzer melden sich einmal an und können auf mehrere Anwendungen zugreifen, ohne sich erneut anmelden zu müssen.

Anwendungsfälle

• Zentralisierte Authentifizierung für mehrere interne Anwendungen
• OAuth2 / OpenID Connect (OIDC) Provider
• Benutzer- und Rollenverwaltung
• Social Login Integration (Google, GitHub, etc.)
• Multi-Tenancy-Szenarien (Realms)
• LDAP/Active Directory Integration

Voraussetzungen

• Ubuntu 20.04 oder neuer
• Docker und Docker Compose
• PostgreSQL (oder andere Datenbank)
• Nginx als Reverse Proxy
• Eine Domain (z.B. auth.example.com)
• Mindestens 4GB RAM empfohlen

Installation mit Docker Compose

Schritt 1: Verzeichnis erstellen

mkdir -p /opt/keycloak
cd /opt/keycloak

Schritt 2: docker-compose.yml erstellen

cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: keycloak-db
    restart: always
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak-net

  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    restart: always
    ports:
      - "8080:8080"
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${DB_PASSWORD}
      KC_HOSTNAME: auth.example.com
      KC_HOSTNAME_STRICT: "true"
      KC_HOSTNAME_STRICT_HTTPS: "true"
      KC_HTTP_RELATIVE_PATH: /
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      KC_PROXY: passthrough
      KC_LOG_LEVEL: info
    depends_on:
      - postgres
    networks:
      - keycloak-net

volumes:
  postgres_data:

networks:
  keycloak-net:
    driver: bridge
EOF

Schritt 3: Environment-Variablen erstellen

cat > .env << 'EOF'
DB_PASSWORD=$(openssl rand -32 | base64)
ADMIN_PASSWORD=$(openssl rand -32 | base64)
EOF

chmod 600 .env

Nginx Reverse Proxy Konfiguration

Nginx-Konfigurationsdatei

cat > /etc/nginx/sites-available/keycloak << 'EOF'
upstream keycloak {
    server localhost:8080;
}

server {
    listen 80;
    server_name auth.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name auth.example.com;

    ssl_certificate /etc/letsencrypt/live/auth.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    client_max_body_size 10M;

    location / {
        proxy_pass http://keycloak;
        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;
        proxy_set_header X-Forwarded-Host $server_name;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}
EOF

Nginx aktivieren

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

SSL-Zertifikat mit Let's Encrypt

sudo apt-get install certbot python3-certbot-nginx
sudo certbot certonly --nginx -d auth.example.com

Keycloak starten

cd /opt/keycloak
docker-compose up -d

Überprüfen Sie die Logs:

docker-compose logs -f keycloak

Admin-Konsole und initiale Konfiguration

Admin-Konsole aufrufen

Öffnen Sie: https://auth.example.com/admin

Melden Sie sich mit:

• Benutzername: admin
• Passwort: (aus .env-Datei)

Realm erstellen

1. Oben links auf "Master" klicken
2. "Create realm" auswählen
3. Name: z.B. "meine-anwendung"
4. Create klicken

Client erstellen (OIDC)

Schritt 1: Im neuen Realm navigieren

Im linken Menü: Clients → Create client

Schritt 2: Client-Konfiguration

• Client ID: meine-app
• Name: Meine Anwendung
• Client type: OpenID Connect

Schritt 3: Zugriffseinstellungen

• Valid redirect URIs: https://myapp.example.com/oauth2/callback
• Valid post logout redirect URIs: https://myapp.example.com/logout
• Web origins: https://myapp.example.com

Schritt 4: Client-Secrets generieren

Im Reiter "Credentials" wird das Client Secret angezeigt. Kopieren Sie diesen Wert!

Benutzer erstellen

Neuen Benutzer hinzufügen

1. Im Menü: Users → Create new user
2. Username: test@example.com
3. Email: test@example.com
4. First Name: Test
5. Last Name: User
6. Create klicken

Passwort setzen

1. Reiter "Credentials"
2. "Set password" klicken
3. Passwort eingeben
4. "Temporary" deaktivieren (falls der Benutzer nicht zur Passwortänderung gezwungen werden soll)
5. Save klicken

Client Scopes konfigurieren

Scope hinzufügen

Im Menü: Client Scopes → Neuen Scope erstellen

Häufige Scopes:

• profile (Benutzerprofilinformationen)
• email (E-Mail-Adresse)
• openid (Standard OIDC Scope)

Scope in Client zuweisen

Im Client unter "Client Scopes" die Scopes als Default oder Optional hinzufügen.

Test mit curl/Postman

Authorization Code Flow testen

curl -X POST \
  https://auth.example.com/realms/meine-anwendung/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=meine-app" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "username=test@example.com" \
  -d "password=YOUR_PASSWORD" \
  -d "scope=openid email profile"

Dies gibt einen JWT-Token zurück.

Token validieren

curl -X GET \
  "https://auth.example.com/realms/meine-anwendung/protocol/openid-connect/userinfo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Integration mit einer einfachen Anwendung

Authorization Code Flow Erklärung

1. Benutzer klickt auf "Mit Keycloak anmelden"
2. Redirect zur Login-Seite: https://auth.example.com/realms/meine-anwendung/protocol/openid-connect/auth?client_id=meine-app&redirect_uri=...
3. Benutzer gibt Anmeldedaten ein
4. Keycloak leitet mit Authorization Code zurück
5. Anwendung tauscht Code gegen Access Token aus (mit client_secret)
6. Anwendung erhält Benutzerinformationen

Beispiel mit Node.js (Passport.js)

const passport = require('passport');
const { Strategy } = require('openid-client');

const issuer_url = 'https://auth.example.com/realms/meine-anwendung';
const client_id = 'meine-app';
const client_secret = 'YOUR_CLIENT_SECRET';
const redirect_uri = 'https://myapp.example.com/oauth2/callback';

Strategy.Discovery(
  issuer_url,
  { client_id, client_secret, redirect_uri },
  (err, strategy) => {
    passport.use('oidc', strategy);
  }
);

app.get('/login', passport.authenticate('oidc'));
app.get('/oauth2/callback', passport.authenticate('oidc', { session: true }), (req, res) => {
  res.redirect('/');
});

Keycloak vs. Authentik – Vergleich

Merkmal	Keycloak	Authentik
Komplexität	Höher, aber sehr umfangreich	Niedriger, moderner UI
Admin UI	Funktional, nicht sehr intuitiv	Modern, benutzerfreundlich
Skalierbarkeit	Sehr gut, große Deployments	Gut, mittlere bis große Deployments
Community	Sehr große, viel Dokumentation	Wachsend, gute Dokumentation
LDAP/AD	Ja, sehr konfigurierbar	Ja, einfach konfiguriert

Häufige Aufgaben

Passwort-Reset für Benutzer

Im Admin-Panel: Users → Benutzer auswählen → Credentials → Set password

Rollen erstellen und zuweisen

1. Realm Roles → Create role
2. Role Name: z.B. "admin" oder "user"
3. User auswählen → Role Mappings → Role hinzufügen

Benutzer exportieren/importieren

docker-compose exec keycloak bash
/opt/keycloak/bin/kc.sh export --realm meine-anwendung --file /tmp/realm.json

Sicherheit

• Verwenden Sie immer HTTPS
• Passwortrichtlinien definieren (Realm Settings → Security Defenses)
• MFA/2FA aktivieren
• Regelmäßige Backups durchführen
• Admin-Passwort nach Installation ändern
• Log-Level monitoring aktivieren

Verwandte Artikel

• 📖 OAuth2 Authentifizierung erklärt
• 📖 Docker Compose Grundlagen Anleitung
• 📖 Nginx Reverse Proxy Konfiguration
• 🔧 Enjyn Auth – Authentifizierung für Ihre Apps
• 🔧 Sichere Server bei Enjyn mieten