Terraform+CSV+GitHub ActionsでGitHub Organizationのメンバー管理をやってみた-②初期構築編

こんにちは！クラウド事業本部の吉田です。

皆さん、GitHub Organization利用していますか？

前回の記事では、Terraform+CSV+GitHub Actionsを利用して、GitHub Organizationのメンバー管理をする方法を紹介させていただきました。

当記事は、その仕組みの初期構築を解説した記事となります。
AWS環境構築とGitHub設定に分けて解説していきます。

記事リンク

• Terraform+CSV+GitHub ActionsでGitHub Organizationのメンバー管理をやってみた-①概要・利用方法編
• Terraform+CSV+GitHub ActionsでGitHub Organizationのメンバー管理をやってみた-②初期構築編　←イマココ
• Terraform+CSV+GitHub ActionsでGitHub Organizationのメンバー管理をやってみた-③仕組み編

AWS環境構築

Terraformにはtfstateファイルというリソースの状態を管理するファイルがあります。
個人検証を除いては、tfstateファイルはリモート管理することが通例です。
リモート管理する場所として、今回はS3を利用します。

AWS上で作成するリソースは以下の通りです。

• tfstateファイル管理用S3
• S3アクセス用IAMロール

簡単なイメージ図は以下の通りです。
（細かいところは省略しています。ご了承ください。）

tfstateファイル管理用S3

特殊な設定は必要ないです。
デフォルトの設定でS3を作成してください。

S3アクセス用IAMロール

OpenID Connect (OIDC) による一時的なクレデンシャルを利用することで、GitHubからAWSへのアクセス認証をよりセキュアにすることができます。
（IAMユーザーのアクセスキー・シークレットキーが不要となる）

OIDCに関しては、以下のドキュメントを参照してください。

OpenID Connect Protocol
アマゾン ウェブ サービスでの OpenID Connect の構成
GitHub ActionsとAWSの連携におけるOIDC認証の活用

OIDC認証のため、AWSアカウント上で以下の設定をします。

• GitHub OIDC プロバイダー
• GitHub Actionsが利用するIAMロール

GitHub OIDC プロバイダー作成

IAMコンソールから「ID プロバイダ」→「プロバイダを追加」の順にクリックします。

設定画面に移りましたら、各項目を設定します。

GitHub Actionsが利用するIAMロール作成

以下の信頼ポリシーとIAMポリシーが設定されたIAMロールを作成してください。

信頼ポリシー

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::{アカウントID}:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
                    "token.actions.githubusercontent.com:sub": "repo:{Organization名}/{リポジトリ名}:pull_request"
                }
            }
        }
    ]
}

一番重要なポイントは、「token.actions.githubusercontent.com:sub」の部分です。
特定のOrganizationとリポジトリを指定することで不正なアクセスを防ぎます。
またPullRequestをトリガーとすることで、意図しないイベントでのリソース変更も防ぐことができます。

IAMポリシー（カスタマー管理ポリシーかインラインポリシー）

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::{tfstateファイル管理用S3名}"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::{tfstateファイル管理用S3名}/*"
        }
    ]
}

tfstateファイル管理用S3に対する操作権限を付与しております。

GitHub設定

GitHub側の設定は大きく分けて３つあります。

• Organizationチームメンバー管理用のリポジトリ作成
• S3アクセス用IAMロールのARNをリポジトリのsecretに登録
• GitHub Apps作成

Organizationチームメンバー管理用のリポジトリ作成

Organizationチームメンバー管理用のリポジトリを作成し、下記リポジトリのサンプルコードを配置してください。
https://github.com/yoshida-takeshi-classmethod/sample-gh-org

展開方法はサンプルコード用のリポジトリからプライベートリポジトリとしてフォークする形でも、
Zipファイルをダウンロードしてそれを作成したリポジトリに展開する形でも構いません。

展開後は以下のファイルを更新してください。

• terraform/organization.tf
  • terraform/README.mdを参照して更新してください。
• terraform/version.tf
  • backendブロックのtfstateファイル管理用S3のバケット名とtfstateファイル名を指定してください。

S3アクセス用IAMロールのARNをリポジトリのsecretに登録

tfstateファイルをS3に保存するために、S3アクセス用IAMロールのARNをリポジトリのsecretに登録をしてください。
「リポジトリのSettings」→「Secrets and variables」→「Actions」→「New repository secret」の順で、リポジトリのsecretを登録できます。

以下のsecretを登録してください。

• AWS_ROLE_ARN: S3アクセス用IAMロールのARN

GitHub Apps作成

GitHub Actionsのワークフロー上でOrganizationのチームメンバーの管理の処理をするterraform plan、terraform applyのステップがあります。
GITHUB_TOKENではOrganizationのPermissionが設定できないため、Personal Access TokensかGitHub Appsトークンを利用する必要があります。

GITHUB_TOKEN のアクセス許可

今回は、運用面でもセキュリティ面でも勝るGitHub Appsトークンの方を採用します。

GitHub Appsトークンを導入するにあたって、下記の記事がとても参考になりました。
GitHub Appsトークン解体新書：GitHub ActionsからPATを駆逐する技術

当記事のGitHub Appsの作成手順は、参考記事の作成手順をOrganization向けにした形となります。
また仕組み編でも改めて紹介させていただきますが、GitHub Appsトークン生成スクリプトとGitHub Actionsワークフロー上のGitHub Appsトークン生成に関するステップも参考記事から引用させていただいております。
重ね重ね感謝を申し上げます。

GitHub Apps作成

「Organizationのsettings」→「Developers settings」→「GitHub Apps」→「New GitHub App」の順でGitHub Appの作成画面に移動し、下記の設定で作成してください。

基本情報

Webhook

「Active」のチェックを外してください。

Permissions

GitHub Appsトークンを利用する箇所は、Organizationのチームメンバーの管理の処理をするterraform plan、terraform applyのステップのため、Organization PermissionsのMembersのwrite権限が必要となります。
また併せてリポジトリのContentsのread権限も必要となります。

• Repository permissions
  • Contents: Read-only
  • Metadata:Read-only
• Organization permissions
  • Members: Read and write

Where can this GitHub App be installed?

「Only on this account」を選択してください。

秘密鍵生成

GitHub Apps作成後に管理画面（General）が表示されましたら、App IDを控えておきます。
下にスクロールしますと「Private keys」の項目がありますので、「Generate a private key」をクリックし、秘密鍵を生成します。

GitHub Appsインストール

管理画面の「Install App」を選択し、インストール先のアカウントにある「Install」をクリックします。
GitHub Appsのアクセスを許可するリポジトリを選択する画面が表示されますので、以下の設定をしたのちInstallをします。

• Only select repositories: Organizationチームメンバー管理用のリポジトリ

App IDと秘密鍵をリポジトリのsecretに登録

App IDと秘密鍵をリポジトリのsecretに登録します。
「リポジトリのSettings」→「Secrets and variables」→「Actions」→「New repository secret」の順で、リポジトリのsecretを登録できます。

以下のsecretを登録してください。

• APP_ID: 控えていたApp ID
• PRIVATE_KEY: ダウンロードした秘密鍵

秘密鍵をsecretに登録した後は、生成した秘密鍵は不要となります。流失のリスクのため、即時削除していただくようお願いします。

最後に

Terraform+CSV+GitHub Actionsを利用して、GitHub Organizationのメンバー管理をする仕組みの初期構築について解説しました。
初期構築が完了しましたら、最初の記事に戻り実際に運用してみてください。

詳細な仕組みについて解説した次の記事も読んでいただけると嬉しいです！

以上、クラウド事業本部の吉田でした！