Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.
Ü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:
- Erstelle in deinem Cloudanbieter eine OIDC-Vertrauensstellung zwischen deiner Cloudrolle und deinen GitHub-Workflows, die Zugriff auf die Cloud benötigen.
- 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.
- 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.
- 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. Einige Beispiele findest du unter Beispiele für Antragstelleransprüche.
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.
Anspruch | Anspruchstyp | BESCHREIBUNG |
---|---|---|
aud | Zielgruppe | Standardmäßig ist dies die URL des Repositorybesitzers, z. B. die Organisation, die das Repository besitzt. Du kannst eine benutzerdefinierte Zielgruppe mit einem Toolkitbefehl festlegen: core.getIDToken(audience) |
iss | Issuer (Aussteller) | Der Aussteller des OIDC-Tokens: https://HOSTNAME/_services/token |
sub | Subject | Definiert den Antragstelleranspruch, der vom Cloudanbieter überprüft werden soll. Diese Einstellung ist wichtig, um sicherzustellen, dass Zugriffstoken nur auf vorhersehbare Weise zugewiesen werden. |
Das OIDC-Token enthält auch zusätzliche Standard-JOSE-Header-Parameter und -Ansprüche.
Header-Parameter | Parametertyp | Beschreibung |
---|---|---|
alg | Algorithmus | Der Algorithmus, der vom OIDC-Anbieter verwendet wird |
kid | Schlüsselbezeichner | Eindeutiger Schlüssel des OIDC-Tokens |
typ | type | Beschreibt den Tokentyp. Dies ist ein JSON Web Token (JWT). |
Anspruch | Anspruchstyp | Beschreibung |
---|---|---|
exp | Ablaufzeit | Identifiziert die Ablaufzeit des JWT |
iat | Ausgestellt um | Der Zeitpunkt, zu dem das JWT ausgestellt wurde. |
jti | JWT-Tokenbezeichner | Eindeutiger Bezeichner des OIDC-Tokens |
nbf | Nicht vor | JWT ist vor diesem Zeitpunkt nicht gültig für die Verwendung. |
Das Token enthält auch benutzerdefinierte Ansprüche, die von GitHub bereitgestellt werden.
Anspruch | BESCHREIBUNG |
---|---|
actor | Das persönliche Konto, das die Workflowausführung ausgelöst hat. |
actor_id | Die ID des persönlichen Kontos, das die Workflowausführung ausgelöst hat. |
base_ref | Der Zielbranch des Pull Requests in einer Workflowausführung. |
enterprise | Der Name des Unternehmens, das das Repository enthält, über das der Workflow ausgeführt wird. |
enterprise_id | Die ID des Unternehmens, das das Repository enthält, von dem aus der Workflow ausgeführt wird. |
environment | Der Name der vom Auftrag verwendeten Umgebung. Wenn der environment -Anspruch enthalten ist (auch über include_claim_keys ), ist eine Umgebung erforderlich und muss bereitgestellt werden. |
event_name | Der Name des Ereignisses, das den Workflow-Lauf ausgelöst hat. |
head_ref | Der Quellbranch des Pull Requests in einer Workflowausführung. |
job_workflow_ref | Bei Aufträgen, die einen wiederverwendbaren Workflow verwenden, ist dies der Verweispfad zum wiederverwendbaren Workflow. Weitere Informationen findest du unter Verwenden von OpenID Connect mit wiederverwendbaren Workflows. |
job_workflow_sha | Bei Aufträgen, die einen wiederverwendbaren Workflow verwenden, wird der Commit-SHA für die wiederverwendbare Workflowdatei verwendet. |
ref | (Referenz) Die Git-Ref, die die Workflowausführung ausgelöst hat. |
ref_type | Der ref -Typ, z. B. „Branch“. |
repository_visibility | Die Sichtbarkeit des Repositorys, in dem der Workflow ausgeführt wird. Akzeptiert die folgenden Werte: internal , private oder public . |
repository | Das Repository, aus dem der Workflow ausgeführt wird. |
repository_id | Das Repository, über das der Workflow ausgeführt wird. |
repository_owner | Der Name der Organisation, in der das repository gespeichert wird. |
repository_owner_id | Die ID der Organisation, in der das repository gespeichert wird. |
run_id | Die ID der Workflowausführung, die den Workflow ausgelöst hat. |
run_number | Die Angabe, wie oft dieser Workflow ausgeführt wurde. |
run_attempt | Die Angabe, wie oft diese Workflowausführung wiederholt wurde. |
runner_environment | Der vom Auftrag verwendete Runner-Typ. Akzeptiert die folgenden Werte: github-hosted oder self-hosted . |
workflow | Der Name des Workflows. |
workflow_ref | Der Verweispfad zum Workflow. Beispiel: octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch . |
workflow_sha | Der Commit-SHA für die Workflowdatei. |
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 des 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.
Hinweis: Zur Steuerung, wie dein Cloudanbieter Zugriffstoken ausgibt, musst du mindestens eine Bedingung definieren, damit nicht vertrauenswürdige Repositorys keine Zugriffstoken für deine Cloudressourcen anfordern können.
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:
Cloudanbieter | Beispiel |
---|---|
Amazon Web Services | "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch" |
Azure | repo:octo-org/octo-repo:ref:refs/heads/demo-branch |
Google Cloud Platform | (assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch') |
HashiCorp Vault | bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch" |
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.
Variable | BESCHREIBUNG |
---|---|
ACTIONS_ID_TOKEN_REQUEST_URL | Die URL für den OIDC-Anbieter von GitHub. |
ACTIONS_ID_TOKEN_REQUEST_TOKEN | Bearertoken für die Anforderung an den OIDC-Anbieter. |
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 write
gesetzt 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
undACTIONS_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. Siehe „Anpassen desaudience
-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
undrepository_visibility
verwendest. Siehe „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 findest du 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. Um die übereinstimmende Bedingung für GitHub zu konfigurieren, 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 findest du unter REST-API-Endpunkte für GitHub Actions OIDC.
Hinweis: Wenn die Organisationsvorlage angewendet wird, wirkt sie sich nicht auf Workflows aus, die bereits OIDC nutzen, es sei denn, für das zugehörige Repository sind benutzerdefinierte Organisationsvorlagen aktiviert. Für alle vorhandenen und neuen Repositorys muss der Repositorybesitzer die REST-API auf Repositoryebene verwenden, um den Empfang dieser Konfiguration durch Einstellung von use_default
auf false
zu aktivieren. Alternativ können Repositorybesitzer*innen die REST-API verwenden, um eine andere Konfiguration speziell für das Repository anzuwenden. Weitere Informationen findest du 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, welches das vordefinierte sub
-Standardformat in dem unter Informationen zur Sicherheitshärtung mit OpenID Connect beschriebenen Token ersetzt.
Hinweis: Der sub
-Anspruch verwendet das gekürzte Formular repo
(z. B repo:ORG-NAME/REPO-NAME
) anstelle von repository
, um auf das Repository zu verweisen.
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 ein Repository zu deaktivieren und auf das standardmäßige sub
-Claim-Format 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 findest du 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:
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.