注: 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
フィールドを検証条件に追加します。 次に例を示します。
"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:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
を参照する必要があります。 詳しくは、「OpenID Connect を使ったセキュリティ強化について」を参照してください。
独自のカスタム保護規則を有効にして、サードパーティ サービスを使ったデプロイを制御できます。 たとえば、Datadog、Honeycomb、ServiceNow などのサービスを使用し、GitHub への展開に対して自動承認を提供できます。
"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 でロールを引き受けることを許可します。
{ "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) をクラウド アクセス トークンと交換します。
アクセス許可設定の追加
ジョブまたはワークフローの実行には、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 トークンをフェッチする必要がある場合は、ワークフロー レベルでアクセス許可を設定できます。 次に例を示します。
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 トークンのみをフェッチする必要がある場合は、そのジョブ内でこのアクセス許可を設定できます。 次に例を示します。
permissions: id-token: write # This is required for requesting the JWT
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
のように指定します。
# 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@v3 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 }}/
# 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@v3
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 }}/