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.
Übersicht
OpenID Connect (OIDC) ermöglicht deinen GitHub Actions-Workflows den Zugriff auf Ressourcen in deinem Cloudanbieter, ohne Anmeldeinformationen als langlebige GitHub-Geheimnisse speichern zu müssen.
Um OIDC zu verwenden, musst du zunächst deinen Cloudanbieter so konfigurieren, dass er OIDC von GitHub als Verbundidentität vertraut, und dann deine Workflows so aktualisieren, dass sie mit Token authentifiziert werden.
Voraussetzungen
-
Informationen zu den grundlegenden Konzepten, nach denen GitHub OpenID Connect (OIDC) sowie die Architektur und Vorteile des Protokolls verwendet, findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.
-
Bevor du fortfährst, musst du deine Sicherheitsstrategie planen, um sicherzustellen, dass Zugriffs-Token nur auf vorhersehbare Weise zugewiesen werden. Zur Steuerung, wie dein Cloud-Anbieter Zugriffs-Token ausgibt, musst du mindestens eine Bedingung definieren, damit nicht vertrauenswürdige Repositorys keine Zugriffs-Token für deine Cloud-Ressourcen anfordern können. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.
Aktualisieren deines GitHub Actions-Workflows
Um deine Workflows für OIDC zu aktualisieren, musst du zwei Änderungen an deinen YAML-Daten vornehmen:
- Füge die Berechtigungseinstellungen für das Token hinzu.
- Verwende die offizielle Aktion deines Cloudanbieters, um das OIDC-Token (JWT) gegen ein Cloudzugriffstoken auszutauschen.
Wenn dein Cloudanbieter noch keine offizielle Aktion anbietet, kannst du deine Workflows aktualisieren, um diese Schritte manuell auszuführen.
Note
Wenn Umgebungen in Workflows oder in OIDC-Richtlinien verwendet werden, wird empfohlen, der Umgebung Schutzregeln für zusätzliche Sicherheit hinzuzufügen. Du kannst z. B. Bereitstellungsregeln für eine Umgebung konfigurieren, um einzuschränken, welche Verzweigungen und Tags in der Umgebung oder in geheimen Umgebungsschlüsseln bereitgestellt werden können. Weitere Informationen findest du unter Verwalten von Umgebungen für die Bereitstellung.
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.
Verwenden von offiziellen Aktionen
Wenn dein Cloudanbieter eine offizielle Aktion für die Verwendung von OIDC mit GitHub Actions erstellt hat, kannst du das OIDC-Token einfach gegen ein Zugriffstoken austauschen. Anschließend kannst du deine Workflows aktualisieren, um dieses Token beim Zugriff auf Cloudressourcen zu verwenden.
Beispielsweise hat Alibaba Cloud für die Integration mit OIDC mit GitHub aliyun/configure-aliyun-credentials-action
erstellt.
Verwenden benutzerdefinierter Aktionen
Wenn dein Cloudanbieter keine offizielle Aktion anbietet oder du es vorziehst, benutzerdefinierte Skripts zu erstellen, kannst du das JSON-Webtoken (JWT) manuell vom OIDC-Anbieter von GitHub anfordern.
Wenn du keine offizielle Aktion verwendest, empfiehlt GitHub, das Actions Core Toolkit zu verwenden. Alternativ kannst du die folgenden Umgebungsvariablen verwenden, um das Token abzurufen: ACTIONS_ID_TOKEN_REQUEST_TOKEN
, ACTIONS_ID_TOKEN_REQUEST_URL
.
Um deine Workflows mithilfe dieses Ansatzes zu aktualisieren, musst du drei Änderungen an deinem YAML vornehmen:
- Füge die Berechtigungseinstellungen für das Token hinzu.
- Füge Code hinzu, der das OIDC-Token vom OIDC-Anbieter von GitHub anfordert.
- Füge Code hinzu, der das OIDC-Token mit deinem Cloudanbieter gegen ein Zugriffstoken austauscht.
Anfordern des JWT mithilfe des Actions Core Toolkits
Das folgende Beispiel zeigt, wie actions/github-script
mit dem core
-Toolkit verwendet wird, um das JWT vom OIDC-Anbieter von GitHub anzufordern. Weitere Informationen findest du unter Creating a JavaScript action (Erstellen einer JavaScript-Aktion).
jobs:
job:
environment: Production
runs-on: ubuntu-latest
steps:
- name: Install OIDC Client from Core Package
run: npm install @actions/core@1.6.0 @actions/http-client
- name: Get Id Token
uses: actions/github-script@v6
id: idtoken
with:
script: |
const coredemo = require('@actions/core')
let id_token = await coredemo.getIDToken()
coredemo.setOutput('id_token', id_token)
Anfordern des JWT mithilfe von Umgebungsvariablen
Im folgenden Beispiel wird gezeigt, wie du Umgebungsvariablen verwendest, um ein JSON-Webtoken anzufordern.
Für deinen Bereitstellungsauftrag musst du die Tokeneinstellungen mithilfe von actions/github-script
mit dem core
-Toolkit definieren. Weitere Informationen findest du unter Creating a JavaScript action (Erstellen einer JavaScript-Aktion).
Beispiel:
jobs:
job:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v6
id: script
timeout-minutes: 10
with:
debug: true
script: |
const token = process.env['ACTIONS_RUNTIME_TOKEN']
const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
core.setOutput('TOKEN', token.trim())
core.setOutput('IDTOKENURL', runtimeUrl.trim())
Du kannst dann curl
verwenden, um ein JWT vom GitHub-OIDC-Anbieter abzurufen. Beispiel:
- run: |
IDTOKEN=$(curl -H "Authorization: bearer ${{steps.script.outputs.TOKEN}}" ${{steps.script.outputs.IDTOKENURL}} -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" | jq -r '.value')
echo $IDTOKEN
jwtd() {
if [[ -x $(command -v jq) ]]; then
jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}"
echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')"
fi
}
jwtd $IDTOKEN
echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT
id: tokenid
Abrufen des Zugriffstokens vom Cloudanbieter
Du musst deinem Cloudanbieter das OIDC-JSON-Webtoken vorlegen, um ein Zugriffstoken abzurufen.
Für jede Bereitstellung müssen deine Workflows Cloudanmeldeaktionen (oder benutzerdefinierte Skripts) verwenden, die das OIDC-Token abrufen und dem Cloudanbieter vorlegen. Der Cloudanbieter überprüft dann die Ansprüche im Token. Wenn dies erfolgreich ist, stellt er ein Cloudzugriffstoken bereit, das nur für diese Auftragsausführung verfügbar ist. Das bereitgestellte Zugriffstoken kann dann bei nachfolgenden Aktionen im Auftrag verwendet werden, um eine Verbindung mit der Cloud herzustellen und deren Ressourcen für die Bereitstellung zu nutzen.
Die Schritte zum Austauschen des OIDC-Tokens gegen ein Zugriffstoken variieren je nach Cloudanbieter.
Zugreifen auf Ressourcen in deinem Cloudanbieter
Nachdem du das Zugriffstoken abgerufen hast, kannst du bestimmte Cloudaktionen oder Skripts verwenden, um dich beim Cloudanbieter zu authentifizieren und seine Ressourcen für die Bereitstellung zu nutzen. Diese Schritte können für jeden Cloudanbieter unterschiedlich sein.
Beispielsweise enthält Alibaba Cloud Standard eigene Anweisungen zur OIDC-Authentifizierung. Weitere Informationen finden Sie unter Dokumentation zu OIDC-basierten SSO in der Dokumentation der Alibaba Cloud.
Darüber hinaus kann die Standardablaufzeit dieses Zugriffstokens für jede Cloud unterschiedlich und auf der Seite des Cloudanbieters konfigurierbar sein.