Kulcsforgatás és életciklus
Ezen az oldalon
Miért elengedhetetlen a kulcsforgatás
A képzések során gyakran hangzik el a kifogás: „Soha nem szivárgott ki a kulcsom, miért cseréljem le?“ A válasz egyetlen szóban összefoglalható: bizonytalanság. Soha nem bizonyítható biztosan, hogy egy kulcs nem került illetéktelen kezekbe – legyen szó egy szerveren felejtett bőbeszédű naplófájlról, egy támogatási jegyben megosztott képernyőmentésről vagy egy fél éve feltört fejlesztői munkállomásról. A rendszeres forgatás ezt a bizonytalanságot korlátozott kockázattá alakítja: még ha másolat is készült a kulcsodról a tudtod nélkül, az a következő forgatáskor érvénytelenné válik. Pontosan ezt az érvelést alkalmazzák a SOC 2 auditorok is; dokumentált forgatási szabályzatot várnak el. Ezt nevezzük az időbeli támadási felület csökkentésének: minél tovább él egy kulcs, annál tágabb az ablak egy csendes kompromittálódás kiaknázására.
Az xAI Management API-ja úgy lett kialakítva, hogy ezt a gyakorlatot fájdalommentessé tegye: dedikált végpontot biztosít, amely lehetővé teszi a kulcs átfordítását a konfigurációk átírása nélkül.
Forgatás a Management API-n keresztül
A forgatási végpont egyszerű:
POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate
Mielőtt használnád, győződj meg róla, hogy érted, mit tesz ez a hívás: új titkos kulcsot generál a meglévő azonosítóhoz, és véglegesen érvényteleníti a régit, miközben megőrzi a kulcshoz rendelt ACL-eket, sebességkorlátokat és konfigurációkat. Ami első alkalommal meglepi a csapatokat, az az, hogy a változás azonnali és visszafordíthatatlan. Ha a production backended éppen ezt a kulcsot használja, amikor elindítod a forgatást, néhány másodpercen belül hitelesítési hibákat kezd kapni. Nincs türelmi idő, nincs lehetőség a visszavonásra.
Éppen ezért production környezetben általában egy kétlépéses eljárást részesítesz előnyben a kiesés elkerülése érdekében. Először hozz létre egy új kulcsot a POST /auth/teams/{teamId}/api-keys végponton, pontosan ugyanazokkal a jogosultságokkal, mint a réginek. Ezután ellenőrizd a terjedését a GET /auth/api-keys/{newKeyId}/propagation hívással – egy frissen létrehozott kulcs nem válik azonnal ismertté az egész infrastruktúrában, és a túl korai telepítés zavaros hibákhoz vezet. Következő lépésként telepítsd az új kulcsot a backendjeidre, és teszteld, hogy a hívások ténylegesen működnek-e vele, nemcsak azt, hogy a telepítés hibamentesen lezárult. Csak ezen megerősítés után tiltsd le a régi kulcsot, vagy hagyd, hogy elérje a lejáratát, mielőtt véglegesen törlöd a DELETE /auth/api-keys/{oldKeyId} végponttal.
Ez az „új kulcs, majd törlés“ megközelítés egy átfedési időszakot biztosít, ahol mindkét kulcs egyszerre létezik: ha az egyik szerveren meghiúsul a telepítés, semmi sem áll le. A helybeni forgatás továbbra is elérhető, ha meg szeretnéd tartani ugyanazt a kulcsazonosítót:
curl -X POST \
"https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Ebben az esetben tervezd meg a backendjeid azonnali frissítését, mivel a régi kulcs a hívás befejeződésének pillanatában megszűnik.
A kulcs teljes életciklusa
Egy jól kezelt kulcs története négy felvonásból áll. Létrehozáskor, a POST /auth/teams/{teamId}/api-keys végponton keresztül, meghatározod a nevét, az ACL-jeit, és – ezt a szokást érdemes meggyökereztetni – a lejáratási dátumát:
{
"name": "prod-chat-service",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"expireTime": "2026-12-31T23:59:59Z"
}
Egy expireTime nélküli kulcs olyan kulcs, amely örökké élni fog, ha senki nem gondol rá; egy lejárati dátummal rendelkező kulcs viszont arra kényszeríti a csapatodat, hogy egy fix dátumon feltegye a megújítás kérdését. Ezt követi a monitorozás: a GET /v1/api-key lekérdezés megmutatja a kulcs státuszát (api_key_blocked, api_key_disabled), az xAI konzol pedig feltárja a használatot és az anomáliákat. Az életciklus közbeni módosításokhoz – átnevezés, ACL-ek módosítása, sebességkorlátok szigorítása, lejárat kitolása – használd a PUT https://management-api.x.ai/auth/api-keys/{api_key_id} végpontot. Végül a törlés, DELETE /auth/api-keys/{apiKeyId}, végleges és visszafordíthatatlan: bármely alkalmazás, amely ezt a kulcsot használja, azonnal leáll. Törlés előtt győződj meg róla, hogy nincs elfelejtett szolgáltatás – egy havi cron job, egy riportoló szkript –, amely még mindig függ tőle.
Melyik forgatási stratégiát válaszd?
A megfelelő gyakoriság a környezeted érzékenységétől függ. Havi forgatás kötelező a rendkívül érzékeny kontextusokban, mint például a pénzügy vagy az egészségügy, ahol a kitettségi ablaknak minimálisnak kell maradnia. Negyedéves forgatás illik a szabványos professzionális környezetekhez: elég gyakori a hatékonysághoz, de elég ritka ahhoz, hogy ne terhelje túl a csapatokat. Az éves forgatás, meghatározott lejáratási dátummal párosítva, az elfogadható minimum – ez alatt a forgatási szabályzatod valójában nem is szabályzat. Minden esetben a ütemezett szkripttel végzett automatizálás megóv attól, hogy egy rendszergazda memóriájától függj.
Az eseményvezérelt forgatás kiegészíti ezt az ütemezést, amelyet nem dátum, hanem körülmények váltanak ki. Leggyakrabban egy olyan alkalmazott távozása esetén indítod el, aki hozzáféréssel rendelkezett a kulcsokhoz: még ha baráti is a válás, az általa ismert kulcsot még aznap forgatni kell – ez biztonsági higiéniai szabály, nem a bizalmatlanság jele. Ugyanezt tedd gyanított kompromittálódás, infrastrukturális biztonsági incidens esetén, vagy ha változik egy olyan szállító, aki hozzáféréssel rendelkezett a rendszereidhez.
Húsz perc a leltárod feletti uralom visszaszerzéséhez
A kulcsaid valós állapotának felfedezésére a legjobb időpont nem az audit napja. Ezért most listázd ki az összes kulcsodat a GET /auth/teams/{teamId}/api-keys végponttal, és azonosítsd azokat, amelyeknek nincs lejáratuk, hogy hozzáadj egy expireTime értéket. Mindegyiknél tedd fel magadnak a kérdést, hogy az ACL-jei megfelelnek-e az azt használó alkalmazás által megkövetelt szigorú minimumnak; egy prototípus számára létrehozott és productionbe újrafelhasznált kulcs szinte mindig túl sok jogosultságot hordoz.
Ezután töröld a nem használt kulcsokat, mert minden aktív kulcs potenciális támadási vektor, és egy kulcs, amelyre senki nem emlékszik, a legrosszabb közülük: senki nem veszi észre a rendellenes használatát. Zárásként dokumentáld, ki fér hozzá melyik kulcshoz és miért. Ez a dokumentum, inkább mint maguk a kulcsok, az, amit a következő auditon előveszel majd.
Főbb megállapítások
- A
POST /auth/api-keys/{id}/rotatevégpont véglegesen érvényteleníti a régi kulcsot, türelmi idő nélkül - Production környezetben előnyben részesítsd az új kulcs létrehozását, majd a régi törlését a kiesés elkerülése érdekében
- Mindig állíts be lejáratási dátumot a kulcsaidhoz
- Automatizáld a forgatást egy ütemezett szkripttel (havi, negyedéves vagy éves gyakorisággal az érzékenységtől függően)
- Indíts azonnali forgatást bármilyen személyi változás vagy biztonsági incidens esetén