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 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 « À 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 ».
-
Assurez-vous que les points de terminaison OIDC suivants sont accessibles par votre fournisseur de cloud :
https://HOSTNAME/_services/token/.well-known/openid-configuration
https://HOSTNAME/_services/token/.well-known/jwks
Remarque : vous pouvez restreindre l’accès aux points de terminaison OIDC en autorisant uniquement les plages d’adresses IP AWS.
Remarque : GitHub ne prend pas en charge les balises de session AWS en mode natif.
Ajout du fournisseur d’identité à AWS
Pour ajouter le fournisseur OIDC GitHub à IAM, consultez la documentation AWS.
- Pour l’URL du fournisseur : Utilisez
https://HOSTNAME/_services/token
- 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 ».
Note : 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 :
"Condition": { "StringEquals": { "HOSTNAME/_services/token:aud": "sts.amazonaws.com", "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch" } }
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token: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 « À propos du renforcement de la sécurité avec 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 ».
"Condition": { "StringEquals": { "HOSTNAME/_services/token:aud": "sts.amazonaws.com", "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod" } }
"Condition": {
"StringEquals": {
"HOSTNAME/_services/token:aud": "sts.amazonaws.com",
"HOSTNAME/_services/token: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.
{ "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" } } } ] }
{
"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 :
- Ajoutez des paramètres d’autorisations pour le jeton.
- 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 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
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
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 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
# 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@v4 - 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 }}/
# 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@v4
- 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 }}/