NPMplus: `auth.kora.luki-net.org` einrichten¶

Dieses Runbook beschreibt die NPMplus-Proxy-Konfiguration für die Keycloak-Subdomain der kora-Plattform. Es ist analog zur auth.avs.luki-net.org-Konfiguration der Demo aufgebaut.

Voraussetzung¶

docker-compose.platform.yml läuft: make dev-platform
kora-platform-keycloak antwortet intern auf kora-platform-keycloak:8080 im Docker-Netz kora-platform-net
NPMplus ist an kora-platform-net angebunden (docker network connect kora-platform-net npmplus)
DNS: auth.kora.luki-net.org zeigt auf die öffentliche IP des Hosts (analog platform.kora.luki-net.org und docs.kora.luki-net.org)

Schritte¶

1. NPMplus-UI öffnen¶

https://<npmplus-host>:4443/ → Proxy Hosts.

2. Neuen Proxy-Host anlegen¶

Tab "Details":

Feld	Wert
Domain Names	`auth.kora.luki-net.org`
Scheme	`http`
Forward Hostname / IP	`kora-platform-keycloak`
Forward Port	`8080`
Cache Assets	off
Block Common Exploits	on
Websockets Support	on (für SSE/WebSocket-Admin-Console)
Access List	Publicly Accessible

Tab "SSL":

Feld	Wert
SSL Certificate	Request a new SSL Certificate (Let's Encrypt)
Force SSL	on
HTTP/2 Support	on
HSTS Enabled	on
HSTS Subdomains	on

3. Custom Nginx-Konfig (Tab "Advanced")¶

Keycloak hinter einem Reverse-Proxy erwartet X-Forwarded-*-Header, damit Redirect-URIs und Cookies korrekt generiert werden. NPMplus setzt die meisten per Default, aber zur Sicherheit:

proxy_set_header X-Forwarded-Host   $host;
proxy_set_header X-Forwarded-Proto  $scheme;
proxy_set_header X-Forwarded-Port   $server_port;
proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP          $remote_addr;

# Keycloak lange Admin-Requests (User-Listen, Import-Status):
proxy_read_timeout  300;
proxy_send_timeout  300;

4. TLS via Let's Encrypt¶

Request Certificate → E-Mail bestätigen → NPMplus holt per ACME das Zertifikat. Ca. 30–60s, dann https://auth.kora.luki-net.org erreichbar.

5. Verifikation¶

curl -sSf https://auth.kora.luki-net.org/realms/kora-platform/.well-known/openid-configuration | jq .issuer
# Erwartet: "https://auth.kora.luki-net.org/realms/kora-platform"

curl -sSf https://auth.kora.luki-net.org/realms/kora-tenants/.well-known/openid-configuration | jq .issuer
# Erwartet: "https://auth.kora.luki-net.org/realms/kora-tenants"

Beide Issuer-URLs müssen https://auth.kora.luki-net.org/... zurückgeben, nicht http://keycloak:8080/.... Falls ja, zeigt Keycloak den ForwardedProto-Header nicht an — KC_PROXY_HEADERS=xforwarded im Compose prüfen.

Referenzen¶

Analog: auth.avs.luki-net.org (Demo-Keycloak auf Host-Port 8180)
Compose-Service: siehe docker-compose.platform.yml Service keycloak
Keycloak-Settings: KC_HOSTNAME, KC_HOSTNAME_STRICT, KC_PROXY_HEADERS
Konzept: Fundament §15.4

NPMplus: auth.kora.luki-net.org einrichten¶