Benutzeridentität in den DobroDesk-SDKs schützen

Signieren auf dem Backend halten

Ihr Backend authentifiziert den aktuellen Kunden, signiert ein kurzlebiges DobroDesk-Kundenidentitäts-JWT für die ausgewählte Integration und gibt es über einen durch die Host-Sitzung geschützten Endpunkt zurück. Die Endpunktantwort für mobile Wrapper ist JSON mit einem authorizationToken-String.

Das SDK erstellt dieses JWT nicht und loadDobroDeskToken ist keine SDK-Funktion. In den folgenden Beispielen ist es eine vom Host bereitgestellte Funktion. Fügen Sie das JWT-Signier-Geheimnis, ein DobroDesk-Support-API-Token oder langlebige Dienstzugänge niemals in Browser-JavaScript, ein Mobile-Bundle oder ein öffentliches Repository ein.

Das Web-Widget unterstützt auch eine anonyme Sitzung. Native SDK-Integrationen benötigen vor Netzwerkoperationen und der Anzeige des Widgets eine signierte Kundenidentität. Native Anfragen senden sie als Authorization: Bearer... mit x-dobrodesk-client: native-v1 und senden keinen Browser-Origin. Nach dem Sitzungsstart verwaltet die native Engine den erhaltenen Sitzungsnachweis und sendet ihn als x-dobrodesk-session-token. Der Host darf diesen Header nicht selbst erzeugen oder ersetzen.

// This function belongs to your application. The route is your backend route.
async function loadDobroDeskToken(): Promise<string> {
  const response = await fetch("/your-backend/dobrodesk-token", {
    method: "POST",
    credentials: "include",
    headers: { Accept: "application/json" },
  });
  if (!response.ok) throw new Error("Customer token request failed");
  const body = (await response.json()) as { authorizationToken?: unknown };
  if (typeof body.authorizationToken !== "string" || !body.authorizationToken)
    throw new Error("Customer token response is invalid");
  return body.authorizationToken;
}

// Web can remain anonymous or apply the token after host login.
widget.setIdentityToken(await loadDobroDeskToken());

// React Native, NativeScript and Capacitor use the signed native shape.
const config = {
  apiOrigin: "https://dobrodesk.com",
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  accountScope: currentCustomer.id,
  credentialProvider: async () => ({
    authorizationToken: await loadDobroDeskToken(),
  }),
};

Signiergeheimnis und Claims konfigurieren

Öffnen Sie unter Admin > Channels > Website widgets die Widget-Integration, setzen Sie den Identitätsmodus auf Require a signed logged-in user und verwenden Sie Copy identity secret. Speichern Sie das kopierte integrationsspezifische Secret zusammen mit der öffentlichen Integration ID in Ihrem Backend-Secret-Manager. Das Secret gehört niemals in einen Browser, ein Mobile-Bundle oder ein öffentliches Repository. Verwenden Sie es als HS256-Signierschlüssel.

Signieren Sie ein dreiteiliges HS256-JWT mit typ JWT. Erforderliche Claims sind iss = dobrodesk-widget:{integrationId}, aud = die öffentliche Integration ID, sub = eine stabile Kunden-ID, die keine E-Mail ist, iat = aktuelle Unix-Sekunden und exp höchstens 15 Minuten nach iat. Der Verifizierer erlaubt 60 Sekunden Uhrabweichung. Optionale Claims sind name, email, email_verified: true und jti. Setzen Sie email_verified nur, wenn der Host die Adresse verifiziert hat.

const textEncoder = new TextEncoder();

const base64url = (bytes: Uint8Array) => {
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
};

// secretStore is your backend secret manager. Never run this in browser code.
export async function createDobroDeskIdentityToken(user: {
  id: string;
  email?: string;
  emailVerified?: boolean;
  name?: string;
}) {
  const integrationId = await secretStore.get("DOBRODESK_WIDGET_ID");
  const identitySecret = await secretStore.get("DOBRODESK_WIDGET_IDENTITY_SECRET");
  const now = Math.floor(Date.now() / 1000);
  const encode = (value: unknown) =>
    base64url(textEncoder.encode(JSON.stringify(value)));
  const header = encode({ alg: "HS256", typ: "JWT" });
  const payload = encode({
    iss: `dobrodesk-widget:${integrationId}`,
    aud: integrationId,
    sub: user.id,
    iat: now,
    exp: now + 5 * 60,
    ...(user.email
      ? {
          email: user.email,
          ...(user.emailVerified === true ? { email_verified: true } : {}),
        }
      : {}),
    ...(user.name ? { name: user.name } : {}),
  });
  const key = await crypto.subtle.importKey(
    "raw",
    textEncoder.encode(identitySecret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"],
  );
  const signature = base64url(
    new Uint8Array(
      await crypto.subtle.sign("HMAC", key, textEncoder.encode(`${header}.${payload}`)),
    ),
  );
  return `${header}.${payload}.${signature}`;
}

Identität bewusst binden und löschen

Setzen Sie accountScope auf einen stabilen Kunden- oder Kontoidentifikator des Hosts, der keine Geheimnisse enthält. Er isoliert den dauerhaften nativen Sitzungszustand und die Outbox. Verwenden Sie einen Scope nicht für mehrere angemeldete Kunden.

Rufen Sie bei Flutter, React Native, NativeScript oder Capacitor logout auf, bevor die Host-Sitzung endet oder accountScope geändert wird. Direkte iOS- und Android-Clients bieten stattdessen resetSession: Setzen Sie den Client zurück und erstellen Sie für das nächste Konto einen neuen. Rufen Sie resetSession auf, wenn der Kunde die aktuelle Unterhaltung bewusst verwirft, aber angemeldet bleibt. Eine Token-Aktualisierung ist kein Kontowechsel und verwendet denselben Account-Scope.

Unsichere Token-Zustände ablehnen

1. Lehnen Sie ein leeres, fehlerhaftes, abgelaufenes oder für den falschen Kunden bestimmtes Token im Host-Endpunkt ab, statt ein Support-Zugangstoken zurückzugeben.
2. Behandeln Sie einen 401- oder session-expired-SDK-Fehler als Aufforderung für ein frisches Token desselben Kontos. Wechseln Sie accountScope nicht still und erstellen Sie keine neue Sitzung.
3. Wenn logout während einer ausstehenden Token-Anfrage angefordert wird, ignorieren Sie das verspätete Token und halten Sie das nächste Konto von der vorherigen Sitzung getrennt.