Web & Entwicklung

GitHub Actions OIDC: So sichern Sie Deployments ohne langlebige Secrets

GitHub Actions OIDC: How to Secure Your Deployments Without Long-Lived Secrets

Erfahren Sie, wie Sie die GitHub Actions Deployment-Sicherheit mit OIDC stärken. Ersetzen Sie langlebige Cloud-Credentials durch kurzlebige Tokens, beschränken Sie den Zugriff mithilfe von IAM Trust-Richtlinien und schützen Sie Ihre CI/CD-Pipelines.

GitHub Actions OIDC: So sichern Sie Ihre Deployments ohne langlebige Secrets

Das Deployment einer Anwendung über GitHub Actions erfordert in der Regel Zugriff auf externe Infrastruktur. Ein Workflow könnte Dateien zu Amazon S3 hochladen, Container veröffentlichen oder Cloud-Ressourcen aktualisieren. Traditionell speichern Teams einen Cloud-Access-Key in den GitHub Secrets. Das funktioniert zwar, aber ein langlebiges Credential bleibt für Angreifer nützlich, wenn ein Workflow, eine Dependency oder ein Log es preisgibt.

OpenID Connect (OIDC) hilft dabei, die CI/CD-Sicherheit zu verstärken, indem langlebige Cloud-Credentials durch temporären Zugriff ersetzt werden, der nur autorisierten Workflow-Identitäten gewährt wird. Es reduziert die Preisgabe von Credentials, begrenzt unbefugten Zugriff und unterstützt stärker kontrollierte Produktions-Deployments.

Dieses Tutorial erläutert die Sicherheitsvorteile, zeigt eine praktische AWS-Konfiguration und identifiziert die Schutzmaßnahmen, die Sie dennoch benötigen. OIDC ist kein magischer Sicherheits-Schalter: Die Trust-Policy, die Rollenberechtigungen und die Workflow-Kontrollen sind genauso wichtig wie der Token-Austausch.

Warum Deployment-Sicherheit wichtig ist

CI/CD-Pipelines sind privilegierte Automatisierungen. Sie können Produktionscode ersetzen, Assets hochladen, Deployment-Konfigurationen lesen oder die Infrastruktur modifizieren. Eine kompromittierte Pipeline kann daher eine größere Auswirkung haben als eine kompromittierte Entwickler-Workstation.

Drei häufige Risiken verdienen besondere Aufmerksamkeit:

  • Credential-Exposition: Ein statischer Cloud-Key, der aus einer Build-Umgebung gestohlen wurde, kann gültig bleiben, bis jemand ihn widerruft.
  • Übermäßige Berechtigungen (Excessive Privileges): Ein Deployment-Credential mit Administratorrechten kann nicht verwandte Dienste beeinträchtigen.
  • Unbefugtes Deployment: Ein nicht vertrauenswürdiger Branch oder Workflow könnte Produktionszugriff erhalten, wenn die Identitätsprüfungen zu weit gefasst sind.

OIDC adressiert einen Teil dieses Problems, indem es die Authentifizierung an eine kurzlebige, verifizierbare Workflow-Identität bindet. Es ersetzt jedoch nicht Least-Privilege-IAM, Code-Reviews oder den Schutz von Umgebungen (Environments).

Was ist OIDC in GitHub Actions?

OpenID Connect ist eine Identitätsschicht, die auf OAuth 2.0 aufbaut. GitHub Actions kann einen signierten JSON Web Token (JWT) vom GitHub OIDC-Provider anfordern:

https://token.actions.githubusercontent.com

Der Token enthält Claims, die die Identität und den Ausführungskontext des Jobs beschreiben. Ein Cloud-Identitätsdienst validiert die Signatur, den Issuer, die Audience und die relevanten Claims des Tokens und entscheidet dann, ob temporäre Credentials ausgestellt werden.

Der externe Dienst muss der beabsichtigten GitHub-Workflow-Identität explizit vertrauen. Das bloße Aktivieren von OIDC in einer YAML-Datei gewährt noch keinen Zugriff.

Siehe GitHub's OIDC documentation.

Statische Credentials vs. OIDC: Sicherheitsvergleich

Sicherheitsaspekt Langlebiger Access-Key OIDC-Federation
Permanentes Cloud-Credential in GitHub Häufig erforderlich Nicht erforderlich für unterstützte Provider
Lebensdauer des Credentials Bis zum Ablauf oder Widerruf Temporäre Session
Verantwortlichkeit für Rotation Team muss den Key-Lebenszyklus verwalten Cloud-Provider stellt kurzlebige Credentials bereit
Identitätsbeschränkungen Abhängig von Credential-Speicherung und IAM Trust-Policy kann Workflow-Identität einschränken
Autorisierung IAM-Berechtigungen IAM-Berechtigungen weiterhin erforderlich
Verbleibendes Risiko Diebstahl und Wiederverwendung des statischen Keys Kompromittierter autorisierter Workflow oder zu breite Trust-Policy

OIDC reduziert das Risiko und die Auswirkungen von Credential-Diebstahl; es eliminiert jedoch nicht jedes Secret. Anwendungen benötigen möglicherweise weiterhin Datenbank-Passwörter, Signierungsschlüssel oder API-Token von Drittanbietern.

Wie der OIDC-Authentifizierungsfluss funktioniert

  1. Ein autorisierter GitHub Actions Job fordert einen Identitätstoken an.
  2. GitHub stellt einen signierten JWT für diesen Job aus.
  3. Der Workflow präsentiert den Token dem Cloud-Identitätsdienst.
  4. Der Cloud-Provider validiert den Token und prüft die konfigurierte Trust-Bedingung.
  5. Wenn die Identität zulässig ist, stellt der Provider temporäre Credentials aus.
  6. Der Workflow verwendet diese Credentials innerhalb des erlaubten Bereichs der Rolle.

Der Cloud-Provider muss einen Token ablehnen, dessen Subject, Audience oder andere erforderliche Bedingungen nicht übereinstimmen. Diese Validierung ist die Grenze zwischen einem sicheren Deployment und einem, der zu viel vertraut.

Schritt 1: GitHubs OIDC-Provider in AWS konfigurieren

AWS IAM unterstützt OpenID Connect Identity Provider. Erstellen Sie einen Identity Provider mit:

Einstellung Wert
Provider URL https://token.actions.githubusercontent.com
Audience sts.amazonaws.com
Provider type OpenID Connect

Die Audience identifiziert den beabsichtigten Empfänger des Tokens. Die AWS Credentials Action verwendet normalerweise sts.amazonaws.com.

Siehe AWS IAM OIDC role configuration.

Schritt 2: Einschränken, wer die Deployment-Rolle annehmen darf

Erstellen Sie eine IAM-Rolle, deren Trust-Policy sts:AssumeRoleWithWebIdentity nur vom GitHub Identity Provider und der beabsichtigten Workflow-Identität erlaubt.

Das folgende Beispiel verwendet das traditionelle GitHub-Branch-basierte Subject-Format:

{
  "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:example-org/example-app:ref:refs/heads/main"
        }
      }
    }
  ]
}

Ersetzen Sie die AWS-Kontonummer, Organisation und das Repository.

Kopieren Sie die Subject-Bedingung nicht blind. GitHub hat ein unveränderliches Standard-Subject-Format für Repositories eingeführt, die nach dem 15. Juli 2026 erstellt wurden. Prüfen Sie das tatsächlich verwendete Subject-Format Ihres Repositories und konfigurieren Sie AWS passend dazu. Environment-basierte Workflows können ebenfalls eine andere Subject-Struktur verwenden. Konsultieren Sie GitHub's OIDC token reference.

Eine restriktive Trust-Policy ist einer der wichtigsten Wege, um zu verhindern, dass unbefugte Workflows Produktions-Credentials erhalten. Vermeiden Sie Wildcard-Subjects, die versehentlich nicht verwandte Repositories oder Kontexte autorisieren.

Schritt 3: Einschränken, was die Rolle tun darf

Vertrauen (Trust) bestimmt, wer eine Rolle annehmen darf. IAM-Berechtigungen bestimmen, was die Rolle nach der Authentifizierung tun kann.

Für ein Deployment, das nur Dateien in einen S3-Bucket hochlädt, lautet eine vereinfachte Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": "arn:aws:s3:::example-deploy-bucket/*"
    }
  ]
}
Illustration of the article's main concept

Dieses Beispiel erlaubt das Hochladen von Objekten, aber keine Kontoadministration oder das Löschen von Buckets. Wenn Ihr Deployment auch veraltete Dateien entfernt oder Bucket-Inhalte auflistet, gewähren Sie nur die zusätzlich erforderlichen Operationen, wie z. B. eingeschränkte s3:DeleteObject oder s3:ListBucket.

Gewähren Sie niemals AdministratorAccess, nur um ein Deployment zum Laufen zu bringen. Temporäre Credentials mit übermäßigen Berechtigungen können immer noch schweren Schaden anrichten.

Schritt 4: Temporäre Credentials von einem Workflow anfordern

Ein Deployment-Job muss berechtigt sein, einen OIDC-Token anzufordern. Das folgende Beispiel lädt ein vorab erstelltes dist/-Verzeichnis zu S3 hoch:

name: Deploy website

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy-role
          aws-region: eu-west-1

      - name: Deploy website
        run: |
          aws s3 cp ./dist/ s3://example-deploy-bucket/ --recursive

Das Beispiel verwendet Major-Version-Action-Referenzen für die Lesbarkeit. Überprüfen Sie in der Produktion die aktuell unterstützten Versionen und fixieren Sie Drittanbieter-Actions nach Möglichkeit auf vollständige Commit-SHAs. Das Beispiel geht davon aus, dass die Website bereits in dist/ gebaut wurde.

Beachten Sie, was fehlt: Es wird kein permanenter AWS Access Key oder Secret Access Key im Workflow gespeichert.

Die offizielle AWS credentials action tauscht den OIDC-Token gegen temporäre AWS-Credentials aus.

Schritt 5: id-token: write verstehen

Diese Berechtigung:

permissions:
  id-token: write

erlaubt es einem Job, einen GitHub OIDC-Identitätstoken anzufordern. Sie gibt dem Job an sich nicht die Erlaubnis, in GitHub-Repositories zu schreiben oder auf AWS zuzugreifen.

Der Cloud-Provider entscheidet weiterhin, ob der Identität vertraut wird, und die IAM-Rolle steuert weiterhin, welche Operationen erlaubt sind.

Gewähren Sie id-token: write nur Jobs, die sich tatsächlich am Cloud-Dienst authentifizieren. Build-, Lint- und Test-Jobs benötigen dies im Allgemeinen nicht.

Schritt 6: Produktionsumgebungen schützen

OIDC kann nicht kompensieren, wenn ein autorisierter Workflow bösartigen Code ausführt. Wenn ein Angreifer einen vertrauenswürdigen Deployment-Workflow ändern oder unüberprüften Code in diesem Kontext ausführen kann, kann er möglicherweise temporäre Credentials erhalten.

GitHub Environments können Kontrollen wie Beschränkungen für Deployment-Branches und erforderliche Reviewer hinzufügen (abhängig von Repository-Einstellungen und Plan-Verfügbarkeit).

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

    permissions:
      contents: read
      id-token: write

Wenn der Workflow eine Umgebung (Environment) nutzt, kann das OIDC-Subject diese Umgebung statt eines Branches identifizieren. Aktualisieren Sie die IAM-Trust-Policy, um den tatsächlichen Claims zu entsprechen und die Umgebung selbst zu schützen.

Kombinieren Sie für die Produktion restriktive Identitäten mit Branch-Protection, Code-Reviews, begrenzten Workflow-Berechtigungen und – wo angemessen – Environment-Approval-Regeln. So wird OIDC Teil einer stärkeren Deployment-Sicherheitsstrategie, anstatt nur ein Ersatz für Credentials zu sein.

Schritt 7: Die angenommene Identität verifizieren und Verweigerungen testen

Fügen Sie nach der Konfiguration der AWS-Authentifizierung einen Diagnoseschritt hinzu:

- name: Verify AWS identity
  run: aws sts get-caller-identity

Prüfen Sie, ob die Antwort das beabsichtigte AWS-Konto und die Deployment-Rolle identifiziert. Der Befehl gibt den Secret Access Key nicht preis.

Testen Sie außerdem, dass ein unbefugter Branch, ein Repository oder eine Umgebung die Produktionsrolle nicht annehmen kann. Ein fehlgeschlagenes unbefugtes Deployment ist ein erfolgreicher Sicherheitstest.

Protokollieren (loggen) Sie während des Debuggings niemals rohe OIDC-Token oder temporäre Credentials.

Häufige OIDC-Sicherheits- und Konfigurationsfehler

Fehlendes id-token: write

Der Job kann keinen OIDC-Token anfordern, sofern er nicht die entsprechende Berechtigung hat. Berechtigungen auf Job-Ebene können Berechtigungen auf Workflow-Ebene überschreiben.

Technical workflow illustration

AWS gibt AccessDenied für die Rollenannahme zurück

Überprüfen Sie den Identity Provider, die Audience, die Rollen-ARN und die Subject-Bedingung. Verifizieren Sie insbesondere das tatsächliche GitHub-Subject-Format, anstatt davon auszugehen, dass jedes Repository dasselbe Standardformat verwendet.

Authentifizierung erfolgreich, aber Upload schlägt fehl

Die Vertrauensstellung (Trust Relationship) ist möglicherweise korrekt, aber der Rolle fehlen die erforderlichen S3-Berechtigungen. Korrigieren Sie die eng gefasste IAM-Berechtigungsrichtlinie, anstatt das Identitätsvertrauen zu erweitern.

Produktionszugriff ist aus zu vielen Kontexten erlaubt

Ein Wildcard-Subject oder unzureichende Environment-Beschränkungen können dazu führen, dass Produktions-Credentials für Workflows verfügbar sind, die diese niemals erhalten sollten. Schränken Sie die Trust-Policy ein und testen Sie unbefugte Fälle.

Ein Pull Request kann nicht deployen

Pull Requests können andere Claims und unvertrauenswürdigen Code enthalten. Schwächen Sie die Produktions-Vertrauensbedingungen nicht ab, nur damit ein Pull Request die Deployment-Rolle annehmen kann. Führen Sie die Validierung getrennt vom Produktions-Deployment durch.

Kann man OIDC mit Azure oder Google Cloud verwenden?

Ja. Der Föderationsmechanismus ist ähnlich, aber die Identitätskonfiguration unterscheidet sich.

Cloud Föderationsmechanismus GitHub Action
AWS IAM OIDC provider und role aws-actions/configure-aws-credentials
Microsoft Azure Federated identity credentials azure/login
Google Cloud Workload Identity Federation google-github-actions/auth

Azure verknüpft in der Regel ein föderiertes Credential mit einer Anwendung oder einer Managed Identity. Google Cloud verwendet einen Workload Identity Pool und Provider, mit direktem Ressourcen-Zugriff oder Service Account Impersonation, je nach Setup.

Jede Plattform hat ihre eigenen Regeln für Audience, Subject-Matching und Autorisierung. Überprüfen Sie die aktuelle offizielle Dokumentation des Providers, bevor Sie ein Beispiel kopieren.

Was ist mit PHP-Websites auf traditionellem Hosting?

Nicht jeder Webhoster akzeptiert GitHub OIDC-Identitäten. Shared Hosting und verwaltetes PHP-Hosting verwenden möglicherweise immer noch SSH-Keys, SFTP-Credentials, Deployment-Webhooks oder Provider-API-Token.

Das Aktivieren von OIDC in GitHub Actions ersetzt nicht automatisch einen SSH-Key, wenn der Zielserver keinen Föderationsmechanismus besitzt.

Wenn OIDC nicht verfügbar ist, verwenden Sie ein dediziertes Deployment-Konto, eng gefasste Berechtigungen, geschützte Secrets und Credential-Rotation. Beschränken Sie nach Möglichkeit den Dateisystem- und Befehlszugriff.

Das Sicherheitsziel ist Least Privilege und eine begrenzte Preisgabe von Credentials, unabhängig davon, ob OIDC unterstützt wird oder nicht.

Deployment-Sicherheits-Checkliste

Bevor Sie in die Produktion deployen, verifizieren Sie, dass:

  • Der OIDC-Issuer und die Audience korrekt konfiguriert sind.
  • Die Trust-Policy nur dem beabsichtigten Repository und Deployment-Kontext entspricht.
  • Die Subject-Bedingung das tatsächliche GitHub-Token-Format Ihres Repositories widerspiegelt.
  • Die IAM-Rolle nur die für das Deployment erforderlichen Berechtigungen hat.
  • Nur Deployment-Jobs id-token: write erhalten.
  • Produktions-Branches und -Umgebungen über angemessenen Schutz verfügen.
  • Drittanbieter-Actions überprüft und nach Möglichkeit auf unveränderliche Commit-SHAs fixiert sind.
  • Unvertrauenswürdige Pull Requests keine Produktionsrollen annehmen können.
  • Unbefugte Branches und Repositories bei der Authentifizierung scheitern.
  • Token und temporäre Credentials niemals unnötig protokolliert oder gespeichert werden.

Häufig gestellte Fragen (FAQ)

Ist OIDC sicherer als statische AWS Access-Keys?

Es reduziert das Risiko des Diebstahls langlebiger Credentials. Starke Trust-Policies, begrenzte Berechtigungen und geschützte Workflows sind weiterhin essenziell.

Eliminiert OIDC GitHub Secrets?

Es ersetzt einige Cloud-Authentifizierungs-Credentials, aber nicht jedes Anwendungs-Secret oder jeden API-Key.

Was gewährt id-token: write?

Es erlaubt einem Workflow, einen Identitätstoken anzufordern. Die Cloud-Berechtigungen werden separat durch den Provider bestimmt.

Können unvertrauenswürdige Pull Requests Produktions-OIDC-Credentials nutzen?

Sie sollten es nicht. Konfigurieren Sie restriktive Trust-Bedingungen und halten Sie Produktions-Deployments getrennt von unvertrauenswürdigem Code.

Funktioniert OIDC mit jedem Hosting-Provider?

Nein. Der Zieldienst oder ein Identity Broker muss GitHubs OIDC-Token unterstützen und ihnen vertrauen.

Fazit: Sicherheit stärken, nicht nur die Authentifizierung

GitHub Actions OIDC ist ein effektiver Weg, um die Deployment-Sicherheit für unterstützte Cloud-Dienste zu erhöhen. Es macht es überflüssig, permanente Cloud-Keys in GitHub aufzubewahren, ermöglicht kurzlebigen Zugriff und erlaubt es Cloud-Trust-Policies zu beschränken, welche Workflows deployen dürfen.

Aber das stärkste Design kombiniert OIDC mit Least-Privilege-IAM, geschützten Umgebungen, überprüftem Workflow-Code und expliziten Tests, die sicherstellen, dass unbefugte Identitäten abgelehnt werden.

Das Ziel ist nicht einfach nur der Ersatz eines Secrets. Es geht darum sicherzustellen, dass nur der richtige Workflow auf die richtigen Ressourcen mit den minimalen Berechtigungen und für die kürzestmögliche praktische Zeit zugreifen kann.

Offizielle Referenzen