GitHub Actions AWS: poista pitkäikäiset avaimet OIDC:llä

GitHub Actions voi hankkia AWS-roolin väliaikaiset tunnukset OIDC:llä ilman GitHub-secreteihin tallennettuja pitkäikäisiä access key -tunnuksia. Lisää GitHubin OIDC-tarjoaja AWS IAM:iin, luo julkaisulle rooli ja anna sitä käyttävälle jobille id-token: write -oikeus. aws-actions/configure-aws-credentials pyytää ajon aikana tunnisteen ja vaihtaa sen roolin tunnuksiksi.

Rajaa roolin luottamus täsmällisellä aud- ja sub-ehdolla ennen kuin annat sille julkaisuun tarvittavat oikeudet. AWS IAM:n GitHub-roolin ohje erottaa luottamuskäytännön, joka määrää kuka voi ottaa roolin käyttöön, käyttöoikeuskäytännöstä, joka määrää mitä roolilla voi tehdä. Workflown käynnistysrajaus ja IAM:n luottamusehto täydentävät toisiaan: kumpikin on määritettävä tarkoitettua julkaisua varten.

Luo tarjoaja ja rajaa roolin luottamus

Lisää AWS IAM:iin OIDC-identiteetintarjoaja osoitteella https://token.actions.githubusercontent.com. Käytä yleisöarvoa sts.amazonaws.com, kun tunnukset haetaan esimerkin AWS-toiminnolla. Luo sen jälkeen rooli, jonka luottamuskäytännön Principal viittaa tämän tarjoajan ARN:ään ja Action on sts:AssumeRoleWithWebIdentity. Rooli tarvitsee erillisen käyttöoikeuskäytännön vasta silloin, kun job tekee identiteettitarkistuksen lisäksi julkaisuun kuuluvia AWS-toimintoja.

Seuraava ehdollinen esimerkki sallii yhden repositorion main-haaran. Tilinumero sekä omistajan ja repositorion nimet ja numerotunnisteet ovat esimerkkiarvoja; vaihda ne oman tilisi ja repositoriosi arvoihin. Esimerkki käyttää muuttumatonta sub-muotoa, joten tarkista oman repositoriosi muoto ennen käytännön tallentamista.

{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Federated":"arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"},"Action":"sts:AssumeRoleWithWebIdentity","Condition":{"StringEquals":{"token.actions.githubusercontent.com:aud":"sts.amazonaws.com","token.actions.githubusercontent.com:sub":"repo:esimerkki@12345/sovellus@67890:ref:refs/heads/main"}}}]}

aud kertoo, mille vastaanottajalle OIDC-tunniste on tarkoitettu. Tässä sen on vastattava AWS STS:n yleisöarvoa. sub yksilöi hyväksyttävän GitHub-työn lähteen, ja StringEquals vaatii koko arvon täsmällistä osumaa. Jos vaihdat sub-arvon organisaation tai repositorion kattavaan jokerimerkkiin, samalla roolilla voi kirjautua myös muita töitä kuin tarkoitettu julkaisu. AWS estää kokonaan puuttuvan tai pelkän jokerimerkin sisältävän sub-ehdon, mutta sallittu laaja ehto voi silti antaa liikaa pääsyä.

Anna tunnisteoikeus vain julkaisevalle jobille

Tallenna seuraava ehdollinen esimerkki .github/workflows-hakemistoon YAML-tiedostona. Sisältö on YAML:n hyväksymässä tiiviissä JSON-muodossa: main-haaran push käynnistää jobin, joka ottaa roolin käyttöön ja näyttää saadun AWS-identiteetin. Vaihda roolin ARN ja alue oman ympäristösi mukaisiksi. Esimerkki ei vielä siirrä sovellusta tai tiedostoa AWS:ään, joten lisää varsinainen julkaisukomento identiteettitarkistuksen jälkeen.

{"name":"AWS OIDC","on":{"push":{"branches":["main"]}},"jobs":{"verify":{"runs-on":"ubuntu-latest","permissions":{"id-token":"write"},"steps":[{"uses":"aws-actions/[email protected]","with":{"aws-region":"eu-north-1","role-to-assume":"arn:aws:iam::123456789012:role/github-deploy"}},{"run":"aws sts get-caller-identity"}]}}}

id-token: write on jobin oikeus pyytää GitHubilta OIDC-tunniste; se ei itsessään anna oikeutta AWS-resursseihin. Toiminto tarvitsee esimerkissä roolin ARN:n ja AWS-alueen, mutta sille ei anneta aws-access-key-id- eikä aws-secret-access-key-syötettä. Oikeuksien sijoittaminen jobille pitää tunnisteen pyytämisen erillään saman workflown mahdollisista muista töistä. Jos lisäät julkaisuun esimerkiksi lähdekoodin noudon, määritä sen tarvitsema GitHub-oikeus erikseen.

Sovita sub haaran tai ympäristön muotoon

GitHubin OIDC-viitteen mukaan 15. heinäkuuta 2026 jälkeen luoduissa github.com-repositorioissa oletusarvoinen sub sisältää omistajan ja repositorion pysyvät numerotunnisteet. Tätä vanhemmat repositoriot säilyttävät nimiin perustuvan oletusmuodon, ellei muuttumatonta muotoa ole otettu käyttöön. Myös repositorion uudelleennimeäminen tai siirto voi siirtää sen muuttumattomaan muotoon. GitHub Enterprise Server ei kuulu tähän käyttöönottoon.

Ilman ympäristöä main-haaran sub päättyy osaan :ref:refs/heads/main. Jos jobille asetetaan GitHub-ympäristö, sub sisältää sen sijaan esimerkiksi päätteen :environment:production; haaranimi ei silloin ole samassa oletusarvoisessa sub-arvossa. Muuta luottamuskäytännön arvo vastaamaan jobin käyttämää muotoa ja ympäristön nimeä täsmälleen. Ympäristölle kannattaa samalla asettaa sallitut julkaisuhaarat ja tarvittavat hyväksyntäsäännöt, koska pelkkä ympäristön nimi luottamusehdossa ei rajaa haaraa.

Älä päättele sub-arvoa vain workflown push-rivistä. Ympäristö, pull request -tapahtuma ja repositorion tunnisteformaatti vaikuttavat siihen, mikä arvo AWS:lle toimitetaan. Täsmällinen mutta vääränmuotoinen ehto estää roolin käytön; liian laaja ehto voi hyväksyä myös työn, jolle roolia ei tarkoitettu. Jos tarvitset oletusarvoista sub-arvoa tarkemman rajauksen esimerkiksi uudelleenkäytettävään workflow’hun, mukauta GitHubin sub-muotoa ja sovita IAM-ehto siihen.

Rajaa AWS-oikeudet julkaisukomentoon

Luottamuskäytäntö vastaa siihen, mistä jobista rooli voidaan ottaa käyttöön. Rooliin liitettävä IAM-käyttöoikeuskäytäntö vastaa erilliseen kysymykseen: mitä komento saa AWS:ssä tehdä. Anna vain julkaisun käyttämät toiminnot ja resurssit. Ehdollisessa S3-esimerkissä yhden valmiin tiedoston lataaminen tietyn bucketin releases-polkuun tarvitsee kyseisiin objekteihin rajatun kirjoitusoikeuden; älä korvaa tätä koko tilin tai kaikkien bucketien oikeudella.

Aloita julkaisukomennon todellisesta toiminnasta. Jos komento myös luetteloi kohdetta, poistaa vanhoja objekteja tai käyttää salattua avainta, se voi tarvita muita oikeuksia; lisää ne vasta nimetylle resurssille ja kyseiseen tarpeeseen. Erota eri ympäristöjen julkaisuroolit, jos niillä on eri kohteet tai hyväksyntävaatimukset. Silloin yhden ympäristön työ ei saa toisen ympäristön oikeuksia vain siksi, että molemmat käyttävät samaa GitHub-repositoriota.

Tarkista onnistuminen ja liian laaja luottamus

Aja sallittu main-haaran työ ja vertaa aws sts get-caller-identity -komennon palauttamaa tiliä ja roolia odotettuihin arvoihin. Jos roolin käyttöönotto epäonnistuu, tarkista ensin tarjoajan osoite, aud-arvo, ARN ja repositorion todellinen sub-muoto. Onnistunut identiteettitarkistus kertoo, että job sai roolin; se ei vielä osoita, että roolin julkaisuoikeudet on rajattu oikein. Testaa varsinainen julkaisukomento vasta sille tarkoitetulla kohteella.

Tee lisäksi kielteinen koe erillisellä testiajolla, jonka sub ei vastaa hyväksyttyä haaraa tai ympäristöä. Esimerkin push-rajaus ei käynnistä jobia muista haaroista, joten pelkkä toisen haaran push ei testaa IAM-ehtoa; testityön on todella yritettävä ottaa sama rooli käyttöön. Odotettu tulos on, että AWS hylkää roolin oletuksen. Tarkista samalla, ettei luottamuskäytännössä ole tarpeettomia jokerimerkkejä ja ettei roolin käyttöoikeuskäytäntö ulotu muihin julkaisukohteisiin.

Kun OIDC-yhteys ja varsinainen julkaisu toimivat, poista vanhojen AWS access key -salaisuuksien käyttö workflow’sta ja poista tarpeettomiksi jääneet avaimet AWS:stä. Tällöin seuraava julkaisu hakee tunnukset ajon aikana saman rajatun roolin kautta.

Lue myös:

• GitHub Actions ilman AWS-avaimia – OIDC vaatii tarkan trust policyn
• GitHub Actions vai GitLab CI? Minuutit peittävät todellisen laskun
• GitHub esti API-avaimen pushin – ohitus jättää silti hälytyksen