Zum Inhalt springen

Was ist OIDC in GitHub Actions?

Zuletzt aktualisiert am

OIDC (OpenID Connect) in GitHub Actions ist eine Methode, mit der ein Workflow seine Identität gegenüber einem Cloud-Anbieter nachweist und kurzlebige Zugangsdaten erhält. Langlebige Zugriffsschlüssel müssen so nicht als Repository-Secrets gespeichert werden.

So funktioniert es

Jeder Job kann bei GitHub ein signiertes JSON Web Token (JWT) anfordern. Das Token enthält Angaben zum Lauf, etwa Repository, Branch oder Tag, Umgebung, Workflow und mehr. Sie konfigurieren Ihre Cloud (AWS, Google Cloud, Azure und andere) so, dass sie dem Token-Aussteller von GitHub vertraut und Tokens nur akzeptiert, wenn deren Angaben zu den von Ihnen festgelegten Regeln passen, zum Beispiel "Repository ist acme/api und Branch ist main".

Zur Laufzeit tauscht der Job das Token gegen temporäre Zugangsdaten, die meist eine Stunde oder weniger gültig sind. Sie laufen von selbst ab. Eine versehentlich geleakte Logzeile ist daher deutlich weniger riskant als ein geleakter dauerhafter Schlüssel.

Der Job benötigt die Berechtigung, das Token anzufordern. Deshalb setzen Workflows mit OIDC id-token: write.

Beispiel

permissions:
  id-token: write   # allow requesting the OIDC token
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-deploy
          aws-region: us-east-1
      - run: aws sts get-caller-identity

Die Vertrauensrichtlinie der Rolle legt fest, welche Repositories und Branches diese Rolle übernehmen dürfen. Eine Schritt-für-Schritt-Anleitung finden Sie unter GitHub Actions OIDC mit AWS.

Warum OIDC nutzen

  • Keine Secrets, die rotiert oder abgesichert werden müssen.
  • Zugangsdaten gelten nur für einen einzelnen Lauf.
  • Zugriffsregeln lassen sich an Branch, Tag oder Umgebung binden.
  • Die Audit-Logs der Cloud zeigen, welcher Workflow welche Rolle übernommen hat.

Häufige Fehler

  • Vergessen von id-token: write. Ohne diese Angabe schlägt die Token-Anforderung mit einem Berechtigungsfehler fehl.
  • Zu weit gefasste Vertrauensrichtlinie. Eine Regel, die repo:acme/* trifft, erlaubt jedem Repository der Organisation, die Rolle zu übernehmen. Legen Sie das Repository fest und idealerweise auch Branch oder Umgebung.
  • Oben permissions setzen und contents: read weglassen. Sobald Sie eine Berechtigung auflisten, sind alle nicht aufgeführten standardmäßig nicht gewährt.
  • Erwarten, dass es bei Fork-Pull-Requests funktioniert. Workflows aus Forks erhalten standardmäßig keine Tokens mit Schreibrechten und keine Secrets.
  • Das Token als Secret-Speicher betrachten. Es belegt nur die Identität. Die Autorisierung bleibt in den Richtlinien Ihrer Cloud.

OIDC funktioniert auf jedem Runner, auch auf einem selbst gehosteten Runner, da das Token von GitHub stammt und nicht von der Maschine. Weitere Tipps zur Absicherung finden Sie unter GitHub Actions absichern.

FAQ

Ersetzt OIDC alle Secrets?

Nein. Es ersetzt Zugriffsschlüssel für Cloud-Dienste. API-Tokens für Drittanbieter, die OIDC nicht unterstützen, bleiben Secrets.

Welche Clouds unterstützen GitHub OIDC?

AWS, Google Cloud und Azure dokumentieren es ebenso wie HashiCorp Vault und viele weitere Werkzeuge. Die genauen Schritte finden Sie in der Dokumentation Ihres Anbieters.

Ist es für Pull Requests sicher?

Beschränken Sie Vertrauensrichtlinien auf bestimmte Branches oder Umgebungen, damit Code aus Pull Requests keine Deploy-Rollen übernehmen kann.