GitHub Actions ilman AWS-avaimia – OIDC vaatii tarkan trust policyn

GitHub Actions voi käyttää AWS:ää ilman GitHub-salaisuuksiin tallennettuja pitkäikäisiä käyttöavaimia. Lisää GitHub OIDC-tunnisteiden tarjoajaksi AWS IAM:iin, luo työn tarvitsemilla oikeuksilla varustettu rooli ja anna työnkulun vaihtaa OIDC-tunnus roolin tilapäisiin AWS-tunnuksiin. Roolin luottamuskäytännössä on tarkistettava sekä tunnuksen vastaanottaja (aud) että sallittu työn konteksti (sub).

Päätä ennen roolin luomista, sidotko sen tietyn repositorion haaraan vai GitHub-ympäristöön. Valinta määrää, millainen sub-arvo tunnuksessa on. Työnkulun oma haarasuodatin ohjaa työn käynnistymistä, mutta IAM:n luottamuskäytäntö ratkaisee, mille tunnukselle AWS antaa roolin tilapäiset käyttöoikeustiedot.

Lisää tunnisteiden tarjoaja ja luo IAM-rooli

Lisää AWS IAM:n Identity providers -näkymässä OpenID Connect -tarjoaja osoitteella https://token.actions.githubusercontent.com. Kun käytät aws-actions/configure-aws-credentials-toimintoa, aseta audience-arvoksi sts.amazonaws.com. Luo sitten Web identity -tyyppinen rooli, jonka luotettu tarjoaja on juuri lisäämäsi GitHubin tarjoaja.

AWS:n IAM-ohje erottaa roolin luottamuskäytännön sen käyttöoikeuskäytännöstä: ensimmäinen määrää, kuka voi ottaa roolin käyttöön, ja jälkimmäinen, mitä AWS-toimintoja roolilla saa tehdä. Liitä rooliin vain työn tarvitsemat oikeudet ja rajaa ne tarvittaviin resursseihin. Pelkkä tarkka luottamuskäytäntö ei korjaa roolia, jolle on annettu tarpeettoman laajat resurssioikeudet.

Jos luot roolin IAM:n lomakkeella, täytä repositorio- ja haarakentät ja tarkista muodostunut käytäntö Trust relationships -välilehdeltä. Tyhjäksi jätetty repositorio tai haara muuttuu lomakkeessa jokerimerkiksi. Tarkista myös, että lomakkeen tuottama sub-arvo vastaa oman repositoriosi käytössä olevaa subject-muotoa, ennen kuin otat roolin käyttöön.

Rajaa aud ja sub täsmäosumalla

Seuraava ehdollinen luottamuskäytäntö hyväksyy yhden repositorion yhden haaran. Korvaa kaikki kulmasulkeissa olevat paikkamerkit omilla arvoillasi. Esimerkki on yhdellä rivillä, jotta sen voi kopioida IAM:n JSON-editoriin.

{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Federated":"arn:aws:iam::<ACCOUNT_ID>: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:<ORG>/<REPO>:ref:refs/heads/<BRANCH>"}}}]}

Aud-arvo osoittaa tunnuksen tarkoitetun AWS STS:lle. Sub-arvossa ovat tässä repositorion omistaja, repositorio ja haaran koko ref-polku. StringEquals vaatii kummallekin ehdolle täsmäosuman: saman organisaation toinen repositorio tai saman repositorion toinen haara ei täytä ehtoa. Esimerkin nimipohjainen sub sopii vain repositorioon, joka käyttää kyseistä subject-muotoa.

Vältä muotoa repo:<ORG>/<REPO>:*, jos roolia tarvitsee vain yksi haara. Se voi kattaa myös repositorion muita haaroja, pull request -töitä ja ympäristöjä. Täsmällinenkin haaraehto rajaa pääsyn haaran tasolle: se ei yksilöi yhtä workflow-tiedostoa, joten saman haaran muukin työnkulku voi täyttää ehdon.

Sovita ehto ympäristöön ja repositorion tunnisteisiin

Jos job-määrityksessä on esimerkiksi environment: production, oletusmuotoinen sub on repo:<ORG>/<REPO>:environment:production. Korvaa tällöin luottamuskäytännön haaramuotoinen sub tällä ympäristömuodolla ja lisää jobiin sama environment-määritys. Oletusmuotoinen ympäristö-sub ei sisällä haaran nimeä. Rajaa siksi ympäristöön pääsevät haarat GitHub-ympäristön deployment branch -säännöillä; työnkulun push-haarasuodatin ei yksin ole ympäristön käyttöoikeussääntö.

GitHubin AWS OIDC -ohjeen mukaan 15. heinäkuuta 2026 jälkeen luotujen repositorioiden sekä pysyviin subject-tunnisteisiin erikseen siirrettyjen vanhempien repositorioiden sub sisältää myös omistajan ja repositorion pysyvät tunnisteet. Haaramuoto on silloin repo:<ORG>@<ORG_ID>/<REPO>@<REPO_ID>:ref:refs/heads/<BRANCH>. Ympäristömuodossa samaan alkuosaan liitetään :environment:<ENVIRONMENT>. Tämä muutos ei koske GitHub Enterprise Serveriä.

Tarkista repositorion OIDC-asetuksista käytössä oleva subject-muoto ennen IAM-ehdon tallentamista. Nimipohjainen ehto ei täsmää tunnukseen, jossa ovat myös pysyvät tunnisteet, vaikka näkyvät nimet olisivat oikein. Jos subject on mukautettu, käytä luottamuskäytännössä sen todellista kokonaisarvoa: mukautus korvaa oletusmuodon. Päivitä IAM-ehto ja GitHubin asetus hallitussa järjestyksessä, jotta käyttöönotossa ei synny turhaa katkosta.

Vaihda OIDC-tunnus työnkulussa AWS-tunnuksiin

Tallenna seuraava ehdollinen työnkulku tiedostoon .github/workflows/aws-oidc.yml ja korvaa paikkamerkit. Yhdelle riville kirjoitettu JSON on myös kelvollista YAML-syntaksia. aws-actions/configure-aws-credentials-toiminnon ohje näyttää OIDC-käytössä id-token: write -oikeuden, roolin ARN-osoitteen ja AWS-alueen; tässä esimerkissä toiminnon versio on v6.3.0.

{"name":"AWS OIDC -tarkistus","on":{"push":{"branches":["<BRANCH>"]},"workflow_dispatch":{}},"jobs":{"verify_aws":{"runs-on":"ubuntu-latest","permissions":{"id-token":"write"},"steps":[{"name":"Hae AWS-tunnukset","uses":"aws-actions/[email protected]","with":{"role-to-assume":"arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>","aws-region":"<AWS_REGION>"}},{"name":"Tarkista rooli","run":"aws sts get-caller-identity"}]}}}

Oikeus id-token: write antaa jobille mahdollisuuden pyytää GitHubin OIDC-tunnuksen. Se ei itsessään anna oikeuksia AWS-resursseihin; AWS tarkistaa roolin luottamuskäytännön ennen tilapäisten tunnusten myöntämistä. Älä lisää työnkulkuun aws-access-key-id- tai aws-secret-access-key-syötteitä, jos tarkoituksena on luopua tallennetuista avaimista. Jos käytät ympäristöön sidottua sub-ehtoa, lisää verify_aws-jobiin myös environment: production ja määritä ympäristön haarasäännöt ennen ajoa.

Tarkista sekä onnistuminen että rajaus

Käynnistä työ sallitusta haarasta. Komennon aws sts get-caller-identity tuloksessa tulee näkyä odotettu AWS-tili ja oletettu rooli. Onnistunut tulos osoittaa, että tunnuksen vaihto ja roolin oletus toimivat. Se ei vielä osoita, että rooliin liitetyt resurssioikeudet olisivat sopivan kapeat; tarkista niiden toiminnot ja resurssit erikseen ennen varsinaista käyttöä.

Haaramuotoisen ehdon kielteistä tarkistusta varten käynnistä sama tarkistustyö käsin toisesta haarasta, jossa työnkulku on käytettävissä. Roolin oletuksen pitäisi epäonnistua, koska haaran sub ei vastaa IAM:n StringEquals-ehtoa. Ympäristömuodossa tarkista puolestaan, ettei kielletty haara pääse ympäristöä käyttävään jobiin. Näin erotat AWS:n tekemän tunnusrajauksen GitHubin ympäristösäännöistä.

Kun sallittu ajo onnistuu, rajauksen kielteinen tarkistus toimii ja työn tarvitsemat AWS-oikeudet on varmistettu, poista vanhojen avainten käyttö työnkulusta. Poista niitä sisältävät GitHub-salaisuudet ja ota tarpeettomat AWS-käyttöavaimet pois käytöstä, kun olet varmistanut, etteivät muut työt tarvitse niitä.