Informationen zur Sicherheitshärtung mit OpenID Connect

Übersicht über OpenID Connect

GitHub Actions-Workflows sind häufig für den Zugriff auf einen Cloudanbieter (z. B. AWS, Azure, GCP oder HashiCorp Vault) ausgelegt, 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 Geheimnis in GitHub gespeichert, und der Workflow stellt dieses Geheimnis bei jeder Ausführung für den Cloudanbieter bereit.

Die Verwendung von hart codierten Geheimnissen erfordert jedoch, dass du Anmeldeinformationen im Cloudanbieter erstellst und dann als Geheimnis in GitHub duplizierst.

Mit OpenID Connect (OIDC) kannst du einen anderen Ansatz verfolgen, indem du deinen Workflow so konfigurierst, dass ein kurzlebiges Zugriffstoken direkt vom Cloudanbieter angefordert wird. Dein Cloudanbieter muss auch OIDC auf seiner Seite unterstützen, und du musst eine Vertrauensstellung konfigurieren, die steuert, welche Workflows die Zugriffstoken anfordern können. Zu den Anbietern, die derzeit OIDC unterstützen, gehören Amazon Web Services, Azure, Google Cloud Platform und HashiCorp Vault.

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 Cloudgeheimnisse: Du musst deine Cloudanmeldeinformationen nicht als langlebige GitHub-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.

Erste Schritte mit OIDC

Das folgende Diagramm enthält einen Überblick darüber, wie der OIDC-Anbieter von GitHub mit deinen Workflows und dem Cloudanbieter integriert ist:

1. Erstelle in deinem Cloudanbieter eine OIDC-Vertrauensstellung zwischen deiner Cloudrolle und deinen GitHub-Workflows, die Zugriff auf die Cloud benötigen.
2. Jedes Mal, wenn dein Auftrag ausgeführt wird, generiert der OIDC-Anbieter von GitHub 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.
3. Du kannst einen Schritt oder eine Aktion in deinem Auftrag einschließen, um dieses Token vom OIDC-Anbieter von GitHub anzufordern und es für den Cloudanbieter bereitzustellen.
4. 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.

Konfigurieren der OIDC-Vertrauensstellung mit der Cloud

Wenn du deine Cloud so konfigurierst, dass sie dem OIDC-Anbieter von GitHub vertraut, musst du Bedingungen hinzufügen, die eingehende Anforderungen filtern, sodass nicht vertrauenswürdige Repositorys oder Workflows keine 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. Daher musst du darauf achten, den Antragsteller und andere Bedingungen in deinem Cloudanbieter ordnungsgemäß zu definieren.
• Die OIDC-Konfigurationsschritte und die Syntax zum Festlegen von Bedingungen für Cloudrollen (mit Antragsteller und anderen Ansprüchen) variieren je nach dem von Ihnen verwendeten Cloudanbieter. Unter Beispiele für Antragstelleransprüche findest du einige Beispiele.

Grundlegendes zum OIDC-Token

Jeder Auftrag fordert ein OIDC-Token vom OIDC-Anbieter von GitHub an, der mit einem automatisch generierten JSON-Webtoken (JWT) reagiert, das für jeden Workflowauftrag, in dem es generiert wird, eindeutig ist. 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://HOSTNAME/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",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://HOSTNAME/_services/token",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

Zum Anzeigen aller Ansprüche, die vom OIDC-Anbieter von GitHub unterstützt werden, lies die claims_supported-Einträge unter https://HOSTNAME/_services/token/.well-known/openid-configuration.

Das Token umfasst die Standardzielgruppe, den Aussteller und die Antragstelleransprüche.

Das OIDC-Token enthält auch zusätzliche Standard-JOSE-Header-Parameter und -Ansprüche.

Das Token enthält auch benutzerdefinierte Ansprüche, die von GitHub bereitgestellt werden.

Definieren von Vertrauensbedingungen für Cloudrollen mithilfe von OIDC-Ansprüchen

Bei OIDC erfordert ein GitHub Actions-Workflow ein Token, um auf Ressourcen in deinem Cloudanbieter zuzugreifen. Der Workflow fordert ein Zugriffstoken von deinem Cloudanbieter an, das die Details überprüft, die vom JWT dargestellt werden. Wenn die Vertrauenskonfiguration im JWT übereinstimmt, reagiert dein Cloudanbieter mit der Ausgabe eines temporären Tokens für den Workflow, das dann für den Zugriff auf Ressourcen in deinem Cloudanbieter verwendet werden kann. Der Cloudanbieter kann so konfiguriert werden, dass nur auf Anforderungen reagiert wird, die aus dem Repository einer bestimmten Organisation stammen. Es können auch zusätzliche Bedingungen angeben werden, die unten beschrieben sind.

Zielgruppen- und Antragstelleransprüche werden in der Regel zusammen verwendet, während die Bedingungen für die Cloudrolle/Ressourcen festgelegt werden, um den Zugriff auf die GitHub-Workflows zu beschränken.

• Zielgruppe: Standardmäßig verwendet dieser Wert die URL der Organisation oder des Repositorybesitzers. Damit kann eine Bedingung festgelegt werden, nach der nur die Workflows in der bestimmten Organisation auf die Cloudrolle zugreifen können.
• Antragsteller: Verfügt standardmäßig über ein vordefiniertes Format und ist eine Verkettung einiger der wichtigsten Metadaten zum Workflow, z. B. die GitHub-Organisation, Repository, Branch oder zugehörige job-Umgebung. Unter Beispiele für Antragstelleransprüche wird dargestellt, wie der Antragstelleranspruch aus verketteten Metadaten zusammengefügt wird.

Wenn präzisere Vertrauensbedingungen benötigt werden, können die Angaben angepasst werden zu Ansprüchen des Antragstellers (sub) der enthalten ist im JWT. Weitere Informationen findest du unter Anpassen der Tokenansprüche.

Es gibt viele zusätzliche Ansprüche, die im OIDC-Token unterstützt werden und zum Festlegen dieser Bedingungen verwendet werden können. Darüber hinaus könnte dein Cloudanbieter zulassen, dass du den Zugriffstoken eine Rolle zuweist, sodass du noch genauere Berechtigungen angeben kannst.

Beispiele für Antragstelleransprüche

Die folgenden Beispiele veranschaulichen, wie du „Antragsteller“ als Bedingung verwendest, und erläutern, wie „Antragsteller“ aus verketteten Metadaten zusammengefügt wird. Der Antragsteller verwendet Informationen aus dem job Kontext und weist deinen Cloudanbieter an, dass Zugriffstokenanforderungen nur für Anforderungen aus Workflows gewährt werden, die in bestimmten Branches und Umgebungen ausgeführt werden. In den folgenden Abschnitten werden einige allgemeine Antragsteller beschrieben, die du verwenden kannst.

Filtern nach einer bestimmten Umgebung

Der Antragstelleranspruch umfasst den Umgebungsnamen, wenn der Auftrag auf eine Umgebung verweist.

Du kannst einen Antragsteller konfigurieren, der nach einem bestimmten Umgebungsnamen filtert. In diesem Beispiel muss die Workflowausführung aus einem Auftrag stammen, der eine Umgebung namens Production in einem Repository namens octo-repo hat, das der Organisation octo-org:

• Syntax: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
• Beispiel: repo:octo-org/octo-repo:environment:Production

Filtern nach pull_request-Ereignissen

Der Antragstelleranspruch enthält die Zeichenfolge pull_request, wenn der Workflow durch ein Pull Request-Ereignis ausgelöst wird, aber nur, wenn der Auftrag nicht auf eine Umgebung verweist.

Du kannst einen Antragsteller konfigurieren, der nach dem pull_request-Ereignis filtert. In diesem Beispiel muss die Workflowausführung durch ein pull_request-Ereignis in einem Repository namens octo-repo ausgelöst worden sein, das der Organisation octo-org gehört:

• Syntax: repo:ORG-NAME/REPO-NAME:pull_request
• Beispiel: repo:octo-org/octo-repo:pull_request

Filtern nach einem bestimmten Branch

Der Antragstelleranspruch enthält den Branchnamen des Workflows, aber nur, wenn der Auftrag nicht auf eine Umgebung verweist und wenn der Workflow nicht durch ein Pull Request-Ereignis ausgelöst wird.

Du kannst einen Antragsteller konfigurieren, der nach einem bestimmten Branchnamen filtert. In diesem Beispiel muss die Workflowausführung aus einem Branch namens demo-branch in einem Repository namens octo-repo ausgelöst worden sein, das der Organisation octo-org gehört:

• Syntax: repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME
• Beispiel: repo:octo-org/octo-repo:ref:refs/heads/demo-branch

Filtern nach einem bestimmten Tag

Der Antragstelleranspruch enthält den Tagnamen des Workflows, aber nur, wenn der Auftrag nicht auf eine Umgebung verweist und wenn der Workflow nicht durch ein Pull Request-Ereignis ausgelöst wird.

Du kannst einen Antragsteller erstellen, der nach einem bestimmten Tag filtert. In diesem Beispiel muss die Workflowausführung mit einem Tag namens demo-tag in einem Repository namens octo-repo ausgelöst worden sein, das der Organisation octo-org gehört:

• Syntax: repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
• Beispiel: repo:octo-org/octo-repo:ref:refs/tags/demo-tag

Konfigurieren des Antragstellers bei deinem Cloudanbieter

Für die Konfiguration des Antragstellers in der Vertrauensstellung deines Cloudanbieters musst du der vertrauenswürdigen Konfiguration die Antragstellerzeichenfolge hinzufügen. In den folgenden Beispielen wird veranschaulicht, wie verschiedene Cloudanbieter denselben Antragsteller repo:octo-org/octo-repo:ref:refs/heads/demo-branch auf unterschiedliche Weise akzeptieren können:

Weitere Informationen findest du in den Leitfäden unter Aktivieren von OpenID Connect für deinen Cloudanbieter.

Aktualisieren deiner Aktionen für OIDC

Für die Aktualisierung deiner benutzerdefinierten Aktionen zur Authentifizierung mithilfe von OIDC kannst du getIDToken() aus dem Actions-Toolkit verwenden, um ein JWT vom OIDC-Anbieter von GitHub anzufordern. Weitere Informationen findest du unter „OIDC-Token“ in der Dokumentation für das npm-Paket.

Du kannst auch einen curl-Befehl verwendest, um die JWT anzufordern, indem du die folgenden Umgebungsvariablen verwendest.

Beispiel:

curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"

curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"

Hinzufügen von Berechtigungseinstellungen

Der Auftrag oder die Workflowausführung erfordert eine permissions-Einstellung mit id-token: write, die es dem OIDC-Anbieter von GitHub erlaubt, für jeden Lauf ein JSON-Web-Token zu erstellen. Sie können das OIDC JWT ID-Token nicht anfordern, wenn permissions für id-token nicht auf writegesetzt ist. Dieser Wert bedeutet jedoch nicht, dass Sie Schreibzugriff auf Ressourcen erhalten, sondern nur, dass Sie das OIDC-Token für eine Aktion oder einen Schritt abrufen und setzen können, um die Authentifizierung mit einem kurzlebigen Zugriffstoken zu ermöglichen. Jede tatsächliche Vertrauenseinstellung wird mithilfe von OIDC-Ansprüchen definiert, weitere Informationen finden Sie unter "Informationen zur Sicherheitshärtung mit OpenID Connect".

Mit der Einstellung id-token: write kann der JWT von GitHub-OIDC-Anbieter mit einer der folgenden Ansätze angefordert werden:

• Verwenden von Umgebungsvariablen auf dem Runner (ACTIONS_ID_TOKEN_REQUEST_URL und ACTIONS_ID_TOKEN_REQUEST_TOKEN).
• Verwenden von getIDToken() aus dem Actions-Toolkit.

Wenn du ein OIDC-Token für einen Workflow abrufen musst, können die Berechtigungen auf Workflowebene festgelegt werden. Beispiel:

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

Wenn Du nur ein OIDC-Token für einen einzelnen Auftrag abrufen musst, kann diese Berechtigung innerhalb dieses Auftrags festgelegt werden. Zum Beispiel:

permissions:
  id-token: write # This is required for requesting the JWT

permissions:
  id-token: write # This is required for requesting the JWT

Möglicherweise müssen Sie hier zusätzliche Berechtigungen angeben, abhängig von den Anforderungen Ihres Workflows.

Für wiederverwendbare Workflows, die sich im Besitz desselben Benutzers bzw. derselben Benutzerin, derselben Organisation oder desselben Unternehmens wie der Aufruferworkflow befinden, kann aus dem Kontext des Aufrufers auf das im wiederverwendbaren Workflow generierte OIDC-Token zugegriffen werden. Für wiederverwendbare Workflows außerhalb des Unternehmens oder der Organisation muss die permissions-Einstellung für id-token auf Aufruferworkflowebene oder in dem bestimmten Auftrag, der den wiederverwendbaren Workflow aufruft, explizit auf write festgelegt werden. Dadurch wird sichergestellt, dass das im wiederverwendbaren Workflow generierte OIDC-Token nur dann in den Workflows der Aufrufer genutzt werden darf, wenn dies vorgesehen ist.

Weitere Informationen findest du unter Wiederverwenden von Workflows.

Anpassen der Tokenansprüche

Du kannst die Sicherheit deiner OIDC-Konfiguration verbessern, indem du die Ansprüche anpasst, die im JWT enthalten sind. Mit diesen Anpassungen kannst du detailliertere Vertrauensbedingungen für deine Cloudrollen definieren, wenn du deinen Workflows den Zugriff auf in der Cloud gehostete Ressourcen gestattest:

• Du kannst Werte für audience-Ansprüche anpassen. Weitere Informationen findest du unter Anpassen des audience-Werts.
• Du kannst das Format deiner OIDC-Konfiguration anpassen, indem du Bedingungen für den Antragstelleranspruch (sub) festlegst, die erfordern, dass JWT-Token aus einem bestimmten Repository, einem wiederverwendbaren Workflow oder einer anderen Quelle stammen.
• Du kannst detaillierte OIDC-Richtlinien definieren, indem du zusätzliche OIDC-Tokenansprüche wie z. B. repository_id und repository_visibility verwendest. Weitere Informationen findest du unter Grundlegendes zum OIDC-Token.

Anpassen des audience-Werts

Wenn du benutzerdefinierte Aktionen in deinen Workflows verwendest, können diese Aktionen das GitHub Actions-Toolkit verwenden, damit du einen benutzerdefinierten Wert für den audience-Anspruch angeben kannst. Einige Cloudanbieter verwenden dies auch in ihren offiziellen Anmeldeaktionen, um einen Standardwert für den audience-Anspruch zu erzwingen. Die GitHub Action für die Azure-Anmeldung bietet beispielsweise einen Standard-aud-Wert von api://AzureADTokenExchange, oder ermöglicht dir, einen benutzerdefinierten aud-Wert in deinen Workflows festzulegen. Weitere Informationen zum GitHub Actions-Toolkit findest du in der Dokumentation im Abschnitt OIDC-Token.

Wenn du den von einer Aktion angebotenen Standard-aud-Wert nicht verwenden möchtest, kannst du einen benutzerdefinierten Wert für den audience-Anspruch angeben. Damit kannst du eine Bedingung festlegen, nach der nur die Workflows in einem bestimmten Repository oder einer bestimmten Organisation auf die Cloudrolle zugreifen können. Wenn die von dir verwendete Aktion dies unterstützt, kannst du das with-Schlüsselwort in deinem Workflow verwenden, um einen benutzerdefinierten aud-Wert an die Aktion zu übergeben. Weitere Informationen finden Sie unter Metadatensyntax für GitHub Actions.

Anpassen der Antragstelleransprüche für eine Organisation oder ein Repository

Um Sicherheit, Compliance und Standardisierung zu verbessern, kannst du die Standardansprüche an deine erforderlichen Zugriffsbedingungen anpassen. Wenn dein Cloudanbieter Bedingungen für Antragstelleransprüche unterstützt, kannst du eine Bedingung erstellen, die überprüft, ob der sub-Wert dem Pfad des wiederverwendbaren Workflows entspricht, z. B. "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main". Das genaue Format variiert je nach OIDC-Konfiguration deines Cloudanbieters. Für die Konfiguration der übereinstimmenden Bedingung für GitHub kannst du die REST-API verwenden, um zu verlangen, dass der sub-Anspruch immer einen bestimmten benutzerdefinierten Anspruch enthalten muss, z. B. job_workflow_ref. Du kannst mithilfe der REST-API eine Anpassungsvorlage auf den OIDC-Antragstelleranspruch anwenden. So kannst du beispielsweise festlegen, dass der sub-Anspruch innerhalb des OIDC-Tokens immer einen bestimmten benutzerdefinierten Anspruch (wie z. B. job_workflow_ref) enthalten muss. Weitere Informationen finden Sie unter REST-API-Endpunkte für GitHub Actions OIDC.

Das Anpassen der Ansprüche führt zu einem neuen Format für den gesamten sub-Anspruch, das das vordefinierte sub-Standardformat in dem unter Informationen zur Sicherheitshärtung mit OpenID Connect beschriebenen Token ersetzt.

In den folgenden Beispielvorlagen werden verschiedene Möglichkeiten zum Anpassen des Antragstelleranspruchs veranschaulicht. Zum Konfigurieren dieser Einstellungen für GitHub geben Organisationsadministratoren mithilfe der REST-API eine Liste der Ansprüche an, die in den Antragstelleranspruch (sub) einbezogen werden müssen.

Um diese Konfiguration anzuwenden, übermittle eine Anforderung an den API-Endpunkt, und schließe die erforderliche Konfiguration in den Anforderungstext ein. Informationen zu Organisationen findest du unter „REST-API-Endpunkte für GitHub Actions OIDC“ und Informationen zu Repositorys unter „REST-API-Endpunkte für GitHub Actions OIDC“.

Um deine Antragstelleransprüche anzupassen, solltest du zuerst eine Vergleichsbedingung in der OIDC-Konfiguration deines Cloudanbieters erstellen, bevor du die Konfiguration mithilfe der REST-API anpasst. Sobald die Konfiguration abgeschlossen ist, folgt bei jeder Ausführung eines neuen Auftrags das während dieses Auftrags generierte OIDC-Token der neuen Anpassungsvorlage. Wenn die Vergleichsbedingung vor der Ausführung des Auftrags nicht in der OIDC-Konfiguration des Cloudanbieters vorhanden ist, wird das generierte Token möglicherweise nicht vom Cloudanbieter akzeptiert, weil die Cloudbedingungen möglicherweise nicht synchronisiert wurden.

Beispiel: Zulassen des Repositorys basierend auf Sichtbarkeit und Besitzer

In dieser Beispielvorlage kann der sub-Anspruch ein neues Format aufweisen, das repository_owner und repository_visibility verwendet:

{
   "include_claim_keys": [
       "repository_owner",
       "repository_visibility"
   ]
}

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um anzugeben, dass Ansprüche bestimmte Werte für repository_owner und repository_visibility aufweisen müssen. Beispiel: "sub": "repository_owner:monalisa:repository_visibility:private" Mit dem Ansatz kannst du den Cloudrollenzugriff auf private Repositorys innerhalb einer Organisation oder eines Unternehmens beschränken.

Beispiel: Zulassen des Zugriffs auf alle Repositorys mit einem bestimmten Besitzer

Durch diese Beispielvorlage kann der sub-Anspruch ein neues Format nur mit dem Wert von repository_owner aufweisen.

Um diese Konfiguration anzuwenden, übermittle eine Anforderung an den API-Endpunkt, und schließe die erforderliche Konfiguration in den Anforderungstext ein. Informationen zu Organisationen findest du unter „REST-API-Endpunkte für GitHub Actions OIDC“ und Informationen zu Repositorys unter „REST-API-Endpunkte für GitHub Actions OIDC“.

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um anzugeben, dass Ansprüche einen bestimmten Wert für repository_owner aufweisen müssen. Beispiel: "sub": "repository_owner:monalisa"

Beispiel: Erfordern eines wiederverwendbaren Workflows

In dieser Beispielvorlage kann der sub-Anspruch ein neues Format aufweisen, das den Wert des job_workflow_ref-Anspruchs enthält. Dadurch kann ein Unternehmen wiederverwendbare Workflows verwenden, um konsistente Bereitstellungen in allen eigenen Organisationen und Repositorys zu erzwingen.

Um diese Konfiguration anzuwenden, übermittle eine Anforderung an den API-Endpunkt, und schließe die erforderliche Konfiguration in den Anforderungstext ein. Informationen zu Organisationen findest du unter „REST-API-Endpunkte für GitHub Actions OIDC“ und Informationen zu Repositorys unter „REST-API-Endpunkte für GitHub Actions OIDC“.

  {
     "include_claim_keys": [
         "job_workflow_ref"
     ]
  }

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um anzugeben, dass Ansprüche einen bestimmten Wert für job_workflow_ref aufweisen müssen. Beispiel: "sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"

Beispiel: Anfordern eines wiederverwendbaren Workflows und anderer Ansprüche

Die folgende Beispielvorlage kombiniert die Anforderung eines bestimmten wiederverwendbaren Workflows mit zusätzlichen Ansprüchen.

Um diese Konfiguration anzuwenden, übermittle eine Anforderung an den API-Endpunkt, und schließe die erforderliche Konfiguration in den Anforderungstext ein. Informationen zu Organisationen findest du unter „REST-API-Endpunkte für GitHub Actions OIDC“ und Informationen zu Repositorys unter „REST-API-Endpunkte für GitHub Actions OIDC“.

In diesem Beispiel wird auch veranschaulicht, wie "context" zum Definieren deiner Bedingungen verwendet werden kann. Dies ist der Teil, der dem Repository im sub-Standardformat folgt. Wenn der Auftrag beispielsweise auf eine Umgebung verweist, enthält der Kontext Folgendes: environment:ENVIRONMENT-NAME.

{
   "include_claim_keys": [
       "repo",
       "context",
       "job_workflow_ref"
   ]
}

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um anzugeben, dass Ansprüche bestimmte Werte für repo, context und job_workflow_ref aufweisen müssen.

Diese Anpassungsvorlage erfordert, dass der sub-Anspruch das folgende Format verwendet: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH. Beispiel: "sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"

Beispiel: Gewähren des Zugriffs auf ein bestimmtes Repository

In dieser Beispielvorlage kannst du für alle Branches/Tags und Umgebungen cloudbasierten Zugriff auf alle Workflows in einem bestimmten Repository gewähren.

Um diese Konfiguration anzuwenden, übermittle eine Anforderung an den API-Endpunkt, und schließe die erforderliche Konfiguration in den Anforderungstext ein. Informationen zu Organisationen findest du unter „REST-API-Endpunkte für GitHub Actions OIDC“ und Informationen zu Repositorys unter „REST-API-Endpunkte für GitHub Actions OIDC“.

{
   "include_claim_keys": [
       "repo"
   ]
}

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um einen repo-Anspruch zu verlangen, der dem erforderlichen Wert entspricht.

Beispiel: Verwenden systemgenerierter GUIDs

Diese Beispielvorlage ermöglicht vorhersagbare OIDC-Ansprüche mit systemgenerierten GUIDs, die bei der Umbenennung von Entitäten (z. B. beim Umbenennen eines Repositorys) unverändert bleiben.

Um diese Konfiguration anzuwenden, übermittle eine Anforderung an den API-Endpunkt, und schließe die erforderliche Konfiguration in den Anforderungstext ein. Informationen zu Organisationen findest du unter „REST-API-Endpunkte für GitHub Actions OIDC“ und Informationen zu Repositorys unter „REST-API-Endpunkte für GitHub Actions OIDC“.

  {
     "include_claim_keys": [
         "repository_id"
     ]
  }

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um einen repository_id-Anspruch zu verlangen, der dem erforderlichen Wert entspricht.

oder:

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um einen repository_owner_id-Anspruch zu verlangen, der dem erforderlichen Wert entspricht.

Zurücksetzen der Anpassungen von Organisationsvorlagen

In dieser Beispielvorlage werden die Antragstelleransprüche auf das Standardformat zurückgesetzt. Mit dieser Vorlage werden alle Anpassungsrichtlinien auf Organisationsebene außer Kraft gesetzt.

Um diese Konfiguration anzuwenden, übermittle eine Anforderung an den API-Endpunkt, und schließe die erforderliche Konfiguration in den Anforderungstext ein. Informationen zu Organisationen findest du unter „REST-API-Endpunkte für GitHub Actions OIDC“ und Informationen zu Repositorys unter „REST-API-Endpunkte für GitHub Actions OIDC“.

{
   "include_claim_keys": [
       "repo",
       "context"
   ]
}

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um anzugeben, dass Ansprüche bestimmte Werte für repo und context aufweisen müssen.

Zurücksetzen der Anpassungen von Repositoryvorlagen

Für alle Repositorys in einer Organisation können angepasste sub-Claim-Vorlagen (auf Organisations- und Repositoryebene) aktiviert oder deaktiviert werden.

Um das Abonnement eines Repositorys zu kündigen und auf das sub-Standardanspruchsformat zurückzusetzen, muss ein Repositoryadministrator den REST-API-Endpunkt unter REST-API-Endpunkte für GitHub Actions OIDC verwenden.

Um Repositorys zur Verwendung des standardmäßigen Anspruchsformats sub zu konfigurieren, verwenden Sie den PUT /repos/{owner}/{repo}/actions/oidc/customization/sub-REST-API-Endpunkt mit dem folgenden Anforderungstext.

{
   "use_default": true
}

Beispiel: Konfigurieren eines Repositorys für die Verwendung einer Organisationsvorlage

Sobald eine Organisation eine angepasste sub-Claim-Vorlage erstellt hat, kann die Vorlage mithilfe der REST-API programmgesteuert auf Repositorys in der Organisation angewendet werden. Ein Repositoryadministrator kann das Repository so konfigurieren, dass es die vom Administrator der Organisation erstellte Vorlage verwendet.

Um das Repository zur Verwendung der Organisationsvorlage zu konfigurieren, muss eine Repositoryadministratorin den PUT /repos/{owner}/{repo}/actions/oidc/customization/sub-REST-API-Endpunkt mit dem folgenden Anforderungstext festlegen. Weitere Informationen finden Sie unter REST-API-Endpunkte für GitHub Actions OIDC.

{
   "use_default": false
}

Aktualisieren deiner Workflows für OIDC

Du kannst jetzt deine YAML-Workflows aktualisieren, um OIDC-Zugriffstoken anstelle von Geheimnissen zu verwenden. Beliebte Cloudanbieter haben ihre offiziellen Anmeldeaktionen veröffentlicht, die es Ihnen erleichtern, mit OIDC zu beginnen. Weitere Informationen zum Aktualisieren deiner Workflows findest du in den cloudspezifischen Leitfäden unten unter Aktivieren von OpenID Connect für deinen Cloudanbieter.

Aktivieren von OpenID Connect für deinen Cloudanbieter

Informationen zum Aktivieren und Konfigurieren von OIDC für deinen spezifischen Cloudanbieter findest du in den folgenden Anleitungen:

• Konfigurieren von OpenID Connect in Amazon Web Services
• Konfigurieren von OpenID Connect in Azure
• Konfigurieren von OpenID Connect in Google Cloud Platform
• Konfigurieren von OpenID Connect in HashiCorp Vault

Informationen zum Aktivieren und Konfigurieren von OIDC für einen anderen Cloudanbieter findest du in der folgenden Anleitung:

• Konfigurieren von OpenID Connect in Cloudanbietern

Debuggen ihrer OIDC-Ansprüche

Sie können die github/actions-oidc-debugger-Aktion verwenden, um die Ansprüche zu visualisieren, die gesendet würden, bevor Sie mit einem Cloudanbieter integrieren. Diese Aktion fordert ein JWT an und druckt die in der JWT enthaltenen Ansprüche, die von GitHub Actions empfangen wurden.