Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Konfigurieren von OpenID Connect in HashiCorp Vault

Verwende OpenID Connect in deinen Workflows zum Authentifizieren bei HashiCorp Vault.

Ü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) und seine Architektur und Vorteile 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 „Konfigurieren der OIDC-Vertrauensstellung mit der Cloud“.

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:

  1. Aktiviere die JWT-auth-Methode, und verwende write, um die Konfiguration auf deinen Tresor anzuwenden. Verwende für die Parameter oidc_discovery_url und bound_issuer den Wert https://token.actions.githubusercontent.com. Diese Parameter ermöglichen es dem Vault-Server, die empfangenen JWTs während des Authentifizierungsprozesses zu überprüfen.

    Shell
    vault auth enable jwt
    Shell
    vault write auth/jwt/config \
      bound_issuer="https://token.actions.githubusercontent.com" \
      oidc_discovery_url="https://token.actions.githubusercontent.com"
  2. 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
  3. 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
  • 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 Parameter bound_subject sowie den Parameter bound_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 Repository repo-name, das dem Konto user-or-org-name angehört.
  • Eine Liste aller verfügbaren Ansprüche, die vom OIDC-Anbieter GitHub unterstützt werden, findest du unter Konfigurieren der OIDC-Vertrauensstellung mit der Cloud.

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:

  1. Füge Berechtigungseinstellungen für das Token hinzu.
  2. Tausche das OIDC-Token (JWT) mithilfe der Aktion hashicorp/vault-action gegen ein Cloudzugriffstoken aus.

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 Wert id-token auf write festgelegt ist. Dadurch können OIDC-Token aus jedem Auftrag im Workflow abgerufen werden.
  • Fordere das JWT vom GitHub-OIDC-Anbieter an, und übergebe dieses Token an HashiCorp Vault, um ein Zugriffstoken zu empfangen:

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 und ACTIONS_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:

YAML
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:

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

Möglicherweise musst Du hier zusätzliche Berechtigungen angeben, abhängig von den Anforderungen Deines Workflows.

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. Ein Beispiel für die Camel-Case-Schreibweise lautet: 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.
YAML
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.

  1. Setze die Option exportToken auf true (Standardwert: false) fest. Dadurch wird das ausgegebene Vault-Zugriffstoken als Umgebungsvariable exportiert: VAULT_TOKEN.
  2. Füge einen Schritt hinzu, um die Vault-API zum Wiederrufen des Zugriffstokens aufzurufen: Revoke a Token (Self).
YAML
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