Rotace a mazání klíčů
Na této stránce
Rotace: Obnova bez výpadku
Rotace klíčů je zásadní bezpečnostní praxe. Vygeneruje nový tajný klíč, který nahradí ten starý, aniž by došlo ke smazání samotného klíče. Starý tajný klíč je okamžitě a trvale zneplatněn.
Provedení rotace
Rotace řeší problém, který mazání nezvládne: obnoví tajný klíč bez ztráty identity klíče. Jeho ACL, limity rychlosti a název operaci přežijí, takže nemusíš nic překonfigurovávat – v trezoru se změní pouze tajný klíč. Díky tomu je pravidelná rotace praktická; opětovné vytvoření klíče by vyžadovalo pokaždé znovu konfigurovat vše.
POST /auth/api-keys/{apiKeyId}/rotate
curl -X POST "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/rotate" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Chování při rotaci
- Starý tajný klíč je okamžitě zneplatněn – jakékoli požadavky s jeho použitím selžou s chybou 401
- Je vygenerován nový tajný klíč a vrácen v odpovědi
- ID klíče (
apiKeyId), název, ACL a limity rychlosti zůstávají nezměněny - Nový tajný klíč se zobrazí pouze jednou – okamžitě si ho ulož
Bezpečný proces rotace
Jedna část tohoto postupu si zaslouží zdůraznění, protože uživatele často překvapí: starý tajný klíč je zneplatněn okamžitě. Neexistuje žádná lhůta, během které by fungovaly oba tajné klíče. Jakékoli služby, které stále používají starou hodnotu, selžou vteřinu po provedení volání. To určuje pořadí šesti níže uvedených kroků: připrav si trezor před spuštěním rotace, ne až po ní.
- Připrav svou infrastrukturu na přijetí nového klíče (proměnná prostředí, trezor)
- Proveď rotaci prostřednictvím API
- Okamžitě aktualizuj tajný klíč ve svém trezoru
- Znovu nasadit své služby s novým klíčem
- Ověř, že požadavky s novým klíčem úspěšně procházejí
- Ověř propagaci pomocí
GET /auth/api-keys/{apiKeyId}/propagation
Kdy rotovat
Rotaci spouštějí tři situace, každá s jinou naléhavostí. Podezření na únik vyžaduje okamžitou rotaci: když tým opustí člen s přístupem ke klíči, když je veřejně vystaven log obsahující klíč, nebo když Git repozitář obsahuje klíč v čistém textu. V těchto případech je každá hodina čekání hodinou expozice, proto proveď rotaci ještě před dokončením analýzy incidentu. Rotace založená na zásadách je preventivní: každých 30, 60 nebo 90 dní, v závislosti na tvých bezpečnostních požadavcích, omezuje životnost klíče, který mohl uniknout bez povšimnutí. Nakonec změny prostředí – migrace infrastruktury nebo přepnutí poskytovatele – jsou přirozenou příležitostí začít znovu s čistými klíči, místo abys staré přenášel do kontextu, pro který nebyly určeny.
Smazání klíče
Smazání je trvalé a nevratné. Otázka, kterou si musíš položit před smazáním, nezní „Je tento klíč kompromitován?“, ale „Stále potřebuji tento rozsah přístupu?“ Pokud je odpověď ano, potřebuješ rotaci: ta neutralizuje odhalený tajný klíč při zachování konfigurace. Smazání je oprávněné pouze u klíče, který již není užitečný – ukončený projekt, odešlý dodavatel nebo vyřazené prostředí.
DELETE /auth/api-keys/{apiKeyId}
curl -X DELETE "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Důsledky smazání
- Klíč a všechny jeho parametry jsou trvale smazány
- Všechny požadavky používající tento klíč okamžitě selžou
- Akce je nevratná – budeš muset vytvořit nový klíč s novými parametry
- Historie využití klíče zůstává dostupná v analytice
Rotace versus smazání
| Aspekt | Rotace | Smazání |
|---|---|---|
| Klíč stále existuje | Ano | Ne |
| Vygenerován nový tajný klíč | Ano | Ne |
| ACL zachována | Ano | Ne |
| Limity zachovány | Ano | Ne |
| Vratné | Ne (starý tajný klíč ztracen) | Ne (klíč smazán) |
| Typické použití | Pravidelná obnova | Zastaralý klíč nebo potvrzený kompromis |
Automatizace rotace
Automatizovaná rotace dává smysl pouze tehdy, pokud je zápis do trezoru součástí stejného skriptu bez jakéhokoli manuálního zásahu mezi tím. Jinak pouze přesuneš riziko: strojově vygenerovaný tajný klíč zkopírovaný ručně má větší šanci skončit ve schránce nebo historii terminálu než klíč vytvořený z konzole.
import requests
import json
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"
# Rotate
response = requests.post(
f"{MANAGEMENT_API}/auth/api-keys/{KEY_ID}/rotate",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
new_key = response.json()
new_secret = new_key.get("secret")
# Store in your vault (example with a .env file)
# In production, use Vault, AWS Secrets Manager, etc.
print(f"New key generated. Update your vault.")
Plánovaná rotace
Integruj rotaci do svého CI/CD pipeline nebo cron jobu:
# Cron example: rotation on the 1st of each month at 3 AM
0 3 1 * * /opt/scripts/rotate-xai-keys.sh
Klíčové poznatky
POST /auth/api-keys/{apiKeyId}/rotatezneplatní starý tajný klíč a vygeneruje nový- Zneplatnění starého tajného klíče je okamžité a trvalé
DELETE /auth/api-keys/{apiKeyId}nevratně smaže klíč- Upřednostňuj rotaci před smazáním, abys zachoval stávající ACL a limity
- Automatizuj rotaci pomocí skriptu a trezoru tajných klíčů
- Po rotaci vždy ověř propagaci