Integrations-Workflows

Die Einbindung der Hansestack API sollte an den kritischen Stellen deiner Benutzerverwaltung erfolgen. Da wir uns in der Public Beta befinden, ist das architektonische Design entscheidend.

Regel #1: Das Fail-Open Prinzip

Hansestack ist ein zusätzlicher Sicherheits-Layer. Die API darf niemals zu einem Single-Point-of-Failure für dein Kerngeschäft werden.

Implementiere zwingend einen Fail-Open-Mechanismus:
Setze in deinem HTTP-Client einen strikten Timeout (z. B. 500ms bis 800ms). Wenn unsere API nicht antwortet, einen 5xx-Error wirft oder du das Rate-Limit überschritten hast, muss dein System den Vorgang fortsetzen, als wäre nichts passiert. Logge den Ausfall intern, aber blockiere niemals deine Nutzer wegen eines API-Ausfalls.

Der generische k-Anonymity Check-Ablauf

Unabhängig davon, an welcher Stelle in deiner Applikation du Hansestack einsetzt, ist der grundlegende Ablauf des k-Anonymity Checks immer identisch. Dieser Flow garantiert, dass Passwörter niemals im Klartext deine Infrastruktur verlassen.

Lokales Hashing: Das Klartext-Passwort wird auf deinem System mittels SHA-1 gehasht.
Präfix-Extraktion: Der Hash wird in ein 5-stelliges Präfix und ein verbleibendes Suffix aufgeteilt.
API-Anfrage: Du sendest ausschließlich das 5-stellige Präfix an die Hansestack API.
Antwort: Die API liefert ein JSON-Objekt mit einer Liste aller kompromittierten Suffixe zurück, die zu diesem Präfix gehören.
Lokaler Abgleich: Dein System prüft lokal, ob das eigene Suffix in der zurückgegebenen Liste enthalten ist. Ist das der Fall, gilt das Passwort als kompromittiert.

    sequenceDiagram
    participant S as Dein System (Frontend/Backend)
    participant H as Hansestack API

    Note over S: SHA-1(Passwort) = Hash
    Note over S: Split in Präfix (5) + Suffix
    S->>H: GET /v1/prefixes/{prefix}
    H-->>S: Liste der kompromittierten Suffixe
    Note over S: Lokaler Abgleich:<br/>Ist Suffix in der Liste?

Anwendungsfälle (Use Cases)

Je nachdem, an welchem Punkt im Lebenszyklus eines Nutzers der Check durchgeführt wird, empfehlen sich unterschiedliche Vorgehensweisen für die Integration und die User Experience (UX).

1. Während der Registrierung (Sign-Up)

Bei der Erstellung eines neuen Kontos verhinderst du proaktiv, dass unsichere Passwörter überhaupt erst in deine Datenbank gelangen.

Best Practice: Implementiere den Check idealerweise direkt im Frontend mittels JavaScript. Sobald der Nutzer das Passwortfeld verlässt (OnBlur-Event) oder während er tippt (mit Debouncing), wird der Check asynchron durchgeführt.

Vorteil: Der Nutzer erhält sofortiges visuelles Feedback ("Dieses Passwort ist Teil eines bekannten Datenleaks. Bitte wähle ein anderes."), noch bevor er das Formular absendet. Das reduziert Frustration.
Hinweis: Führe den Check zur Sicherheit im Backend noch einmal durch, bevor der Datensatz final gespeichert wird.

2. Während des Logins (Sign-In)

Beim Login prüfst du bestehende Passwörter deines Datenbestands. Um die Serverlast gering zu halten, sollte der Leak-Check erst ausgelöst werden, nachdem E-Mail und Passwort lokal in deiner Datenbank als korrekt verifiziert wurden.

Hier gibt es zwei etablierte Architektur-Ansätze:

Ansatz A: Synchroner Check (Blocking im Auth-Flow)
Der Check passiert direkt während der Authentifizierung.

Lokaler Login ist erfolgreich.
Leak-Check gegen Hansestack wird durchgeführt.
Ist das Passwort kompromittiert, wird der Nutzer zwar eingeloggt, die Session wird jedoch temporär eingeschränkt.
Der Nutzer wird sofort auf eine Seite weitergeleitet, die ihn zwingend zu einer Passwortänderung auffordert ("Forced Password Reset"). Er kann den Dienst erst nach der Änderung nutzen.

Ansatz B: Asynchroner Check (Non-Blocking Background Job)
Dieser Ansatz ist optimal, wenn der Login-Flow unter keinen Umständen durch externe Netzwerk-Calls verzögert werden darf.

Der Nutzer loggt sich regulär ein und erhält sofort Zugriff.
Der Server stößt asynchron einen Background-Job (z. B. via Message Queue oder Goroutine) für den Leak-Check an.
Wird ein Leak festgestellt, wird ein Flag in der Nutzer-Datenbank gesetzt.
Beim nächsten Seitenaufruf oder durch WebSockets erhält der Nutzer einen permanenten Warn-Banner im Dashboard ("Dein Passwort wurde kompromittiert, bitte ändere es") oder er wird per E-Mail informiert.

3. Bei der Passwortänderung (Password Reset)

Jedes Mal, wenn ein Nutzer sein Passwort ändert – sei es freiwillig in den Profileinstellungen oder über einen "Passwort vergessen"-Link –, muss das neue Passwort geprüft werden.

Der Workflow verhält sich hier identisch zur Registrierung: Ein kompromittiertes Passwort wird vom System abgelehnt und nicht gespeichert. Der Nutzer wird aufgefordert, eine sichere Alternative zu wählen.

Quickstart API-Dokumentation