Identitätsverifizierung

Warum verifizieren#

Standardmäßig ist das SDK anonym: Es generiert eine stabile visitor_id und bewahrt sie im Keystore der Plattform auf. Das reicht für eine Konversation auf einem Gerät. Um einen bestimmten Nutzer wiederzuerkennen, den Verlauf bei erneuter Anmeldung oder auf einem anderen Gerät wiederherzustellen und eine Konversation zuverlässig an ein Kontaktprofil zu binden, benötigt das Backend einen Beweis, dass der Client der ist, für den er sich ausgibt. Würde das SDK einfach "Ich bin Nutzer 42" senden, könnte jeder eine fremde ID vortäuschen und den Chat einer anderen Person lesen — deshalb verlangt Respondo eine kryptografische Signatur, userHash, die nur Ihr Backend erzeugen kann.

Das identity_secret erhalten#

Das identity_secret ist eine geheime Zeichenkette, die an Ihren Agenten gebunden ist (den KI-Worker, mit dem Ihr Widget-Kanal verbunden ist). Generieren Sie es im Dashboard unter Channels → Widget → Identity verification. Da es am Agenten hängt, teilen sich alle Kanäle dieses Agenten dasselbe Secret — Web-Widget und Mobile-SDK gleichermaßen. Es gewährt das Recht, Identitäten zu signieren, daher muss es ausschließlich auf Ihrem Backend liegen und darf niemals in der App ausgeliefert werden.

Die userHash-Formel#

userHash ist ein HMAC-SHA256 über eine einzelne signierte Identitäts-Zeichenkette, kodiert als Hex in Kleinbuchstaben:

userHash = HMAC_SHA256( identity_secret, payload )

payload = userId          // wenn userId gesetzt ist
        = email           // andernfalls, wenn email gesetzt ist
        = (ungültig)      // wenn beide leer sind, gibt es nichts zu signieren

• Das Secret ist der HMAC-Schlüssel; die Identitäts-Zeichenkette ist die Nachricht — nicht umgekehrt.
• Signieren Sie genau eine Zeichenkette — die rohe userId (oder E-Mail), ohne Salt oder JSON-Wrapper.
• Wenn Sie sowohl userId als auch E-Mail übergeben, signieren Sie die userId (sie hat Vorrang).
• Die Ausgabe ist Hex (64 Zeichen für SHA-256), nicht Base64.

Backend-Beispiele#

Berechnen Sie die Signatur auf Ihrem Backend und übergeben Sie den fertigen userHash an die App.

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

// HMAC_SHA256(identity_secret, userId) als Hex in Kleinbuchstaben.
func ComputeUserHash(identitySecret, userID string) string {
    mac := hmac.New(sha256.New, []byte(identitySecret))
    mac.Write([]byte(userID))
    return hex.EncodeToString(mac.Sum(nil))
}

const crypto = require("crypto");

// Gibt den userHash zurück, der an Respondo.identify auf dem Mobile-Client übergeben wird.
function computeUserHash(identitySecret, userId) {
  return crypto
    .createHmac("sha256", identitySecret)
    .update(userId, "utf8")
    .digest("hex");
}

import hmac
import hashlib

# Gibt den userHash zurück, der an Respondo.identify auf dem Mobile-Client übergeben wird.
def compute_user_hash(identity_secret: str, user_id: str) -> str:
    return hmac.new(
        identity_secret.encode(),
        user_id.encode(),
        hashlib.sha256,
    ).hexdigest()

<?php
// Gibt den userHash zurück, der an Respondo.identify auf dem Mobile-Client übergeben wird.
function computeUserHash(string $identitySecret, string $userId): string {
    return hash_hmac('sha256', $userId, $identitySecret);
}

Wie der Hash zu Respondo gelangt#

Zwei Etappen, und nur die erste müssen Sie selbst bauen:

1. Ihr Backend → Ihre App. Sie liefern den Hash aus, wie Sie möchten. Am günstigsten ist ein zusätzliches Feld in der Login-/Bootstrap-Antwort, die Sie ohnehin zurückgeben — kein zusätzlicher Roundtrip. Ein eigener Endpunkt auf Ihrem eigenen Backend (etwa POST /myapp/identity mit der Antwort { userId, userHash }) funktioniert genauso gut. Respondo hostet diesen Endpunkt nicht — Sie implementieren ihn.
2. Ihre App → Respondo. Übernimmt das SDK für Sie. Sobald Sie identify aufrufen, hängt das SDK den Hash an jede relevante Anfrage an, und das Backend verifiziert ihn jedes Mal erneut.

POST /api/v1/chat                      body   identity.userHash
GET  /api/v1/chat/resume               query  user_hash
GET  /api/v1/chat/history              query  user_hash
GET  /api/v1/chat/ws                   frames    user_hash (subscribe/identify JSON frames after connect — not in the handshake URL)
GET  /api/v1/widget/tours              query  user_hash
GET  /api/v1/widget/checklists         query  user_hash
POST /api/v1/widget/push/register      body   user_hash

Der Hash wird bei jeder Anfrage erneut geprüft und nicht einmalig gegen eine Session eingetauscht — genau das macht eine gestohlene userId für sich allein wertlos.

Identität an das SDK übergeben#

Holen Sie die signierte Identität von Ihrem Backend und übergeben Sie dann den userHash an identify auf jeder Plattform:

Respondo.identify(
    RespondoIdentity(userId = "42", email = "user@example.com", userHash = hash),
)

Respondo.identify(
    RespondoIdentity(userId: "42", email: "user@example.com", userHash: hash)
)

Respondo.identify(RespondoIdentity(
  userId: '42', email: 'user@example.com', userHash: hash,
));

Verhalten bei ungültigem userHash#

Wenn die Verifizierung für den Agenten aktiviert ist und die Signatur fehlt oder falsch ist, führt das Backend eine stille Herabstufung auf anonym durch: Der Chat funktioniert weiterhin, die visitor_id bleibt erhalten, und die Konversation wird an den anonymen Kontakt gebunden — aber es gibt keine Verknüpfung zum Profil und keinen geräteübergreifenden Verlauf. Wenn ein Nutzer "nicht erkannt wird", liegt es fast immer an der Signatur: Prüfen Sie, dass Sie die userId (nicht E-Mail oder JSON) signiert, das richtige identity_secret verwendet und Hex in Kleinbuchstaben ausgegeben haben. Wenn das identity_secret des Agenten leer ist, ist die Verifizierung aus, und userId / E-Mail werden unverändert akzeptiert.

Das Rotieren des identity_secret ist faktisch eine harte Umstellung: Jeder mit dem alten Secret erzeugte Hash verifiziert sofort nicht mehr, sodass bereits angemeldete Nutzer stillschweigend auf anonym zurückfallen, bis Ihr Backend ihren userHash mit dem neuen Secret neu berechnet und erneut liefert. Rollen Sie das Secret nur, wenn Sie die signierende Seite im selben Zeitfenster aktualisieren können.