Sign inGet started

Channels autorisieren

Jeder Client mit dem App-Key kann öffentliche Channels abonnieren. Zwei Channel-Namenspräfixe erfordern, dass Ihr Backend das Abonnement autorisiert. Channels werden nicht separat konfiguriert.
Ein Channel mit dem Namen private-… erfordert, dass Ihr Backend jedes Abonnement genehmigt. Ein Channel mit dem Namen presence-… tut dasselbe und hängt dem Abonnenten zusätzlich eine Identität an, sodass alle im Channel sehen können, wer sonst noch da ist. Jeder andere Name ist öffentlich.
Nur Ihr Backend kennt das App-Secret. Der Client bittet Ihren Server, ein bestimmtes Abonnement zu signieren, und die Realtime-Edge überprüft diese Signatur, bevor sie es akzeptiert. Ihr Server entscheidet, ob der Aufrufer abonnieren darf, ohne das Secret gegenüber dem Client offenzulegen.

Client auf Ihren Endpunkt verweisen

Geben Sie dem Client eine authEndpoint auf Ihrem eigenen Backend:
import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
  authEndpoint: "/bird/auth",
});

const room = bird.subscribe("presence-room-1");
Der Client ruft diesen Endpunkt für jedes private oder Presence-Abonnement auf, einschließlich Abonnements, die nach einem Reconnect wiederhergestellt werden. Die Autorisierung gilt für eine Verbindung, weil die Signatur deren Connection-ID enthält.
Der Browser-Client erfordert standardmäßig einen Same-Origin-Endpunkt. Setzen Sie allowCrossOriginAuth: true, um einen Cross-Origin-Endpunkt authEndpoint zu verwenden. Der Browser-Client sendet konfigurierte authHeaders nur an Same-Origin-Endpunkte.

Was Ihr Endpunkt empfängt und zurückgibt

Der Client sendet per POST JSON:
Codebeispiel
{ "connection_id": "26896.319537", "channel_name": "presence-room-1" }
Antworten Sie mit der Signatur:
Codebeispiel
{ "auth": "your-app-key:8f9a…" }
Geben Sie bei einem Presence-Channel zusätzlich die Mitglieder-Identität als JSON-String zurück, denselben String, den Sie signiert haben:
Codebeispiel
{
  "auth": "your-app-key:8f9a…",
  "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Ada\"}}"
}
member_id ist die Identität, die andere Mitglieder sehen, und der Wert, auf den die Disconnect-Operation abzielt. member_info sind optionale JSON-Daten, die an jedes Channel-Mitglied geliefert werden. Das Limit beträgt 1 KB, fügen Sie also nur kleine, nicht-sensible Profildaten ein.
Autorisieren Sie den Aufrufer in diesem Endpunkt anhand seines Session-Cookies oder Bearer-Tokens. Geben Sie 403 Forbidden zurück, wenn der Aufrufer dem Channel nicht beitreten darf. Weisen Sie bei Presence-Channels die Identität in derselben Antwort zu.

Der String, den Sie signieren

Verketten Sie die Teile mit Doppelpunkten und wenden Sie dann HMAC-SHA256 mit dem App-Secret an, hex-kodiert. Stellen Sie dem Ergebnis den App-Key und einen Doppelpunkt voran.
Channel-TypZu signierender String
private-…<connection_id>:<channel_name>
private-encrypted-…<connection_id>:<channel_name>
presence-…<connection_id>:<channel_name>:<member_data>
Signieren Sie bei Presence-Channels exakt den member_data-String, den Sie zurückgeben. Eine erneute Serialisierung desselben Objekts kann die Schlüsselreihenfolge oder Abstände ändern und die Signatur ungültig machen.
Ein verschlüsselter Channel wird wie ein privater signiert, und seine Auth-Antwort gibt zusätzlich den Entschlüsselungsschlüssel des Channels als shared_secret zurück. Der SDK-Helper fügt ihn automatisch hinzu; Verschlüsselte Channels behandelt die Ableitung und das Channel-Verhalten.
Jede Server-SDK stellt einen authorizeChannel-Helper bereit. Er signiert mit den konfigurierten App-Zugangsdaten und gibt den Antwort-Body zurück, ohne eine Netzwerkanfrage zu senden. Bei verschlüsselten Channels fügt der Helper auch shared_secret hinzu.
app.post("/bird/auth", async (req, res) => {
  const { connection_id, channel_name } = req.body;

  // Your own authorization decision goes here.
  const user = getUserFromSession(req);
  if (!user || !mayJoin(user, channel_name)) return res.sendStatus(403);

  const memberData = channel_name.startsWith("presence-")
    ? JSON.stringify({ member_id: user.id, member_info: { name: user.name } })
    : undefined;

  res.json(
    await bird.realtime.authorizeChannel({
      connectionId: connection_id,
      channelName: channel_name,
      memberData,
    }),
  );
});
Der Signiervertrag ist in einer Sprache ohne SDK derselbe: Wenden Sie HMAC-SHA256 auf den String mit dem App-Secret an, hex-kodieren Sie das Ergebnis und stellen Sie den App-Key und einen Doppelpunkt voran.

Mitglieder und Verbindungen

Ein Mitglied ist eine Identität, während eine Verbindung ein offener WebSocket ist. Wenn jemand Ihre App in drei Tabs öffnet, hat ein Mitglied drei Verbindungen. member_added wird ausgelöst, wenn die erste Verbindung abonniert, und member_removed wird ausgelöst, wenn die letzte geht. Andere Verbindungen ändern die Verbindungsanzahl des Channels, ohne Mitglieder-Events auszulösen.

Häufige Fehler

Ein abgelehntes Abonnement kommt als Client-Fehler an. Prüfen Sie diese häufigen Ursachen:
  • Ungültige Signatur. Der von Ihnen signierte String stimmt nicht überein. Fast immer ein erneut serialisiertes member_data oder eine Signatur, die über den Channel-Namen ohne das Präfix private- oder presence- berechnet wurde.
  • Ungültiger Key. Der Key in auth gehört zu einer anderen App oder wurde widerrufen. Bei einer Key-Rotation müssen sowohl der appKey des Clients als auch das Secret, mit dem Ihr Endpunkt signiert, aktualisiert werden.
  • Fehlende Mitgliedsdaten. Ein Presence-Abonnement kam ohne member_data an. Presence-Channels können nicht anonym beigetreten werden.
  • Ein 403 von Ihrem eigenen Endpunkt. Ihre Autorisierungsentscheidung hat abgelehnt, was das beabsichtigte Ergebnis für einen Benutzer ist, der nicht beitreten darf.

Nächste Schritte

  • Erstes Realtime-Event senden ist die End-to-End-Anleitung, auf der dieser Guide aufbaut.
  • Verschlüsselte Channels bauen auf dieser Signatur auf und übergeben genehmigten Abonnenten zusätzlich einen Entschlüsselungsschlüssel.
  • Presence-Channels behandeln die Mitgliederliste, Mitglieder-Events und das Lesen von Presence-Daten von Ihrem Server.
  • Mitgliederverbindungen beenden ist die andere Signatur, die Ihr Backend berechnet, und diejenige, mit der Sie die Verbindungen eines Mitglieds schließen können.
  • Webhooks & Events behandelt realtime.*-Events, einschließlich Beitritt und Verlassen von Mitgliedern, auf Ihrem eigenen Endpunkt.

Verwandte Ressourcen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.

Übung ausprobieren und ein Implementierungs-Briefing erhalten