Realtime beveiliging

Uw sessieregels bepalen wie zich mag abonneren.

Er is geen rechtenmodel om te configureren in Bird. Een privé- of presence-abonnement wordt goedgekeurd door een endpoint dat u schrijft, met de sessie die u al hebt, en ondertekend met een geheim dat alleen uw servers bewaren. Bird verifieert de handtekening; u bepaalt het beleid.

auth.ts

200 · signed

// Your endpoint. The only place the app secret lives.
app.post("/bird/auth", async (req, res) => {
  const { connection_id, channel_name } = req.body;
  const user = await session(req);

  if (!mayJoin(user, channel_name)) return res.sendStatus(403);

  // Signs <connection_id>:<channel_name>[:<member_data>] with the app
  // secret, and adds shared_secret on an encrypted channel.
  res.json(
    await bird.realtime.authorizeChannel({
      connectionId: connection_id,
      channelName: channel_name,
      memberData: JSON.stringify({
        member_id: user.id,
        member_info: { name: user.name },
      }),
    }),
  );
});

auth.ts

200 · signed

// Your endpoint. The only place the app secret lives.
app.post("/bird/auth", async (req, res) => {
  const { connection_id, channel_name } = req.body;
  const user = await session(req);

  if (!mayJoin(user, channel_name)) return res.sendStatus(403);

  // Signs <connection_id>:<channel_name>[:<member_data>] with the app
  // secret, and adds shared_secret on an encrypted channel.
  res.json(
    await bird.realtime.authorizeChannel({
      connectionId: connection_id,
      channelName: channel_name,
      memberData: JSON.stringify({
        member_id: user.id,
        member_info: { name: user.name },
      }),
    }),
  );
});

Eén sleutel is openbaar. De andere niet.

Alles volgt uit die scheiding.

Elke app op de Bird Realtime API heeft een sleutel en een geheim. De sleutel is bedoeld om in clientcode mee te leveren; het geheim authenticeert de aanroepen van uw server en ondertekent abonnementen, en wordt eenmalig getoond bij aanmaak. Iedereen die het bezit kan naar uw app publiceren en een presence-identiteit vervalsen, dus behandel het als een databasewachtwoord. Rotatie is additief in plaats van verstorend: maak een tweede sleutel aan, deploy deze en trek de oude in.

Vier controles, vier vragen

Wie mag abonneren, wie mag een verbinding houden, wie kan een payload lezen en wie is nog steeds toegelaten.

01
Ondertekende abonnementen.
De client stuurt zijn verbindings-id en de kanaalnaam naar uw endpoint. U controleert de aanroeper, weigert met een 403 als deze niet mag deelnemen, of retourneert een HMAC-SHA256-handtekening over verbindings-id en kanaalnaam, voorafgegaan door de app-sleutel. Omdat het verbindings-id in de handtekening zit, dekt een goedkeuring één verbinding en kan deze niet op een andere worden hergespeeld. Een presence-kanaal ondertekent ook de ledenidentiteit, en dit moet exact de string zijn die u retourneert: hetzelfde object opnieuw serialiseren kan sleutels herordenen en de handtekening ongeldig maken.
02
Geautoriseerde verbindingen.
De app-sleutel is openbaar, dus iedereen die uw pagina kan laden, kan er een socket mee openen. Schakel geautoriseerde verbindingen in en elke nieuwe verbinding heeft 30 seconden om te bewijzen dat iets met het geheim ervoor heeft ingestaan, via een privé-abonnement of een aanmelding. Alles wat dat niet doet, wordt gesloten met code 4009, en ongeautoriseerde verbindingen tellen nooit mee voor uw quotum. Abonneren op een openbaar kanaal bewijst niets en autoriseert geen verbinding.
03
End-to-end-versleuteling.
Een private-encrypted-kanaal wordt door uw server verzegeld voordat het verzoek uw proces verlaat, met een 32-byte mastersleutel die nooit in een Realtime API-verzoek verschijnt. Elk kanaal leidt zijn eigen sleutel af, dus het autoriseren van een client voor één versleuteld kanaal geeft geen toegang tot een ander. Bird kan een verloren sleutel niet herstellen, en rotatie beschermt toekomstige payloads in plaats van eerdere.
04
Toegang nu intrekken.
Een uitgelogde gebruiker, een gewijzigd wachtwoord, een geblokkeerd account: ontkoppel het lid en elke verbinding die die identiteit heeft, wordt gesloten, op elk apparaat. De clients behandelen die sluiting als definitief in plaats van opnieuw te proberen, en uw eigen endpoints stoppen met ondertekenen voor hen, zodat ze niet terug kunnen komen.

Versleutelde kanalen

Payloads die Bird niet kan lezen, op infrastructuur die Bird beheert.

Lees de versleutelingsgids

De server-SDK herkent het kanaalprefix, leidt de sleutel van dat kanaal af uit uw mastersleutel en verzegelt de payload lokaal. De edge stuurt cijfertekst door en uw autorisatie-endpoint geeft de afgeleide sleutel alleen aan clients die het goedkeurt. Twee beperkingen om rekening mee te houden: kanaal- en eventnamen reizen in leesbare tekst, dus kies namen die niet onthullen wat u beschermt, en versleuteling kan niet worden gecombineerd met presence of met client-events. Caching kan wel: een private-encrypted-cache-kanaal slaat zijn gecachte event verzegeld op.

encrypted.ts

sealed locally

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY!,
  realtime: {
    key: process.env.BIRD_REALTIME_KEY,
    secret: process.env.BIRD_REALTIME_SECRET,
    // 32 random bytes, yours alone. Never sent to Bird.
    encryptionMasterKey: process.env.BIRD_REALTIME_MASTER_KEY,
  },
});

// Sealed in your process. The edge forwards ciphertext.
await bird.realtime.publish(APP_ID, {
  event: "order.updated",
  channels: ["private-encrypted-orders"],
  data: { order_id: "ord_123", status: "shipped" },
});

Wat autorisatie niet doet.

Het vereisen van geautoriseerde verbindingen bepaalt wie een socket open mag houden. Het verandert niet wie een kanaal kan lezen: een openbaar kanaal blijft leesbaar voor elke geautoriseerde verbinding, dus events die bij één klant horen, horen op een privékanaal waarvan uw endpoint de naam controleert. En omdat uw endpoints de autoriteit zijn, deelt een te ruim endpoint toegang net zo vrij uit als een gelekte sleutel. Dezelfde eerlijkheid geldt voor client-events, die de edge niet valideert: gebruik ze voor signalen en routeer alles met autoriteit via uw server.

Waar de data staat.

Een app kiest zijn regio bij aanmaak en behoudt deze voor altijd, zodat u de regio kiest die het dichtst bij uw gebruikers ligt, en de regio van een app kan verschillen van de thuisregio van uw workspace. Apps zijn ook de isolatiegrens: twee apps zien nooit elkaars kanalen, en daarom is één app per omgeving de juiste manier om staging-verkeer uit productie te houden.

Ga dieper in de documentatie.

Kanalen autoriseren bevat het verzoek- en antwoordcontract en de exacte string om te ondertekenen. Geautoriseerde verbindingen vereisen behandelt het 30-secondenvenster en code 4009, versleutelde kanalen behandelt sleutelgeneratie en -rotatie, en ledenverbindingen beëindigen is de aanmeld- en ontkoppelstroom.