Einrichtung eines SSL Zertifikats

Dieser Artikel führt dich durch die Einrichtung eines SSL-Zertifikats auf deinem Q.wiki-Server. Abhängig von deiner Q.wiki-Version folge den entsprechenden Anweisungen:

• Neu-Installation: Folge den Abschnitten „Certificate Signing Request erstellen" und „SSL-Zertifikat einrichten"
• Zertifikat erneuern (Version < 6.8): Siehe Abschnitt „SSL-Zertifikat einrichten"
• Zertifikat erneuern (Version ≥ 6.8): Siehe Abschnitt „SSL-Zertifikat aktualisieren ab Version 6.8"

Certificate Signing Request (CSR) erstellen

Für die SSL-Einrichtung benötigst du einen CSR und einen privaten Schlüssel. Folge diesen Schritten:

1. Privaten Schlüssel generieren

Navigiere zum SSL-Verzeichnis und erstelle einen neuen Schlüssel:

cd /etc/ssl/private
openssl genrsa -out fqdn.key.pem 2048

Ersetze fqdn mit dem vollständigen Hostnamen deines Q.wiki-Servers (z. B. qwiki.acme.local).

2. CSR-Konfigurationsdatei anlegen

Erstelle eine Konfigurationsdatei für den CSR:

vim fqdn.csr.conf

Füge folgende Konfiguration ein und ersetze die rot markierten Werte mit deinen Angaben:

[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
C = DE
ST = NRW
L = AACHEN
O = Deine Organisation
OU = IT-Services
CN = qwiki.acme.local
emailAddress = admin@example.de

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = qwiki.acme.local
DNS.2 = qwikiserver.acme.local

CN: Die URL, über die Q.wiki im Browser aufgerufen wird
DNS.1: Der öffentliche DNS-Name
DNS.2: Der FQDN des Servers

3. CSR aus der Konfiguration erzeugen

Speichere die Konfigurationsdatei und erstelle den CSR:

openssl req -new -out fqdn.csr -key fqdn.key.pem -config fqdn.csr.conf

Die Datei fqdn.csr wird im aktuellen Verzeichnis erstellt. Du kannst sie jetzt mit SCP auf deinen lokalen Rechner herunterladen oder den Inhalt kopieren und in eine lokale Datei einfügen. Mit diesem CSR kannst du bei deiner Zertifizierungsstelle (CA) ein SSL-Zertifikat anfordern.

SSL-Zertifikat einrichten

Nachdem du das Zertifikat von deiner CA erhalten hast, führe folgende Schritte aus:

1. Zertifikat und Schlüssel auf den Server kopieren

Kopiere das Zertifikat und den privaten Schlüssel auf den Q.wiki-Server in das Verzeichnis /etc/ssl/private. Alle weiteren Befehle werden in diesem Verzeichnis ausgeführt.

2. Dateiformat überprüfen

Q.wiki benötigt einen RSA-Schlüssel (ohne Passwort) und ein X.509-Zertifikat im Base64-Format. Wenn dein Zertifikat im DER- oder PKCS#12-Format vorliegt, muss es konvertiert werden.

DER-Format konvertieren

openssl x509 -inform der -in fqdn.xyz -out fqdn.cert.pem

PKCS#12-Format konvertieren

Privaten Schlüssel extrahieren:

openssl pkcs12 -in fqdn.pfx -nocerts -nodes -out fqdn.key.pem

Zertifikat extrahieren:

openssl pkcs12 -in fqdn.pfx -clcerts -nokeys -out fqdn.cert.pem

3. Privaten Schlüssel überprüfen

Teste, ob der Schlüssel korrekt formatiert ist:

openssl rsa -noout -in fqdn.key.pem

Falls eine Passwortabfrage erscheint, muss das Passwort entfernt werden – andernfalls wird bei jedem Webserver-Neustart die manuelle Passworteingabe erforderlich.

4. Dateiberechtigungen setzen

chown root:root fqdn.*
chmod 0600 fqdn.*

5. Nginx-Konfiguration bearbeiten (nur Ersteinrichtung)

Öffne die Nginx-Konfigurationsdatei:

vim /etc/nginx/sites-enabled/qwiki_http.conf

Ersetze den gesamten Inhalt mit folgende Konfiguration (passe die rot markierten Werte an):

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name qwiki_http;

    rewrite ^/(.*)$ https://qwiki.acme.local/$1 permanent;
}

server {
    listen 443 default_server ssl;
    listen [::]:443 default_server ssl;

    server_name qwiki_https;

    root /var/www/qwikis/core;

    ssl_certificate /etc/ssl/private/fqdn.cert.pem;
    ssl_certificate_key /etc/ssl/private/fqdn.key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location ~ (/pub/System|/robots.txt) {
        sendfile on;
        tcp_nopush on;
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }

    location /api/phoenix {
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://elixir;
    }

    location / {
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://qwiki;
    }
}

6. Q.wiki-Konfiguration anpassen (nur Ersteinrichtung)

Öffne die Q.wiki-Konfigurationsdatei:

vim /var/www/qwiki/core/lib/LocalSite.cfg

Suche nach dem Eintrag DefaultUrlHost und ersetze das Protokoll von http zu https:

$Foswiki::cfg{DefaultUrlHost} = 'https://qwiki.acme.local';

Speichere die Datei.

7. Services neu starten

a2enmod ssl
systemctl restart nginx qwiki

Das SSL-Zertifikat ist nun aktiv. Überprüfe die Verbindung, indem du Q.wiki über https:// aufrufst.

SSL-Zertifikat aktualisieren ab Version 6.8

In Q.wiki ab Version 6.8 können Zertifikate über die Benutzeroberfläche verwaltet werden. Folge diesen Schritten:

1. Q.wiki Commander Shell öffnen

qmmander

2. Q.wiki-Konfiguration aufrufen

Navigiere im Menu zu den Sicherheitseinstellungen und öffne die Zertifikatverwaltung.

3. Zertifikat und Schlüssel aktualisieren

Update die Pfade zum neuen Zertifikat und Schlüssel. Üblicherweise werden diese unter /root/qwiki/ abgelegt:

ABSOLUTE_TLS_CRT_PATH: /root/qwiki/fqdn.cert.pem
ABSOLUTE_TLS_KEY_PATH: /root/qwiki/fqdn.key.pem

4. Konfiguration speichern und neu laden

Speichere die Änderungen und führe im Q.wiki Commander folgende Option aus:

Update certificate

Die neuen Zertifikate werden sofort aktiviert, ohne dass ein Neustart erforderlich ist.