OpenID Connect-Referenz

SAML-Tokenansprüche

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 OIDC-Token enthält die folgenden Ansprüche.

Standardzielgruppe, Aussteller und 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.

Zusätzliche Standard-JOSE-Headerparameter 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.

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 finden Sie unter Using OpenID Connect with reusable 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.

OIDC-Ansprüche zum Definieren von Vertrauensbedingungen für Cloudrollen

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:

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 zum Konfigurieren bestimmter Cloudanbieter findest du in den Anleitungen, die unter Sicherheitshärtung deiner Bereitstellungen aufgeführt sind.

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 OpenID Connect.

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 Referenz zur Metadatensyntax.

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, welches das vordefinierte sub-Standardformat in dem unter Beispiele für Antragstelleransprüche 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.

Beispiel: Kontextwert mit :

In diesem Beispiel wird veranschaulicht, wie mit einem Kontextwert mit einem :-Zeichen umgegangen wird. Dies ist der Fall, wenn der Auftrag beispielsweise auf eine Umgebung namens production:eastus verweist.

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": [
       "environment",
       "repository_owner"
   ]
}

Konfiguriere in der OIDC-Konfiguration deines Cloudanbieters die sub-Bedingung, um anzugeben, dass Ansprüche einen bestimmten Wert für environment und repository_owner aufweisen müssen. Beispiel: "sub": "environment:production%3Aeastus:repository_owner:octo-org"

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
}

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.

Workflowberechtigungen für das Anfordern des OIDC-Token

Erforderliche Berechtigung

• Der Auftrag oder Workflow muss die id-token: write-Berechtigung erteilen, um den OIDC-Anbieter von GitHub zum Erstellen eines JSON Web Token (JWT) zuzulassen:

  permissions:
    id-token: write
  

• Ohne id-token: write kann das OIDC JWT ID-Token nicht angefordert werden. Diese Einstellung aktiviert nur das Abrufen und Festlegen des OIDC-Tokens. es gewährt keinen Schreibzugriff auf andere Ressourcen.

Festlegen von Berechtigungen

• Um ein OIDC-Token für einen Workflow abzurufen, lege die Berechtigung auf Workflowebene fest:

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

• Um ein OIDC-Token für einen einzelnen Auftrag abzurufen, lege die Berechtigung innerhalb dieses Auftrags fest:

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

• Je nach Workflowanforderungen sind möglicherweise zusätzliche Berechtigungen erforderlich.

Wiederverwendbare Workflows

• Für wiederverwendbare Workflows, die sich im Besitz desselben Benutzers, derselben Organisation oder desselben Unternehmens wie der Aufrufer befinden, kann aus dem Kontext des Aufrufers auf das im wiederverwendbaren Workflow generierte OIDC-Token zugegriffen werden.
• Lege für wiederverwendbare Workflows außerhalb deines Unternehmens oder deiner Organisation die Einstellung permissions für id-token auf write explizit auf Anruferworkflow- oder Auftragsebene fest. Dadurch wird sichergestellt, dass das OIDC-Token nur für beabsichtigte Aufruferworkflows verfügbar ist.

Methoden zum Anfordern des OIDC-Tokens

Benutzerdefinierte Aktionen können das OIDC-Token wie folgt anfordern:

• Die getIDToken()-Methode aus dem Toolkit für Aktionen Weitere Informationen findest du unter OIDC Token in der Dokumentation für das npm-Paket.

• Die folgenden Umgebungsvariablen auf dem Runner

  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.

  Zum Beispiel:

  Shell

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