Anmeldung & Sicherheit

Node64 ist ab Werk abgesichert: kein Standardpasswort, Passwörter mit argon2id, verschlüsselte Geheimnisse und ein Audit-Log. Auf Wunsch kommen Zwei-Faktor-Anmeldung, Passkeys, Single Sign-on über OpenID Connect oder Forward-Auth über deinen Reverse-Proxy dazu.

Anmeldung und Admin-Konto

Node64 hat ein Admin-Konto, das du beim ersten Start selbst anlegst. Ein Standardpasswort gibt es nicht. Der Einrichtungsassistent unter /setup erscheint nur, solange noch kein Benutzer existiert.

• Benutzername: 3 bis 64 Zeichen, erlaubt sind Buchstaben, Ziffern, Punkt, Minus und Unterstrich (Vorgabe admin).
• Passwort: mindestens 10 Zeichen. Gespeichert wird nur ein argon2id-Hash.
• Alternative für automatische Installationen: NODE64_ADMIN_USER und NODE64_ADMIN_PASSWORD legen das Konto beim allerersten Start an. Danach werden die Variablen ignoriert. Details unter Konfiguration.

Sprache, Zeitzone und Passwort änderst du jederzeit unter Einstellungen. Der lokale Benutzer mit Passwort bleibt immer die Grundlage – alle anderen Anmeldewege ergänzen ihn nur.

Sitzungen und Schutz vor Rateversuchen

Zwei-Faktor-Anmeldung (TOTP)

Mit der Zwei-Faktor-Anmeldung fragt Node64 nach dem Passwort zusätzlich einen Code aus einer Authenticator-App ab, zum Beispiel Aegis, 2FAS oder Google Authenticator.

1. Öffne Einstellungen → Zwei-Faktor-Anmeldung (/settings/2fa) und klicke auf Einrichten.
2. Scanne den QR-Code mit deiner App oder tippe das angezeigte Geheimnis von Hand ein.
3. Gib den Code aus der App ein und aktiviere die Zwei-Faktor-Anmeldung. Alle anderen Sitzungen werden dabei abgemeldet.
4. Speichere die acht Wiederherstellungscodes an einem sicheren Ort. Jeder Code gilt genau einmal und wird nur dieses eine Mal angezeigt.

Passwort vergessen: Notfallzugang

Passwort vergessen oder verloren? Eine „Passwort vergessen“-Mail gibt es bewusst nicht – Node64 läuft bei dir und braucht keinen Mailserver. Stattdessen setzt du das Passwort mit einem Befehl im laufenden Container neu. Das kann nur, wer Zugriff auf den Docker-Host hat – also du, nicht jemand aus dem Netz.

1. Befehl auf dem Docker-Host ausführen
   
   bash

   docker exec node64 /node64 reset-password

   Mit docker compose: docker compose exec node /node64 reset-password (statt node der Dienstname aus deiner compose-Datei).
2. Neues Passwort ablesen
   Der Befehl erzeugt ein zufälliges Passwort mit 20 Zeichen und zeigt es einmal an. Alle bisherigen Sitzungen werden beendet.
3. Anmelden und Passwort ändern
   Mit dem neuen Passwort anmelden und unter Einstellungen ein eigenes festlegen.

• Der Node muss dafür nicht angehalten werden; Daten, Checks und Einstellungen bleiben unverändert.
• Der Vorgang steht im Audit-Log („Passwort geändert“, Zusatz „reset-password (Kommandozeile)“).
• Passkeys und verknüpfte SSO-Konten bleiben bestehen – damit kommst du auch ohne Passwort rein, falls eingerichtet.

Passkeys

Passkeys sind eine Anmeldung ohne Passwort und ohne Benutzernamen: Auf der Login-Seite klickst du auf Mit Passkey anmelden und bestätigst mit Fingerabdruck, Face ID, Geräte-PIN oder einem Sicherheitsschlüssel wie einem YubiKey.

• Voraussetzung: Die Node muss über HTTPS mit einem Hostnamen aufgerufen werden, zum Beispiel https://node64.example.com. Unter einer IP-Adresse lassen Browser keine Passkeys zu. Einzige Ausnahme ist http://localhost.
• Ein Passkey gilt nur für den Hostnamen, unter dem du ihn angelegt hast.
• Anlegen unter Einstellungen → Anmeldung → Passkeys (/settings/login). Mehrere Passkeys pro Benutzer sind möglich, etwa Handy und YubiKey.
• Ein Passkey ist eine eigenständige Anmeldung, kein zweiter Faktor zum Passwort. Passwort und App-2FA bleiben daneben bestehen.

Single Sign-on über OpenID Connect

Wenn du im Homelab schon einen Identitätsanbieter betreibst, meldest du dich auch bei Node64 darüber an. Das klappt mit jedem OIDC-Anbieter, etwa Authelia, Authentik, Keycloak, Pocket ID, Zitadel oder Kanidm.

Einrichten

1. Lege beim Anbieter einen vertraulichen Client an (confidential): Authorization Code mit PKCE, Scopes openid profile email.
2. Trage als Redirect URI die Adresse ein, die Node64 unter Einstellungen → Anmeldung anzeigt. Sie hat die Form https://<node>/login/oidc/callback.
3. Trage in Node64 Issuer-URL, Client-ID und Client-Secret ein. Das Secret wird verschlüsselt gespeichert.
4. Klicke im eigenen Benutzer unter Verknüpfte Konten auf Mit … verknüpfen und melde dich einmal beim Anbieter an.
5. Ab jetzt steht auf der Login-Seite Mit … anmelden.

Der Ablauf ist mit state, nonce und PKCE abgesichert. Jede SSO-Anmeldung steht im Audit-Log.

Beispiel: Authelia

identity_providers:
  oidc:
    clients:
      - client_id: node64
        client_name: Node64
        client_secret: '$pbkdf2-sha512$...'   # Hash des Secrets, das du in Node64 einträgst
        public: false
        authorization_policy: two_factor
        require_pkce: true
        pkce_challenge_method: S256
        redirect_uris: ['https://node64.example.com/login/oidc/callback']
        scopes: [openid, profile, email]
        token_endpoint_auth_method: client_secret_basic

Die Issuer-URL in Node64 ist dann die Adresse von Authelia, z. B. https://auth.example.com.

Beispiel: Authentik

1. Einen OAuth2/OpenID-Provider vom Typ Confidential anlegen und die Redirect URI von Node64 eintragen.
2. Eine Anwendung mit dem Slug node64 anlegen und mit dem Provider verbinden.
3. Issuer-URL in Node64: https://authentik.example.com/application/o/node64/

Beispiel: Keycloak

Bei Keycloak gelten dieselben Eckdaten: ein Client mit Client-Authentifizierung (vertraulich), Authorization Code Flow, die Redirect URI https://node64.example.com/login/oidc/callback und die Scopes openid profile email. Die Issuer-URL ist typischerweise die Adresse deines Realms, etwa https://keycloak.example.com/realms/homelab.

Forward-Auth über den Reverse-Proxy

Steht Node64 hinter Traefik, Caddy oder Nginx mit Authelia oder Authentik als Forward-Auth, meldet der Proxy den angemeldeten Benutzer in einem HTTP-Kopf, standardmäßig Remote-User. Node64 meldet dich dann ohne eigene Login-Seite an.

  # Forward-Auth: der Proxy sagt, wer angemeldet ist

  Browser             Reverse-Proxy                     Node64
 ┌────────┐  HTTPS  ┌─────────────────────┐ Remote-User ┌────────────────────┐
 │   Du   │ ──────► │ Traefik/Caddy/Nginx │ ──────────► │ 1. Verbindung aus  │
 └────────┘         │ + Authelia oder     │   admin     │    Proxy-Netz?     │
                    │   Authentik         │             │ 2. lokaler Benutzer│
                    │   (Login + 2FA)     │             │    „admin“ da?     │
                    └─────────────────────┘             └────────────────────┘

 # Direkt ohne Proxy: kommt nicht aus dem Proxy-Netz, Kopf wird ignoriert
  Browser ─────────────────────────────────────────► Node64 (normaler Login)

• Standardmäßig aus. Eingeschaltet unter Einstellungen → Anmeldung → Forward-Auth.
• Vertrauenswürdige Proxy-Netze: Der Kopf gilt nur für Verbindungen aus den eingetragenen Adressen des Proxys – einzelne IPs oder Netze in CIDR-Schreibweise, durch Komma getrennt. Geprüft wird die Adresse der Verbindung selbst, nie X-Forwarded-For. „Alle Adressen“ (0.0.0.0/0 bzw. ::/0) ist gesperrt. Die Seite zeigt dir an, von welcher Adresse deine aktuelle Anfrage kommt.
• Genau ein Benutzer: Der Name im Kopf muss genau dem lokalen Benutzernamen entsprechen. Nimm in Authelia oder Authentik also denselben Namen wie in Node64.
• Bei jeder Anfrage geprüft: Wer sich beim Proxy abmeldet, ist auch in Node64 abgemeldet.
• Name des Kopfs ist einstellbar, falls dein Proxy einen anderen verwendet.
• Der Proxy muss den Kopf selbst setzen und einen vom Browser mitgeschickten überschreiben. Bei der Forward-Auth von Authelia und Authentik ist das der Fall.
• Ist die Node zusätzlich direkt erreichbar, schadet das nicht: Direkte Anfragen kommen nicht von der Proxy-Adresse und landen bei der normalen Anmeldung.

API-Keys

Für Skripte, Automationen und Prometheus legst du API-Keys an. Das geht im Menüpunkt API (Seite /api/docs, Abschnitt API-Keys).

• Ein Key beginnt mit node64_ und wird nur einmal angezeigt. Node64 speichert nur einen Hash, dazu Name, Kurzhinweis und „zuletzt benutzt“.
• Genutzt wird er als Kopf Authorization: Bearer node64_… – nur für Pfade unter /api/.
• Ein Key handelt mit den Rechten deines Benutzers. Lege daher je Zweck einen eigenen Key an (z. B. prometheus, backup-skript) und lösche ihn, wenn du ihn nicht mehr brauchst.
• Falsche Keys bremst Node64 je IP aus: nach 5 Fehlversuchen nur noch ein Versuch alle 30 Sekunden.

Mehr dazu in der Doku zur lokalen API.

Audit-Log

Das Audit-Log unter /audit hält fest, wer wann was geändert hat: Zeit, Akteur, Aktion, Ziel, Details, IP-Adresse und Herkunft. Jede Anmeldung steht darin; bei SSO, Passkey und Forward-Auth mit dem Weg, über den sie kam (sso …, passkey, forward-auth …). Aktionen über einen API-Key tragen die Herkunft api:<Key-Name>.

Wie lange Einträge bleiben, stellst du unter Einstellungen → Daten & Sicherung ein (Audit-Log aufbewahren): 90, 180, 365 Tage (Standard), 730 Tage oder unbegrenzt. Ältere Einträge – auch die Aufrufe über die KI-Schnittstelle – werden gelöscht.

Du kannst nach Bereichen filtern:

curl -H "Authorization: Bearer DEIN_API_KEY" \
  "http://node64.lan:8080/api/audit?area=login&limit=50"

Logs und Log-Level

Unter Logs (/logs) siehst du die letzten 2000 Zeilen direkt in der Oberfläche und kannst sie herunterladen. Zusätzlich schreibt Node64 alles auf die Standardausgabe, also in docker logs node64.

• Stufen: debug, info (Standard), warn, error. Beim Start setzt du sie mit NODE64_LOG_LEVEL, das Format mit NODE64_LOG_FORMAT (text oder json).
• Zur Laufzeit umschalten: unter Einstellungen → Logging, global oder je Bereich (Modul).
• Automatisch zurück: Ein geändertes Level fällt nach 30, 60 (Standard) oder 240 Minuten wieder zurück – oder bleibt, wenn du „nie“ wählst. So läuft Debug nicht versehentlich dauerhaft.
• Geheimnisse bleiben maskiert: Werte, die nach Passwort, Token oder Schlüssel aussehen, stehen nie im Klartext im Log – auch nicht bei Debug.
• Per API: GET /api/logs sowie GET und PUT /api/logging.

Geheimnisse verschlüsselt (secret.key)

Kanal-Tokens, SMTP-Passwörter, das OIDC-Secret, der ipv64-API-Key und private Zertifikatsschlüssel liegen AES-256-GCM-verschlüsselt in der Datenbank. Der Schlüssel dazu ist die Datei /data/secret.key, die Node64 beim ersten Start erzeugt.

Node64 sendet keine Telemetrie. Die Prüfung auf neue Versionen ist ausgeschaltet, bis du sie einschaltest, und ruft dann nur eine Versionsdatei bei ipv64.net ab.

Sicherheitstipps

• Langes, eigenes Passwort und dazu die Zwei-Faktor-Anmeldung oder einen Passkey.
• Oberfläche nicht ins Internet stellen. Port 8080 gehört ins Heimnetz. Für den Zugriff von unterwegs nimm ein VPN oder einen Reverse-Proxy mit Forward-Auth bzw. SSO davor.
• HTTPS mit eigenem Namen statt selbstsigniertem Zertifikat – das braucht es auch für Passkeys. Node64 spricht HTTP und HTTPS auf demselben Port.
• Hinter einem eigenen Reverse-Proxy NODE64_TRUST_PROXY=true setzen. Dann sieht Node64 die echte Client-IP (Audit-Log, Ratelimit) und erkennt HTTPS und Hostnamen für Passkeys und die SSO-Rückleitung. Ohne eigenen Proxy bleibt die Option aus.
• Je Zweck ein API-Key und nicht mehr benötigte Keys löschen.
• Docker-Socket nur bei Bedarf einbinden. Node64 stellt nur lesende Anfragen, trotzdem erlaubt der Socket viel. Ein Socket-Proxy, der nur Container-Abfragen zulässt, ist die sicherere Wahl (siehe Healthchecks).
• Container schlank lassen: Node64 läuft ohne Root (UID 65532), in einem Image ohne Betriebssystem und Shell und auf Wunsch mit schreibgeschütztem Root-Dateisystem. Nur /data muss beschreibbar sein.
• Regelmäßig ins Audit-Log schauen – besonders nach unerwarteten Anmeldungen. Läuft Honeypot64, meldet es Angriffe auf die Anmeldung selbst.
• Backups samt secret.key außerhalb des Servers aufbewahren.

Etwas unklar, fehlt etwas oder hast du eine Frage zu Node64? Frag im offiziellen Forum v64.tech.