OIDC接続

AWSリソースの準備ができたので、次はGitHub ActionsからAWSへ接続するための設定を行います。ビルドしたコンテナイメージをECRにプッシュしたり、ECSにデプロイしたりするには、GitHub ActionsからAWSリソースへアクセスする必要があります。そのための前準備としてGitHub ActionsとAWSの接続設定を行います。

1. なぜOIDCを使うのか

GitHub ActionsからAWSに接続する方法はいくつかありますが、大きく分けると次の2通りになります。

  1. IAMユーザのアクセスキーID・シークレットアクセスキーをGitHubのSecretsに登録し、ワークフローから使用する
  2. OIDCで、GitHub Actionsが発行したIDトークンをAWSが検証し、一時的なクレデンシャルを発行してアクセスする

1の方法はシンプルですが、アクセスキーが万が一漏洩すると第三者がAWSリソースに恒久的にアクセスできてしまうというリスクがあります。また、定期的なローテーションも必要になります。

一方、2のOIDC(OpenID Connect)を使う方法では、アクセスキーを保存する必要がなく、毎回一時的な短命クレデンシャルが発行されます。漏洩リスクが大幅に軽減され、ローテーションも不要になるため、本番環境ではこちらが推奨される方法です。今回は実務で使える形を体験するために、OIDCでの接続を採用します。

📝 OIDCとは
OIDC(OpenID Connect)は、認証を行うための仕組みの一つです。GitHub ActionsとAWSの場合、ワークフロー実行時にGitHubが「このリポジトリ・ブランチから実行された」というIDトークンを発行し、AWSがそれを検証して一時的なクレデンシャルを発行します。信頼関係を事前にAWS側に登録しておくことで、「特定のリポジトリからのワークフロー実行時だけAWSへのアクセスを許可する」といった細かい制御ができます。

2. OIDCの設定に必要な作業

OIDCでGitHub ActionsとAWSを接続するには、AWS側で2つの設定を行う必要があります。

作業 内容
IAM Identity Providerの作成 GitHubのOIDCプロバイダ(token.actions.githubusercontent.com)をAWSに登録する
IAMロールの作成 GitHub Actionsが引き受けるロールを作成し、信頼関係と権限を設定する

これらを順番に作成していきます。

3. IAM Identity Providerの作成

まず、GitHubをOIDCプロバイダとしてAWSに登録します。これにより、GitHubから発行されたIDトークンをAWSが信頼できるようになります。

AWSマネジメントコンソールでIAMのダッシュボードを開きます。検索バーに「IAM」と入力し、サービスを選択してください。

左メニューからIDプロバイダを選択し、プロバイダを追加をクリックします。

以下の設定でプロバイダを追加します。

設定項目 値 設定の基準
プロバイダのタイプ OpenID Connect OIDCでGitHubと接続するため
プロバイダのURL https://token.actions.githubusercontent.com GitHub ActionsのOIDCエンドポイント
対象者 sts.amazonaws.com AWS STSをターゲットとするため

入力後、プロバイダを追加をクリックします。

IDプロバイダの一覧にtoken.actions.githubusercontent.comが追加されていれば、ここまでの操作は完了です。

💡 ポイント
以前はOIDCプロバイダを作成する際に「サムプリント(指紋)」の登録が必要でしたが、現在のAWSでは自動的に検証される仕組みになっているため、この手順は不要です。プロバイダのURLと対象者を指定するだけで登録できます。

4. IAMロールの作成

次に、GitHub Actionsが引き受けるIAMロールを作成します。このロールには、「どのGitHubリポジトリからのアクセスを許可するか」という信頼関係と、「そのロールがAWSで何をできるか」という権限の2つを設定します。

IAMのダッシュボードの左メニューからロールを選択し、ロールを作成をクリックします。

4.1 信頼されたエンティティの選択

ロール作成画面で、信頼されたエンティティのタイプを選択します。

設定項目 値 設定の基準
信頼されたエンティティタイプ ウェブアイデンティティ OIDCプロバイダを信頼するため
アイデンティティプロバイダー token.actions.githubusercontent.com 先ほど作成したOIDCプロバイダ
Audience sts.amazonaws.com AWS STSをターゲットとするため
GitHub組織 ご自身のGitHubユーザ名 リポジトリのオーナー名
GitHubリポジトリ devopscamp-cicd-handson 対象のリポジトリ名
GitHubブランチ main mainブランチからのアクセスだけを許可するため。feature/xxxブランチ等からAWSを操作できないようにする
💡 ポイント
GitHub組織には、ご自身のGitHubユーザ名(個人アカウントの場合)または組織名を指定します。GitHubリポジトリには、本章で作成したリポジトリ名(devopscamp-cicd-handson)を指定してください。リポジトリ名を変えている場合は、その名前を指定します。
💡 ポイント
ブランチを空欄にすると、リポジトリ内のあらゆるブランチからAWSへアクセスできてしまいます。今回のワークフローは mainへのpush でのみ動作する前提なので、mainブランチのみを信頼する設定にしておくとセキュリティが高まります。feature/xxxブランチ等から意図せずAWSリソースが操作される事故を防げます。

将来、ステージング環境を追加する場合は staging ブランチを許可リストに追加する、という形で拡張できます。

設定後、次へをクリックします。

4.2 許可ポリシーの追加

このロールには、あとのステップでインラインポリシー(特定のリソース・アクションに絞ったカスタムポリシー)として必要な権限を追加します。このステップではAWS管理ポリシーは何も選択せず、そのまま次へをクリックしてください。

💡 ポイント
AWSが用意する管理ポリシー(例: AmazonEC2ContainerRegistryPowerUser)は広く使いやすい反面、リソースやアクションが広めに許可されがちです。本章では「最小権限の原則」を体感してもらうため、必要なECR・ECSのアクションだけを、対象リソースも絞ったインラインポリシーで付与します。

4.3 名前、確認、および作成

最後にロールの名前と説明を入力します。

設定項目 値 設定の基準
ロール名 github-actions-deploy-role GitHub Actionsからのデプロイに使うロール
説明 Role for deployment from GitHub Actions ロールの目的を明確にするため

入力後、画面下部のロールを作成をクリックします。

⚠️ 「ロールの説明が無効です」エラーが出る場合
AWSのIAMロール説明欄は日本語を受け付けません。英数字と記号のみで入力してください。使用可能な文字は A-Za-z0-9、タブ、改行、および `_+=,.@-/[{}]!#$%^*():;"'`` の記号です。説明欄はオプションなので、空欄のままでも構いません。

ロール一覧にgithub-actions-deploy-roleが表示されていれば、ここまでの操作は完了です。

4.4 デプロイ権限の追加(インラインポリシー)

作成したロールにはまだ権限が何もついていません。ECRへのイメージプッシュとECSへのデプロイを行うために、インラインポリシーとして必要な権限を設定します。

先ほど作成したgithub-actions-deploy-roleの詳細画面を開きます。

許可タブから許可を追加 > インラインポリシーを作成をクリックします。

JSONタブを選択し、以下の内容を入力します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ECRAuth",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Sid": "ECRPush",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:PutImage",
        "ecr:BatchGetImage"
      ],
      "Resource": "arn:aws:ecr:*:*:repository/test-repository"
    },
    {
      "Sid": "ECSDeploy",
      "Effect": "Allow",
      "Action": [
        "ecs:UpdateService",
        "ecs:DescribeServices",
        "ecs:DescribeTaskDefinition",
        "ecs:RegisterTaskDefinition",
        "ecs:DeregisterTaskDefinition",
        "ecs:ListTasks",
        "ecs:DescribeTasks"
      ],
      "Resource": "*"
    },
    {
      "Sid": "PassExecutionRole",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::*:role/ecsTaskExecutionRole-cicd-handson"
    }
  ]
}

ポリシーは4ブロックに分かれています。各ブロックが「何に」「何の権限を」「なぜ」与えているかを以下の表で解説します。

Sid 対象リソース 与える権限 なぜ必要か
ECRAuth 全ECR(*) ecr:GetAuthorizationToken docker login 時にECRから一時認証トークンを取得する必要がある。このAPIはアカウント単位の操作のため、リポジトリでリソースを絞れない仕様
ECRPush test-repository リポジトリのみ ecr:BatchCheckLayerAvailability / ecr:InitiateLayerUpload / ecr:UploadLayerPart / ecr:CompleteLayerUpload / ecr:PutImage / ecr:BatchGetImage docker push でイメージをアップロードするために必要な一連の操作。レイヤーの確認・アップロード開始・転送・完了・登録までをカバーする。リソースを絞ることで他のECRリポジトリには手出しできないようにしている
ECSDeploy 全ECS(*) ecs:UpdateService / ecs:DescribeServices / ecs:DescribeTaskDefinition / ecs:RegisterTaskDefinition / ecs:DeregisterTaskDefinition / ecs:ListTasks / ecs:DescribeTasks タスク定義を新しいリビジョンとして登録し、ECSサービスを更新してデプロイするために必要。RegisterTaskDefinition はリソース絞り込みが利かない仕様のため、本章では * としている
PassExecutionRole ecsTaskExecutionRole-cicd-handson ロールのみ iam:PassRole ECSがタスクを起動する際、コンテナにCloudWatch Logsへの書き込み権限などを与える「タスク実行ロール」をECS側に渡す必要がある。CloudFormationで作成した特定ロールだけに絞ることで、任意のIAMロールを勝手に渡せないようにしている

次へをクリックし、ポリシー名にDeployPolicyと入力してポリシーの作成をクリックします。

github-actions-deploy-roleの許可一覧にDeployPolicyが追加されていれば、ここまでの操作は完了です。

5. ロールARNの確認

作成したIAMロールのARNは、後ほどGitHub Actionsのワークフローから参照します。github-actions-deploy-roleの詳細画面の上部に表示されているARNを確認しておきましょう。

ARNは以下のような形式になっています。

arn:aws:iam::123456789012:role/github-actions-deploy-role

この中の123456789012の部分がAWSアカウントIDです。このアカウントIDはGitHub Actionsワークフローから参照するため、次のステップでGitHubのシークレットに登録します。

6. GitHubシークレットの登録

GitHub Actionsのワークフローからロールを参照する際、AWSアカウントIDをコードにハードコードすると、リポジトリを見た人にアカウントIDが知られてしまいます。アカウントID自体は機密情報ではありませんが、安全な運用としてはGitHubのシークレット機能に登録し、ワークフローから動的に参照する形が推奨されます。

ここでは、AWSアカウントIDをGitHubシークレットに登録します。

GitHubの対象リポジトリ(devopscamp-cicd-handson)のページを開きます。

Settingsタブをクリックし、左メニューからSecrets and variables > Actionsを選択します。

New repository secretボタンをクリックし、以下の内容でシークレットを登録します。

設定項目 値 設定の基準
Name AWS_ACCOUNT_ID ワークフローから参照する際の名前
Secret 先ほど確認したAWSアカウントID(例: 123456789012) 対象のAWSアカウント

Add secretボタンをクリックすると、シークレットが登録されます。

シークレット一覧にAWS_ACCOUNT_IDが表示されていれば、ここまでの操作は完了です。