Configuration d’OpenID Connect dans HashiCorp Vault

Vue d’ensemble

OpenID Connect (OIDC) permet à vos workflows GitHub Actions de s’authentifier auprès d’un coffre-fort HashiCorp Vault pour récupérer des secrets.

Ce guide fournit une vue d’ensemble de la façon de configurer HashiCorp Vault pour approuver le protocole OIDC de GitHub en tant qu’identité fédérée et montre comment utiliser cette configuration dans l’action hashicorp/vault-action pour récupérer des secrets à partir de HashiCorp Vault.

Prérequis

• Pour en savoir plus sur les concepts de base décrivant la façon dont GitHub utilise OIDC (OpenID Connect) ainsi que sur son architecture et ses avantages, consultez « À propos du renforcement de la sécurité avec OpenID Connect ».

• Avant de continuer, vous devez planifier votre stratégie de sécurité pour veiller à ce que les jetons d’accès soient uniquement alloués de manière prévisible. Pour contrôler la façon dont votre fournisseur de cloud émet des jetons d’accès, vous devez définir au moins une condition, afin que les dépôts non approuvés ne puissent pas demander de jetons d’accès à vos ressources cloud. Pour plus d’informations, consultez « À propos du renforcement de la sécurité avec OpenID Connect ».

• Si vous suivez ce guide sur GHE.com, sachez que vous devez remplacer certaines valeurs dans la documentation suivante. Consultez « À propos du renforcement de la sécurité avec OpenID Connect ».

Ajout du fournisseur d’identité à HashiCorp Vault

Pour utiliser OIDC avec HashiCorp Vault, vous devez ajouter une configuration d’approbation pour le fournisseur OIDC GitHub. Pour plus d’informations, consultez la documentation sur HashiCorp Vault.

Pour configurer le serveur Vault afin qu’il accepte les jetons JWT pour l’authentification :

1. Activez la méthode auth JWT et utilisez write pour appliquer la configuration à votre coffre. Pour les paramètres oidc_discovery_url et bound_issuer, utilisez https://token.actions.githubusercontent.com. Ces paramètres permettent au serveur Vault de vérifier les jetons JWT reçus pendant le processus d’authentification.

   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"
   

   Note

   Si une URL unique de l'émetteur pour une entreprise a été définie à l'aide de l'API REST (comme décrit dans « À propos du renforcement de la sécurité avec OpenID Connect »), les valeurs de bound_issuer et oidc_discover_url doivent correspondre à cette URL unique. Par exemple, pour une entreprise nommée octocat qui utilise l’URL d’émetteur unique, bound_issuer et oidc_discovery_url doivent être définis avec la valeur https://token.actions.githubusercontent.com/octocat.

2. Configurez une stratégie qui accorde l’accès uniquement aux chemins que vos workflows utiliseront pour récupérer des secrets. Pour plus d’informations sur les stratégies avancées, consultez la documentation sur les stratégies 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. Configurez des rôles pour regrouper différentes stratégies. Si l’authentification réussit, ces stratégies seront attachées au jeton d’accès de coffre résultant.

   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 définit la validité du jeton d’accès résultant.
• Vérifiez que le paramètre bound_claims est défini selon vos exigences de sécurité, et qu’il comprend au moins une condition. Si vous le souhaitez, vous pouvez également définir le paramètre bound_subject ainsi que le paramètre bound_audiences.
• Pour vérifier les revendications arbitraires dans la charge utile JWT reçue, le paramètre bound_claims comprend un ensemble de revendications avec les valeurs nécessaires. Dans l’exemple ci-dessus, le rôle accepte toutes les demandes d’authentification entrantes provenant du dépôt repo-name qui appartient au compte user-or-org-name.
• Pour voir toutes les revendications disponibles prises en charge par le fournisseur OIDC de GitHub, consultez « À propos du renforcement de la sécurité avec OpenID Connect ».

Pour plus d’informations, consultez la documentation sur HashiCorp Vault.

Mise à jour de votre workflow GitHub Actions

Pour mettre à jour vos workflows pour OIDC, vous devez apporter deux modifications à votre code YAML :

1. Ajoutez des paramètres d’autorisations pour le jeton.
2. Utilisez l’action hashicorp/vault-action pour échanger le jeton OIDC (JWT) afin d’obtenir un jeton d’accès cloud.

Pour ajouter l’intégration OIDC à vos workflows afin de leur permettent d’accéder aux secrets dans Vault, vous devez apporter les modifications suivantes au code :

• Accordez l’autorisation d’extraire le jeton à partir du fournisseur OIDC GitHub :
  • Le workflow a besoin des paramètres permissions: avec la valeur id-token définie sur write. Cela vous permet d’extraire le jeton OIDC de chaque travail dans le workflow.
• Demandez le jeton JWT auprès du fournisseur OIDC GitHub et présentez-le à HashiCorp Vault pour recevoir un jeton d’accès :
  • Vous pouvez utiliser l’action hashicorp/vault-action pour récupérer le jeton JWT et recevoir le jeton d’accès du coffre. Vous pouvez également utiliser le kit de ressources Actions afin de récupérer les jetons de votre travail.

Cet exemple montre comment utiliser OIDC avec l’action officielle pour demander un secret à HashiCorp Vault.

Ajout de paramètres d’autorisations

L’exécution du projet ou du flux de travail nécessite un paramètre permissions avec id-token: write pour autoriser le fournisseur OIDC de GitHub à créer un JSON Web Token pour chaque exécution. Vous ne pourrez pas demander le jeton OIDC JWT ID si le permissions pour id-token n’est pas défini sur write, mais cette valeur n’implique pas l’octroi d’un accès en écriture à des ressources, permettant uniquement de récupérer et de définir le jeton OIDC pour une action ou une étape afin de permettre l’authentification avec un jeton d’accès à courte durée. Tout paramètre d’approbation réel est défini à l’aide de revendications OIDC, pour plus d’informations, consultez « À propos du renforcement de la sécurité avec OpenID Connect ».

Le paramètre id-token: write permet au JWT d’être demandé à partir du fournisseur OIDC de GitHub à l’aide de l’une des approches suivantes :

• Utilisation de variables d’environnement sur l’exécuteur (ACTIONS_ID_TOKEN_REQUEST_URL et ACTIONS_ID_TOKEN_REQUEST_TOKEN).
• Utilisation du getIDToken() issu du kit de ressources Actions.

Si vous devez extraire un jeton OIDC pour un workflow, l’autorisation peut être définie au niveau du workflow. Par exemple :

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

Si vous avez uniquement besoin d’extraire un jeton OIDC pour un seul travail, alors cette autorisation peut être définie au sein de ce travail. Par exemple :

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

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

Vous aurez peut-être besoin de spécifier des autorisations supplémentaires ici, en fonction des exigences liées à votre workflow.

Pour les workflows réutilisables appartenant au même utilisateur, à la même organisation ou à la même entreprise que le workflow de l’appelant, le jeton OIDC généré dans le workflow réutilisable est accessible à partir du contexte de l’appelant. Pour les workflows réutilisables en dehors de votre entreprise ou organisation, le paramètre permissions pour id-token doit être défini explicitement avec la valeur write au niveau du workflow de l’appelant ou dans le travail spécifique qui appelle le workflow réutilisable. Cela garantit que le jeton OIDC généré dans le workflow réutilisable n’est autorisé à être consommé dans les workflows de l’appelant que si c’est prévu.

Pour plus d’informations, consultez « Réutilisation des workflows ».

Demande du jeton d’accès

L’action hashicorp/vault-action reçoit un jeton JWT à partir du fournisseur OIDC GitHub, puis demande un jeton d’accès à partir de votre instance HashiCorp Vault pour récupérer des secrets. Pour plus d’informations, consultez la documentation GitHub Actions HashiCorp Vault.

Cet exemple montre comment créer un travail qui demande un secret à HashiCorp Vault.

• VAULT-URL : remplacez cela par l’URL de votre coffre HashiCorp Vault.
• VAULT-NAMESPACE : à remplacer par l’espace de noms que vous avez défini dans HashiCorp Vault. Par exemple : admin.
• ROLE-NAME : remplacez cela par le rôle que vous avez défini dans la relation d’approbation HashiCorp Vault.
• SECRET-PATH : remplacez cela par le chemin d’accès au secret que vous récupérez à partir de HashiCorp Vault. Par exemple : 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.

Révocation du jeton d’accès

Par défaut, le serveur Vault révoque automatiquement les jetons d’accès quand leur durée de vie a expiré. Vous n’êtes donc pas obligé de révoquer manuellement les jetons d’accès. Toutefois, si vous souhaitez révoquer des jetons d’accès immédiatement après l’achèvement ou l’échec de votre travail, vous pouvez révoquer manuellement le jeton émis à l’aide de l’API Vault.

1. Définissez l’option exportToken sur true (valeur par défaut : false). Cette opération exporte le jeton d’accès Vault émis en tant que variable d’environnement : VAULT_TOKEN.
2. Ajoutez une étape pour appeler l’API Vault Revoke a Token (Self) afin de révoquer le jeton d’accès.

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

Pour aller plus loin

• Utilisation d’OpenID Connect avec des workflows réutilisables - À propos des exécuteurs auto-hébergés