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

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

この記事の内容

Note

GitHub ホステッド ランナーは、現在 GitHub Enterprise Server ではサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。

概要

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

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

Note

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

前提条件

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

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

  • クラウド プロバイダーが次の OIDC エンドポイントにアクセスできることを確認する必要があります。

    • https://HOSTNAME/_services/token/.well-known/openid-configuration
    • https://HOSTNAME/_services/token/.well-known/jwks

    Note

    AWS IP アドレス範囲のみを許可することで、OIDC エンドポイントへのアクセスを制限できます。

    Note

    GitHub では、AWS セッション タグがネイティブでサポートされていません。

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

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

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

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

IAM でロールと信頼を構成するには、AWS ドキュメント「GitHub Actions 用の AWS 資格情報 の構成」と「GitHub OIDC ID プロバイダーのロールの構成」を参照してください。

Note

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

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

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

環境でワークフローを使用する場合、sub フィールドは環境名 repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME を参照する必要があります。 詳しくは、「OpenID Connect を使ったセキュリティ強化について」を参照してください。

独自のカスタム保護規則を有効にして、サードパーティ サービスを使ったデプロイを制御できます。 たとえば、Datadog、Honeycomb、ServiceNow などのサービスを使用し、GitHub への展開に対して自動承認を提供できます。

JSON
"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token: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. この aws-actions/configure-aws-credentials アクションを使って、OIDC トークン (JWT) をクラウド アクセス トークンと交換します。

アクセス許可設定の追加

ジョブまたはワークフローの実行には、GitHub の OIDC プロバイダーが実行ごとに JSON Web Token を作成できるようにするために、id-token: write を含む permissions 設定が必要です。 id-token の permissions が write に設定されていない場合、OIDC JWT ID トークンを要求することはできません。ただし、この値はリソースへの書き込みアクセスを許可することを意味せず、アクションまたはステップの OIDC トークンをフェッチして設定し、有効期間の短いアクセス トークンを使用して認証を有効にできるだけです。 実際の信頼の設定は OIDC 要求を使用して定義されます。詳細については、「OpenID Connect を使ったセキュリティ強化について」を参照してください。

この id-token: write 設定により、次のいずれかの方法を使用して、GitHub の OIDC プロバイダーから JWT を要求できます。

  • ランナーで環境変数を使用する (ACTIONS_ID_TOKEN_REQUEST_URL および ACTIONS_ID_TOKEN_REQUEST_TOKEN)。
  • アクション ツールキットから getIDToken() を使用する。

ワークフローの OIDC トークンをフェッチする必要がある場合は、ワークフロー レベルでアクセス許可を設定できます。 次に例を示します。

YAML
permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

1 つのジョブに対して OIDC トークンのみをフェッチする必要がある場合は、そのジョブ内でこのアクセス許可を設定できます。 次に例を示します。

YAML
permissions:
  id-token: write # This is required for requesting the JWT

ワークフローの要件に応じて、ここで追加のアクセス許可を指定する必要がある場合があります。

呼び出し元ワークフローと同じユーザー、Organization、または Enterprise が所有する再利用可能なワークフローの場合、再利用可能なワークフローで生成された OIDC トークンに呼び出し元のコンテキストからアクセスできます。 Enterprise または Organization 外部の再利用可能なワークフローについては、id-token の permissions 設定を、呼び出し元ワークフロー レベル、または再利用可能ワークフローを呼び出す特定のジョブで write に設定してください。 これにより、再利用可能なワークフローで生成された OIDC トークンは、意図した場合にのみ呼び出し元ワークフローで使用できるようになります。

詳しくは、「ワークフローの再利用」を参照してください。

アクセス トークンの要求

この aws-actions/configure-aws-credentials アクションを使うと、GitHub OIDC プロバイダーから JWT を受け取り、アクセス トークンを AWS に要求します。 詳細については、AWS のドキュメントを参照してください。

  • 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 static website using aws s3
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@v4
      - 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 }}/

参考資料