Ajutised märgid WebSocketi ühenduste jaoks
Sellel lehel
Probleem: kliendi autentimine ilma võtit paljastamata
Grok API-ga hääl- või reaalaja rakenduse loomisel pead looma WebSocketi ühenduse otse brauserist või mobiilirakendusest. Liikluse suunamine läbi oma serveri tekitab viivitusi, mis rikuvad sujuva häälsuhtluse. Otseühendused aga tekitavad autentimisprobleemi: mitte kunagi ei tohi lisada oma API-võtit kliendipoolsesse koodi.
Põhjus on lihtne: iga võti, mis on sisestatud frontend’i JavaScripti, dekompileeritavasse mobiilirakendusse või levitatavasse binaarfaili, on kompromiteeritud hetkel, kui selle avaldad. Iga kasutaja saab avada brauseri arendaja tööriistad ja selle lugeda. Lahenduseks pakub xAI ajutisi märke: ajutisi märke, mida kliendid saavad kasutada ilma peakunagi nägemata.
Kuidas ajutised märgid töötavad
Arhitektuur järgib üht põhimõtet: API-võti ei lahku kunagi sinu serverist ja klient saab vaid lühiajalise märgi. Voog on lühike. Klient küsib märgi sinu taustasüsteemilt, mis kutsub POST /v1/realtime/client_secrets, kasutades sinu API-võtit. See väljakutse on ainus koht, kus võti ilmneb, ja see toimub täielikult serveripoolselt. xAI tagastab ajutise märgi koos selle aegumiskuupäevaga, mille sinu taustasüsteem edastab kliendile. Seejärel avab klient WebSocketi ühenduse aadressile wss://api.x.ai/v1/realtime, esitades selle märgi. Ühelgi hetkel ei näe brauser peakunagi; see haldab märki, mis aegub iseenesest.
Sinu taustasüsteemi loomiskutse näeb välja selline:
curl -X POST https://api.x.ai/v1/realtime/client_secrets \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expires_after": {"seconds": 600}}'
Ja vastus:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Kestuse osas on sul kolm võrdluspunkti: dokumenteeritud miinimumväärtus puudub (mõni sekund on võimalik), vaikimisi väärtus on 600 sekundit (10 minutit) ja maksimum on 3600 sekundit (1 tund).
Õige kestuse valimine
Märgi kestus peab vastama sinu kasutusjuhtumile ja see valik on tegelik turvalisusotsus. Juhuslike häälsuhtluste jaoks – küsimused-vastused, häälkäsklused, dikteerimine – piisab 300–600 sekundisest aknast: seanss lõpeb ammu enne aegumist. Pikaajaliste hääldialoogide jaoks, nagu klienditugi, intervjuu või abistatud koosolek, sea eesmärgiks 600–1800 sekundit, et vältida vestluse katkemist keset lauset. Pikaajalised töösessioonid – reaalajas transkriptsioon, pidev hääle jälgimine – võivad õigustada 1800–3600 sekundit, kuid kasuta maksimaalset kestust ettevaatlikult: see suurendab ärakasutamise akent, kui märk varastatakse.
Kuldreegel on kokkuvõtvalt selline: vali alati oma kasutusjuhtumiga ühilduv lühim võimalik kestus. Kui märk pealt kuuldakse, muudab kümne minuti pikkune aegumine potentsiaalselt tõsise intsidenti väikeseks tüütuseks.
Taustasüsteemi teostus
Siin on näide turvalisest proksist Node.js-is:
// Taustasüsteemi marsruut - ÄRA avalda kliendipoolselt
app.post("/api/realtime-token", authenticateUser, async (req, res) => {
const response = await fetch(
"https://api.x.ai/v1/realtime/client_secrets",
{
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.XAI_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
expires_after: { seconds: 600 }
})
}
);
const token = await response.json();
res.json({ token: token.value, expires_at: token.expires_at });
});
Selles näites kannavad kolm detaili kogu seadistuse turvalisust. API-võti asub serveri keskkonnamuutujas, mitte kunagi koodis. authenticateUser vahevara kontrollib kasutaja identiteeti enne märgi väljastamist – ilma selleta saaks igaüks hankida märke ja tarbida sinu kvooti sinu kulul. Ja kliendile tagastatakse ainult ajutine märk, mitte kunagi võti.
Koodiülevaadetes kerkib regulaarselt esile mõni lõks. API-võti, mis libises frontend’i „ainult prototüübi jaoks“, satub paratamatult tootmisse. Märk luuakse mugavuse mõttes süstemaatiliselt maksimaalse kestusega, kuigi kasutusjuhtum nõuab sellest vaid neljandikku. Generatsiooni lõpp-punkt jäetakse ilma autentimise kontrollita, olles avatud kõigile. Ja uuendamise käsitlemise puudumine kliendipoolsel poolel, mis tekitab seansi keskel aegumisvigu läbipaistva uuestiühenduse asemel: kuna vastus annab sulle expires_at, on sinu kliendil kõik vajalik uue märgi taotlemiseks enne tähtaega, mitte pärast seda.
Peamised punktid
- Ajutised märgid võimaldavad WebSocketi autentimist ilma sinu API-võtit paljastamata
- Lõpp-punkt:
POST /v1/realtime/client_secrets(ainult serveripoolne kutse) - Konfigureeritav kestus mõnest sekundist kuni maksimaalselt 3600 sekundini (vaikimisi: 600 s)
- Sinu taustasüsteem toimib autentimise proksina kliendi ja xAI vahel
- Vali alati oma kasutusega ühilduv lühim kestus