アマゾン ウェブ サービスでの OpenID Connect の構成

ワークフロー内で OpenID Connect を使用して、アマゾン ウェブ サービスで認証を行います。

この記事で

概要

OpenID Connect (OIDC) を使用すると、 GitHub Actions ワークフローは、有効期間の長い GitHub シークレットとして AWS の資格情報を格納する必要なく、アマゾン ウェブ サービス (AWS) 内のリソースにアクセスできます。

このガイドでは、 GitHubの OIDC をフェデレーション ID として信頼するように AWS を構成する方法について説明し、トークンを使用して AWS に対して認証し、リソースにアクセスする aws-actions/configure-aws-credentials のワークフロー例を示します。

メモ

OIDC のカスタム要求のサポートは、AWS では使用できません。

前提条件

  • GitHub が OpenID Connect (OIDC) を使用する方法の基本的な概念とそのアーキテクチャと利点については、「OpenID Connect」を参照してください。

  • 先に進む前に、アクセス トークンが予測可能な方法でのみ割り当てられるようにセキュリティ戦略を計画する必要があります。 クラウド プロバイダーがアクセス トークンを発行する方法を制御するには、少なくとも 1 つの条件を定義し、信頼できないリポジトリがクラウド リソースにアクセス トークンを要求できないようにする必要があります。 詳しくは、「OpenID Connect」をご覧ください。

  • GHE.com に関するこのガイドに従っている場合は、次のドキュメントの特定の値を置き換える必要があることを理解してください。 「OpenID Connect」を参照してください。

AWS への ID プロバイダーの追加

OIDC プロバイダーを IAM に追加するには、AWS のドキュメントを参照してください。

  • プロバイダー URL: https://token.actions.githubusercontent.com
  • 「対象者」には sts.amazonaws.com を指定します。(公式のアクションを利用する場合)。

ロールと信頼ポリシーの構成

IAMでのロール及び信頼関係の設定に関しては、AWSドキュメントのGitHub ActionsのためのAWS資格情報の設定およびGitHub OIDCアイデンティティプロバイダーのロール設定をご覧ください。

メモ

AWS Identity and Access Management (IAM) では、ユーザーは、token.actions.githubusercontent.com:subの OIDC ID プロバイダー (IdP) を信頼するすべてのロールの信頼ポリシーで、IAM 条件キー (GitHub) を評価することをお勧めします。 ロール信頼ポリシーでこの条件キーを評価すると、ロールを引き受けられる GitHub アクションが制限されます。

信頼ポリシーを編集して、sub フィールドを検証条件に追加します。 次に例を示します。

JSON
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

環境でワークフローを使用する場合、sub フィールドは環境名 repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME を参照する必要があります。 詳しくは、「OpenID Connect リファレンス」をご覧ください。

メモ

環境がワークフローまたは OIDC ポリシーで使われる場合は、セキュリティを強化するために環境に保護規則を追加することをお勧めします。 たとえば、環境のデプロイ規則を構成して、環境にデプロイできるブランチとタグを制限したり、環境シークレットにアクセスしたりできます。 詳しくは、「デプロイメント用の環境管理」をご覧ください。

JSON
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:environment:prod"
  }
}

次の例では、StringLike をワイルドカード演算子 (*) と共に使用して、任意のブランチ、pull request マージ ブランチ、または octo-org/octo-repo organization とリポジトリの環境が AWS でロールを引き受けることを許可します。

JSON
{
    "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"
                }
            }
        }
    ]
}


          GitHub Actions ワークフローの更新

OIDC のワークフローを更新するには、YAML に 2 つの変更を行う必要があります。

  1. トークンのアクセス許可設定を追加します。
  2. OIDC トークン (JWT) をクラウド アクセス トークンと交換するには、aws-actions/configure-aws-credentials アクションを使用します。

アクセス許可設定の追加

GitHub の OIDC プロバイダーが実行ごとに JSON Web Token を生成できるようにするためには、permissions``id-token: write を用いた設定がジョブまたはワークフロー実行に必要です。

メモ

ワークフローのアクセス許可で id-token: write を設定しても、リソースへの変更または書き込みを行うアクセス許可はワークフローに付与されません。 そうではなく、ワークフローは、アクションまたはステップのための OIDC トークンを要求 (フェッチ) して使用 (設定) することのみが許可されます。 その後、このトークンは、有効期間の短いアクセス トークンを使って外部サービスで認証を行うために使われます。

必要なアクセス許可、構成例、高度なシナリオについて詳しくは、「OpenID Connect リファレンス」をご覧ください。

アクセス トークンの要求

          `aws-actions/configure-aws-credentials` アクションは、OIDC プロバイダーから JWT を受け取り、その後 AWS からアクセス トークンを要求します。 詳細については、AWS の[ドキュメント](https://github.com/aws-actions/configure-aws-credentials)を参照してください。
  • BUCKET-NAME： これを S3 バケットの名前に置き換えます。
  • AWS-REGION：ここれを、お客様のAWSリージョンの名前に置き換えてください。
  • ROLE-TO-ASSUME: この部分をあなたの AWS ロールに置き換えてください。 たとえば、arn:aws:iam::1234567890:role/example-role のように指定します。
YAML
# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow creates a static website using Amazon S3
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。
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@v6
      - 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 }}/

参考資料