Verwenden von OpenID Connect mit wiederverwendbaren Workflows

Du kannst wiederverwendbare Workflows mit OIDC verwenden, um deine Bereitstellungsschritte zu standardisieren und festzuschreiben.

In diesem Artikel

Note

Auf GitHub gehostete Runner werden aktuell nicht auf GitHub Enterprise Server unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

Informationen zu wiederverwendbaren Workflows

Anstatt Bereitstellungsaufträge zu kopieren und von einem Workflow in einen anderen einzufügen, kannst du einen wiederverwendbaren Workflow erstellen, der die Bereitstellungsschritte ausführt. Ein wiederverwendbarer Workflow kann von einem anderen Workflow genutzt werden, wenn er eine der in Wiederverwenden von Workflows beschriebenen Zugriffsanforderungen erfüllt.

Du solltest mit den Konzepten vertraut sein, die unter Wiederverwenden von Workflows und Informationen zur Sicherheitshärtung mit OpenID Connect beschrieben werden.

Definieren der Vertrauensbedingungen

Wenn du wiederverwendbare Workflows in Kombination mit OpenID Connect (OIDC) verwendest, kannst du konsistente Bereitstellungen in deinem Repository, deiner Organisation oder deinem Unternehmen erzwingen. Dies erreichst du durch das Definieren von Vertrauensbedingungen für Cloudrollen basierend auf wiederverwendbaren Workflows. Die verfügbaren Optionen variieren je nach verwendetem Cloudanbieter:

  • Verwenden von job_workflow_ref:

    • Um Vertrauensbedingungen auf der Grundlage wiederverwendbarer Workflows zu erstellen, muss dein Cloudanbieter benutzerdefinierte Ansprüche für job_workflow_ref unterstützen. Dadurch kann dein Cloudanbieter identifizieren, von welchem Repository der Auftrag ursprünglich stammt.
    • Für Clouds, die nur die Standardansprüche (Zielgruppe (aud) und Antragsteller (sub)) unterstützen, kannst du die API verwenden, um den Anspruch sub so anzupassen, dass er job_workflow_ref enthält. Weitere Informationen finden Sie unter Informationen zur Sicherheitshärtung mit OpenID Connect. Unterstützung für benutzerdefinierte Ansprüche ist derzeit für Google Cloud Platform und HashiCorp Vault verfügbar.

  • Anpassen der Tokenansprüche:

Funktionsweise des Tokens mit wiederverwendbaren Workflows

Während einer Workflowausführung stellt der OIDC-Anbieter von GitHub ein OIDC-Token für den Cloudanbieter bereit, das Informationen zum Auftrag enthält. Wenn dieser Auftrag Teil eines wiederverwendbaren Workflows ist, enthält das Token die Standardansprüche, die Informationen zum aufrufenden Workflow enthalten. Außerdem umfasst es den benutzerdefinierten Anspruch job_workflow_ref, der Informationen zum aufgerufenen Workflow enthält.

Das folgende OIDC-Token ist beispielsweise für einen Auftrag konzipiert, der Teil eines aufgerufenen Workflows war. workflow, ref und andere Attribute beschreiben den aufrufenden Workflow, während job_workflow_ref sich auf den aufgerufenen Workflow bezieht:

YAML
{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo: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_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "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
}

Wenn dein wiederverwendbarer Workflow Bereitstellungsschritte ausführt, benötigt er in der Regel Zugriff auf eine bestimmte Cloudrolle, und du musst allen Repositorys in deiner Organisation das Aufrufen dieses wiederverwendbaren Workflows erlauben. Erstelle hierzu die Vertrauensbedingung, die jedes Repository und jeden aufrufenden Workflow zulässt, und filtere dann nach der Organisation und dem aufgerufenen Workflow. Im nächsten Abschnitt findest du einige Beispiele.

Beispiele

Filtern nach wiederverwendbaren Workflows innerhalb eines bestimmten Repositorys

Du kannst einen benutzerdefinierten Anspruch konfigurieren, der nach jedem wiederverwendbaren Workflow in einem bestimmten Repository filtern kann. In diesem Beispiel muss die Workflowausführung von einem Auftrag stammen, der in einem wiederverwendbaren Workflow im Repository octo-org/octo-automation und in jedem Repository im Besitz der Organisation octo-org definiert ist.

  • Antragsteller:

    • Syntax: repo:ORG_NAME/*
    • Beispiel: repo:octo-org/*

  • Benutzerdefinierter Anspruch:

    • Syntax: job_workflow_ref:ORG_NAME/REPO_NAME
    • Beispiel: job_workflow_ref:octo-org/octo-automation@*

Filtern nach einem bestimmten wiederverwendbaren Workflow in einem bestimmten Verweis

Du kannst einen benutzerdefinierten Anspruch konfigurieren, der nach einem bestimmten wiederverwendbaren Workflow filtert. In diesem Beispiel muss die Workflowausführung von einem Auftrag stammen, der im wiederverwendbaren Workflow octo-org/octo-automation/.github/workflows/deployment.yml und in jedem Repository im Besitz der Organisation octo-org definiert ist.

  • Antragsteller:

    • Syntax: repo:ORG_NAME/*
    • Beispiel: repo:octo-org/*

  • Benutzerdefinierter Anspruch:

    • Syntax: job_workflow_ref:ORG_NAME/REPO_NAME/.github/workflows/WORKFLOW_FILE@ref
    • Beispiel: job_workflow_ref:octo-org/octo-automation/.github/workflows/deployment.yml@ 10040c56a8c0253d69db7c1f26a0d227275512e2