Zum Inhalt
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// installation

IDP (Keycloak)

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Übersicht

Der Identity-Provider-Dienst (IDP) basiert auf Keycloak und stellt OpenID-Connect-Authentifizierung (OIDC) und -Autorisierung für die basebox-KI-Plattform bereit. Er verwaltet Benutzeridentitäten, Realms, Clients und Authentifizierungsabläufe.

Deployment

Der IDP wird per Helm-Chart in Kubernetes-Cluster bereitgestellt, mit einer integrierten, von CloudNativePG verwalteten PostgreSQL-Datenbank.

Helm-Chart-Konfiguration

Grundeinstellungen

Parameter Standard Beschreibung
replicaCount 1 Anzahl der IDP-Pod-Replikate
image.repository gitea.basebox.health/basebox-distribution/idp Container-Image-Repository
image.pullPolicy IfNotPresent Image-Pull-Policy
image.tag latest Auszurollender Image-Tag
fullnameOverride idp Vollständigen Namen des Deployments überschreiben

Dienstkonfiguration

Parameter Standard Beschreibung
service.type ClusterIP Kubernetes-Service-Typ
service.port 8080 Service-Port

Ressourcenverwaltung

Parameter Standard Beschreibung
resources.requests.cpu 250m Minimale CPU-Zuteilung
resources.requests.memory 512Mi Minimale Speicherzuteilung
resources.limits.cpu 1000m Maximale CPU-Zuteilung
resources.limits.memory 2Gi Maximale Speicherzuteilung

Autoscaling

Parameter Standard Beschreibung
autoscaling.enabled false Horizontales Pod-Autoscaling aktivieren (für Produktion empfohlen)
autoscaling.minReplicas 1 Minimale Anzahl Replikate
autoscaling.maxReplicas 3 Maximale Anzahl Replikate
autoscaling.targetCPUUtilizationPercentage 80 Ziel-CPU-Auslastung für die Skalierung
autoscaling.targetMemoryUtilizationPercentage 80 Ziel-Speicherauslastung für die Skalierung

Health-Checks

Parameter Standard Beschreibung
livenessProbe.httpGet.path /health/live Endpunkt der Liveness-Probe
livenessProbe.initialDelaySeconds 30 Verzögerung vor der ersten Liveness-Probe
livenessProbe.periodSeconds 10 Prüfintervall
livenessProbe.failureThreshold 10 Anzahl Fehler bis zum Neustart
readinessProbe.httpGet.path /health/ready Endpunkt der Readiness-Probe
readinessProbe.initialDelaySeconds 30 Verzögerung vor der ersten Readiness-Probe
readinessProbe.periodSeconds 10 Prüfintervall
readinessProbe.failureThreshold 10 Anzahl Fehler bis zur Markierung als nicht bereit

Keycloak-Konfiguration

Kerneinstellungen

Parameter Beschreibung Beispiel
keycloak.url Interne Keycloak-URL http://idp:8080
keycloak.realm Standard-Keycloak-Realm basebox
keycloak.clientId Keycloak-Client-ID idp
keycloak.clientSecret Keycloak-Client-Secret <generate-secure-secret>
keycloak.keycloak_admin_user Keycloak-Admin-Benutzername admin
keycloak.keycloak_admin_password Keycloak-Admin-Passwort <secure-password>

Datenbankkonfiguration

Der IDP nutzt CloudNativePG zur Verwaltung der PostgreSQL-Datenbank.

Datenbankeinstellungen

Parameter Standard Beschreibung
database.enabled true Datenbankerstellung aktivieren
database.imageName ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm PostgreSQL-Image
database.host idp-db-rw Datenbank-Host (Read-Write-Service)
database.port 5432 Datenbank-Port
database.username idp Datenbank-Benutzername
database.password <secure-password> Datenbank-Passwort
database.name idp Datenbankname

CloudNativePG-Cluster-Einstellungen

Parameter Standard Beschreibung
idp-db.cluster.instances 1 Anzahl PostgreSQL-Instanzen
idp-db.cluster.storage.size 5Gi Speichergröße der Datenbank
idp-db.cluster.storage.storageClass default Zu verwendende Storage Class
idp-db.cluster.monitoring.enablePodMonitor false Prometheus-Monitoring aktivieren

Umgebungsvariablen

Datenbankverbindung (aus Secrets)

Variable Quelle Beschreibung
KC_DB_URL_HOST Secret idp-database Datenbank-Hostname
KC_DB_URL_PORT Secret idp-database Datenbank-Port
KC_DB_URL_DATABASE Secret idp-database Datenbankname
KC_DB_USERNAME Secret idp-database Datenbank-Benutzername
KC_DB_PASSWORD Secret idp-database Datenbank-Passwort

Keycloak-Kernkonfiguration

Variable Beschreibung
KC_DB_VENDOR Datenbankanbieter (POSTGRES)
KC_DB_SCHEMA Datenbankschema (public)
KC_HEALTH_ENABLED Health-Endpunkte aktivieren
KC_METRICS_ENABLED Metrik-Endpunkte aktivieren
KC_PROXY Proxy-Modus (edge für Reverse Proxy)
KC_PROXY_HEADERS Behandlung der Proxy-Header (xforwarded)
KC_HTTP_RELATIVE_PATH Relativer Pfad für Keycloak (/auth)
KC_HOSTNAME Öffentlicher Hostname für Keycloak
KC_HOSTNAME_STRICT Strikte Hostname-Prüfung

Integrationskonfiguration

Variable Beschreibung
KEYCLOAK_URL Interne Keycloak-URL für API-Aufrufe
AISRV_URL URL des AISRV-Backend-Dienstes
REALM_NAME Name des anzulegenden/zu nutzenden Standard-Realms

Organisations- und Admin-Konfiguration

Variable Beschreibung
ORGANIZATION_NAME Name der Standardorganisation
ADMIN_EMAIL E-Mail-Adresse des Administrators
ADMIN_PASSWORD Passwort des Administrators
ADMIN_LANG Sprache des Administrators (en, de etc.)
KEYCLOAK_ADMIN Keycloak-Admin-Benutzername (aus Secret)
KEYCLOAK_ADMIN_PASSWORD Keycloak-Admin-Passwort (aus Secret)

Betriebskonfiguration

Variable Standard Beschreibung
MAX_RETRIES 30 Maximale Wiederholungen bei der Initialisierung
RETRY_INTERVAL 20 Sekunden zwischen Wiederholungen
JAVA_OPTS_APPEND -Dinfinispan.shutdown.hook.enabled=false JVM-Optionen
QUARKUS_MICROMETER_ENABLED true Quarkus-Metriken aktivieren

Konfigurationsbeispiele

Produktivkonfiguration

# values-production.yaml
replicaCount: 2

image:
  repository: gitea.basebox.health/basebox-distribution/idp
  tag: "v1.2.3"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8080

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
  hosts:
    - host: auth.company.com
      paths:
        - path: /auth
          pathType: Prefix
  tls:
    - secretName: idp-tls
      hosts:
        - auth.company.com

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 2000m
    memory: 4Gi

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 5
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 75

keycloak:
  url: http://idp:8080
  realm: basebox
  clientId: idp
  clientSecret: "<generate-secure-secret-32-chars>"
  keycloak_admin_user: admin
  keycloak_admin_password: "<generate-secure-password>"

database:
  enabled: true
  imageName: ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm
  host: idp-db-rw
  port: 5432
  username: idp
  password: "<generate-secure-database-password>"
  name: idp

idp-db:
  cluster:
    instances: 3
    storage:
      size: 20Gi
      storageClass: fast-ssd
    monitoring:
      enablePodMonitor: true

env:
  # Database connection (from secrets)
  KC_DB_URL_HOST:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: host
  KC_DB_URL_PORT:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: port
  KC_DB_URL_DATABASE:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: name
  KC_DB_USERNAME:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: username
  KC_DB_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: idp-database
        key: password

  # Keycloak configuration
  KC_DB_VENDOR: POSTGRES
  KC_DB_SCHEMA: public
  KC_HEALTH_ENABLED: "true"
  KC_METRICS_ENABLED: "true"
  KC_PROXY: "edge"
  KC_PROXY_HEADERS: "xforwarded"
  KC_HTTP_RELATIVE_PATH: "/auth"
  KC_HOSTNAME: "auth.company.com"
  KC_HOSTNAME_STRICT: "false"

  # Integration
  KEYCLOAK_URL: "http://idp:8080"
  AISRV_URL: "http://aisrv:8888"
  REALM_NAME: "production"

  # Organization
  ORGANIZATION_NAME: "company"
  ADMIN_EMAIL: "admin@company.com"
  ADMIN_PASSWORD: "<secure-admin-password>"
  ADMIN_LANG: "en"

  # Admin credentials (from secrets)
  KEYCLOAK_ADMIN:
    valueFrom:
      secretKeyRef:
        name: keycloak-admin-secret
        key: KEYCLOAK_ADMIN
  KEYCLOAK_ADMIN_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: keycloak-admin-secret
        key: KEYCLOAK_ADMIN_PASSWORD

  # Operational
  MAX_RETRIES: "30"
  RETRY_INTERVAL: "20"
  JAVA_OPTS_APPEND: "-Dinfinispan.shutdown.hook.enabled=false"
  QUARKUS_MICROMETER_ENABLED: "true"

Hochverfügbarkeitskonfiguration

# values-ha.yaml
replicaCount: 3

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 65
  targetMemoryUtilizationPercentage: 70

resources:
  requests:
    cpu: 1000m
    memory: 2Gi
  limits:
    cpu: 3000m
    memory: 6Gi

idp-db:
  cluster:
    instances: 3
    storage:
      size: 50Gi
      storageClass: fast-ssd
    monitoring:
      enablePodMonitor: true

affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
            - key: app.kubernetes.io/name
              operator: In
              values:
                - idp
        topologyKey: kubernetes.io/hostname

Gateway-API-Konfiguration

# values-gateway.yaml
httpRoute:
  enabled: true
  annotations:
    example.com/rate-limit: "100"
  parentRefs:
    - name: company-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - auth.company.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /auth

env:
  KC_HOSTNAME: "auth.company.com"
  KC_HTTP_RELATIVE_PATH: "/auth"
  KC_PROXY: "edge"
  KC_PROXY_HEADERS: "xforwarded"

Installation

Voraussetzungen

  • Kubernetes-Cluster (1.23+)
  • Helm 3.x
  • kubectl konfiguriert
  • CloudNativePG-Operator installiert (für die Datenbankverwaltung)
  • Storage-Provisioner mit dynamischer Bereitstellung

CloudNativePG-Operator installieren

# Install CloudNativePG operator (if not already installed)
helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg \
  --namespace cnpg-system \
  --create-namespace \
  cnpg/cloudnative-pg

IDP-Chart installieren

# Install with custom values
helm install idp oci://gitea.basebox.health/basebox-distribution/helm/idp \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace

# Verify installation
kubectl get pods -n basebox -l app.kubernetes.io/name=idp
kubectl get cluster -n basebox idp-db

Upgrade

# Upgrade with new values
helm upgrade idp oci://gitea.basebox.health/basebox-distribution/helm/idp \
  --values values-production.yaml \
  --namespace basebox

# Check rollout status
kubectl rollout status deployment/idp -n basebox

Deinstallation

# Uninstall the chart
helm uninstall idp --namespace basebox

# Note: Database PVCs are not automatically deleted
# Delete manually if needed:
kubectl delete pvc -n basebox -l cnpg.io/cluster=idp-db

Prüfung

Deployment prüfen

# Check IDP pods
kubectl get pods -n basebox -l app.kubernetes.io/name=idp

# Check database cluster
kubectl get cluster -n basebox idp-db

# Check database pods
kubectl get pods -n basebox -l cnpg.io/cluster=idp-db

# View IDP logs
kubectl logs -n basebox -l app.kubernetes.io/name=idp --tail=100

# View database logs
kubectl logs -n basebox idp-db-1

Health-Endpunkte testen

# Port forward IDP service
kubectl port-forward -n basebox svc/idp 8080:8080

# Test liveness endpoint
curl http://localhost:8080/health/live

# Test readiness endpoint
curl http://localhost:8080/health/ready

# Test metrics endpoint (if enabled)
curl http://localhost:8080/metrics

Keycloak Admin Console aufrufen

# Port forward for admin access
kubectl port-forward -n basebox svc/idp 8080:8080

# Access admin console at:
# http://localhost:8080/auth/admin

Secrets-Verwaltung

Das Chart erzeugt automatisch zwei Kubernetes-Secrets:

Secret idp-database

Enthält die Datenbank-Verbindungsdaten: - host – Datenbank-Hostname - port – Datenbank-Port - name – Datenbankname - username – Datenbank-Benutzername - password – Datenbank-Passwort

Secret keycloak-admin-secret

Enthält die Keycloak-Admin-Zugangsdaten: - KEYCLOAK_ADMIN – Admin-Benutzername - KEYCLOAK_ADMIN_PASSWORD – Admin-Passwort

Wichtig: Ändern Sie Standardpasswörter in Produktiv-Deployments.

Datenbankverwaltung

Backup und Wiederherstellung

CloudNativePG bietet eingebaute Backup-Funktionen:

# Add to idp-db configuration
idp-db:
  cluster:
    backup:
      barmanObjectStore:
        destinationPath: s3://backups/idp-db
        s3Credentials:
          accessKeyId:
            name: backup-s3-creds
            key: ACCESS_KEY_ID
          secretAccessKey:
            name: backup-s3-creds
            key: SECRET_ACCESS_KEY
      retentionPolicy: "30d"

Datenbank-Monitoring

Monitoring mit Prometheus aktivieren:

idp-db:
  cluster:
    monitoring:
      enablePodMonitor: true

Datenbank-Skalierung

PostgreSQL-Replikate skalieren:

idp-db:
  cluster:
    instances: 3  # Primary + 2 replicas

Sicherheitsaspekte

Passwortsicherheit

  • Sichere Passwörter erzeugen für alle Konten mit kryptografisch sicheren Verfahren
  • Passwörter regelmäßig rotieren für Admin- und Datenbankkonten
  • Kubernetes-Secrets oder externe Secret-Verwaltung nutzen (Vault, AWS Secrets Manager)
  • Secrets nie in die Versionskontrolle einchecken

Netzwerksicherheit

  • Service-Typ ClusterIP für rein internen Zugriff nutzen
  • Ingress mit TLS-/SSL-Zertifikaten konfigurieren
  • Network Policies zur Verkehrsbeschränkung umsetzen
  • Hinter Reverse Proxy KC_PROXY=edge nutzen

Datenbanksicherheit

  • SSL/TLS für Datenbankverbindungen in Produktion aktivieren
  • Getrennte Zugangsdaten für Anwendungs- und Admin-Zugriff nutzen
  • Regelmäßige Backups und getestete Wiederherstellungsverfahren
  • Datenbanklogs auf verdächtige Aktivität überwachen

RBAC-Konfiguration

  • Dem Datenbankbenutzer das Recht SUPERUSER gewähren (für die Initialisierung erforderlich)
  • Berechtigungen nach der Ersteinrichtung prüfen und minimieren
  • Getrennte Service Accounts für verschiedene Komponenten nutzen

Performance-Tuning

JVM-Konfiguration

Java-Heap-Größe für bessere Leistung anpassen:

env:
  JAVA_OPTS_APPEND: >-
    -Xms1g -Xmx2g
    -XX:MetaspaceSize=256m
    -XX:MaxMetaspaceSize=512m
    -Dinfinispan.shutdown.hook.enabled=false

Connection Pooling

Den Datenbank-Connection-Pool in den Keycloak-Einstellungen über die Admin Console oder Umgebungsvariablen konfigurieren.

Caching

Keycloak nutzt Infinispan für verteiltes Caching. Bei Deployments mit mehreren Replikaten die Cache-Konfiguration prüfen.

Monitoring und Metriken

Prometheus-Metriken

Metrikerfassung aktivieren:

env:
  KC_METRICS_ENABLED: "true"
  QUARKUS_MICROMETER_ENABLED: "true"

Metriken sind unter dem Endpunkt /metrics verfügbar.

Health-Checks

  • Liveness: /health/live – Prüft, ob Keycloak läuft
  • Readiness: /health/ready – Prüft, ob Keycloak bereit ist, Anfragen zu bedienen

Datenbank-Monitoring

CloudNativePG exportiert Metriken für: - Status des Connection Pools - Replikationsverzögerung - Query-Performance - Speichernutzung

Hochverfügbarkeit

Für Produktiv-Deployments mit Hochverfügbarkeitsanforderung:

  1. Mehrere IDP-Replikate: replicaCount: 3 setzen oder Autoscaling nutzen
  2. PostgreSQL-Cluster: idp-db.cluster.instances: 3 setzen
  3. Pod-Anti-Affinität: Pods über Knoten verteilen
  4. Health-Check-Tuning: Schwellenwerte an Ihre Umgebung anpassen
  5. Ressourcenzuteilung: Ausreichend CPU/Speicher sicherstellen
  6. Persistenter Speicher: Zuverlässige Storage Class mit Replikation nutzen

Integration mit anderen Diensten

AISRV-Integration

Der IDP arbeitet mit AISRV für Benutzer- und Organisationsverwaltung zusammen:

env:
  AISRV_URL: "http://aisrv:8888"
  REALM_NAME: "production"
  ORGANIZATION_NAME: "your-org"

Frontend-Integration

Frontend-Anwendungen verbinden sich per OIDC mit dem IDP:

  • Authority-URL: https://auth.company.com/auth/realms/{realm}
  • Token-Endpunkt: /auth/realms/{realm}/protocol/openid-connect/token
  • Autorisierungs-Endpunkt: /auth/realms/{realm}/protocol/openid-connect/auth

Initialisierungsprozess

Beim ersten Start führt der IDP aus:

  1. Initialisierung des Datenbankschemas
  2. Keycloak-Bootstrap
  3. Realm-Erstellung (angegeben in REALM_NAME)
  4. Organisationseinrichtung (angegeben in ORGANIZATION_NAME)
  5. Anlegen des Admin-Benutzers
  6. Client-Konfiguration

Der Prozess nutzt MAX_RETRIES und RETRY_INTERVAL, um Abhängigkeiten zu behandeln.