SSL-Zertifikate & Reverse-Proxy
Zertifikat-Speicherort
Egal ob Sie ein eigenes Zertifikat hochgeladen oder ein selbstsigniertes Zertifikat während der Installation erstellt haben, die Dateien werden an folgendem Ort gespeichert:
- Pfad:
/srv/docker/edulution-ui/data/traefik/ssl/ - Zertifikatsdatei:
cert.cert - Schlüsseldatei:
cert.key
Zertifikat austauschen
Um ein bestehendes Zertifikat manuell auszutauschen, ersetzen Sie
einfach die Dateien cert.cert und cert.key im oben genannten
Verzeichnis und starten Sie die edulution Plattform neu.
Let's Encrypt
Mit Let's Encrypt bezieht und erneuert Traefik das Zertifikat selbst.
Die Dateien liegen ebenfalls
in /srv/docker/edulution-ui/data/traefik/ssl/:
| Datei | Inhalt |
|---|---|
acme.json | Zertifikat und Schlüssel von Let's Encrypt |
acmedns.json | Zugangsdaten für den ACME-DNS-Dienst; unter fulldomain steht das Ziel des CNAME-Eintrags |
Bestehende Installation auf Let's Encrypt umstellen
Diese Anleitung gilt für eine Installation, die bisher ein selbstsigniertes
oder hochgeladenes Zertifikat verwendet. Führen Sie alle Befehle als root in
/srv/docker/edulution-ui aus und ersetzen Sie Domain und E-Mail-Adresse
durch Ihre eigenen.
-
Registrieren Sie die Domain beim ACME-DNS-Dienst und legen Sie die Zugangsdaten ab. Der letzte Befehl gibt die Fulldomain aus:
DOMAIN=ui.musterschule.deEMAIL=admin@musterschule.decurl -s -X POST https://acme-dns.netzint.de/register > /root/acmedns-registration.jsonjq --arg d "$DOMAIN" '{($d): .}' /root/acmedns-registration.json > data/traefik/ssl/acmedns.jsonecho '{}' > data/traefik/ssl/acme.jsonchmod 600 data/traefik/ssl/acmedns.json data/traefik/ssl/acme.jsonjq -r .fulldomain /root/acmedns-registration.json -
Legen Sie bei Ihrem DNS-Anbieter den CNAME-Eintrag
_acme-challenge.ui.musterschule.demit der Fulldomain als Ziel an und prüfen Sie ihn:dig +short CNAME _acme-challenge.$DOMAIN @1.1.1.1 -
Richten Sie Traefik für Let's Encrypt ein:
cp traefik.yml /root/traefik.yml.bakcat >> edulution.env <<EOFACME_DNS_API_BASE=https://acme-dns.netzint.deACME_DNS_STORAGE_PATH=/etc/traefik/ssl/acmedns.jsonEOFcat >> traefik.yml <<EOFcertificatesResolvers:letsencrypt:acme:email: $EMAILstorage: /etc/traefik/ssl/acme.jsondnsChallenge:provider: acme-dnsresolvers:- "1.1.1.1:53"- "8.8.8.8:53"delayBeforeCheck: 30disablePropagationCheck: trueEOFMit den
resolversfindet Traefik den neuen CNAME-Eintrag sofort, auch wenn der Resolver der VM noch eine ältere Antwort zwischengespeichert hat.disablePropagationChecküberlässt die Prüfung des Eintrags Let's Encrypt. Sonst fragt Traefik die zuständigen Nameserver selbst, und das ist in vielen Schulnetzen gesperrt. -
Stellen Sie die Router auf Let's Encrypt um und entfernen Sie das bisherige Standardzertifikat:
cp data/traefik/config/edulution-default.yml /root/edulution-default.yml.bakcurl -fsSL https://get.edulution.io/download/edulution-default-le.yml.template \| sed -e "s/{{DOMAIN}}/$DOMAIN/g" \> data/traefik/config/edulution-default.ymltest -f data/traefik/config/cert.yml && mv data/traefik/config/cert.yml /root/cert.yml.bakcert.ymlmuss weg: Traefik fordert für eine Domain nichts an, solange ein anderes Zertifikat sie abdeckt, und dazu zählt auch ein selbstsigniertes. -
Erzeugen Sie Traefik neu, damit es die geänderte
edulution.envliest:docker compose up -d --force-recreate edu-traefik -
Prüfen Sie nach etwa zwei Minuten das ausgelieferte Zertifikat. Bei
issuermuss Let's Encrypt stehen:echo | openssl s_client -connect $DOMAIN:443 -servername $DOMAIN 2>/dev/null \| openssl x509 -noout -issuer -ext subjectAltName
Zurück zum bisherigen Zertifikat: Kopieren Sie die drei Sicherungen aus
/root an ihren Platz zurück, entfernen Sie die beiden ACME_DNS_-Zeilen
aus edulution.env und führen Sie Schritt 5 erneut aus.
Fehlerbehebung
Traefik schreibt nur Fehler ins Log (docker logs edulution-traefik), eine
erfolgreiche Anforderung erscheint dort nicht. Welche Zertifikate vorliegen,
zeigt jq '.letsencrypt.Certificates[].domain' data/traefik/ssl/acme.json.
| Anzeichen | Ursache | Abhilfe |
|---|---|---|
Im Log: returned NXDOMAIN for _acme-challenge.… | Der CNAME-Eintrag fehlt oder ist falsch benannt. Oder der Resolver hat die Antwort von vor dem Anlegen zwischengespeichert, je nach Zone bis zu 3 Stunden. | Eintrag beim zuständigen Nameserver prüfen (dig +short CNAME _acme-challenge.ui.musterschule.de @<Nameserver>), resolvers wie in Schritt 3 ergänzen, Traefik neu starten (docker restart edulution-traefik) |
Im Log: DNS call error: … i/o timeout [ns=acme-dns.netzint.de.:53 …] | In traefik.yml fehlen die beiden letzten Zeilen aus Schritt 3 (Installationen vor Version 2.1 des Installers), und ausgehendes DNS zu fremden Nameservern ist gesperrt. | Unter dnsChallenge die Zeilen delayBeforeCheck: 30 und disablePropagationCheck: true ergänzen, Traefik neu starten |
Kein Fehler im Log, der Browser zeigt das bisherige Zertifikat oder TRAEFIK DEFAULT CERT, acme.json enthält nur *.ui.musterschule.de | Die Domainangabe in edulution-default.yml fordert nur die Subdomains an (Installationen vor Version 2.1 des Installers), oder cert.yml deckt die Domain bereits ab | DOMAIN=ui.musterschule.de setzen, Schritt 4 ausführen, Traefik neu starten (docker restart edulution-traefik) |
Verbindung zum Linuxmuster-Server per LDAPS
Richtet der Installer den Linuxmuster-Server selbst ein (ab Version 2.1 des Installers), verbindet er Keycloak per LDAPS (Port 636) und legt die CA des Servers ab. Dann ist nichts weiter zu tun.
Bei einem bestehenden Linuxmuster-Server ist ldap:// (Port 389)
voreingestellt. Benutzer- und Bind-Passwörter gehen dann unverschlüsselt über
das Netz.
So stellen Sie auf LDAPS um:
-
Wählen Sie in Schritt 5 der Einrichtung bei LDAP-Schema den Wert
ldaps://. -
Tragen Sie bei Externe Domain des linuxmuster.net-Servers den Namen
server.<Domain>ein, mit der Domain des Linuxmuster-Servers. Keycloak verbindet sich nur mit einer Adresse aus dem Zertifikat, und diesen Namen enthält jedes Zertifikat des Servers. Die IP-Adresse undserverstehen nur in Zertifikaten, dielinuxmuster-base7ab Version 7.4.21 erstellt hat. -
Kopieren Sie nach Abschluss der Installation die CA in den Truststore von Keycloak und starten Sie Keycloak neu:
scp root@server.<Domain>:/etc/linuxmuster/ssl/cacert.pem \/srv/docker/edulution-ui/data/keycloak/truststores/linuxmuster-ca.pemdocker restart edulution-keycloak -
Melden Sie sich mit einem Benutzer des Linuxmuster-Servers an. Erst das zeigt, ob LDAPS funktioniert: Der Verbindungstest prüft das Zertifikat bei dieser Anbindung nicht und besteht auch ohne CA.
Meldung im Log (docker logs edulution-keycloak) | Ursache | Abhilfe |
|---|---|---|
PKIX path building failed | Die CA des Linuxmuster-Servers fehlt im Truststore. | Schritt 3 ausführen |
No subject alternative DNS name matching … found., No subject alternative names matching IP address … found., No name matching … found oder No subject alternative names present | Die Adresse steht nicht im Zertifikat des Linuxmuster-Servers (siehe Schritt 2). | In der Keycloak-Administrationsoberfläche unter User federation → ldap → Connection URL server.<Domain> eintragen |
Betrieb hinter einem Reverse-Proxy oder einer Firewall
Häufig wird die edulution Plattform nicht direkt aus dem Internet erreichbar sein, sondern hinter einer Firewall mit "Web Server Protection" oder einem anderen Reverse-Proxy betrieben.
In diesem Szenario übernimmt die Firewall oder der Proxy die SSL-Terminierung (die Verschlüsselung). Die edulution Plattform selbst wird dann unverschlüsselt über HTTP betrieben.
Das System erkennt automatisch, wenn es hinter einem Reverse-Proxy
betrieben wird (anhand von X-Forwarded-For Headern in der Anfrage) und
passt sein Verhalten entsprechend an. Während der Installation wird in
diesem Fall der Schritt zur SSL-Einrichtung übersprungen. Hierbei ist
wichtig dass auf der Firewall/Proxy Websocket-Verbindungen erlaubt sind,
da die edulution Plattform diese für die Kommunikation mit dem Browser benötigt.
Wo diese Einstellung zu finden ist, hängt vom jeweiligen Produkt ab.
Diese Seite richtet sich an eine andere Zielgruppe
Sie ist geschrieben für: Admin · Einrichtung. Ihre aktuelle Auswahl blendet sie deshalb aus.