Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Avainten kierrätys ja poistaminen

Oppitunti 4 / 14 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kierrätys: Uudista ilman keskeytyksiä
  2. Kierrätyksen suorittaminen
  3. Avaimen poistaminen
  4. Automatisoi kierrätys
  5. Keskeiset asiat

Kierrätys: Uudista ilman keskeytyksiä

Avainten kierrätys on kriittinen tietoturvakäytäntö. Se luo uuden salaisen avaimen korvaamaan vanhan poistamatta itse avainta. Vanha salainen arvo mitätöidään välittömästi ja peruuttamattomasti.

Kierrätyksen suorittaminen

Kierrätys ratkaisee ongelman, jota poistaminen ei pysty hoitamaan: salaisen arvon uudistaminen menettämättä avaimen identiteettiä. Sen käyttöoikeudet (ACL), nopeusrajoitukset ja nimi säilyvät operaation yli, joten sinun ei tarvitse määrittää mitään uudelleen – vain salainen arvo muuttuu holvissasi. Tämä tekee säännöllisestä kierrätyksestä käytännöllistä; avaimen uudelleenluonti vaatisi kaikkien asetusten määrittämistä uudelleen joka kerta.

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"

Kierrätyksen toiminta

  • Vanha salainen avain mitätöidään välittömästi – kaikki sitä käyttävät pyynnöt epäonnistuvat 401-virheellä
  • Uusi salainen avain luodaan ja palautetaan vastauksessa
  • Avaimen tunnus (apiKeyId), nimi, käyttöoikeudet ja nopeusrajoitukset pysyvät muuttumattomina
  • Uusi salainen avain näytetään vain kerran – tallenna se välittömästi

Turvallinen kierrätysprosessi

Yksi osa tätä menettelyä ansaitsee erityistä huomiota, koska se yllättää käyttäjät usein: vanha salainen arvo mitätöidään välittömästi. Ei ole olemassa armonaikaa, jolloin molemmat salaiset arvot toimisivat. Kaikki palvelut, jotka käyttävät edelleen vanhaa arvoa, epäonnistuvat sekunnin kuluttua kutsusta. Tämä määrää alla olevien kuuden vaiheen järjestyksen: valmista holvisi ennen kierrätyksen käynnistämistä, ei sen jälkeen.

  1. Valmistele infrastruktuurisi hyväksymään uusi avain (ympäristömuuttuja, holvi)
  2. Suorita kierrätys API:n kautta
  3. Päivitä salainen arvo holviisi välittömästi
  4. Ota käyttöön uudelleen palvelusi uudella avaimella
  5. Varmista, että pyynnöt onnistuvat uudella avaimella
  6. Varmista levitys komennolla GET /auth/api-keys/{apiKeyId}/propagation

Milloin kierrättää

Kolme tilannetta laukaisee kierrätyksen, ja jokaisella on eri kiireellisyys. Epäilty vuoto vaatii välitöntä kierrätystä: avaimen käyttöoikeudet omaava tiimin jäsen lähtee, lokitiedosto, joka sisältää avaimen, paljastuu julkisesti tai Git-varasto sisältää avaimen selväkielisenä. Näissä tapauksissa jokainen odotustunti on tunti altistumista, joten kierrätä ennen incidenttianalyysin suorittamista. Käytäntöön perustuva kierrätys on ennaltaehkäisevää: 30, 60 tai 90 päivän välein turvallisuusvaatimuksistasi riippuen se rajoittaa sellaisen avaimen elinkaarta, joka on saattanut vuotaa huomaamatta. Lopuksi ympäristömuutokset – kuten infrastruktuurin siirto tai tarjoajan vaihto – ovat luonteva tilaisuus aloittaa alusta puhtain avaimin sen sijaan, että vanhat avaimet siirrettäisiin kontekstiin, jota varten niitä ei ole koskaan suunniteltu.

Avaimen poistaminen

Poistaminen on pysyvää ja peruuttamatonta. Kysymys, joka sinun tulee esittää ennen poistamista, ei ole “Onko tämä avain vaarantunut?”, vaan “Tarvitsenko vielä tätä käyttöoikeusaluetta?” Jos vastaus on kyllä, tarvitset kierrätystä: se neutraloi paljastuneen salaisen arvon säilyttäen samalla määritykset. Poistaminen on perusteltua vain avaimelle, joka ei ole enää hyödyllinen – pysäytetty projekti, lähtenyt toimittaja tai käytöstä poistettu ympäristö.

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"

Poistamisen seuraukset

  • Avain ja kaikki sen parametrit poistetaan pysyvästi
  • Kaikki tätä avainta käyttävät pyynnöt epäonnistuvat välittömästi
  • Toiminto on peruuttamaton – sinun on luotava uusi avain uusilla parametreilla
  • Avaimen käyttöhistoria pysyy saatavilla analytiikassa

Kierrätys vs. poistaminen

NäkökohtaKierrätysPoistaminen
Avain on edelleen olemassaKylläEi
Uusi salainen arvo luodaanKylläEi
Käyttöoikeudet säilyvätKylläEi
Rajoitukset säilyvätKylläEi
PeruutettavissaEi (vanha salainen arvo menetetty)Ei (avain poistettu)
Tyypillinen käyttöSäännöllinen uudistaminenVanhentunut avain tai vahvistettu kompromissoituminen

Automatisoi kierrätys

Automatisoitu kierrätys on järkevää vain, jos kirjoittaminen holviin on osa samaa skriptiä ilman manuaalista väliintuloa välissä. Muuten siirrät vain riskiä: koneen generoima salainen arvo, joka kopioidaan käsin, päätyy todennäköisemmin leikepöydälle tai päätteen historiaan kuin konsolista luotu avain.

import requests
import json

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"

# Kierrätä
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")

# Tallenna holviisi (esimerkki .env-tiedostolla)
# Tuotannossa käytä Vaultia, AWS Secrets Manageria jne.
print(f"Uusi avain luotu. Päivitä holvisi.")

Ajastettu kierrätys

Integroi kierrätys CI/CD-putkeesi tai cron-tehtävään:

# Cron-esimerkki: kierrätys joka kuukauden 1. päivä klo 3.00
0 3 1 * * /opt/scripts/rotate-xai-keys.sh

Keskeiset asiat

  • POST /auth/api-keys/{apiKeyId}/rotate mitätöi vanhan salaisen arvon ja luo uuden
  • Vanhan salaisen arvon mitätöinti on välitöntä ja pysyvää
  • DELETE /auth/api-keys/{apiKeyId} poistaa avaimen peruuttamattomasti
  • Suosi kierrätystä poistamisen sijaan säilyttääksesi olemassa olevat käyttöoikeudet ja rajoitukset
  • Automatisoi kierrätys skriptillä ja salaisuuksien holvilla
  • Varmista aina levitys kierrätyksen jälkeen