configure aws credentials

為GitHub操作配置AWS憑據

配置您的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身份提供商端點結合使用。

有關如何做到這一點的更多信息，請繼續閱讀。

關於GHES的注意

如果您使用的是GHE（GitHub Enterprise Server），則該文檔中的某些文檔可能不准確，請注意在相關時查看GitHub文檔。

例如，發出的OIDC JWT的URL與通常的token.actions.githubusercontent.com不同，並且將是您的Enterprise Server唯一的。結果，當您創建身份提供商時，您需要以不同的方式進行配置。

目前，我們沒有GHES測試環境來驗證這一動作。如果您在GHES跑步並遇到問題，請告訴我們。

安全建議

我們建議遵循Amazon IAM的最佳實踐，適用於GitHub Actions Workfrows中使用的AWS證書，包括：

• 請勿將憑據存儲在存儲庫的代碼中。
• 授予GitHub Actions Workflows中使用的憑據至少特權。僅授予在github操作工作流程中執行操作所需的權限。即使在測試中，也不要假定過於允許的角色。
• 監視GitHub操作工作流程中使用的憑據的活動。
• 盡可能使用臨時憑據。
• 定期旋轉您使用的任何長期憑據。

使用此動作

有五種不同支持的方法來檢索憑據：

• 使用GitHub的OIDC提供商（ AssumeRoleWithWebIdentity ）
• 作為IAM用戶進行（未進行STS呼叫）
• 使用訪問密鑰作為操作輸入（ AssumeRole ）
• 使用WebIdentity代幣文件（ 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才能假設，則可以為外部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

由於不被視為敏感信息，因此默認情況下，您的帳戶ID默認情況下不會掩蓋。但是，如果需要，您可以將mask-aws-account-id輸入設置為true以掩蓋您的帳戶ID，如果需要。

未設置當前憑據

有時，跑步者中的現有憑據可能會妨礙預期的結果。您可以unset-current-credentials輸入設置為true以解決此問題。

AWS_SECRET_ACCESS_KEY中的特殊字符

某些邊緣案例無法正確解析AWS_SECRET_ACCESS_KEY如果它包含特殊字符。有關更多信息，請參閱AWS CLI文檔。如果您設置了special-characters-workaround選項，則此操作將不斷重試憑證，直到我們獲得沒有特殊字符的憑據為止。此選項覆蓋了disable-retry和retry-max-attempts選項。我們建議您除非需要，否則您不會啟用此選項，因為在成功之前無限地重試API並不是最佳實踐。

OIDC

我們建議使用GitHub的OIDC提供商獲得您的行動所需的短期AWS憑據。使用OIDC時，您將配置IAM接受GitHub OIDC端點的JWT。然後，此操作將創建一個使用OIDC端點的工作流程獨特的JWT，它將使用JWT命中具有短期憑據的指定角色。

為了工作

1. 配置您的工作流程以使用id-token: write權限。

2. 如果需要，配置您的受眾。

3. 在您的AWS帳戶中，將IAM配置為信任GitHub的OIDC身份提供商。

4. 配置具有適當索賠限制和權限範圍的IAM角色。

   注意：據報導，命名您的角色“ Githubactions”無效。參見＃953。

5. 在設置此操作時指定該角色的ARN。

首先，為了使此操作創建JWT，您的工作流文件必須具有id-token: write許可：

    permissions :
      id-token : write
      contents : read

OIDC觀眾

創建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

配置IAM到信任GitHub

要使用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的更多信息

有關OIDC和GITHUB操作的更多信息，請參閱：

• AWS文檔：創建OpenID Connect（OIDC）身份提供商
• AWS文檔：IAM JSON政策元素：條件
• GitHub文檔：關於使用OpenID Connect的安全性硬化
• GitHub文檔：在Amazon Web服務中配置OpenID連接
• GitHub ChangElog：GitHub操作：使用OpenID Connect的安全雲部署

自主跑者

如果您在已經可以訪問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 CLI安裝到您的環境中。打算在執行aws命令之前運行此操作的自主跑步者（如果尚未存在）需要安裝AWS CLI。默認情況下，大多數GitHub託管的Runner環境應包括AWS CLI。

例子

asherolewithwebidentity（推薦）

    - 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 。

在存儲庫秘密中具有靜態IAM憑證的假設

    - 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安全。