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 Azure, ohne dass die Azure-Anmeldeinformationen als langlebige GitHub-Geheimnisse gespeichert werden müssen.
Dieser Leitfaden gibt einen Überblick über die Konfiguration von Azure, um OIDC von GitHub als Verbundidentität zu vertrauen, und enthält ein Workflowbeispiel für die azure/login
-Aktion, die Token zur Authentifizierung bei Azure und zum Zugriff auf Ressourcen verwendet.
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.
-
Sie müssen sicherstellen, dass auf die folgenden OIDC-Endpunkte von Ihrem Cloudanbieter zugegriffen werden kann:
https://HOSTNAME/_services/token/.well-known/openid-configuration
https://HOSTNAME/_services/token/.well-known/jwks
Note
Microsoft Entra ID (früher Azure AD genannt) verfügt nicht über feste IP-Adressbereiche, die für diese Endpunkte definiert sind.
-
Stellen Sie sicher, dass der Wert des Ausstelleranspruchs, der im JSON Web Token (JWT) enthalten ist, auf eine öffentlich routingfähige URL festgelegt ist. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.
Hinzufügen der Verbundanmeldeinformationen zu Azure
Der OIDC-Anbieter von GitHub arbeitet mit dem Workloadidentitätsverbund von Azure zusammen. Eine Übersicht findest du in der Dokumentation von Microsoft unter Workloadidentitätsverbund (Vorschau).
Um den OIDC-Identitätsanbieter in Azure zu konfigurieren, musst du die folgende Konfiguration ausführen. Anweisungen zum Vornehmen dieser Änderungen findest du in der Azure-Dokumentation.
- Erstellen einer Entra-ID-Anwendung und eines Dienstprinzipals.
- Fügen Sie Verbundanmeldeinformationen für die Entra-ID-Anwendung hinzu.
- Erstelle GitHub-Geheimnisse zum Speichern der Azure-Konfiguration.
Weitere Anleitungen zum Konfigurieren des Identitätsanbieters:
- Stelle für die Sicherheitshärtung sicher, dass du Informationen zur Sicherheitshärtung mit OpenID Connect gelesen hast. Ein Beispiel findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.
- Für die
audience
-Einstellung wird der Wertapi://AzureADTokenExchange
empfohlen, aber du kannst hier auch andere Werte angeben.
Aktualisieren deines GitHub Actions-Workflows
Um deine Workflows für OIDC zu aktualisieren, musst du zwei Änderungen an deinen YAML-Daten vornehmen:
- Füge Berechtigungseinstellungen für das Token hinzu.
- Tausche das OIDC-Token (JWT) mithilfe der Aktion
azure/login
gegen ein Cloudzugriffstoken aus.
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.
Anfordern des Zugriffstokens
Die azure/login
-Aktion empfängt ein JWT vom GitHub-OIDC-Anbieter und fordert dann ein Zugriffstoken von Azure an. Weitere Informationen findest du in der azure/login
-Dokumentation.
Im folgenden Beispiel wird ein OIDC-ID-Token mit Azure ausgetauscht, um ein Zugriffstoken zu empfangen, das dann für den Zugriff auf Cloudressourcen verwendet werden kann.
name: Run Azure Login with OIDC on: [push] permissions: id-token: write contents: read jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: 'Az CLI login' uses: azure/login@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 with: client-id: ${{ secrets.AZURE_CLIENT_ID }} tenant-id: ${{ secrets.AZURE_TENANT_ID }} subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} - name: 'Run az commands' run: | az account show az group list
name: Run Azure Login with OIDC
on: [push]
permissions:
id-token: write
contents: read
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: 'Az CLI login'
uses: azure/login@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
- name: 'Run az commands'
run: |
az account show
az group list