GitHub Actions OIDC zu AWS: keine langlebigen Schlüssel
Zuletzt aktualisiert am
Wenn Sie AWS_ACCESS_KEY_ID und AWS_SECRET_ACCESS_KEY als GitHub-Secrets speichern, funktioniert ein geleakter Schlüssel von überall, bis jemand ihn bemerkt und rotiert. OpenID Connect (OIDC) ersetzt diese Schlüssel: Jeder Workflow-Lauf fordert bei GitHub ein signiertes Token an, und AWS tauscht es gegen temporäre Zugangsdaten, die nach spätestens einer Stunde ablaufen. Dieser Leitfaden zeigt die Einrichtung und wie Sie sie sauber absichern.
So funktioniert es
- Der Workflow fordert bei GitHub ein ID-Token an. Das Token enthält, für welches Repository, welchen Branch und welche Umgebung der Job läuft.
- Der Job legt das Token bei AWS STS mit
AssumeRoleWithWebIdentityvor. - AWS prüft die Signatur gegen den von Ihnen registrierten Identity Provider, wertet die Trust Policy der Rolle anhand der Claims des Tokens aus und gibt temporäre Zugangsdaten zurück.
In GitHub liegt kein Geheimnis. Die Sicherheit entsteht durch die Bedingungen in der Trust Policy, daher ist es entscheidend, diese sorgfältig zu formulieren.
Schritt 1: Identity Provider anlegen
Legen Sie in IAM einen OpenID-Connect-Provider mit folgenden Angaben an:
- Provider-URL:
https://token.actions.githubusercontent.com - Audience:
sts.amazonaws.com
AWS prüft die Signaturen von GitHub-Tokens mit der eigenen Bibliothek vertrauenswürdiger Root-CAs, daher müssen Sie für diesen Provider keinen Thumbprint mehr pflegen. In der Konsole sind es wenige Klicks; mit der CLI sieht es so aus:
aws iam create-open-id-connect-provider \
--url https://token.actions.githubusercontent.com \
--client-id-list sts.amazonaws.com
Sie benötigen pro Konto nur einen Provider, den alle Rollen gemeinsam nutzen.
Schritt 2: Rolle mit einer engen Trust Policy anlegen
Der Claim sub (Subject) kennzeichnet den Workflow-Kontext. Gängige Formate:
- Branch:
repo:ORG/REPO:ref:refs/heads/main - Umgebung:
repo:ORG/REPO:environment:production - Pull Request:
repo:ORG/REPO:pull_request - Tag:
repo:ORG/REPO:ref:refs/tags/v1.0.0
Trust Policy für Deployments aus der Umgebung production eines Repositorys:
{
"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:my-org/my-repo:environment:production"
}
}
}
]
}
Use StringEquals with an exact sub where you can. If you need several branches, use StringLike with a narrow pattern such as repo:my-org/my-repo:ref:refs/heads/release/. Never use a trust policy that checks only aud, and never repo:my-org/:*: that lets any repository in the organization, including ones with weak review, assume the role.
Hängen Sie eine Berechtigungsrichtlinie an, die nur das enthält, was der Job benötigt, etwa s3:PutObject auf einen Bucket oder eine ECR-Push-Richtlinie für ein Repository. Getrennte Rollen für Build, Deployment auf Staging und Deployment auf Production begrenzen den Schaden im Ernstfall, und umgebungsbasierte Subjects ermöglichen es, für Production eine manuelle Freigabe zu verlangen.
Schritt 3: Im Workflow verwenden
Der Job benötigt die Berechtigung, das Token anzufordern:
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/gha-deploy-production
aws-region: us-east-1
role-session-name: gha-${{ github.run_id }}
- run: aws sts get-caller-identity
- run: aws s3 sync ./dist s3://my-bucket --delete
id-token: write gewährt keinen Schreibzugriff auf Ihr Repository; es erlaubt lediglich das Anfordern des OIDC-Tokens. Beim Setzen dieser Berechtigung entfallen zudem die Standardberechtigungen, die Sie nicht explizit aufführen, deshalb contents: read. Fixieren Sie aws-actions/configure-aws-credentials auf einen SHA, wie unter GitHub Actions absichern beschrieben.
aws sts get-caller-identity ist die schnellste Prüfung, ob die Rolle übernommen wurde und ob Konto und Rollen-ARN den Erwartungen entsprechen.
Anpassung des Subject-Claims
Standardmäßig hat der sub das oben beschriebene Format. Organisations- und Repository-Inhaber können über die OIDC-Einstellungen per API festlegen, welche Claims in sub enthalten sind, zum Beispiel repository_id oder job_workflow_ref. Mit job_workflow_ref können Sie erzwingen, dass nur ein bestimmter wiederverwendbarer Workflow die Rolle übernehmen darf:
"StringLike": {
"token.actions.githubusercontent.com:job_workflow_ref": "my-org/platform-workflows/.github/workflows/deploy.yml@refs/heads/main"
}
AWS unterstützt für diesen Provider nur eine begrenzte Menge an Claim-Schlüsseln in IAM-Bedingungen. Prüfen Sie vor dem Einsatz in der AWS-IAM-Dokumentation die Liste der unterstützten Schlüssel, etwa aud, sub und job_workflow_ref.
Häufige Fehler
| Fehler | Ursache | Lösung |
|---|---|---|
Not authorized to perform sts:AssumeRoleWithWebIdentity | sub stimmt nicht mit der Trust Policy überein | Geben Sie die Token-Claims aus oder vergleichen Sie Branch, Umgebung und Repository-Namen exakt, einschließlich Groß- und Kleinschreibung |
Credentials could not be loaded | id-token: write fehlt | Fügen Sie die Berechtigung auf Job- oder Workflow-Ebene hinzu |
No OpenIDConnect provider found | Provider fehlt in diesem Konto oder die URL ist falsch | Legen Sie ihn mit der oben genannten URL an |
Funktioniert auf main, schlägt in einem PR fehl | PR-Läufe haben einen anderen sub | Legen Sie eine separate, schreibgeschützte Rolle für pull_request an, oder gewähren Sie PRs keinen AWS-Zugriff |
| Schlägt mit environment fehl | Dem Job fehlt environment:, daher hat sub die Form ref | Setzen Sie environment: im Job |
| Sitzung während des Jobs abgelaufen | Die Standarddauer beträgt 1 Stunde | Verwenden Sie role-duration-seconds bis zum Maximum der Rolle, oder teilen Sie den Job auf |
Pull Requests und Forks
Fork-PRs können kein OIDC-Token für die Identität Ihres Repositorys anfordern, was genau das ist, was Sie wollen. Bei PRs aus demselben Repository sollten Sie ihnen keinen Schreibzugriff auf AWS geben: Ein PR kann die Workflow-Datei ändern, daher muss jede Rolle, die ein PR übernehmen kann, für jeden mit Schreibzugriff auf das Repository unbedenklich sein. Geben Sie PR-Rollen nur Leserechte oder verwenden Sie plan-Zugriff ausschließlich für Infrastrukturprüfungen.
Über AWS hinaus
Dasselbe Muster funktioniert für GCP Workload Identity Federation, Azure Federated Credentials, HashiCorp Vault und Paketregistries, die Trusted Publishing unterstützen (PyPI, npm und RubyGems). Wenn Sie alle davon auf OIDC umstellen, entfallen Ihre langlebigen Secrets.
FAQ
Muss ich trotzdem noch etwas rotieren?
Nein, es gibt keine Zugriffsschlüssel zu rotieren. Prüfen Sie aber weiterhin Ihre Trust-Policies, denn sie sind jetzt Ihre Zugriffskontrolle.
Kann ich OIDC mit selbst gehosteten Runnern verwenden?
Ja. Das Token wird von GitHub für den Job ausgestellt, unabhängig davon, wo er läuft. Der Runner benötigt weiterhin Netzwerkzugriff auf AWS STS. Bei Runnern von Drittanbietern prüfen Sie, ob OIDC unterstützt wird.
Was enthält das Token?
Claims, darunter iss, aud, sub, repository, ref, environment, workflow und run_id. Die Dokumentation von GitHub listet alle auf.
Ist es sicher, die Rollen-ARN im Workflow abzulegen?
Ja. Eine ARN ist ein Bezeichner, kein Geheimnis. Die Trust-Policy entscheidet, wer sie verwenden darf.
Verwandt
Für allgemeine Workflow-Härtung lesen Sie Sicherung von GitHub Actions. Schätzen Sie Ihre Deployment-Kosten mit dem EC2-Kostenrechner und dem S3-Kostenrechner. compiler.dev-Runner können GitHub-OIDC-Token wie jeder andere Runner anfordern. Eine Trust-Policy, die Sie heute schreiben, funktioniert also weiterhin, auch wenn Sie den Ort ändern, an dem Jobs laufen.
Verwandt
- Was ist OIDC in GitHub Actions?OIDC ermöglicht GitHub-Actions-Workflows kurzlebige Cloud-Zugangsdaten ohne gespeicherte Secrets. Mit Funktionsweise, YAML-Beispiel und häufigen Fehlern.
- TypeScript-Monorepo in GitHub Actions beschleunigenTypprüfung und Linting in TypeScript-Monorepos auf GitHub Actions beschleunigen: inkrementelles tsc, Projektreferenzen, Lint-Caches und parallele Jobs.
- Playwright im Monorepo mit GitHub Actions beschleunigenPlaywright-E2E-Tests in einem Node-Monorepo auf GitHub Actions beschleunigen: App einmal bauen, E2E überspringen, wenn sich die Web-App nicht ändert.
- CI-Geschwindigkeits-Badge in Ihre README einfügenZeigen Sie die Geschwindigkeit Ihrer CI mit einem README-Badge: die mediane Laufzeit Ihrer Repository-Workflows auf GitHub Actions, automatisch aktualisiert.