Configuration d’OpenID Connect dans les fournisseurs de cloud

Vue d’ensemble

OpenID Connect (OIDC) permet à vos workflows GitHub Actions d’accéder aux ressources dans votre fournisseur de cloud, sans avoir à stocker d’informations d’identification en tant que secrets GitHub à long terme.

Pour utiliser OIDC, vous devez d’abord configurer votre fournisseur de cloud pour approuver le protocole OIDC de GitHub en tant qu’identité fédérée, puis mettre à jour vos workflows afin de vous authentifier à l’aide de jetons.

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

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 officielle à partir de votre fournisseur de cloud pour échanger le jeton OIDC (JWT) afin d’obtenir un jeton d’accès cloud.

Si votre fournisseur de cloud n’offre pas encore d’action officielle, vous pouvez mettre à jour vos workflows pour effectuer ces étapes manuellement.

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

Utilisation d’actions officielles

Si votre fournisseur de cloud a créé une action officielle pour l’utilisation d’OIDC avec GitHub Actions, il vous permet d’échanger facilement le jeton OIDC pour obtenir un jeton d’accès. Vous pouvez ensuite mettre à jour vos workflows afin d’utiliser ce jeton lors de l’accès aux ressources cloud.

Utilisation d’actions personnalisées

Si votre fournisseur de cloud n’a pas d’action officielle ou si vous préférez créer des scripts personnalisés, vous pouvez demander manuellement le jeton JSON Web Token (JWT) à partir du fournisseur OIDC GitHub.

Si vous n’utilisez pas d’action officielle, GitHub recommande que vous utilisiez le kit de ressources principal Actions. Vous pouvez également utiliser les variables d’environnement suivantes pour récupérer le jeton : ACTIONS_RUNTIME_TOKEN, ACTIONS_ID_TOKEN_REQUEST_URL.

Pour mettre à jour vos workflows à l’aide de cette approche, vous devez apporter trois modifications à votre code YAML :

1. Ajoutez des paramètres d’autorisations pour le jeton.
2. Ajoutez du code qui demande le jeton OIDC à partir du fournisseur OIDC de GitHub.
3. Ajoutez du code qui échange le jeton OIDC avec votre fournisseur de cloud pour obtenir un jeton d’accès.

Demande du jeton JWT à l’aide du kit de ressources principal Actions

L’exemple suivant montre comment utiliser actions/github-script avec le kit de ressources core pour demander le jeton JWT auprès du fournisseur OIDC de GitHub. Pour plus d’informations, consultez « Creating a JavaScript action ».

jobs:
  job:
    environment: Production
    runs-on: ubuntu-latest
    steps:
    - name: Install OIDC Client from Core Package
      run: npm install @actions/core@1.6.0 @actions/http-client
    - name: Get Id Token
      uses: actions/github-script@v6
      id: idtoken
      with:
        script: |
          const coredemo = require('@actions/core')
          let id_token = await coredemo.getIDToken()
          coredemo.setOutput('id_token', id_token)

Demande du jeton JWT à l’aide de variables d’environnement

L’exemple suivant montre comment utiliser des variables d’environnement pour demander un jeton JSON Web Token.

Pour votre travail de déploiement, vous devez définir les paramètres de jeton en utilisant actions/github-script avec le kit de ressources core. Pour plus d’informations, consultez « Creating a JavaScript action ».

Par exemple :

jobs:
  job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/github-script@v6
      id: script
      timeout-minutes: 10
      with:
        debug: true
        script: |
          const token = process.env['ACTIONS_RUNTIME_TOKEN']
          const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
          core.setOutput('TOKEN', token.trim())
          core.setOutput('IDTOKENURL', runtimeUrl.trim())

Vous pouvez ensuite utiliser curl pour récupérer un jeton JWT à partir du fournisseur OIDC de GitHub. Par exemple :

    - run: |
        IDTOKEN=$(curl -H "Authorization: bearer  ${{steps.script.outputs.TOKEN}}" ${{steps.script.outputs.IDTOKENURL}}  -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" | jq -r '.value')
        echo $IDTOKEN
        jwtd() {
            if [[ -x $(command -v jq) ]]; then
                jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}"
                echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')"
            fi
        }
        jwtd $IDTOKEN
        echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT
      id: tokenid

Obtention du jeton d’accès à partir du fournisseur de cloud

Vous devez présenter le jeton JWT OIDC à votre fournisseur de cloud afin d’obtenir un jeton d’accès.

Pour chaque déploiement, vos workflows doivent utiliser des actions de connexion cloud (ou des scripts personnalisés) qui récupèrent le jeton OIDC et le présentent à votre fournisseur de cloud. Le fournisseur de cloud valide ensuite les revendications dans le jeton. S’il réussit, il fournit un jeton d’accès cloud disponible uniquement pour cette exécution de travail. Le jeton d’accès fourni peut ensuite être utilisé par les actions suivantes dans le travail pour la connexion au cloud et le déploiement sur ses ressources.

Les étapes d’échange du jeton OIDC pour un jeton d’accès varient pour chaque fournisseur de cloud.

Accès aux ressources dans votre fournisseur de cloud

Une fois que vous avez obtenu le jeton d’accès, vous pouvez utiliser des scripts ou des actions cloud spécifiques pour vous authentifier auprès du fournisseur de cloud et déployer sur ses ressources. Ces étapes peuvent différer pour chaque fournisseur de cloud. En outre, le temps d’expiration par défaut de ce jeton d’accès peut varier entre chaque cloud et peut être configurable du côté du fournisseur de cloud.

Pour aller plus loin

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