Controlla chi si connette e si iscrive con le regole di sessione che usi già.
Invia aggiornamenti privati sugli ordini, avvisi sull'account ed eventi dello spazio di lavoro a client browser e mobile senza esporre le credenziali del backend nel codice client. Il tuo endpoint di autenticazione verifica la sessione di chi chiama e firma le sottoscrizioni ai canali privati o di presenza per ogni connessione, mentre la crittografia end-to-end protegge i payload sensibili prima che lascino il tuo server.
auth.ts
200 · firmato403 · Forbidden200 · firmato200 · firmato// 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 }, }), }), );});
POST/bird/auth
Corpo della risposta
{ "auth": "d0e95a856ddc1b09d4c8:8f9a2c71e4…", "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Maya Chen\"}}" }
auth.ts
200 · firmato403 · Forbidden200 · firmato200 · firmato// 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 }, }), }), );});
POST/bird/auth
Corpo della risposta
{ "auth": "d0e95a856ddc1b09d4c8:8f9a2c71e4…", "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Maya Chen\"}}" }
auth.ts
200 · firmato403 · Forbidden200 · firmato200 · firmato// 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 }, }), }), );});
POST/bird/auth
Corpo della risposta
{ "auth": "d0e95a856ddc1b09d4c8:8f9a2c71e4…", "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Maya Chen\"}}" }
Distribuisci ai client una chiave pubblica
mantenendo i segreti di firma sul tuo server.
Un'app sulla API Realtime di Bird separa le credenziali di connessione dei client dall'autorità del backend. Browser e app mobile aprono i WebSocket con una chiave pubblica dell'app che puoi incorporare senza rischi nei bundle client, mentre il tuo backend custodisce il segreto usato per pubblicare eventi e firmare i token di sottoscrizione. Quando la tua policy di sicurezza richiede la rotazione delle credenziali, puoi creare una seconda coppia di chiavi, distribuirla nei tuoi servizi e revocare la coppia precedente senza disconnettere gli utenti attivi.
Proteggi connessioni, canali e payload a ogni livello
Verifica chi può aprire un socket, autorizza i canali a cui accede, cifra i dati sensibili degli eventi e revoca l'accesso quando una sessione termina.
- 01
Sottoscrizioni ai canali firmate.
Quando un client browser o mobile si iscrive a un canale privato o di presenza, il tuo backend verifica la sessione dell'utente e firma un token HMAC-SHA256 legato a quello specifico ID di connessione e nome del canale. Legare la firma all'ID del socket impedisce di riutilizzare un token su un'altra connessione, e le firme di presenza fissano anche l'identità del membro mostrata nella stanza.
- 02
Connessioni WebSocket autenticate.
Poiché la chiave pubblica dell'app si trova nel codice client, qualsiasi visitatore potrebbe tentare di aprire un WebSocket inattivo. Attivando le connessioni autorizzate, ogni nuovo socket deve autenticarsi tramite il tuo backend entro 30 secondi, effettuando l'accesso o iscrivendosi a un canale privato. I socket non verificati si chiudono automaticamente e non contano nella tua quota di connessioni.
- 03
Payload cifrati end-to-end.
Per aggiornamenti regolamentati o riservati, l'SDK server cifra i payload degli eventi in locale con una chiave master da 32 byte che resta sulla tua infrastruttura. Ogni canale cifrato deriva una propria chiave di decifratura: autorizzare un client a un flusso riservato non gli dà accesso a un altro, e i server intermedi vedono solo testo cifrato durante il transito.
- 04
Revoca immediata delle sessioni.
Quando un utente esce, cambia password o perde l'accesso allo spazio di lavoro, una sola chiamata server disconnette la sua identità di membro da tutte le schede del browser e i dispositivi mobili aperti. I client considerano la chiusura definitiva invece di riconnettersi in loop, e il tuo endpoint di autenticazione può rifiutare i successivi tentativi di accesso dopo la revoca della sessione.
Canali crittografati
Proteggi i payload sensibili prima che lascino il tuo server.
Configura una chiave master da 32 byte nell'SDK server per cifrare gli eventi riservati all'interno del tuo processo prima della pubblicazione. Bird instrada il contenuto cifrato ai sottoscrittori, e il tuo endpoint di autorizzazione consegna ai client browser approvati la chiave di decifratura derivata del canale. Puoi anche combinare la crittografia con la cache dell'ultimo evento, così i client appena connessi ricevono lo stato più recente come testo cifrato. Usa nomi generici per canali ed eventi, perché i metadati di instradamento non vengono cifrati.
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" },
});
Isola i flussi dei tenant e convalida lo stato sul tuo server.
L'autenticazione delle connessioni e l'autorizzazione dei canali coprono parti diverse del controllo degli accessi. Richiedere connessioni autorizzate blocca i socket anonimi, mentre i canali privati e di presenza limitano quale utente autenticato o tenant può leggere un determinato flusso. Mantieni gli aggiornamenti specifici dei clienti su canali privati verificati dal tuo endpoint di autenticazione, usa gli eventi client-to-client per segnali effimeri dell'interfaccia come gli indicatori di digitazione e instrada le azioni che modificano lo stato attraverso il tuo backend.
Vincola il traffico a una regione e isola gli ambienti per app.
Scegli una regione dedicata quando crei un'app Realtime per mantenere le connessioni WebSocket e gli eventi pubblicati vicini ai tuoi utenti, anche se la regione principale del tuo spazio di lavoro è altrove. Ogni app gira in un proprio namespace isolato con credenziali e quote separate: creando app distinte per sviluppo, staging e produzione, i broadcast di test restano fuori dai canali dei clienti reali.
Guide all'implementazione per il tuo backend.
Consulta autorizzazione dei canali per il formato della richiesta webhook e gli helper di firma dell'SDK. Leggi richiedere connessioni autorizzate per imporre l'handshake di connessione di 30 secondi, canali cifrati per configurare le chiavi master e la loro rotazione, e terminare le connessioni dei membri per implementare l'accesso degli utenti e la disconnessione remota.
Continua a sviluppare
con Realtime.
Combina l'autorizzazione dei canali con presenza in tempo reale, cache dello stato e webhook del backend usando le stesse credenziali dell'app.
Canali
Instrada broadcast pubblici, flussi privati, payload cifrati e stato in cache in base al prefisso del canale.
→Presenza
Mostra chi è online su schede e dispositivi, rileva le uscite e invia messaggi diretti ai singoli utenti.
→Webhooks
Avvia workflow nel backend quando i canali diventano attivi, i membri escono o una cache va popolata.
→Scala senza perdere il controllo.
Separate production and sandbox traffic into dedicated workspaces, scope API keys to the exact channels each service or agent needs, and track permission changes in the audit log.