ACL-ohjaus ja vähimmän oikeuden periaate
Tällä sivulla
Vähimmän oikeuden periaate sovellettuna API-rajapintoihin
Vähimmän oikeuden periaate on yksi kyberturvallisuuden vanhimmista käsitteistä: järjestelmän jokaisella komponentilla pitäisi olla pääsy vain niihin resursseihin, jotka ovat sen toiminnan kannalta ehdottoman välttämättömiä. Ajatus on intuitiivinen, kun sen tuo fyysiseen maailmaan: et anna rakennuksen yleisavainta henkilölle, joka vain kastelua aulaan sijoitettuja kasveja. Sovvellettuna xAI:n API-avaimiin tämä tarkoittaa, että jokainen avain on rajoitettava koskemaan vain niitä päätepisteitä ja malleja, joita sitä käyttävä sovellus todella tarvitsee. Jos tämä avain vuotaa, hyökkääjä perii sen oikeudet: yhteen malliin rajoitettu chat-avain aiheuttaa äärettömästi vähemmän vahinkoa kuin avain, joka avaa koko malliluettelon.
xAI toteuttaa tämän periaatteen granulaarin ACL-järjestelmän (Access Control List) avulla, jonka käymme läpi alla.
xAI:n ACL-järjestelmä
ACL-muoto on api-key:{type}:{value}. Kaksi tyyppiä koskettavat sinua päivittäisessä työssä: api-key:endpoint:{endpoint} rajoittaa käytettäviä päätepisteitä ja api-key:model:{model_id} rajoittaa käytettäviä malleja. Käytössä on myös jokerimerkki api-key:endpoint:*, joka myöntää pääsyn kaikkiin päätepisteisiin. Tämä on kätevää kehitysvaiheessa, mutta kielletty tuotannossa, juuri siksi että se kumoaa vähimmän oikeuden periaatteen hyödyn.
Yksittäin valtuutettavissa olevat päätepisteet ovat: chat (keskustelun täydennys, ylivoimaisesti yleisin), embed (upotusten luonti), image (kuvien luonti ja muokkaus), models (malliluettelon katselu), tokenize (tekstin tokenisointi), documents (dokumenttien hallinta) ja sample (otannan teko).
Katsotaanpa, miltä tämä näyttää käytännön esimerkissä. Kuvittele asiakaspalveluun tarkoitettu chatbotti, joka käyttää vain grok-4.3-mallia chat-tilassa. Sen ihanteellinen avain näyttää tältä:
{
"name": "support-chatbot-prod",
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.3"
],
"qps": 5,
"qpm": 100,
"tpm": 500000,
"expireTime": "2026-12-31T23:59:59Z"
}
Lue tämä konfiguraatio sopimuksena: avain pääsee vain chat-päätepisteeseen – ei kuvia, ei upotuksia, joten väärinkäyttö näihin tarkoituksiin on mahdotonta. Se voi käyttää vain grok-4.3-mallia, mikä estää vahingolliset tai tahalliset kutsut kalliimpiin malleihin. Se on rajoitettu 5 pyyntöön sekunnissa ja 100 pyyntöön minuutissa, ja se vanhenee ennalta määrättynä päivämääränä. Jos projektin kehittäjä yrittää lisätä kuvien luontia kertomatta siitä kenellekään, API kieltäytyy: tekninen rajoite pakottaa arkkitehtonisen päätöksen noudattamisen.
Nopeusrajoitukset: ylimääräinen turvallisuuskerros
ACL:t vastaavat kysymykseen “mitä”, nopeusrajoitukset vastaavat kysymykseen “kuinka paljon”. QPS (Queries Per Second) rajoittaa pyyntöjä sekunnissa: tämä on suojasi tahattomia piikkejä vastaan – olipa kyseessä perjantai-iltana refaktoroinnin seurauksena syntynyt ääretön silmukka tai sovellukseesi kohdistuva DDoS-hyökkäys. QPM (Queries Per Minute) tasaa liikennettä pidemmällä aikavälillä ja havaitsee väärinkäytöksiä, jotka jäisivät QPS-tutkasta huomaamatta. TPM (Tokens Per Minute) puolestaan rajoittaa kulutettujen tokenien määrää: se suojaa erittäin pitkiltä yksittäisiltä pyynnöiltä – esimerkiksi käyttäjältä, joka liittää chatbottiisi 200-sivuisen dokumentin – jotka tyhjentäisivät budjettisi minuuteissa ylittämättä koskaan sallittua pyyntömäärää.
Avainstrategia ympäristökohtaisesti
Käytännössä et määritä yhtä ainoaa avainta, vaan avainperheen, ja jokaisella ympäristöllä on oma logiikkansa. Kehitysvaiheessa käännät tuotantologian päälaelleen: laajat oikeudet, tiukat rajoitukset.
{
"name": "dev-team-alpha",
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 2,
"qpm": 30,
"tpm": 100000,
"expireTime": "2026-06-30T23:59:59Z"
}
Kehittäjät voivat tutkia kaikkea, mutta alhaiset rajoitukset estävät yllättävät laskut, jos testi menee pieleen. Esituotantoympäristössä (staging) sen sijaan replikoit tuotannon ACL-säännöt täsmälleen (api-key:endpoint:chat, api-key:model:grok-4.3, QPS 5, QPM 100, TPM 500000): tämä on ainoa tapa havaita oikeusongelmat etukäteen. Jos esituotantokoodi yrittää suorittaa kutsun, jonka tuotanto hylkää, on parempi löytää virhe nyt kuin ensimmäisenä käyttöönoton tuntina. Tuotantoavain yhdistää taas esituotannon tiukat oikeudet todelliseen liikenteeseen mitoitettuihin rajoituksiin (esimerkiksi QPS 20, QPM 600, TPM 2000000) ja ajoitettuun vanhenemiseen – "expireTime": "2027-03-31T23:59:59Z" avaimelle nimeltä prod-chatbot-v2.
Oikeuksien tarkistus ja auditointi
Nähdäksesi, mitä aktiivinen avain saa todella tehdä, kysy API:lta avaimella itsellään:
curl https://api.x.ai/v1/api-key \
-H "Authorization: Bearer $XAI_API_KEY"
Vastaus listaa voimassa olevat ACL:t, tilat api_key_blocked ja api_key_disabled, avaimen maskatun version (redacted_api_key) sekä team_id:n. Tee tavaksi verrata näitä ACL:iä säännöllisesti sovelluksen todellisiin tarpeisiin: oikeudet pyrkivät kertymään ajan myötä, eivätkä ne koskaan pienene spontaanisti. Mallien osalta päätepiste GET /auth/teams/{teamId}/models palauttaa tiimillesi saatavilla olevien mallien luettelon hintoineen – arvokasta tietoa relevanttien malli-ACL:ien määrittelyyn ja käyttämättömien kalliiden mallien karsimiseen.
Kaiken tämän vahvistamiseksi suorita avaimillesi täydellinen auditointi. Listaa jokaisen tiimin aktiiviset avaimet ja kysy sitten jokaiselta: ovatko sen ACL:t minimaalisia, ilman jokerimerkkejä tuotannossa? Ovatko sen nopeusrajoitukset kohtuullisia? Onko vanhenemispäivä asetettu? Kertooko sen nimi sovelluksen ja ympäristön – “prod-chatbot-v2” kertoo tarinan, “key-test-2” ei kerro mitään? Poista orpoavaimet ja dokumentoi tulos: tästä dokumentista tulee lähtökohta seuraavalle auditoinnille, ja näet silmänräpäyksessä, mikä on ajautunut väärään suunnan välillä.
Keskeiset asiat
- Jokaisella avaimella on oltava rajoittavat ACL:t: vain tarvittavat päätepisteet ja mallit
- Älä koskaan käytä
*-jokerimerkkiä tuotannossa - Yhdistä ACL:t todelliseen käyttöön sovitettuihin nopeusrajoituksiin (QPS, QPM, TPM)
- Luo erilliset avaimet jokaiselle ympäristölle (dev, staging, prod) ja sovellukselle – esituotannolle samat ACL:t kuin tuotannolle
- Auditoi säännöllisesti aktiivisten avainten oikeudet komennolla
GET /v1/api-key