Zum Hauptinhalt springen

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/:

DateiInhalt
acme.jsonZertifikat und Schlüssel von Let's Encrypt
acmedns.jsonZugangsdaten 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.

  1. Registrieren Sie die Domain beim ACME-DNS-Dienst und legen Sie die Zugangsdaten ab. Der letzte Befehl gibt die Fulldomain aus:

    DOMAIN=ui.musterschule.de
    EMAIL=admin@musterschule.de
    curl -s -X POST https://acme-dns.netzint.de/register > /root/acmedns-registration.json
    jq --arg d "$DOMAIN" '{($d): .}' /root/acmedns-registration.json > data/traefik/ssl/acmedns.json
    echo '{}' > data/traefik/ssl/acme.json
    chmod 600 data/traefik/ssl/acmedns.json data/traefik/ssl/acme.json
    jq -r .fulldomain /root/acmedns-registration.json
  2. Legen Sie bei Ihrem DNS-Anbieter den CNAME-Eintrag _acme-challenge.ui.musterschule.de mit der Fulldomain als Ziel an und prüfen Sie ihn:

    dig +short CNAME _acme-challenge.$DOMAIN @1.1.1.1
  3. Richten Sie Traefik für Let's Encrypt ein:

    cp traefik.yml /root/traefik.yml.bak
    cat >> edulution.env <<EOF

    ACME_DNS_API_BASE=https://acme-dns.netzint.de
    ACME_DNS_STORAGE_PATH=/etc/traefik/ssl/acmedns.json
    EOF
    cat >> traefik.yml <<EOF

    certificatesResolvers:
    letsencrypt:
    acme:
    email: $EMAIL
    storage: /etc/traefik/ssl/acme.json
    dnsChallenge:
    provider: acme-dns
    resolvers:
    - "1.1.1.1:53"
    - "8.8.8.8:53"
    delayBeforeCheck: 30
    disablePropagationCheck: true
    EOF

    Mit den resolvers findet 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.

  4. 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.bak
    curl -fsSL https://get.edulution.io/download/edulution-default-le.yml.template \
    | sed -e "s/{{DOMAIN}}/$DOMAIN/g" \
    > data/traefik/config/edulution-default.yml
    test -f data/traefik/config/cert.yml && mv data/traefik/config/cert.yml /root/cert.yml.bak

    cert.yml muss weg: Traefik fordert für eine Domain nichts an, solange ein anderes Zertifikat sie abdeckt, und dazu zählt auch ein selbstsigniertes.

  5. Erzeugen Sie Traefik neu, damit es die geänderte edulution.env liest:

    docker compose up -d --force-recreate edu-traefik
  6. Prüfen Sie nach etwa zwei Minuten das ausgelieferte Zertifikat. Bei issuer muss 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.

AnzeichenUrsacheAbhilfe
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.deDie Domainangabe in edulution-default.yml fordert nur die Subdomains an (Installationen vor Version 2.1 des Installers), oder cert.yml deckt die Domain bereits abDOMAIN=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:

  1. Wählen Sie in Schritt 5 der Einrichtung bei LDAP-Schema den Wert ldaps://.

  2. 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 und server stehen nur in Zertifikaten, die linuxmuster-base7 ab Version 7.4.21 erstellt hat.

  3. 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.pem
    docker restart edulution-keycloak
  4. 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)UrsacheAbhilfe
PKIX path building failedDie 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 presentDie 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.

Zur Übersicht