Zum Inhalt springen

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

  1. 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.
  2. Der Job legt das Token bei AWS STS mit AssumeRoleWithWebIdentity vor.
  3. 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

FehlerUrsacheLösung
Not authorized to perform sts:AssumeRoleWithWebIdentitysub stimmt nicht mit der Trust Policy übereinGeben Sie die Token-Claims aus oder vergleichen Sie Branch, Umgebung und Repository-Namen exakt, einschließlich Groß- und Kleinschreibung
Credentials could not be loadedid-token: write fehltFügen Sie die Berechtigung auf Job- oder Workflow-Ebene hinzu
No OpenIDConnect provider foundProvider fehlt in diesem Konto oder die URL ist falschLegen Sie ihn mit der oben genannten URL an
Funktioniert auf main, schlägt in einem PR fehlPR-Läufe haben einen anderen subLegen Sie eine separate, schreibgeschützte Rolle für pull_request an, oder gewähren Sie PRs keinen AWS-Zugriff
Schlägt mit environment fehlDem Job fehlt environment:, daher hat sub die Form refSetzen Sie environment: im Job
Sitzung während des Jobs abgelaufenDie Standarddauer beträgt 1 StundeVerwenden 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.

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.

Diesen Workflow auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen