Ephemér tokenek WebSocket-kapcsolatokhoz
Ezen az oldalon
A probléma: kliens hitelesítése a kulcs feltárása nélkül
Amikor hangalapú vagy valós idejű alkalmazást építesz a Grok API-val, közvetlen WebSocket-kapcsolatot kell létesítened a böngészőből vagy a mobilkliensből. Ha a forgalmat a szervereden keresztül irányítod, az olyan késleltetést okoz, amely megszakítja a folyékony hangbeszélgetést. A közvetlen kapcsolatok azonban hitelesítési problémát vetnek fel: soha nem szerepeltetheted az API-kulcsodat a kliensoldali kódban.
Az ok egyszerű: bármely kulcs, amelyet beágyazol a frontend JavaScriptbe, egy visszafejthető mobilalkalmazásba vagy egy terjesztett bináris fájlba, abban a pillanatban kompromittálódik, hogy közzéteszed. Bármely felhasználó megnyithatja a böngésző fejlesztői eszközeit, és elolvashatja azt. Ennek megoldására az xAI ephemér tokeneket kínál: ideiglenes tokeneket, amelyeket a kliensek használhatnak anélkül, hogy valaha is látnák a mesterkulcsot.
Hogyan működnek az ephemér tokenek
Az architektúra egyetlen elvet követ: az API-kulcs soha nem hagyja el a szerveredet, és a kliens csak egy rövid élettartamú tokent kap. A folyamat rövid. A kliens tokent kér a backendedtől, amely meghívja a POST /v1/realtime/client_secrets végpontot az API-kulcsoddal. Ez a hívás az egyetlen hely, ahol a kulcs megjelenik, és ez teljes egészében szerveroldalon történik. Az xAI visszaad egy ephemér tokent a lejárati dátumával együtt, amelyet a backended továbbít a kliensnek. Ezután a kliens megnyitja a WebSocket-kapcsolatot a wss://api.x.ai/v1/realtime címre, bemutatva ezt a tokent. A böngésző soha, egyetlen pillanatig sem látja a mesterkulcsot; csak egy olyan tokent kezel, amely magától lejár.
A backendedről indított létrehozási hívás így néz ki:
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}}'
És a válasz:
{
"value": "Bearer eyJhbGciOiJSUzI1NiIs...",
"expires_at": 1712001200
}
Az időtartamot illetően három irányadó érték van: nincs dokumentált alsó korlát (néhány másodperc is lehetséges), az alapértelmezett érték 600 másodperc (10 perc), a maximum pedig 3600 másodperc (1 óra).
A megfelelő időtartam kiválasztása
A token élettartamának illeszkednie kell a használati esetedhez, és ez a választás valós biztonsági döntés. Szórványos hanginterakciókhoz – kérdések és válaszok, hangparancsok, diktálás – egy 300–600 másodperces ablak bőségesen elegendő: a munkamenet jóval a lejárat előtt véget ér. Tartós hangbeszélgetésekhez, mint például az ügyfélszolgálat, egy interjú vagy egy támogatott megbeszélés, célozz meg 600–1800 másodpercet, hogy elkerüld a beszélgetés közbeni megszakadást. Hosszabb munkamenetekhez – valós idejű átírás, folyamatos hangfigyelés – indokolt lehet az 1800–3600 másodperc, de a maximális időtartammal óvatosan bánj: ez növeli a kiaknázási ablakot, ha a tokent ellopják.
Az aranyszabály így foglalható össze: mindig a használati esetedhez compatible legrövidebb időtartamot válaszd. Ha egy tokent elfognak, egy tízperces lejárat egy potenciálisan súlyos incidensből apró kellemetlenséget csinál.
Backend megvalósítás
Íme egy példa egy biztonságos proxyra Node.js-ben:
// Backend útvonal - SOHA ne tedd elérhetővé kliensoldalon
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 });
});
Ebben a példában három részlet hordozza a teljes beállítás biztonságát. Az API-kulcs egy szerveroldali környezeti változóban él, soha nem a kódban. Az authenticateUser middleware ellenőrzi a felhasználó személyazonosságát, mielőtt tokent állítana ki – enélkül bárki szerezhetne tokeneket, és a te költségedre fogyasztaná a kvótádat. És csak az ephemér tokent, soha nem a kulcsot adjuk vissza a kliensnek.
Néhány buktató rendszeresen felbukkan a kódreview-k során. Az API-kulcs, amelyet „csak a prototípus kedvéért“ csúsztattak be a frontendbe, invariably productionbe kerül. A token, amelyet kényelemből szisztematikusan maximális időtartammal hoznak létre, holott a használati eset annak negyedét igényelné. A generáló végpont, amelyet hitelesítés-ellenőrzés nélkül hagytak, mindenki számára nyitva. És a megújítás kezelésének hiánya a kliensoldalon, ami lejáratási hibákat okoz a munkamenet közepén ahelyett, hogy átlátszóan újracsatlakozna: mivel a válasz tartalmazza az expires_at értéket, a kliensednek minden eszköze megvan arra, hogy új tokent kérjen a határidő előtt, nem pedig után.
Főbb megállapítások
- Az ephemér tokenek lehetővé teszik a WebSocket-hitelesítést az API-kulcsod feltárása nélkül
- Végpont:
POST /v1/realtime/client_secrets(kizárólag szerveroldali hívás) - Konfigurálható időtartam: néhány másodperctől maximum 3600 másodpercig (alapértelmezett: 600s)
- A backended hitelesítési proxyként működik a kliens és az xAI között
- Mindig a használatodhoz compatible legrövidebb időtartamot válaszd