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

注: 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 のワークフロー例を示します。

注: 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
注: AWS IP アドレス範囲のみを許可することで、OIDC エンドポイントへのアクセスを制限できます。

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

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

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

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

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

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

注: AWS の ID とアクセス管理 (IAM) では、 GitHub の OIDC ID プロバイダー (IdP) を信頼するすべてのロールのtoken.actions.githubusercontent.com:sub信頼ポリシーで、IAM 条件キーを評価することをお勧めします。ロール信頼ポリシーでこの条件キーを評価すると、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"
  }
}

"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:OWNER/REPOSITORY:environment:NAME を参照する必要があります。詳しくは、「OpenID Connect を使ったセキュリティ強化について」を参照してください。

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

JSON

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

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

{
    "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 つの変更を行う必要があります。

トークンのアクセス許可設定を追加します。
この aws-actions/configure-aws-credentials アクションを使って、OIDC トークン (JWT) をクラウドアクセストークンと交換します。

アクセス許可設定の追加

ジョブまたはワークフローの実行には、id-token: write の permissions 設定が必要です。 id-token の permissions 設定が read または none の場合、OIDC JWT ID トークンを要求することはできません。

この 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

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

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

アクセストークンの要求

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

<example-bucket-name>: ここに S3 バケットの名前を追加します。
<role-to-assume>: 例を AWS ロールに置き換えます。
<example-aws-region>: ここに AWS リージョンの名前を追加します。

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 : "<example-bucket-name>"
  AWS_REGION : "<example-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@v3
        with:
          role-to-assume: arn:aws:iam::1234567890:role/example-role
          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 }}/

# 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 : "<example-bucket-name>"
  AWS_REGION : "<example-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@v3
        with:
          role-to-assume: arn:aws:iam::1234567890:role/example-role
          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 }}/

参考資料

再利用可能なワークフローでの OpenID Connect の使用 - セルフホステッドランナーの概要

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

この記事の内容

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