configure aws credentials

GitHubアクションのAWS資格情報を構成します

他のGitHubアクションで使用するために、AWS資格情報と地域環境変数を構成します。

このアクションにより、AWS JavaScript SDKクレデンシャル解像度チェーンとセッション環境変数をエクスポートして、他のアクションを使用します。環境変数のエクスポートは、AWS API呼び出しのAWS SDKとAWS CLIの両方によって検出されます。

概要

AWSへのAPI呼び出しは資格情報に署名する必要があるため、AWS SDKまたはAWSツールのいずれかを使用する場合、AWS資格情報とAWS領域を提供する必要があります。 GitHubアクションでそれを行う1つの方法は、IAM資格情報を含むリポジトリシークレットを使用することですが、これは長期的な資格情報を使用することに関するAWSセキュリティガイドラインには従いません。代わりに、一時的な資格情報を取得して、代わりにツールで使用するために長期資格情報またはJWTを使用することをお勧めします。このgithubアクションはまさにそれを促進します。

AWS SDKとツールは、標準化された環境変数で資格情報を探します。本質的に、このアクションは標準の資格情報の解像度フローを通じて実行され、最後に環境変数をエクスポートして後で使用します。

AWSから資格情報を取得するための5つの方法をサポートしていますが、構成されたAWS IAM IDプロバイダーエンドポイントと組み合わせてGitHubのOIDCプロバイダーを使用することをお勧めします。

その方法の詳細については、読んでください。

GHEについてのメモ

このドキュメントの一部は、GHES（GitHub Enterprise Server）を使用している場合に不正確になる場合があります。関連する場合は、GitHubドキュメントを確認してください。

たとえば、OIDC JWTが発行されるURLは、通常のtoken.actions.githubusercontent.comとは異なり、エンタープライズサーバーに固有のものになります。その結果、IDプロバイダーを作成するときに、これを異なる方法で構成する必要があります。

現在、このアクションを検証するGHESテスト環境はありません。 GHESで走って問題が発生している場合は、お知らせください。

セキュリティの推奨事項

GitHubアクションワークフローで使用されているAWS資格情報のAmazon IAMベストプラクティスをフォローすることをお勧めします。

• リポジトリのコードに資格情報を保存しないでください。
• GitHub Actions Workflowsで使用される資格情報に最小限の特権を付与します。 GitHubアクションワークフローでアクションを実行するために必要なアクションのみを付与します。テストであっても、過度に寛容な役割を想定しないでください。
• GitHubアクションワークフローで使用される資格情報のアクティビティを監視します。
• 可能であれば、一時的な資格情報を使用してください。
• 使用する長期的な資格情報を定期的に回転させます。

このアクションを使用します

資格情報を取得するための5つの異なるサポートされた方法があります。

• GitHubのAssumeRoleWithWebIdentityプロバイダーを使用する
• IAMユーザーとしての進行（STSコールは行われません）
• アクションキーをアクション入力として使用する（ AssumeRole ）
• WebIdentityトークンファイルを使用AssumeRoleWithWebIdentity
• ランナーに既存の資格情報を使用する（ AssumeRole ）

AWS JavaScript SDKを使用しているため、Node.jsには常に資格情報の解像度フローを使用します。入力に応じて、アクションはこのフローの一部をオーバーライドする可能性があります。

上記の最初のオプションを使用することをお勧めします：GithubのOIDCプロバイダー。この方法では、OIDCを使用して、アクションに必要な短命の資格情報を取得します。 OIDCの役割を引き受けるためにAWSアカウントを設定する方法の詳細については、OIDCを参照してください。

次の表には、アクションにどの値が提供されるかに基づいてクレデンシャルを取得するために使用する方法について説明します。

使用されているアイデンティティ	aws-access-key-id	role-to-assume	web-identity-token-file	role-chaining	id-token許可
[bused bused github oidcプロバイダーを使用して、役割を直接想定します		✔			✔
IAMユーザー	✔
IAMユーザー資格情報を使用して役割を想定します	✔	✔
WebIdentityトークンファイル資格情報を使用して役割を想定します		✔	✔
既存の資格情報を使用して役割を想定します		✔		✔

注：既存の資格情報を使用するためには、 role-chaining必ずしも必要ではありません。 「SDKによってロードされた資格情報が一致しない」エラーを取得している場合は、このオプションを有効にしてみてください。

オプション

詳細については、action.ymlを参照してください。

オプション	説明	必須
AWS-REGION	どの地域を使用するか	はい
役割への顧問	資格情報を取得する役割。一部の認証タイプにのみ必要です。	いいえ
AWS-ACCESS-KEY-ID	使用するAWSアクセスキー。一部の認証タイプにのみ必要です。	いいえ
AWS-Secret-Access-Key	使用する秘密の鍵。一部の認証タイプにのみ必要です。	いいえ
aws-session-token	使用するAWSセッショントークン。 UNCommon認証シナリオで使用されます。	いいえ
ロールチェーン	環境からの既存の資格情報を使用して、新しい役割を引き受けます。	いいえ
観客	OIDCを使用するときのJWTオーディエンス。中国地域のように、非デフォルトAWSパーティションで使用されています。	いいえ
http-proxy	API呼び出しに使用するHTTPプロキシ。	いいえ
Mask-Aws-Account-ID	AWSアカウントIDは秘密とは見なされません。これを設定すると、とにかくアカウントIDが出力から非表示になります。	いいえ
ロール期間秒	役割を想定する場合、秒単位での想定される役割の期間。デフォルトは1時間です。	いいえ
ロールエクタナルID	想定する役割の外部ID。あなたの役割がそれを必要とする場合にのみ必要です。	いいえ
ロールセッション名	デフォルトは「githubactions」になりますが、必要に応じて変更される場合があります。	いいえ
ロールスキップセッションタグ	設定されている場合はセッションタグ付けをスキップします。	いいえ
インラインセッションポリティ	ここでインラインポリシーを定義することにより、想定される役割ポリシーをさらに制限できます。	いいえ
マネージドセッションポリス	ここで管理されたポリシーを指定することにより、想定される役割ポリシーをさらに制限することができます。	いいえ
出力クレデンシャル	設定すると、アクションステップ出力としてクレデンシャルを取得します。デフォルトはfalseになります。	いいえ
無制限のクレジンシャル	設定すると、アクションランナーの既存の資格情報を設定しようとします。	いいえ
無効化 - retry	役割呼び出しを想定するための無効な再試行ロジック。デフォルトでは、RETRIESが有効になっています。	いいえ
retry-max-attemps	あきらめる前に、再試行の試みの数を制限します。デフォルトは12です。	いいえ
特別なキャラクターワークアラウンド	まれに、一部の環境では、秘密の鍵の特殊文字を容認することはできません。このオプションは、Secret Accessキーに特殊文字が含まれないまで、資格情報の取得を再試行します。このオプションは、無効化と再試行を無効にします。	いいえ

資格寿命

デフォルトのセッション期間は1時間です。

これを調整したい場合は、期間をrole-duration-secondsに渡すことができますが、IAMの役割が作成されたときに定義された最大値を超えることはできません。

外部ID

あなたの役割が想定するために外部IDを必要とする場合、あなたは外部IDにrole-external-id入力を提供することができます

セッションのタグ付けと名前

デフォルトのセッション名は「githubactions」であり、 role-session-nameで目的の名前を指定することで変更できます。セッションには、次のGITHUB_がタグ付けされます。

鍵	価値
github	「行動」
リポジトリ	github_repository
ワークフロー	github_workflow
アクション	github_action
俳優	github_actor
支店	github_ref
専念	github_sha

注：すべてのタグ値は、タグ要件に準拠する必要があります。特に、 GITHUB_WORKFLOWが長すぎると切断されます。 GITHUB_ACTORまたはGITHUB_WORKFLOW無効な文字が含まれている場合、文字は「*」に置き換えられます。

アクションは、私たちの推奨に従い、Webidentityの役割を想定していない限り、ロール仮定中にデフォルトでセッションタグ付けを使用します。 WebIdentityの役割の仮定の場合、セッションタグをエンコードされたWebIdentityトークンに含める必要があります。これは、タグはOIDCプロバイダーによってのみ提供できることを意味し、アクション内のAsiserolewithwithwithidentity API呼び出し中に設定できません。詳細については、＃419を参照してください。

アクションの入力でTrueとしてrole-skip-session-tagging提供することにより、このセッションのタグ付けをスキップできます。

      uses : aws-actions/configure-aws-credentials@v4
      with :
        role-skip-session-tagging : true

セッションポリシー

セッションポリシーは必要ありませんが、IAMの役割に変更を加えることなく、フェッチされた資格情報の範囲を制限することができます。ワークフローファイルで直前のセッションポリシーを指定するか、ARNの既存の管理セッションポリシーを参照することができます。

インラインセッションポリシー

インラインセッションポリシーとして使用するStringified 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管理ポリシーのAmazonリソース名（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は、機密情報とは見なされていないため、デフォルトでワークフローログにマスクされていません。ただし、必要に応じて、ワークフローログのアカウントIDをマスクするには、 mask-aws-account-id入力をtrueに設定できます。

現在の資格情報を設定します

ランナーの既存の資格情報は、意図した結果を妨げることがあります。この問題を回避するために、 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を使用する場合、GitHubのOIDCエンドポイントからJWTSを受け入れるようにIAMを構成します。このアクションは、OIDCエンドポイントを使用してワークフロー実行に固有のJWTを作成し、JWTを使用して、短期資格情報で指定された役割を引き受けます。

これを機能させるために

1. id-token: write許可を使用するようにワークフローを構成します。

2. 必要に応じて、視聴者を構成します。

3. AWSアカウントでは、GitHubのOIDC IDプロバイダーを信頼するようにIAMを構成します。

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

Githubを信頼するためにIAMを構成します

GithubのOIDCプロバイダーを使用するには、最初にIAM IDPとしてプロバイダーと連邦を設定する必要があります。 GitHub OIDCプロバイダーは、アカウントごとに1回作成するだけで作成する必要があります（つまり、GitHubのOIDCが想定できる複数のIAMロールは、単一のOIDCプロバイダーを共有できます）。これは、あなたのためにこの信頼を構成するサンプルクラウド形成テンプレートです。

token.actions.githubusercontent.comを認証するときにthumbprintが使用されないため、以下のサムプリントはすべてのfに設定されていることに注意してください。これは、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ユーザーまたはリポジトリは潜在的に役割を引き受ける可能性があります。 CloudFormationテンプレートに示すように、主題はGitHub組織とリポジトリにスコープできます。ただし、それを組織とリポジトリまでスコーピングすると、場合によっては役割の仮定が失敗する可能性があります。ワークフローに依存する科目値がどうなるかについての特定の詳細については、サンプルの主張を参照してください。また、信頼ポリシーでフィルタリングできる情報を完全に制御したい場合は、被験者のクレームをカスタマイズすることもできます。被験者（ sub ）キーが何であるかわからない場合は、 actions-oidc-debuggerアクションをワークフローに追加して、サブジェクト（ sub ）キーの価値を確認できます。

GitHubドキュメントで説明されているように、より高い特異性のために追加の請求条件を追加できます。実装の詳細により、すべてのOIDCクレームが現在IAMによってサポートされているわけではありません。

OIDCの詳細情報

OIDCおよびGitHubアクションの詳細については、次をご覧ください。

• AWSドキュメント：OpenID Connect（OIDC）IDプロバイダーの作成
• AWSドキュメント：IAM JSONポリシー要素：条件
• GitHub Docs：OpenID Connectを使用したセキュリティ硬化について
• Github Docs：Amazon WebサービスでOpenID Connectの構成
• github changelog：githubアクション：OpenID Connectを使用してクラウド展開をセキュア

自己ホストランナー

EC2インスタンスなど、AWS資格情報に既にアクセスできる自己ホストランナーでGitHubアクションを実行する場合、このアクションにIAMユーザーアクセスキー資格情報を提供する必要はありません。標準のAWS JavaScript SDKクレデンシャル解決方法を使用して資格情報を見つけます。そのため、AWS JS SDKがランナーで認証できる場合、このアクションも同様です。

アクション入力にアクセスキー資格情報が与えられていない場合、このアクションは、JavaScriptのAWS SDKのデフォルトの方法を使用して、ランナー環境の資格情報を使用します。

このアクションを使用して、環境でリージョンとアカウント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

この場合、ランナーの資格情報は、役割を引き受けるための権限を持たなければなりません。

また、Amazon EKSIRSAを使用している場合など、Web Identityトークンファイルを使用する役割を引き受けることもできます。 rootとして実行されないEKSワーカーノードで実行されるポッドは、このファイルを使用してWeb IDの役割を引き受けることができます。

プロキシ構成

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ホストランナー環境には、デフォルトでAWS CLIを含める必要があります。

例

assererolewithweithidedity（推奨）

    - 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 arn:aws:iam::123456789100:role/my-github-actions-roleセッション名MySessionNameで想定します。

同じワークフローでアクションによって以前に想定されていた役割を持つasrieRole

    - 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

この2段階の例では、最初のステップではOIDCを使用して、 arn:aws:iam::123456789100:role/my-github-actions-role前の例のように想定します。それに続いて、2番目のステップでは、この役割を使用して別の役割を想定します。ARN arn:aws:iam::987654321000:role/my-second-role 。

リポジトリの秘密に静的IAM資格情報を備えたAsriserole

    - 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

この例では、Secret AWS_ROLE_TO_ASSUMEにはarn:aws:iam::123456789100:role/my-github-actions-roleのような文字列が含まれています。静的資格情報と同じアカウントで役割を想定するには、 role-to-assume: my-github-actions-roleのロール名を単純に指定できます。

ステップ出力から資格情報を取得すると、一時的な資格情報を備えたAssionerole

    - 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に設定されている場合、フェッチされた資格情報を出力として参照できることを示しています。この例は、セッショントークンがフェッチされ、このアクションに渡される状況でaws-session-token入力を使用できることも示しています。

ライセンスの概要

このコードは、MITライセンスの下で利用可能になります。

セキュリティ開示

このプロジェクトで潜在的なセキュリティの問題を報告したい場合は、GitHubの問題を作成しないでください。代わりに、こちらの指示に従って、AWSセキュリティに直接メールで送信してください。