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
Mit OpenID Connect (OIDC) kannst du deine GitHub Actions-Workflows gegenüber HashiCorp Vault authentifizieren, um Geheimnisse abzurufen.
In diesem Leitfaden erfährst du, wie du HashiCorp Vault so konfigurierst, dass OIDC auf GitHub als vertrauenswürdige Verbundidentität eingestuft wird. Außerdem wird gezeigt, wie diese Konfiguration in der Aktion hashicorp/vault-action verwendet wird, um Geheimnisse aus HashiCorp Vault abzurufen.
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.
Hinzufügen des Identitätsanbieters zu HashiCorp Vault
Für die Verwendung von OIDC mit HashiCorp Vault musst du eine Vertrauenskonfiguration für den OIDC-Anbieter auf GitHub hinzufügen. Weitere Informationen findest du in der Dokumentation zu HashiCorp Vault.
So konfigurierst du deinen Vault-Server so, dass er JWTs (JSON Web Token) für die Authentifizierung akzeptiert:
-
Aktiviere die JWT-
auth
-Methode, und verwendewrite
, um die Konfiguration auf deinen Tresor anzuwenden. Verwende für die Parameteroidc_discovery_url
undbound_issuer
den Werthttps://HOSTNAME/_services/token
. Diese Parameter ermöglichen es dem Vault-Server, die empfangenen JWTs während des Authentifizierungsprozesses zu überprüfen.Shell vault auth enable jwt
vault auth enable jwt
Shell vault write auth/jwt/config \ bound_issuer="https://HOSTNAME/_services/token" \ oidc_discovery_url="https://HOSTNAME/_services/token"
vault write auth/jwt/config \ bound_issuer="https://HOSTNAME/_services/token" \ oidc_discovery_url="https://HOSTNAME/_services/token"
-
Konfiguriere eine Richtlinie, die nur Zugriff auf die spezifischen Pfade gewährt, die deine Workflows zum Abrufen von Geheimnissen verwenden. Weiterführende Richtlinien findest du in der Richtliniendokumentation zu HashiCorp Vault.
Shell vault policy write myproject-production - <<EOF # Read-only permission on 'secret/data/production/*' path path "secret/data/production/*" { capabilities = [ "read" ] } EOF
vault policy write myproject-production - <<EOF # Read-only permission on 'secret/data/production/*' path path "secret/data/production/*" { capabilities = [ "read" ] } EOF
-
Konfiguriere Rollen, um verschiedene Richtlinien in Gruppen zusammenzufassen. Wenn die Authentifizierung erfolgreich ist, werden diese Richtlinien an das resultierende Vault-Zugriffstoken angefügt.
Shell vault write auth/jwt/role/myproject-production -<<EOF { "role_type": "jwt", "user_claim": "actor", "bound_claims": { "repository": "user-or-org-name/repo-name" }, "policies": ["myproject-production"], "ttl": "10m" } EOF
vault write auth/jwt/role/myproject-production -<<EOF { "role_type": "jwt", "user_claim": "actor", "bound_claims": { "repository": "user-or-org-name/repo-name" }, "policies": ["myproject-production"], "ttl": "10m" } EOF
ttl
definiert die Gültigkeit des resultierenden Zugriffstokens.- Stelle sicher, dass der Parameter
bound_claims
für deine Sicherheitsanforderungen definiert ist und mindestens eine Bedingung enthält. Optional kannst du außerdem den Parameterbound_subject
sowie den Parameterbound_audiences
festlegen. - Um beliebige Ansprüche in den empfangenen JWT-Nutzdaten zu überprüfen, enthält der Parameter
bound_claims
eine Reihe von Ansprüchen und ihre erforderlichen Werte. Im obigen Beispiel akzeptiert die Rolle alle eingehenden Authentifizierungsanforderungen aus dem Repositoryrepo-name
, das dem Kontouser-or-org-name
angehört. - Zum Anzeigen aller verfügbaren Ansprüche, die vom OIDC-Anbieter von GitHub unterstützt werden, sieh dir Informationen zur Sicherheitshärtung mit OpenID Connect an.
Weitere Informationen findest du in der Dokumentation zu HashiCorp Vault.
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
hashicorp/vault-action
gegen ein Cloudzugriffstoken aus.
Hinweis: Wenn Umgebungen in Workflows oder in OIDC-Richtlinien verwendet werden, empfehlen wir, 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 Verwenden von Umgebungen für die Bereitstellung.
Um die OIDC-Integration zu deinen Workflows hinzuzufügen, damit diese auf Geheimnisse in Vault zugreifen können, sind die folgenden Codeänderungen erforderlich:
- Erteile die Berechtigung zum Abrufen von Token vom OIDC-Anbieter auf GitHub:
- Der Workflow benötigt
permissions:
-Einstellungen, bei denen der Wertid-token
aufwrite
festgelegt ist. Dadurch können OIDC-Token aus jedem Auftrag im Workflow abgerufen werden.
- Der Workflow benötigt
- Fordere das JWT vom GitHub-OIDC-Anbieter an, und übergebe dieses Token an HashiCorp Vault, um ein Zugriffstoken zu empfangen:
- Du kannst die
hashicorp/vault-action
-Aktion verwenden, um das JWT abzurufen und das Zugriffstoken aus Vault zu erhalten, oder du kannst die Token für deinen Auftrag mit dem Toolkit für Aktionen abrufen.
- Du kannst die
In diesem Beispiel wird veranschaulicht, wie OIDC mit der offiziellen Aktion verwendet wird, um ein Geheimnis aus HashiCorp Vault anzufordern.
Hinzufügen von Berechtigungseinstellungen
Der Auftrag oder die Workflowausführung erfordert eine Einstellung permissions
mit id-token: write
. Du kannst das OIDC JWT-ID-Token nicht anfordern, wenn die Einstellung permissions
für id-token
auf read
oder none
festgelegt ist.
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. Beispiel:
permissions: id-token: write # This is required for requesting the JWT
permissions:
id-token: write # This is required for requesting the JWT
Hinweis:
Bei Verwendung des Schlüssels permissions
werden alle nicht angegebenen Berechtigungen auf Kein Zugriff festgelegt, mit Ausnahme des Metadatenbereichs, der immer Lesezugriff erhält. Infolgedessen musst du möglicherweise andere Berechtigungen hinzufügen, zum Beispiel contents: read
. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.
Anfordern des Zugriffstokens
Die Aktion hashicorp/vault-action
empfängt ein JWT vom GitHub-OIDC-Anbieter und fordert anschließend ein Zugriffstoken von deiner HashiCorp Vault-Instanz an, um Geheimnisse abzurufen. Weitere Informationen findest du in der Dokumentation zu HashiCorp Vault GitHub Action.
In diesem Beispiel wird veranschaulicht, wie ein Auftrag erstellt wird, der ein Geheimnis aus HashiCorp Vault anfordert.
<Vault URL>
: Ersetze diesen Wert durch die URL deiner HashiCorp Vault-Instanz.<Vault Namespace>
: Ersetze diesen Wert durch den Namespace, den du in HashiCorp Vault festgelegt hast. Beispiel:admin
.<Role name>
: Ersetze diesen Wert durch die Rolle, die du in der HashiCorp Vault-Vertrauensstellung festgelegt hast.<Secret-Path>
: Ersetze diesen Wert durch den Pfad zum Geheimnis, das du aus HashiCorp Vault abrufst. Beispiel:secret/data/production/ci npmToken
.
jobs: retrieve-secret: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - name: Retrieve secret from Vault uses: hashicorp/vault-action@v2.4.0 with: method: jwt url: <Vault URL> namespace: <Vault Namespace - HCP Vault and Vault Enterprise only> role: <Role name> secrets: <Secret-Path> - name: Use secret from Vault run: | # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
jobs:
retrieve-secret:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- name: Retrieve secret from Vault
uses: hashicorp/vault-action@v2.4.0
with:
method: jwt
url: <Vault URL>
namespace: <Vault Namespace - HCP Vault and Vault Enterprise only>
role: <Role name>
secrets: <Secret-Path>
- name: Use secret from Vault
run: |
# This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
Hinweis:
- Wenn dein Vault-Server nicht über das öffentliche Netzwerk erreichbar ist, solltest du einen selbstgehosteten Runner mit anderen verfügbaren Vault-Authentifizierungsmethoden verwenden. Weitere Informationen findest du unter Informationen zu selbstgehosteten Runnern.
- Für eine Vault Enterprise-Bereitstellung (einschließlich HCP Vault) muss
<Vault Namespace>
festgelegt werden. Weitere Informationen findest du unter Vault-Namespace.
Widerrufen des Zugriffstokens
Standardmäßig widerruft der Vault-Server Zugriffstoken nach dem jeweiligen TTL-Ablauf automatisch, sodass du die Zugriffstoken nicht manuell widerrufen musst. Wenn du die Zugriffstoken jedoch sofort nach Abschluss oder Scheitern deines Auftrags widerrufen möchtest, kannst du die ausgegebenen Token mithilfe der Vault-API manuell widerrufen.
- Setze die Option
exportToken
auftrue
(Standardwert:false
) fest. Dadurch wird das ausgegebene Vault-Zugriffstoken als Umgebungsvariable exportiert:VAULT_TOKEN
. - Füge einen Schritt hinzu, um die Vault-API zum Wiederrufen des Zugriffstokens aufzurufen: Revoke a Token (Self).
jobs: retrieve-secret: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - name: Retrieve secret from Vault uses: hashicorp/vault-action@v2.4.0 with: exportToken: true method: jwt url: <Vault URL> role: <Role name> secrets: <Secret-Path> - name: Use secret from Vault run: | # This step has access to the secret retrieved above; see hashicorp/vault-action for more details. - name: Revoke token # This step always runs at the end regardless of the previous steps result if: always() run: | curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \ <Vault URL>/v1/auth/token/revoke-self
jobs:
retrieve-secret:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- name: Retrieve secret from Vault
uses: hashicorp/vault-action@v2.4.0
with:
exportToken: true
method: jwt
url: <Vault URL>
role: <Role name>
secrets: <Secret-Path>
- name: Use secret from Vault
run: |
# This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
- name: Revoke token
# This step always runs at the end regardless of the previous steps result
if: always()
run: |
curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \
<Vault URL>/v1/auth/token/revoke-self