Configuration d’OpenID Connect dans Amazon Web Services

Utilisez OpenID Connect dans vos workflows pour vous authentifier auprès d’Amazon Web Services.

Dans cet article

Vue d’ensemble

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

Ce guide explique comment configurer AWS pour approuver le protocole OIDC de GitHub en tant qu’identité fédérée et il inclut un exemple de workflow pour aws-actions/configure-aws-credentials qui utilise des jetons pour s’authentifier auprès d’AWS et accéder aux ressources.

Remarque

La prise en charge des réclamations personnalisées pour OIDC n’est pas disponible dans AWS.

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 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 « OpenID Connect ».

Ajout du fournisseur d’identité à AWS

Pour ajouter le fournisseur OIDC GitHub à IAM, consultez la documentation AWS.

  • Pour l’URL du fournisseur : Utilisez https://token.actions.githubusercontent.com
  • Pour le « public » : utilisez sts.amazonaws.com si vous utilisez l’action officielle.

Configuration du rôle et de la stratégie d’approbation

Pour configurer le rôle et la confiance dans IAM, consultez la documentation AWS « Configurer les informations d’identification AWS pour les GitHub Actions » et « Configurer un rôle pour le fournisseur d’identité GitHub OIDC ».

Remarque

AWS Identity and Access Management (IAM) recommande aux utilisateurs d’évaluer la clé de condition IAM, token.actions.githubusercontent.com:sub, dans la stratégie de confiance de tout rôle qui fait confiance au fournisseur d’identité OIDC (IdP) de GitHub. L’évaluation de cette clé de condition dans les limites des rôles de stratégie de confiance dont les actions GitHub peuvent assumer le rôle.

Modifiez la stratégie d’approbation pour ajouter le champ sub aux conditions de validation. Par exemple :

JSON
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

Si vous utilisez un flux de travail avec un environnement, le champ sub doit référencer le nom de l’environnement : repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME. Pour plus d’informations, consultez « Informations de référence sur OpenID Connect ».

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 « Gestion des environnements pour le déploiement ».

JSON
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:environment:prod"
  }
}

Dans l’exemple suivant, StringLike est utilisé avec un opérateur générique (*) pour autoriser toute branche, toute branche de fusion de demande de tirage ou tout environnement de l’organisation octo-org/octo-repo et du dépôt à assumer un rôle dans AWS.

JSON
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456123456:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:*"
                },
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

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 aws-actions/configure-aws-credentials pour échanger le jeton OIDC (JWT) afin d’obtenir un jeton d’accès cloud.

Ajout de paramètres d’autorisations

L’exécution d’une tâche ou d’un flux de travail nécessite un paramètre permissions avec id-token: write pour permettre au fournisseur OIDC de GitHub de créer un jeton Web JSON pour chaque exécution.

Remarque

Le paramètre id-token: write dans les autorisations du flux de travail ne donne pas au flux de travail l’autorisation de modifier ou d’écrire dans des ressources. Au lieu de cela, il permet uniquement au flux de travail de demander (récupérer) et d’utiliser (définir) un jeton OIDC pour une action ou une étape. Ce jeton est ensuite utilisé pour s’authentifier auprès de services externes à l’aide d’un jeton d’accès à courte durée de vie.

Pour plus d’informations sur les autorisations requises, les exemples de configuration et les scénarios avancés, consultez Informations de référence sur OpenID Connect.

Demande du jeton d’accès

L’action aws-actions/configure-aws-credentials reçoit un jeton JWT à partir du fournisseur OIDC GitHub, puis demande un jeton d’accès à partir d’AWS. Pour plus d’informations, consultez la documentation AWS.

  • BUCKET-NAME : Remplacez ceci par le nom de votre compartiment S3.
  • AWS-REGION : Remplacez ceci par le nom de votre région AWS.
  • ROLE-TO-ASSUME: remplacez ce champ par votre rôle AWS. Par exemple, arn:aws:iam::1234567890:role/example-role
YAML
# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow Creates static website using aws s3
name: AWS example workflow
on:
  push
env:
  BUCKET_NAME : "BUCKET-NAME"
  AWS_REGION : "AWS-REGION"
# permission can be added at job level or workflow level
permissions:
  id-token: write   # This is required for requesting the JWT
  contents: read    # This is required for actions/checkout
jobs:
  S3PackageUpload:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v5
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
        with:
          role-to-assume: ROLE-TO-ASSUME
          role-session-name: samplerolesession
          aws-region: ${{ env.AWS_REGION }}
      # Upload a file to AWS s3
      - name: Copy index.html to s3
        run: |
          aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/

Pour aller plus loin