OpenID Connect

Übersicht über OpenID Connect (OIDC)

          GitHub Actions Workflows sind häufig für den Zugriff auf einen Cloudanbieter (z. B. AWS, Azure, GCP, HashiCorp Vault und andere) konzipiert, um Software bereitzustellen oder die Clouddienste zu verwenden. Bevor der Workflow auf diese Ressourcen zugreifen kann, werden dem Cloudanbieter Anmeldeinformationen, z. B. ein Kennwort oder ein Token, bereitgestellt. Diese Anmeldeinformationen werden in der Regel als geheimer Schlüssel GitHubgespeichert, und der Workflow stellt diesen geheimen Schlüssel bei jeder Ausführung an den Cloudanbieter vor.

Die Verwendung hartcodierter Geheimnisse erfordert jedoch, dass Sie Anmeldeinformationen im Cloudanbieter erstellen und diese dann in GitHub als Geheimnis duplizieren.

Nachdem du eine vertrauenswürdige Verbindung mit einem Cloudanbieter hergestellt hast, der OIDC unterstützt, kannst du deinen Workflow so konfigurieren, dass ein kurzlebiges Zugriffstoken direkt vom Cloudanbieter angefordert wird.

Vorteile der Verwendung von OIDC

Wenn du deine Workflows für die Verwendung von OIDC-Token aktualisierst, kannst du die folgenden bewährten Sicherheitspraktiken übernehmen:

        **Keine Cloud-Geheimnisse:** Sie müssen Ihre Cloudanmeldeinformationen nicht als langlebige Geheimnisse duplizieren. Stattdessen kannst du die OIDC-Vertrauensstellung auf deinem Cloudanbieter konfigurieren und dann deine Workflows aktualisieren, um ein kurzlebiges Zugriffstoken vom Cloudanbieter über OIDC anzufordern.

        **Authentifizierungs- und Autorisierungsverwaltung**: Du hast genauere Kontrolle darüber, wie Workflows Anmeldeinformationen verwenden können, indem du die Authentifizierungs- (authN) und Autorisierungstools (authZ) deines Cloudanbieters verwendest, um den Zugriff auf Cloudressourcen zu steuern.

        **Rotierende Anmeldeinformationen**: Mit OIDC stellt dein Cloudanbieter ein kurzlebiges Zugriffstoken aus, das nur für einen einzelnen Auftrag gültig ist und dann automatisch abläuft.

Wie OIDC mit GitHub Actions integriert wird

Das folgende Diagramm gibt einen Überblick darüber, wie GitHubder OIDC-Anbieter in Ihre Workflows und Cloudanbieter integriert wird:

Diagramm der Integration eines Cloudanbieters mit GitHub Actions über Zugriffstoken und JSON-Webtoken-Cloudrollen-IDs.

Sie richten eine OIDC-Vertrauensstellung im Cloudanbieter ein, sodass bestimmte GitHub Workflows Cloudzugriffstoken im Auftrag einer definierten Cloudrolle anfordern können.
Jedes Mal, wenn Ihr Auftrag ausgeführt wird, GitHubgeneriert der OIDC-Anbieter automatisch ein OIDC-Token. Dieses Token enthält mehrere Ansprüche zum Einrichten einer sicherheitsfesten und überprüften Identität über den spezifischen Workflow, der versucht, sich zu authentifizieren.
Ein Schritt oder eine Aktion im Workflowauftrag kann ein Token vom GitHubOIDC-Anbieter anfordern, der dann dem Cloudanbieter als Nachweis der Identität des Workflows angezeigt werden kann.
Nachdem der Cloudanbieter die im Token dargestellten Ansprüche erfolgreich überprüft hat, stellt er ein kurzlebiges Cloudzugriffstoken bereit, das nur für die Dauer des Auftrags verfügbar ist.

Grundlegendes zum OIDC-Token

Jeder Auftrag fordert ein OIDC-Token vom GitHubOIDC-Anbieter an, der mit einem automatisch generierten JSON-Webtoken (JWT) antwortet, das für jeden Workflowauftrag eindeutig ist, in dem er generiert wird. Wenn der Auftrag ausgeführt wird, wird das OIDC-Token für den Cloudanbieter bereitgestellt. Zur Überprüfung des Tokens ermittelt der Cloudanbieter, ob der Antragsteller des OIDC-Tokens und andere Ansprüche mit den Bedingungen übereinstimmen, die für die OIDC-Vertrauensdefinition der Cloudrolle vorkonfiguriert wurden.

Im folgenden Beispiel verwendet das OIDC-Token einen Antragsteller (sub), der auf eine Auftragsumgebung namens prod im Repository octo-org/octo-repo verweist.

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "runner_environment": "github-hosted",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "enterprise": "avocado-corp",
  "enterprise_id": "2",
  "repo_property_workspace_id": "ws-abc123",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

Herstellen einer OIDC-Vertrauensstellung mit dem Cloudanbieter

Um OIDC in Ihren Workflows zu verwenden, müssen Sie eine Vertrauensstellung zwischen GitHub und Ihrem Cloudanbieter einrichten. Damit stellst du sicher, dass nur autorisierte Workflows Zugriffstoken für deine Cloudressourcen anfordern können.

Bevor dein Cloudanbieter ein Zugriffstoken erteilt, überprüft er, ob die subject und andere Ansprüche, die zum Festlegen von Bedingungen in seinen Vertrauenseinstellungen verwendet werden, mit denen im JSON-Webtoken (JWT) der Anforderung übereinstimmen. Stimmt die Vertrauenskonfiguration überein, gibt dein Cloudanbieter ein temporäres Zugriffstoken für den Workflow aus.

Weitere Informationen zu Vorgehensweise und Syntax bei der Konfiguration einer OIDC-Vertrauensstellung und dem Festlegen von Bedingungen für Cloudanbieter findest du unter OpenID Connect-Referenz.

Konfigurieren von OIDC auf GHE.com

Wenn Sie Teil eines Unternehmens sind, das GitHub Enterprise-Cloud mit Datenresidenz verwendet und GHE.com konfiguriert hat, müssen Sie beim Einrichten von OIDC bestimmte Werte ersetzen.

Weitere Informationen finden Sie unter OpenID Connect-Referenz.

Authentifizieren benutzerdefinierter Aktionen mit OIDC

Benutzerdefinierte Aktionen verwenden für die Authentifizierung mit OIDC die getIDToken()-Methode aus dem Toolkit für Aktionen oder einen curl-Befehl.

Weitere Informationen finden Sie unter OpenID Connect-Referenz.

Aktualisieren deiner Workflows für OIDC

          GitHub Actions Workflows können OIDC-Token anstelle von geheimen Schlüsseln verwenden, um sich bei Cloudanbietern zu authentifizieren. Viele beliebte Cloudanbieter bieten offizielle Anmeldeaktionen, die den Verwendungsprozess von OIDC in Workflows vereinfachen. Weitere Informationen zum Aktualisieren deiner Workflows bei bestimmten Cloudanbietern findest du unter [AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments).

Verwenden von anpassbaren Repository-Eigenschaften als OIDC-Claims

Organisations- und Unternehmensadministratoren können benutzerdefinierte Repositoryeigenschaften als Ansprüche in OIDC-Token enthalten. Dies ermöglicht attributbasierte Zugriffssteuerungsrichtlinien (ABAC) in Ihrem Cloudanbieter, Artefaktregistrierung oder geheimen Manager, die von Repositorymetadaten und nicht hartcodierten Zulassungslisten gesteuert werden.

Funktionsweise von benutzerdefinierten Eigenschaftenanforderungen

Der Ablauf für die Verwendung benutzerdefinierter Eigenschaften als OIDC-Ansprüche ist wie folgt:

       **Definieren sie benutzerdefinierte Eigenschaften.** Ein Administrator einer Organisation oder eines Unternehmens erstellt benutzerdefinierte Eigenschaften (z. B. `business_unit`, `data_classification` oder `environment_tier`) und weist Repositorys Werte zu. Weitere Informationen findest du unter [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) und [AUTOTITLE](/actions/reference/security/oidc#including-repository-custom-properties-in-oidc-tokens).

       **Aktivieren sie Eigenschaften in OIDC-Token.** Ein Organisations- oder Unternehmensadministrator wählt aus, welche benutzerdefinierten Eigenschaften in OIDC-Token mit der Einstellungsbenutzeroberfläche oder der REST-API eingeschlossen werden sollen.

       **Ansprüche werden automatisch angezeigt.** Jeder Workflow-Durchlauf in einem Repository, für das ein Wert für eine aktivierte Eigenschaft festgelegt ist, enthält diesen Wert in seinem OIDC-Token, dem das Präfix "`repo_property_`" vorangestellt ist. Es sind keine Konfigurationsänderungen auf Workflowebene erforderlich.

       **Aktualisieren von Cloudvertrauensrichtlinien.** Sie aktualisieren die Vertrauensbedingungen Ihres Cloudanbieters, um die neuen `repo_property_*` Ansprüche auszuwerten, wodurch differenzierte, attributbasierte Zugriffsentscheidungen ermöglicht werden.

Da dies auf dem vorhandenen OIDC-Modell für kurzlebige Anmeldeinformationen von GitHub basiert, sind keine langlebigen geheimen Schlüssel erforderlich, und jedes Token wird pro Workflowdurchlauf abgesteckt, überprüfbar und automatisch erneuert.

Voraussetzungen

Benutzerdefinierte Eigenschaften müssen bereits auf der Organisation- oder Unternehmensebene definiert werden. Weitere Informationen finden Sie unter Verwalten von benutzerdefinierten Eigenschaften für Repositorys in Ihrer Organisation.
Sie müssen ein Organisationsadministrator oder Unternehmensadministrator sein.

Hinzufügen einer benutzerdefinierten Eigenschaft zu OIDC-Tokenansprüchen

Um eine benutzerdefinierte Eigenschaft in OIDC-Token einzuschließen, verwenden Sie die REST-API oder die Einstellungsbenutzeroberfläche für Ihre Organisation oder Ihr Unternehmen.

        **Verwenden der Einstellungs-UI:** Navigieren Sie zur Seite "Aktionen OIDC-Einstellungen" Ihrer Organisation oder Ihres Unternehmens, um anzuzeigen und zu verwalten, welche benutzerdefinierten Eigenschaften in OIDC-Token enthalten sind.

        **Verwenden der REST-API:** Senden Sie eine `POST` Anforderung an den `/orgs/{org}/actions/oidc/customization/properties/repo` Endpunkt, um den OIDC-Tokenansprüchen für Ihre Organisation eine benutzerdefinierte Eigenschaft hinzuzufügen. Informationen zu Anforderungsparametern und vollständigen Details finden Sie in der REST-API-Dokumentation zum Verwalten von benutzerdefinierten OIDC-Eigenschaften: [AUTOTITLE](/rest/actions/oidc).

Beispiel-OIDC-Token mit benutzerdefinierten Eigenschaften

Das folgende Beispiel zeigt ein OIDC-Token, das zwei benutzerdefinierte Eigenschaften enthält: eine Single-Select-Eigenschaft business_unit und eine Zeichenfolgeneigenschaft workspace_id. Jede benutzerdefinierte Eigenschaft wird im Token mit dem repo_property_ Präfix angezeigt.

{
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "aud": "https://github.com/my-org",
  "repository": "my-org/my-repo",
  "repository_owner": "my-org",
  "ref": "refs/heads/main",
  "repo_property_business_unit": "payments",
  "repo_property_workspace_id": "ws-abc123"
}

Sie können die Ansprüche in den repo_property_* Vertrauensbedingungen Ihres Cloudanbieters verwenden, um flexible, attributbasierte Zugriffssteuerungsrichtlinien zu erstellen. Weitere Informationen zum Anspruchsformat, unterstützten Eigenschaftstypen und Grenzwerten finden Sie unter OpenID Connect-Referenz.

OIDC-Unterstützung für Dependabot

          Dependabot kann OIDC verwenden, um sich bei privaten Registrys zu authentifizieren, wodurch die Notwendigkeit entfällt, langfristige Anmeldeinformationen als Repository-Geheimnisse zu speichern. Mit der OIDC-basierten Authentifizierung Dependabot können Aktualisierungsaufträge dynamisch kurzlebige Anmeldeinformationen von Ihrem Cloudidentitätsanbieter abrufen.

          Dependabot unterstützt die OIDC-Authentifizierung für jeden Registrierungstyp, der `username` und `password` Authentifizierung verwendet, wenn die Registrierung auf AWS CodeArtifact, Azure DevOps Artifacts oder JFrog Artifactory gehostet wird.

Die Vorteile der OIDC-Authentifizierung für Dependabot :

        **Erweiterte Sicherheit:** Entfernt statische, langlebige Anmeldeinformationen aus Ihren Repositorys.

        **Einfachere Verwaltung:** Ermöglicht den sicheren, richtlinienkonformen Zugriff auf private Registrierungen.

        **Vermeiden Sie die Ratenbegrenzung:** Dynamische Anmeldeinformationen helfen Ihnen, Geschwindigkeitsbeschränkungen zu vermeiden, die mit statischen Tokens verbunden sind.

Weitere Informationen finden Sie unter Konfigurieren des Zugriffs auf private Registrierungen für Dependabot.

Nächste Schritte

Weitere Informationen zum Konfigurieren von OIDC findest du unter Sicherheitshärtung deiner Bereitstellungen.

Referenzinformationen zu OIDC findest du unter OpenID Connect-Referenz.

In diesem Artikel