Rotacja i usuwanie kluczy
Na tej stronie
Rotacja: Odnowienie bez przerw
Rotacja kluczy to kluczowa praktyka bezpieczeństwa. Generuje ona nowy klucz tajny, który zastępuje stary, bez usuwania samego klucza. Stary sekret zostaje natychmiast i trwale unieważniony.
Przeprowadzanie rotacji
Rotacja rozwiązuje problem, którego nie da się rozwiązać przez usunięcie: odnowienie sekretu bez utraty tożsamości klucza. Jego listy kontroli dostępu (ACL), limity szybkości i nazwa przetrwają tę operację, więc nie musisz niczego konfigurować ponownie – w Twoim magazynie zmienia się tylko sekret. Dzięki temu regularna rotacja staje się praktyczna; ręczne odtworzenie klucza wymagałoby za każdym razem ponownej konfiguracji wszystkiego.
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"
Zachowanie podczas rotacji
- Stary klucz tajny zostaje natychmiast unieważniony – każde żądanie używające go zakończy się błędem 401
- Generowany jest nowy klucz tajny i zwracany w odpowiedzi
- ID klucza (
apiKeyId), nazwa, listy ACL i limity szybkości pozostają niezmienione - Nowy klucz tajny jest wyświetlany tylko raz – zapisz go niezwłocznie
Bezpieczny proces rotacji
Jeden element tej procedury zasługuje na szczególne podkreślenie, ponieważ często zaskakuje użytkowników: stary sekret jest unieważniany natychmiast. Nie ma okresu karencji, w którym oba sekrety działałyby jednocześnie. Wszystkie usługi nadal używające starej wartości przestaną działać w ułamku sekundy po wywołaniu operacji. Dyktuje to kolejność sześciu poniższych kroków: przygotuj swój magazyn przed uruchomieniem rotacji, a nie po niej.
- Przygotuj swoją infrastrukturę do przyjęcia nowego klucza (zmienna środowiskowa, magazyn)
- Przeprowadź rotację przez API
- Zaktualizuj sekret w swoim magazynie natychmiast
- Wdróż ponownie swoje usługi z nowym kluczem
- Zweryfikuj, czy żądania kończą się sukcesem przy użyciu nowego klucza
- Zweryfikuj propagację poprzez
GET /auth/api-keys/{apiKeyId}/propagation
Kiedy przeprowadzać rotację
Trzy sytuacje wymagają rotacji, każda z inną pilnością. Podejrzenie wycieku wymaga natychmiastowej rotacji: członek zespołu mający dostęp do klucza odchodzi, log zawierający klucz zostaje publicznie ujawniony lub repozytorium Git zawiera klucz w postaci zwykłego tekstu. W takich przypadkach każda godzina oczekiwania to godzina ekspozycji, więc przeprowadź rotację przed zakończeniem analizy incydentu. Rotacja oparta na polityce ma charakter prewencyjny: co 30, 60 lub 90 dni, w zależności od wymagań bezpieczeństwa, ogranicza czas życia klucza, który mógł wyciec niezauważony. Wreszcie, zmiany w środowisku – migracja infrastruktury lub zmiana dostawcy – są naturalną okazją do rozpoczęcia pracy od nowa z czystymi kluczami, zamiast przenoszenia starych do kontekstu, dla którego nie zostały zaprojektowane.
Usuwanie klucza
Usunięcie jest trwałe i nieodwracalne. Pytanie, które należy sobie zadać przed usunięciem, nie brzmi: „Czy ten klucz został skompromitowany?“, ale: „Czy nadal potrzebuję tego zakresu dostępu?“. Jeśli odpowiedź brzmi „tak“, potrzebujesz rotacji: neutralizuje ona ujawniony sekret, zachowując jednocześnie konfigurację. Usunięcie jest uzasadnione tylko w przypadku klucza, który nie jest już potrzebny – zakończony projekt, były dostawca lub wycofane środowisko.
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"
Konsekwencje usunięcia
- Klucz i wszystkie jego parametry zostają trwale usunięte
- Wszystkie żądania używające tego klucza natychmiast zakończą się niepowodzeniem
- Akcja jest nieodwracalna – będziesz musiał utworzyć nowy klucz z nowymi parametrami
- Historia użycia klucza pozostaje dostępna w analityce
Rotacja kontra usunięcie
| Aspekt | Rotacja | Usunięcie |
|---|---|---|
| Klucz nadal istnieje | Tak | Nie |
| Wygenerowano nowy sekret | Tak | Nie |
| Listy ACL zachowane | Tak | Nie |
| Limity zachowane | Tak | Nie |
| Odwracalność | Nie (stary sekret utracony) | Nie (klucz usunięty) |
| Typowe zastosowanie | Regularne odnawianie | Przestarzały klucz lub potwierdzony kompromis |
Automatyzacja rotacji
Automatyzacja rotacji ma sens tylko wtedy, gdy zapis do magazynu jest częścią tego samego skryptu, bez żadnej ręcznej interwencji pomiędzy tymi krokami. W przeciwnym razie jedynie przenosisz ryzyko: sekret wygenerowany maszynowo i kopiowany ręcznie częściej trafi do schowka lub historii terminala niż klucz utworzony z konsoli.
import requests
import json
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"
# Rotacja
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")
# Zapisz w swoim magazynie (przykład z plikiem .env)
# W środowisku produkcyjnym użyj Vault, AWS Secrets Manager itp.
print(f"Wygenerowano nowy klucz. Zaktualizuj swój magazyn.")
Zaplanowana rotacja
Zintegruj rotację ze swoim potokiem CI/CD lub zadaniem cron:
# Przykład Cron: rotacja 1. dnia każdego miesiąca o 3:00
0 3 1 * * /opt/scripts/rotate-xai-keys.sh
Kluczowe wnioski
POST /auth/api-keys/{apiKeyId}/rotateunieważnia stary sekret i generuje nowy- Unieważnienie starego sekretu jest natychmiastowe i trwałe
DELETE /auth/api-keys/{apiKeyId}usuwa klucz nieodwracalnie- Preferuj rotację zamiast usuwania, aby zachować istniejące listy ACL i limity
- Automatyzuj rotację za pomocą skryptu i magazynu sekretów
- Zawsze weryfikuj propagację po przeprowadzeniu rotacji