Skip to main content

Konfigurieren von OpenID Connect in HashiCorp Vault

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

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:

  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://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
    
    Shell
    vault write auth/jwt/config \
      bound_issuer="https://HOSTNAME/_services/token" \
      oidc_discovery_url="https://HOSTNAME/_services/token"
    
  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.
  • 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:

  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.

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 Verwalten 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 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. Zum Beispiel:

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

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.
YAML
jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        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@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
        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

Weitere Informationsquellen