Konfigurieren von OpenID Connect in 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) 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://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.
• 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.

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:
  • 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.

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

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

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.

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

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

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

• Verwenden von OpenID Connect mit wiederverwendbaren Workflows - Informationen zu selbstgehosteten Runnern