Rotirea și ștergerea cheilor
Pe această pagină
Rotire: Reînnoire fără întreruperi
Rotirea cheilor este o practică esențială de securitate. Aceasta generează o nouă cheie secretă pentru a o înlocui pe cea veche, fără a șterge cheia în sine. Vechiul secret este invalidat imediat și definitiv.
Efectuarea unei rotiri
Rotirea rezolvă o problemă pe care ștergerea nu o poate aborda: reînnoirea secretului fără a pierde identitatea cheii. Listele sale de control al accesului (ACL), limitele de rată și numele supraviețuiesc operațiunii, astfel încât nu trebuie să reconfigurați nimic—doar secretul se schimbă în seiful dumneavoastră. Acest lucru face ca rotirea regulată să fie practică; recrearea unei chei ar necesita reconfigurarea tuturor elementelor de fiecare dată.
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"
Comportamentul rotirii
- Vechiul secret este invalidat imediat—orice cerere care îl utilizează va eșua cu o eroare 401
- Un nou secret este generat și returnat în răspuns
- ID-ul cheii (
apiKeyId), numele, ACL-urile și limitele de rată rămân neschimbate - Noul secret este afișat o singură dată—stocați-l imediat
Proces sigur de rotire
O parte a acestei proceduri merită subliniată deoarece îi surprinde adesea pe utilizatori: vechiul secret este invalidat imediat. Nu există o perioadă de grație în care ambele secrete să funcționeze. Orice serviciu care utilizează încă vechea valoare va eșua la o secundă după apel. Acest lucru dictează ordinea celor șase pași de mai jos: pregătiți seiful înainte de a declanșa rotirea, nu după.
- Pregătiți infrastructura pentru a accepta o nouă cheie (variabilă de mediu, seif)
- Efectuați rotirea prin API
- Actualizați secretul în seif imediat
- Redeploiați serviciile cu noua cheie
- Verificați dacă cererile reușesc cu noua cheie
- Verificați propagarea prin
GET /auth/api-keys/{apiKeyId}/propagation
Când să rotiți
Trei situații declanșează rotirea, fiecare având o urgență diferită. Suspectarea unei scurgeri necesită o rotire imediată: un membru al echipei cu acces la cheie pleacă, un jurnal care conține o cheie este expus public sau un repository Git conține o cheie în text clar. În aceste cazuri, fiecare oră de așteptare reprezintă o oră de expunere, așa că rotiți înainte de a finaliza analiza incidentului. Rotirea bazată pe politici este preventivă: la fiecare 30, 60 sau 90 de zile, în funcție de cerințele dumneavoastră de securitate, aceasta limitează durata de viață a unei chei care ar fi putut fi compromisă neobservat. În final, schimbările de mediu—migrarea infrastructurii sau schimbarea furnizorilor—reprezintă o oportunitate naturală de a începe proaspăt cu chei curate, în loc să transportați chei vechi într-un context pentru care nu au fost concepute.
Ștergerea unei chei
Ștergerea este permanentă și irevocabilă. Întrebarea pe care trebuie să v-o puneți înainte de a șterge nu este „Este această cheie compromisă?“, ci „Mai am nevoie de acest scop de acces?“. Dacă răspunsul este da, aveți nevoie de rotire: aceasta neutralizează secretul expus păstrând în același timp configurația. Ștergerea este justificată doar pentru o cheie care nu mai este utilă—un proiect oprit, un furnizor care a plecat sau un mediu dezafectat.
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"
Consecințele ștergerii
- Cheia și toți parametrii săi sunt șterși definitiv
- Toate cererile care utilizează această cheie vor eșua imediat
- Acțiunea este ireversibilă—va trebui să creați o nouă cheie cu noi parametri
- Istoricul de utilizare al cheii rămâne disponibil în analitice
Rotire vs. ștergere
| Aspect | Rotire | Ștergere |
|---|---|---|
| Cheia mai există | Da | Nu |
| Se generează un nou secret | Da | Nu |
| ACL-urile sunt păstrate | Da | Nu |
| Limitele sunt păstrate | Da | Nu |
| Reversibil | Nu (secretul vechi este pierdut) | Nu (cheia este ștearsă) |
| Utilizare tipică | Reînnoire regulată | Cheie învechită sau compromis confirmat |
Automatizarea rotirii
Rotirea automatizată are sens doar dacă scrierea în seif face parte din același script, fără intervenție manuală între ele. În caz contrar, mutați doar riscul: un secret generat de mașinărie, copiat manual, este mai probabil să ajungă în clipboard sau în istoricul terminalului decât o cheie creată din consolă.
import requests
import json
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"
# Rotire
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")
# Stocare în seif (exemplu cu un fișier .env)
# În producție, utilizați Vault, AWS Secrets Manager, etc.
print(f"New key generated. Update your vault.")
Rotire programată
Integrați rotirea în pipeline-ul CI/CD sau într-un job cron:
# Exemplu Cron: rotire în prima zi a fiecărei luni la ora 3:00
0 3 1 * * /opt/scripts/rotate-xai-keys.sh
Puncte cheie
POST /auth/api-keys/{apiKeyId}/rotateinvalidează vechiul secret și generează unul nou- Invalidarea vechiului secret este imediată și permanentă
DELETE /auth/api-keys/{apiKeyId}șterge cheia ireversibil- Preferați rotirea în detrimentul ștergerii pentru a menține ACL-urile și limitele existente
- Automatizați rotirea cu un script și un seif de secrete
- Verificați întotdeauna propagarea după o rotire