configure aws credentials
v4.0.2
配置您的AWS凭据和区域环境变量，以用于其他GitHub操作。
此操作实现了AWS JavaScript SDK凭据分辨率链，并导出会话环境变量，以便您使用其他操作。 AWS SDK和AWS CLI均可用于AWS API呼叫，可检测到环境变量的出口。
需要使用凭据信息签名API呼叫，因此，当您使用AWS SDK或AWS工具之一时，必须为其提供AWS凭据和AWS区域。在GitHub操作中执行此操作的一种方法是使用具有IAM凭据的存储库秘密，但这并不遵循AWS有关使用长期凭据的安全准则。取而代之的是，我们建议您使用长期凭据或JWT获取临时凭据，并将其与工具一起使用。这种行动促进了这一点。
AWS SDK和工具在标准化环境变量中寻找您的凭据。从本质上讲，此操作通过标准的凭证分辨率流进行，最后，导出环境变量供您以后使用。
我们支持从AWS获取凭据的五种方法，但是我们建议您将GitHub的OIDC提供商与已配置的AWS IAM IAM IAM身份提供商端点结合使用。
有关如何做到这一点的更多信息，请继续阅读。
如果您使用的是GHE（GitHub Enterprise Server），则该文档中的某些文档可能不准确，请注意在相关时查看GitHub文档。
例如，发出的OIDC JWT的URL与通常的token.actions.githubusercontent.com不同，并且将是您的Enterprise Server唯一的。结果，当您创建身份提供商时，您需要以不同的方式进行配置。
目前，我们没有GHES测试环境来验证这一动作。如果您在GHES跑步并遇到问题，请告诉我们。
我们建议遵循Amazon IAM的最佳实践，适用于GitHub Actions Workfrows中使用的AWS证书，包括：
有五种不同支持的方法来检索凭据：
AssumeRoleWithWebIdentity ）AssumeRole ）AssumeRoleWithWebIdentity ）AssumeRole ）因为我们使用AWS JavaScript SDK，所以我们始终将使用Node.js的凭证分辨率流。根据您的输入，该动作可能会覆盖该流程的一部分。
我们建议使用上面的第一个选项：GitHub的OIDC提供商。此方法使用OIDC获得您的动作所需的短期凭据。有关如何设置AWS帐户以在OIDC担任角色的更多信息，请参见OIDC。
下表描述了我们将使用哪种方法来获得您的凭据，该方法基于将哪些值提供给该操作的值：
| 使用的身份 | aws-access-key-id | role-to-assume | web-identity-token-file | role-chaining | id-token许可 |
|---|---|---|---|---|---|
| [✅建议]直接使用GitHub OIDC提供商直接扮演角色 | ✔ | ✔ | |||
| IAM用户 | ✔ | ||||
| 使用IAM用户凭据担任角色 | ✔ | ✔ | |||
| 使用WebIdentity代币文件凭据担任角色 | ✔ | ✔ | |||
| 使用现有凭据担任角色 | ✔ | ✔ |
注意：使用现有凭据并非总是需要role-chaining 。如果您获得“ SDK加载的凭据不匹配”错误，请尝试启用此选项。
有关更多详细信息，请参见Action.yml。
| 选项 | 描述 | 必需的 |
|---|---|---|
| AWS区域 | 哪个AWS区域要使用 | 是的 |
| 角色对录 | 获得证书的角色。仅对于某些身份验证类型需要。 | 不 |
| aws-access-key-id | AWS访问使用密钥。仅对于某些身份验证类型需要。 | 不 |
| AWS秘密访问键 | AWS秘密使用钥匙。仅对于某些身份验证类型需要。 | 不 |
| AWS会议 | AWS会话令牌要使用。用于不常见的身份验证方案。 | 不 |
| 角色链 | 使用来自环境的现有凭据担任新角色。 | 不 |
| 观众 | 使用OIDC时的JWT受众。在非默认AWS分区中使用，例如中国地区。 | 不 |
| http-proxy | 用于API调用的HTTP代理。 | 不 |
| mask-aws-account-id | AWS帐户ID不被视为秘密。无论如何，设置此将隐藏帐户ID。 | 不 |
| 角色持续一秒钟 | 如果担任角色，则假定的角色持续时间。默认为1小时。 | 不 |
| 角色 - 外部ID | 角色的外部ID。仅当您的角色需要时才需要。 | 不 |
| 角色主题名称 | 默认为“ githubactions”，但如果需要，可能会更改。 | 不 |
| 角色跳跃会议 | 跳过会话标记（如果设置）。 | 不 |
| 内联活动 | 您可以通过在此处定义内联策略来进一步限制假定的角色政策。 | 不 |
| 托管课程 | 您可以通过在此处指定托管政策来进一步限制假定的角色政策。 | 不 |
| 输出信用 | 设置后，输出获取的凭据作为操作步骤输出。默认为false。 | 不 |
| 未设定的信用 | 设置后，尝试尚未设置动作跑步者中的任何现有凭据。 | 不 |
| 禁用重返 | 假定角色调用的禁用重试/退缩逻辑。默认情况下，启用了检索。 | 不 |
| 重试麦克斯攻击 | 放弃之前限制重试尝试的数量。默认为12。 | 不 |
| 特殊字符 - 工作 | 罕见的是，某些环境无法在秘密密钥中忍受特殊字符。此选项将重试获取凭据，直到秘密访问密钥不包含特殊字符为止。此选项覆盖禁用重返和重试的最大值。 | 不 |
默认会话持续时间为1小时。
如果您想将其调整，则可以将持续时间传递到role-duration-seconds ，但是持续时间不能超过创建IAM角色时定义的最大值。
如果您的角色需要一个外部ID才能假设，则可以为外部ID提供role-external-id输入
默认的会话名是“ githubactions”，您可以通过在role-session-name中指定所需的名称来修改它。会话将标记以下标签：（请参阅GITHUB_环境变量定义的GitHub文档）
| 钥匙 | 价值 |
|---|---|
| github | “行动” |
| 存储库 | github_repository |
| 工作流程 | github_workflow |
| 行动 | github_action |
| 演员 | github_actor |
| 分支 | github_ref |
| 犯罪 | github_sha |
注意：所有标签值必须符合标签要求。特别是，如果GITHUB_WORKFLOW太长，将被截断。如果GITHUB_ACTOR或GITHUB_WORKFLOW包含无效的字符，则字符将被“*”替换。
该操作将在角色假设期间默认使用会话标记，除非您遵循我们的建议并在Webidentity中担任角色。对于WebIdentity的角色假设，必须将会话标签包括在编码的Web Indidentity令牌中。这意味着只能由OIDC提供商提供标签，并且在操作中的Apherolelolelewithwebidentity API呼叫期间无法设置标签。有关更多信息，请参见＃419。
您可以通过在动作的输入中提供role-skip-session-tagging来跳过此会话标签：
uses : aws-actions/configure-aws-credentials@v4
with :
role-skip-session-tagging : true不需要会话策略，但是它们允许您限制所取证凭证的范围，而无需更改IAM角色。您可以在工作流文件中指定内联会话策略，或者通过其ARN参考现有的托管会话策略。
您想用作内联策略的弦乐JSON格式的IAM策略。根据偏好，可以将JSON写在这样的一行上：
uses : aws-actions/configure-aws-credentials@v4
with :
inline-session-policy : ' {"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:List*","Resource":"*"}]} '或者我们也可以拥有一个格式很好的JSON：
uses : aws-actions/configure-aws-credentials@v4
with :
inline-session-policy : >-
{
"Version": "2012-10-17",
"Statement": [
{
"Sid":"Stmt1",
"Effect":"Allow",
"Action":"s3:List*",
"Resource":"*"
}
]
} 您想用作托管会话策略的IAM管理策略的亚马逊资源名称（ARNS）。政策必须与角色相同的帐户中。您可以通过这样的单一托管政策：
uses : aws-actions/configure-aws-credentials@v4
with :
managed-session-policies : arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess我们可以通过多个托管政策喜欢以下方式：
uses : aws-actions/configure-aws-credentials@v4
with :
managed-session-policies : |
arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess
arn:aws:iam::aws:policy/AmazonS3OutpostsReadOnlyAccess现在，您可以为STS呼叫失败时配置重试设置。默认情况下，我们以指数向后12次重试。您可以通过将disable-retry输入设置为true来完全禁用此行为，也可以配置其retry-max-attempts输入的次数。
由于不被视为敏感信息，因此默认情况下，您的帐户ID默认情况下不会掩盖。但是，如果需要，您可以将mask-aws-account-id输入设置为true以掩盖您的帐户ID，如果需要。
有时，跑步者中的现有凭据可能会妨碍预期的结果。您可以unset-current-credentials输入设置为true以解决此问题。
某些边缘案例无法正确解析AWS_SECRET_ACCESS_KEY如果它包含特殊字符。有关更多信息，请参阅AWS CLI文档。如果您设置了special-characters-workaround选项，则此操作将不断重试凭证，直到我们获得没有特殊字符的凭据为止。此选项覆盖了disable-retry和retry-max-attempts选项。我们建议您除非需要，否则您不会启用此选项，因为在成功之前无限地重试API并不是最佳实践。
我们建议使用GitHub的OIDC提供商获得您的行动所需的短期AWS凭据。使用OIDC时，您将配置IAM接受GitHub OIDC端点的JWT。然后，此操作将创建一个使用OIDC端点的工作流程独特的JWT，它将使用JWT命中具有短期凭据的指定角色。
为了工作
配置您的工作流程以使用id-token: write权限。
如果需要，配置您的受众。
在您的AWS帐户中，将IAM配置为信任GitHub的OIDC身份提供商。
配置具有适当索赔限制和权限范围的IAM角色。
注意：据报道，命名您的角色“ Githubactions”无效。参见＃953。
在设置此操作时指定该角色的ARN。
首先，为了使此操作创建JWT，您的工作流文件必须具有id-token: write许可：
permissions :
id-token : write
contents : read创建JWT时，需要指定受众。通常，您将使用sts.amazonaws.com ，如果您不指定一个操作，则此操作默认情况下使用此操作。对于大多数情况，这将有效。当使用非默认AWS分区（例如中国地区）时，可能需要改变默认受众。您可以通过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-role要使用GitHub的OIDC提供商，您必须首先与提供商的联合会设置为IAM IGP。 GitHub OIDC提供商只需要每个帐户一次创建一次（即GitHub的OIDC可以承担的多个IAM角色可以共享一个OIDC提供商）。这是一个示例云形式模板，它将为您配置此信任。
请注意，下面的指纹已设置为所有F，因为在身份验证token.actions.githubusercontent.com上未使用拇指标记。这是仅当GitHub的OIDC对IAM进行身份验证时使用的一种特殊情况。 IAM使用其受信任的CA库进行身份验证。该值仍然是API，因此必须指定它。
您可以复制下面的模板，也可以从此处加载：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 要与Amazon IAM授予最小特权的最佳实践保持一致，假设角色策略文件应包含一个指定允许担任该角色的受试者（ sub ）的Condition 。 Github还建议对正确的受众（ aud ）进行过滤。请参阅AWS IAM文档，您可以在信托政策中过滤哪些声明。
没有主题（ sub ）条件，任何GitHub用户或存储库都可以潜在地担任该角色。如云形式模板中所示，可以将主题范围范围为GitHub组织和存储库。但是，将其划分到您的组织和回购可能会导致角色假设在某些情况下失败。请参阅示例主题主张有关主题价值将取决于您的工作流程的具体详细信息。如果您想完全控制您的信托政策中可以过滤的信息，也可以自定义主题索赔。如果您不确定自己的主题（ sub ）密钥是什么，则可以将actions-oidc-debugger操作添加到工作流程中，以查看主题（ sub ）密钥的值以及其他主张。
如GitHub文档中所述，可以添加其他索赔条件以提高特异性。由于实施细节，并非IAM目前都支持所有OIDC索赔。
有关OIDC和GITHUB操作的更多信息，请参阅：
如果您在已经可以访问AWS凭据（例如EC2实例）的自托管跑步者中运行github操作，那么您无需为此操作提供IAM用户访问密钥凭据。我们将使用标准AWS JavaScript SDK凭据分辨率方法来查找您的凭据，因此，如果AWS JS SDK可以在您的跑步者身上进行身份验证，则此操作也将。
如果在操作输入中未给出访问密钥凭据，则此操作将使用AWS SDK的JavaScript使用Runner环境中的凭据。
您可以使用此操作简单地配置环境中的区域和帐户ID，然后使用您的操作工作流进行的所有AWS API调用的跑步者的凭据：
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2在这种情况下，您的跑步者的凭据必须具有拨打您的操作工作流量调用的任何AWS API的权限。
或者，您可以使用此操作来扮演角色，然后使用您的操作工作流程的所有AWS API调用的角色凭据：
uses : aws-actions/configure-aws-credentials@v4
with :
aws-region : us-east-2
role-to-assume : my-github-actions-role在这种情况下，您的跑步者的凭据必须具有担任角色的权限。
您还可以使用Web Identity代币文件扮演角色，例如使用Amazon EKS IRSA。在EKS Worker节点中运行的Pods不按root运行，可以使用此文件来扮演Web Identity的角色。
如果需要使用HTTP代理，则可以手动将其设置在操作中。
此外，此操作将始终考虑HTTP_PROXY环境变量。
手动配置代理：
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 "在环境变量中配置的代理：
# Your environment configuration
HTTP_PROXY= " http://companydomain.com:3128 "此工作流程不会将AWS CLI安装到您的环境中。打算在执行aws命令之前运行此操作的自主跑步者（如果尚未存在）需要安装AWS CLI。默认情况下，大多数GitHub托管的Runner环境应包括AWS CLI。
- 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在此示例中，该动作将从GitHub提供的环境变量中加载OIDC令牌，并使用它来扮演arn:aws:iam::123456789100:role/my-github-actions-role并带有会话名称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在这个两个步骤的示例中，第一步将使用OIDC来扮演角色arn:aws:iam::123456789100:role/my-github-actions-role就像前面的示例一样。在此之后，第二步将使用此角色扮演不同的角色， 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在此示例中，秘密AWS_ROLE_TO_ASSUME包含一个类似arn:aws:iam::123456789100:role/my-github-actions-role 。要在与静态凭据同一帐户中扮演角色，您可以简单地指定角色名称，例如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此示例表明，如果将output-credentials设置为true，则可以将获取的凭据作为输出。此示例还表明，您可以在将Session代币获取并传递给此操作的情况下使用aws-session-token输入。
此代码可根据MIT许可提供。
如果您想在此项目中报告潜在的安全问题，请不要创建GitHub问题。相反，请按照此处的说明或直接发送电子邮件给AWS安全。
