GitHub Actions ohne AWS-Schlüssel: Die Trust Policy entscheidet

GitHub Actions kann per OpenID Connect (OIDC) auf AWS zugreifen, ohne dauerhaft gültige AWS-Schlüssel als Repository-Secret zu speichern. Die GitHub-Anleitung zur AWS-Anbindung beschreibt, wie ein Job sein OIDC-Token gegen temporäre Zugangsdaten für eine IAM-Rolle eintauscht.

Ob dieser Tausch gelingt, hängt von der Trust Policy der Rolle ab. Sie muss die erwartete Audience und einen sub-Claim prüfen, der zum zulässigen Repository und Branch oder Environment passt. Als bedingtes Beispiel dient hier ein Deployment aus dem Branch main; ein Lauf aus einem Test-Branch soll dieselbe Rolle nicht übernehmen können.

OIDC-Provider und IAM-Rolle anlegen

GitHubs OIDC-Provider ist mit einer AWS IAM-Rolle verbunden, deren Ressourcenrechte getrennt begrenzt sind.

Lege in AWS IAM einen OIDC-Identitätsanbieter mit der URL https://token.actions.githubusercontent.com an. Für die übliche AWS-Partition und aws-actions/configure-aws-credentials ist sts.amazonaws.com die Audience. Der Provider macht GitHubs Token-Aussteller in IAM bekannt; die Entscheidung über eine konkrete Rollenübernahme fällt erst anhand der Trust Policy.

Erstelle eine eigene IAM-Rolle für das Deployment. Ihre Berechtigungsrichtlinie bestimmt, welche AWS-Aktionen mit den temporären Zugangsdaten auf welchen Ressourcen erlaubt sind. Die Trust Policy regelt dagegen, wer die Rolle übernehmen darf. Begrenze daher auch die Berechtigungsrichtlinie auf die tatsächlich benötigten Aktionen und Ressourcen: Eine enge Identitätsprüfung schränkt die Rechte nach erfolgreicher Anmeldung nicht von selbst ein.

Halte die AWS-Konto-ID, die Rollen-ARN sowie den genauen Namen von Eigentümer, Repository und Branch bereit. Die ARN des Providers folgt in der üblichen AWS-Partition dem Muster arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com. Ersetze ACCOUNT_ID und alle folgenden Beispielwerte durch die Angaben deiner Umgebung.

Die Trust Policy auf das passende Subject begrenzen

Trage als Federated Principal die ARN des OIDC-Providers und als Aktion sts:AssumeRoleWithWebIdentity ein. Unter Condition und StringEquals muss token.actions.githubusercontent.com:aud den Wert sts.amazonaws.com haben. Für token.actions.githubusercontent.com:sub setze den vollständigen Subject-Wert des zulässigen Jobs, etwa repo:ORG@ORG_ID/REPO@REPO_ID:ref:refs/heads/main, wenn das Repository das Format mit festen IDs verwendet.

Die IAM-Anleitung von AWS erklärt die Grenze der eingebauten Prüfung: IAM weist eine GitHub-Trust-Policy ohne sub-Bedingung oder mit einem ausschließlich aus Wildcards bestehenden Wert zurück. Ein Muster wie repo:ORG/REPO:* kann dagegen gültig sein und dennoch Branches, Pull-Request-Kontexte und Environments umfassen, die keine Deployment-Rechte erhalten sollen. Prüfe deshalb die tatsächlich gespeicherte Richtlinie, auch wenn du die Rolle über die IAM-Konsole erstellt hast.

StringEquals eignet sich für einen exakt bekannten Subject-Wert. Sind mehrere Branches ausdrücklich zugelassen, lassen sich ihre vollständigen Werte einzeln angeben; StringLike und Wildcards brauchen eine bewusste Begründung. Das Standard-Subject mit Repository und Branch bezeichnet zudem keine bestimmte Workflow-Datei: Ein anderer berechtigter Job im selben Kontext kann dieselbe Bedingung erfüllen. Die Kontrolle darüber, wer dort Workflows ändern und ausführen kann, gehört somit zur Zugriffsgrenze.

Das Subject des tatsächlichen Jobs abgleichen

Der Subject-Claim eines GitHub Actions Jobs muss zum Branch oder Environment in der AWS-Trust-Policy passen.

Das Subject-Format hängt vom Repository ab. Laut der Dokumentation der AWS-Credentials-Action enthalten Repositories auf github.com, die am oder nach dem 15. Juli 2026 erstellt wurden, feste Eigentümer- und Repository-IDs im sub-Claim; das gilt auch für ältere Repositories mit entsprechender Umstellung oder einer Umbenennung seit diesem Datum. Ein älteres Repository ohne diese Umstellung kann weiterhin repo:ORG/REPO:ref:refs/heads/main senden. Die Trust Policy muss exakt zum Format des eigenen Repositories passen.

Verwendet der Job ein GitHub Environment, enthält das Standard-Subject dessen Namen anstelle des Branch-Abschnitts, beispielsweise repo:ORG/REPO:environment:prod im älteren Format. Eine Policy für :ref:refs/heads/main passt dann nicht zu diesem Job. Soll ein Environment die Rolle nutzen, beschränke dort über Schutzregeln auch die zulässigen Deployment-Branches und Tags; der Environment-Name im Subject ist für sich genommen keine Freigabe nur für main.

Übernimm deshalb keinen Subject-Wert ungeprüft aus einer Beispielrichtlinie. Ein falsch gewähltes Format führt zur Ablehnung des gewünschten Jobs, während eine großzügige Wildcard unerwünschte Kontexte zulassen kann. Bei einem angepassten Subject-Format muss die Bedingung ebenfalls den vollständigen Wert abbilden, den der Job tatsächlich sendet.

Dem Workflow das ID-Token-Recht geben

Setze beim betreffenden Job unter permissions den Eintrag id-token: write. Damit darf der Job ein OIDC-Token anfordern; die Einstellung erteilt noch keine AWS-Ressourcenrechte. Falls actions/checkout den Repository-Inhalt lädt, ergänze contents: read. Berechtigungen auf Job-Ebene vermeiden, dass andere Jobs sie allein durch eine globale Workflow-Einstellung erhalten.

Füge danach einen Schritt mit aws-actions/configure-aws-credentials ein. Übergib über role-to-assume die ARN der IAM-Rolle und über aws-region die verwendete Region; wähle eine für die eigene Umgebung passende Version der Action. Für diesen OIDC-Weg sind Eingaben für statische AWS-Zugangsschlüssel nicht erforderlich. Nach erfolgreicher Rollenübernahme stehen die temporären Zugangsdaten den nachfolgenden Schritten zur Verfügung.

Im bedingten Beispiel läuft der Deployment-Job bei einem Push auf main. Sein Token muss sowohl den Audience-Wert als auch den in IAM eingetragenen Subject-Wert treffen. Ein Trigger für main allein ist keine AWS-Zugriffskontrolle: Maßgeblich ist, was die Rolle bei der Anfrage an STS tatsächlich akzeptiert.

Erlaubten Lauf und Ablehnung prüfen

Ein GitHub Actions Lauf auf main übernimmt die AWS-Rolle; derselbe Job aus einem Test-Branch wird abgewiesen.

Starte den vorgesehenen Lauf auf main und führe nach dem Credentials-Schritt aws sts get-caller-identity aus. Vergleiche die ausgegebene Identität mit der erwarteten Rolle und dem erwarteten AWS-Konto. Dieser Aufruf zeigt, ob die Rollenübernahme gelungen ist; ob die Berechtigungsrichtlinie die benötigte Deployment-Aktion zulässt, prüfst du mit einer passenden AWS-Operation.

Für den Negativtest muss derselbe Job auch aus einem ausdrücklich nicht freigegebenen Test-Branch ausführbar sein, etwa über einen dafür eingerichteten Trigger. Die Trust Policy bleibt dabei auf main beschränkt. Der Testlauf soll bereits beim Credentials-Schritt an der Rollenübernahme scheitern. Ein Fehler erst beim Zugriff auf eine AWS-Ressource würde die beabsichtigte Grenze der Trust Policy nicht belegen.

Entferne für diesen Test statische AWS-Credentials und alternative Anmeldewege aus dem Job, damit sie das Ergebnis nicht verdecken. Gelingt die Rollenübernahme aus dem Test-Branch, untersuche den tatsächlichen sub-Wert, Wildcards und weitere Allow-Einträge der Trust Policy. Scheitert schon der erlaubte Lauf, vergleiche Provider-URL, Audience, id-token: write und Subject-Format einschließlich eines möglichen Environments mit der Konfiguration des Jobs.

Lesen Sie auch: