configure aws credentials
v4.0.2
Configurez vos informations d'identification AWS et vos variables d'environnement régional pour une utilisation dans d'autres actions GitHub.
Cette action met en œuvre la chaîne de résolution des informations d'identification AWS JavaScript et exporte des variables d'environnement de session pour vos autres actions à utiliser. Les exportations de variables d'environnement sont détectées à la fois par les SDK AWS et les appels AWS AWS CLI pour AWS.
Les appels de l'API à AWS doivent être signés avec des informations d'identification, donc lorsque vous utilisez l'un des SDK AWS ou un outil AWS, vous devez lui fournir des informations d'identification AWS et une région AWS. Une façon de le faire dans les actions GitHub consiste à utiliser un secret de référentiel avec IAM des informations d'identification, mais cela ne suit pas les directives de sécurité AWS sur l'utilisation des informations d'identification à long terme. Au lieu de cela, nous vous recommandons d'utiliser un diplôme à long terme ou JWT pour récupérer un diplôme temporaire et l'utiliser avec vos outils à la place. Cette action GitHub facilite juste cela.
Les SDK et outils AWS recherchent vos informations d'identification dans des variables d'environnement standardisées. En substance, cette action passe par le flux de résolution des informations d'identification standard et, à la fin, exporte des variables d'environnement à utiliser plus tard.
Nous prenons en charge cinq méthodes pour récupérer les informations d'identification de AWS, mais nous vous recommandons d'utiliser le fournisseur OIDC de GitHub en conjonction avec un point de terminaison du fournisseur d'identité AWS IAM configuré.
Pour plus d'informations sur la façon de procéder, lisez la suite.
Une partie de cette documentation peut être inexacte si vous utilisez GHES (GitHub Enterprise Server), veuillez noter la note de la documentation GitHub, une fois pertinente.
Par exemple, l'URL dont la JWT OIDC est émise est différente de la token.actions.githubusercontent.com et sera unique à votre serveur d'entreprise. En conséquence, vous devrez configurer cela différemment lorsque vous créez le fournisseur d'identité.
Nous n'avons pas actuellement un environnement de test de GHE pour valider cette action. Si vous courez dans des ghes et rencontrez des problèmes, veuillez nous le faire savoir.
Nous vous recommandons de suivre les meilleures pratiques d'Amazon IAM pour les informations d'identification AWS utilisées dans les flux de travail GitHub Actions, notamment:
Il existe cinq façons différentes de récupérer les informations d'identification:
AssumeRoleWithWebIdentity )AssumeRole )AssumeRoleWithWebIdentity )AssumeRole )Parce que nous utilisons le SDK AWS JavaScript, nous utiliserons toujours le flux de résolution des informations d'identification pour Node.js. Selon vos entrées, l'action peut remplacer les parties de ce flux.
Nous vous recommandons d'utiliser la première option ci-dessus: le fournisseur OIDC de GitHub. Cette méthode utilise OIDC pour obtenir des informations d'identification de courte durée nécessaires à vos actions. Voir OIDC pour plus d'informations sur la façon de configurer votre compte AWS pour assumer un rôle avec OIDC.
Le tableau suivant décrit la méthode que nous utiliserons pour obtenir vos informations d'identification en fonction des valeurs fournies à l'action:
| Identité utilisée | aws-access-key-id | role-to-assume | web-identity-token-file | role-chaining | id-token |
|---|---|---|---|---|---|
| [✅ Recommandé] Supposons un rôle directement à l'aide du fournisseur GitHub OIDC | ✔ | ✔ | |||
| IAM User | ✔ | ||||
| Assumer le rôle en utilisant les informations d'identification de l'utilisateur IAM | ✔ | ✔ | |||
| Assumer le rôle à l'aide des informations d'identification du fichier de jeton webidentity | ✔ | ✔ | |||
| Assumer le rôle en utilisant des informations d'identification existantes | ✔ | ✔ |
Remarque: role-chaining n'est pas toujours nécessaire pour utiliser les informations d'identification existantes. Si vous obtenez une erreur "les informations d'identification par le SDK ne correspond pas", essayez d'activer cette option.
Voir Action.yml pour plus de détails.
| Option | Description | Requis |
|---|---|---|
| AWS-Région | Quelle région AWS utiliser | Oui |
| rôle-supposition | Rôle pour lequel récupérer les informations d'identification. Uniquement requis pour certains types d'authentification. | Non |
| AWS-Access-Key-ID | Clé d'accès AWS à utiliser. Uniquement requis pour certains types d'authentification. | Non |
| AWS-Secret-Access-Key | Clé secrète AWS à utiliser. Uniquement requis pour certains types d'authentification. | Non |
| aws-session-token | Jeton de session AWS à utiliser. Utilisé dans les scénarios d'authentification inhabituels. | Non |
| rond | Utilisez des informations d'identification existantes de l'environnement pour assumer un nouveau rôle. | Non |
| public | Le public JWT lors de l'utilisation de OIDC. Utilisé dans les cloisons AWS non défaut, comme les régions chinoises. | Non |
| http-proxy | Un proxy HTTP à utiliser pour les appels API. | Non |
| masque-aws-compcou-id | Les identifiants de compte AWS ne sont pas considérés comme secrètes. Le définition de celle-ci masquera de toute façon les ID de compte de la sortie. | Non |
| rôles-durée-secondes | La durée du rôle supposée en secondes, si vous assumez un rôle. Par défaut à 1 heure. | Non |
| Rôle-extérieur-id | L'ID externe du rôle à assumer. Nécessaire uniquement si votre rôle l'exige. | Non |
| nom-session | Par défaut "githubactions", mais peut être modifié si nécessaire. | Non |
| rôles de skip-sasion | Ignore le taggage de session si défini. | Non |
| politique de session en ligne | Vous pouvez encore limiter la politique de rôle supposée en définissant une politique en ligne ici. | Non |
| polis gérées | Vous pouvez en outre restreindre la politique de rôle supposée en spécifiant une politique gérée ici. | Non |
| Sortie-création | Lorsqu'il est défini, les sorties ont obtenu des informations d'identification comme sortie d'action. Par défaut est faux. | Non |
| insensé | Lorsqu'il est défini, tente de non-déclencher les informations d'identification existantes dans votre coureur d'action. | Non |
| désactiver | Logique de réessayer / backoff désactivée pour assumer les appels de rôle. Par défaut, les tentatives sont activées. | Non |
| RETRY-MAX-ATTACTS | Limite le nombre de tentatives de réessayer avant d'abandonner. Par défaut à 12. | Non |
| caractéristiques spéciaux | Rimité, certains environnements ne peuvent pas tolérer des caractères spéciaux dans une clé secrète. Cette option réessayera les informations d'identification de récupération jusqu'à ce que la touche d'accès secrète ne contienne pas de caractères spéciaux. Cette option l'emporte sur la désactivation de la rétraction et de la réessayer-max-tempts. | Non |
La durée de session par défaut est de 1 heure .
Si vous souhaitez ajuster cela, vous pouvez passer une durée à role-duration-seconds , mais la durée ne peut pas dépasser le maximum qui a été défini lorsque le rôle IAM a été créé.
Si votre rôle nécessite un ID externe pour supposer, vous pouvez fournir à l'identifiant externe l'entrée role-external-id
Le nom de session par défaut est "GitHubactions", et vous pouvez le modifier en spécifiant le nom souhaité dans role-session-name . La session sera étiquetée avec les balises suivantes: (reportez-vous à la documentation de GitHub pour les définitions de variables d'environnement GITHUB_ )
| Clé | Valeur |
|---|---|
| Github | "Actes" |
| Dépôt | Github_repository |
| Flux de travail | Github_workflow |
| Action | Github_action |
| Acteur | Github_actor |
| Bifurquer | Github_ref |
| Commettre | Github_sha |
Remarque: Toutes les valeurs de balise doivent être conformes aux exigences de balise. En particulier, GITHUB_WORKFLOW sera tronqué s'il est trop long. Si GITHUB_ACTOR ou GITHUB_WORKFLOW contiennent des caractères non valides, les caractères seront remplacés par un '*'.
L'action utilisera le marquage de session par défaut lors de l'hypothèse du rôle, sauf si vous suivez notre recommandation et assumez un rôle avec un identifiant Web. Pour l'hypothèse du rôle de l'identification Web, les balises de session doivent être incluses dans le jeton codé de identification Web. Cela signifie que les étiquettes ne peuvent être fournies que par le fournisseur OIDC, et ils ne peuvent pas définir pendant l'appel API PassumerolewithWebidentity dans l'action. Voir # 419 pour plus d'informations.
Vous pouvez ignorer ce marquage de session en fournissant role-skip-session-tagging comme vrai dans les entrées de l'action:
uses : aws-actions/configure-aws-credentials@v4
with :
role-skip-session-tagging : trueLes politiques de session ne sont pas nécessaires, mais elles vous permettent de limiter la portée des informations d'identification récupérées sans modifier les rôles IAM. Vous pouvez spécifier les politiques de session en ligne directement dans votre fichier de workflow ou vous référer à une politique de session gérée existante par son ARN.
Une politique IAM au format JSON Stringified que vous souhaitez utiliser comme politique de session en ligne. Selon les préférences, le JSON pourrait être écrit sur une seule ligne comme ceci:
uses : aws-actions/configure-aws-credentials@v4
with :
inline-session-policy : ' {"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:List*","Resource":"*"}]} 'Ou nous pouvons également avoir un JSON bien formaté:
uses : aws-actions/configure-aws-credentials@v4
with :
inline-session-policy : >-
{
"Version": "2012-10-17",
"Statement": [
{
"Sid":"Stmt1",
"Effect":"Allow",
"Action":"s3:List*",
"Resource":"*"
}
]
} Les noms de ressources Amazon (ARN) des politiques gérées par IAM que vous souhaitez utiliser comme politiques de session gérées. Les politiques doivent exister dans le même compte que le rôle. Vous pouvez adopter une seule politique gérée comme ceci:
uses : aws-actions/configure-aws-credentials@v4
with :
managed-session-policies : arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccessEt nous pouvons passer plusieurs politiques gérées comme ceci:
uses : aws-actions/configure-aws-credentials@v4
with :
managed-session-policies : |
arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess
arn:aws:iam::aws:policy/AmazonS3OutpostsReadOnlyAccess Vous pouvez désormais configurer les paramètres de retche pour le moment où l'appel STS échoue. Par défaut, nous réessayons avec une backoff exponentielle 12 fois. Vous pouvez désactiver complètement ce comportement en définissant l'entrée disable-retry sur true , ou vous pouvez configurer le nombre de fois où il rétracte avec l'entrée retry-max-attempts .
Votre ID de compte n'est pas masqué par défaut dans les journaux de workflow car il n'est pas considéré comme des informations sensibles. Cependant, vous pouvez définir l'entrée mask-aws-account-id dans true pour masquer votre ID de compte dans les journaux de workflow si vous le souhaitez.
Parfois, les informations d'identification existantes dans votre coureur peuvent entraver le résultat prévu. Vous pouvez définir l'entrée de unset-current-credentials à true pour contourner ce problème.
Certains cas de bord ne sont pas en mesure d'analyser correctement un AWS_SECRET_ACCESS_KEY s'il contient des caractères spéciaux. Pour plus d'informations, veuillez consulter la documentation AWS CLI. Si vous définissez l'option special-characters-workaround , cette action réessayera continuellement les informations d'identification jusqu'à ce que nous en obtenions une qui n'a pas de caractères spéciaux. Cette option remplacent les options disable-retry et retry-max-attempts . Nous vous recommandons de ne pas activer cette option sauf si nécessaire, car la réessayer les API infiniment jusqu'à ce qu'elles réussissent ne sont pas la meilleure pratique.
Nous vous recommandons d'utiliser le fournisseur OIDC de GitHub pour obtenir des informations d'identification AWS de courte durée nécessaires à vos actions. Lorsque vous utilisez OIDC, vous configurez IAM pour accepter JWTS à partir du point de terminaison OIDC de GitHub. Cette action créera ensuite un JWT unique à l'exécution du flux de travail en utilisant le point de terminaison OIDC, et il utilisera le JWT pour assumer le rôle spécifié avec des informations d'identification à court terme.
Pour que cela fonctionne
Configurez votre flux de travail pour utiliser la permission id-token: write .
Configurez votre public, si nécessaire.
Dans votre compte AWS, configurez IAM pour faire confiance au fournisseur d'identité OIDC de GitHub.
Configurez un rôle IAM avec des limites de revendication et une portée d'autorisation appropriées.
Remarque : Nommer votre rôle "githubactions" aurait ne pas fonctionné. Voir # 953.
Spécifiez l'ARN de ce rôle lors de la mise en place de cette action.
Tout d'abord, pour que cette action crée le JWT, votre fichier de workflow doit avoir le id-token: write :
permissions :
id-token : write
contents : read Lorsque le JWT est créé, un public doit être spécifié. Normalement, vous utiliseriez sts.amazonaws.com , et cette action utilise cela par défaut si vous n'en spécifiez pas. Cela fonctionnera pour la plupart des cas. La modification du public par défaut peut être nécessaire lors de l'utilisation de partitions AWS non défaut, telles que les régions chinoises. Vous pouvez spécifier le public via la contribution audience :
- name : Configure AWS Credentials for China region audience
uses : aws-actions/configure-aws-credentials@v4
with :
audience : sts.amazonaws.com.cn
aws-region : us-east-3
role-to-assume : arn:aws-cn:iam::123456789100:role/my-github-actions-rolePour utiliser le fournisseur OIDC de GitHub, vous devez d'abord configurer la fédération avec le fournisseur comme IAM IDP. Le fournisseur GitHub OIDC ne doit être créé qu'une seule fois par compte (c'est-à-dire plusieurs rôles IAM qui peuvent être supposés par l'OIDC du GitHub peuvent partager un seul fournisseur OIDC). Voici un exemple de modèle CloudFormation qui configurera cette confiance pour vous.
Notez que l'empreinte ci-dessous a été définie sur tous les F, car l'empreinte net n'est pas utilisée lors de l'authentification token.actions.githubusercontent.com . Il s'agit d'un cas spécial utilisé uniquement lorsque l'OIDC de GitHub s'authentifie à IAM . IAM utilise sa bibliothèque de CAS de confiance pour s'authentifier. La valeur est toujours l'API, elle doit donc être spécifiée.
Vous pouvez copier le modèle ci-dessous ou le charger à partir d'ici: https://d38mtn6aq9zhn6.cloudfront.net/configure-aws-credentials-latest.yml
Parameters :
GitHubOrg :
Description : Name of GitHub organization/user (case sensitive)
Type : String
RepositoryName :
Description : Name of GitHub repository (case sensitive)
Type : String
OIDCProviderArn :
Description : Arn for the GitHub OIDC Provider.
Default : " "
Type : String
OIDCAudience :
Description : Audience supplied to configure-aws-credentials.
Default : " sts.amazonaws.com "
Type : String
Conditions :
CreateOIDCProvider : !Equals
- !Ref OIDCProviderArn
- " "
Resources :
Role :
Type : AWS::IAM::Role
Properties :
AssumeRolePolicyDocument :
Statement :
- Effect : Allow
Action : sts:AssumeRoleWithWebIdentity
Principal :
Federated : !If
- CreateOIDCProvider
- !Ref GithubOidc
- !Ref OIDCProviderArn
Condition :
StringEquals :
token.actions.githubusercontent.com:aud : !Ref OIDCAudience
StringLike :
token.actions.githubusercontent.com:sub : !Sub repo:${GitHubOrg}/${RepositoryName}:*
GithubOidc :
Type : AWS::IAM::OIDCProvider
Condition : CreateOIDCProvider
Properties :
Url : https://token.actions.githubusercontent.com
ClientIdList :
- sts.amazonaws.com
ThumbprintList :
- ffffffffffffffffffffffffffffffffffffffff
Outputs :
Role :
Value : !GetAtt Role.Arn Pour s'aligner sur les meilleures pratiques d'Amazon IAM pour accorder le moins de privilèges, le document de politique de rôle de supposition devrait contenir une Condition qui spécifie un sujet ( sub ) autorisé à assumer le rôle. GitHub recommande également le filtrage du bon public ( aud ). Voir la documentation AWS IAM sur les demandes que vous pouvez filtrer dans vos politiques de confiance.
Sans condition de sujet ( sub ), tout utilisateur ou référentiel GitHub pourrait potentiellement assumer le rôle. Le sujet peut être étendu à une organisation et à un référentiel GitHub, comme indiqué dans le modèle CloudFormation. Cependant, la portée à votre organisation et à votre repo peut entraîner l'échec de l'hypothèse du rôle dans certains cas. Voir l'exemple de réclamations du sujet pour des détails spécifiques sur ce que la valeur du sujet dépendra de votre flux de travail. Vous pouvez également personnaliser votre demande de sujet si vous souhaitez un contrôle total sur les informations pour lesquelles vous pouvez filtrer dans votre politique de confiance. Si vous n'êtes pas sûr de votre clé de sujet ( sub ), vous pouvez ajouter l'action actions-oidc-debugger à votre flux de travail pour voir la valeur de la clé du sujet ( sub ), ainsi que d'autres affirmations.
Des conditions de réclamation supplémentaires peuvent être ajoutées pour une spécificité plus élevée, comme expliqué dans la documentation GitHub. En raison des détails de mise en œuvre, toutes les réclamations OIDC ne sont pas actuellement appuyées par IAM.
Pour plus d'informations sur les actions OIDC et GitHub, veuillez consulter:
Si vous exécutez vos actions GitHub dans un coureur auto-hébergé qui a déjà accès aux informations d'identification AWS, telles qu'une instance EC2, vous n'avez pas besoin de fournir des informations d'identification de clés d'accès aux utilisateurs IAM à cette action. Nous utiliserons les méthodes de résolution des informations d'identification SDK AWS JavaScript standard pour trouver vos informations d'identification, donc si le SDK AWS JS peut s'authentifier sur votre coureur, cette action le fera également.
Si aucune information de clé d'accès n'est fournie dans les entrées d'action, cette action utilisera les informations d'identification de l'environnement coureur en utilisant les méthodes par défaut pour le SDK AWS pour JavaScript.
Vous pouvez utiliser cette action pour simplement configurer la région et l'ID de compte dans l'environnement, puis utiliser les informations d'identification du coureur pour tous les appels d'API AWS passés par votre flux de travail d'actions:
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2Dans ce cas, les informations d'identification de votre coureur doivent avoir des autorisations pour appeler les AWS AWS appelées par votre flux de travail d'actions.
Ou, vous pouvez utiliser cette action pour assumer un rôle, puis utiliser les informations d'identification de rôle pour tous les appels AWS AWS passés par le flux de travail de vos actions:
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : my-github-actions-roleDans ce cas, les informations d'identification de votre coureur doivent avoir des autorisations pour assumer le rôle.
Vous pouvez également assumer un rôle à l'aide d'un fichier de jeton d'identité Web, comme si vous utilisez Amazon EKS IRSA. Les pods exécutés dans les nœuds de travailleurs EKS qui ne s'exécutent pas comme racine peuvent utiliser ce fichier pour assumer un rôle avec une identité Web.
Si besoin utilise un proxy HTTP, vous pouvez le définir manuellement dans l'action.
De plus, cette action examinera toujours la variable d'environnement HTTP_PROXY .
Proxy configuré manuellement:
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : my-github-actions-role
http-proxy : " http://companydomain.com:3128 "Proxy configuré dans la variable d'environnement:
# Your environment configuration
HTTP_PROXY= " http://companydomain.com:3128 " Ce flux de travail n'installe pas la CLI AWS dans votre environnement. Les coureurs auto-hébergés qui ont l'intention d'exécuter cette action avant d'exécuter les commandes aws doivent avoir l'installation de la CLI AWS si elle n'est pas déjà présente. La plupart des environnements de coureurs hébergés par GitHub devraient inclure la CLI AWS par défaut.
- name : Configure AWS Credentials
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
role-session-name : MySessionName Dans cet exemple, l'action chargera le jeton OIDC de la variable d'environnement fournis par GitHub et l'utilisera pour assumer le rôle arn:aws:iam::123456789100:role/my-github-actions-role avec le nom de session MySessionName .
- name : Configure AWS Credentials
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
role-session-name : MySessionName
- name : Configure other AWS Credentials
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : arn:aws:iam::987654321000:role/my-second-role
role-session-name : MySessionName
role-chaining : true Dans cet exemple en deux étapes, la première étape utilisera OIDC pour assumer le rôle arn:aws:iam::123456789100:role/my-github-actions-role comme dans l'exemple précédent. Après cela, une deuxième étape utilisera ce rôle pour assumer un rôle différent, arn:aws:iam::987654321000:role/my-second-role .
- name : Configure AWS Credentials
uses : aws-actions/configure-aws-credentials@v4
with :
aws-access-key-id : ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key : ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region : us-east-2
role-to-assume : ${{ secrets.AWS_ROLE_TO_ASSUME }}
role-external-id : ${{ secrets.AWS_ROLE_EXTERNAL_ID }}
role-duration-seconds : 1200
role-session-name : MySessionName Dans cet exemple, le secret AWS_ROLE_TO_ASSUME contient une chaîne comme arn:aws:iam::123456789100:role/my-github-actions-role . Pour assumer un rôle dans le même compte que les informations d'identification statiques, vous pouvez simplement spécifier le nom de rôle, comme role-to-assume: my-github-actions-role .
- name : Configure AWS Credentials 1
id : creds
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : arn:aws:iam::123456789100:role/my-github-actions-role
output-credentials : true
- name : get caller identity 1
run : |
aws sts get-caller-identity
- name : Configure AWS Credentials 2
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
aws-access-key-id : ${{ steps.creds.outputs.aws-access-key-id }}
aws-secret-access-key : ${{ steps.creds.outputs.aws-secret-access-key }}
aws-session-token : ${{ steps.creds.outputs.aws-session-token }}
role-to-assume : arn:aws:iam::123456789100:role/my-other-github-actions-role
- name : get caller identity2
run : |
aws sts get-caller-identity Cet exemple montre que vous pouvez référencer les informations d'identification récupérées en tant que sorties si output-credentials est définie sur true. Cet exemple montre également que vous pouvez utiliser l'entrée aws-session-token dans une situation où les jetons de session sont récupérés et transmis à cette action.
Ce code est mis à disposition sous la licence MIT.
Si vous souhaitez signaler un problème de sécurité potentiel dans ce projet, veuillez ne pas créer de problème GitHub. Au lieu de cela, veuillez suivre directement les instructions ici ou envoyer un e-mail AWS Security.
