Remarque : Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.
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 ».
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 :
-
Activez la méthode
auth
JWT et utilisezwrite
pour appliquer la configuration à votre coffre. Pour les paramètresoidc_discovery_url
etbound_issuer
, utilisezhttps://HOSTNAME/_services/token
. 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
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"
-
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
vault policy write myproject-production - <<EOF # Read-only permission on 'secret/data/production/*' path path "secret/data/production/*" { capabilities = [ "read" ] } EOF
-
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
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ètrebound_subject
ainsi que le paramètrebound_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ôtrepo-name
qui appartient au compteuser-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 :
- Ajoutez des paramètres d’autorisations pour le jeton.
- Utilisez l’action
hashicorp/vault-action
pour échanger le jeton OIDC (JWT) afin d’obtenir un jeton d’accès cloud.
Remarque : lorsque des environnements sont utilisés dans des workflows ou dans des stratégies OIDC, nous vous recommandons d’ajouter des règles de protection à l’environnement pour plus de sécurité. Par exemple, vous pouvez configurer des règles de déploiement sur un environnement pour restreindre les branches et balises pouvant être déployées dans l’environnement ou accéder aux secrets d’environnement. Pour plus d’informations, consultez « Utilisation d’environnements pour le déploiement ».
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 valeurid-token
définie surwrite
. Cela vous permet d’extraire le jeton OIDC de chaque travail dans le workflow.
- Le workflow a besoin des paramètres
- 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.
- Vous pouvez utiliser l’action
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 travail ou du workflow nécessite un paramètre permissions
avec id-token: write
. Vous ne pourrez pas demander le jeton OIDC JWT ID si le paramètre permissions
est id-token
a la valeur read
ou none
.
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
etACTIONS_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
Remarque :
Lorsque la clé permissions
est utilisée, toutes les autorisations non spécifiées sont définies sur Aucun accès, à l’exception de l’étendue de métadonnées, qui obtient toujours l’accès en lecture. Par conséquent, vous devrez peut-être ajouter d’autres autorisations, telles que contents: read
. Pour plus d’informations, consultez « Authentification automatique par jeton ».
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@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.
Remarque :
- Si votre serveur Vault n’est pas accessible à partir du réseau public, vous pouvez utiliser un exécuteur auto-hébergé avec d’autres méthodes d’authentification Vault disponibles. Pour plus d’informations, consultez « À propos des exécuteurs auto-hébergés ».
<Vault Namespace>
doit être défini pour un déploiement Vault Enterprise (y compris HCP Vault). Pour plus d’informations, consultez Espace de noms Vault.
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.
- Définissez l’option
exportToken
surtrue
(valeur par défaut :false
). Cette opération exporte le jeton d’accès Vault émis en tant que variable d’environnement :VAULT_TOKEN
. - 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@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