はじめに
GitHub App を使ったサービス連携を設定したことはありますか？
AWS Security Agent (現在は AWS Continuum の一部) 、GitHub Actions の一部、Slack 連携など、最近のサードパーティサービスは GitHub App を認証基盤に使っています。
どれも初回セットアップはGitHubの画面に遷移し「Install」をクリックしてリポジトリを選ぶだけ。
最初はあまり気にしてませんでしたが、お客様から「認証認可どうなってるの？」と聞かれたときに回答できませんでした。
この記事では、調査したGitHub App の認証フローを AWS Security Agent（GitHub リポジトリのコードレビューを実施するサービス）を題材に図解します。
JWT・Installation Access Token がどう組み合わさっているかを理解すれば、GitHub App を採用する他のサービスにも応用が利きます。
この記事は GitHub.com との連携を前提とし、 GitHub 側の認証フローに絞って説明しています。
また、GitHub App の標準仕様（一般論） と AWS Security Agent 固有の話 を区別して書いています。
Security Agent の内部実装が非公開の部分は「GitHub App の仕様上こうなる」という推定であることを明示しています。
結論
いきなり結論ですが、GitHub App という GitHub 公式の連携メカニズムを使っています。
ユーザーが「Install」をクリックした瞬間に GitHub App が Organization／ユーザー にインストールされ、以降はすべて短命トークン（JWT → Installation Access Token）で API アクセスします。
初回セットアップ
① AWS コンソールから GitHub にリダイレクト
AWS マネジメントコンソールの 統合 → 統合を追加 → GitHub → 「GitHubでAWS SecurityAgentを開く」 をクリックすると、GitHub にリダイレクトされます。
② GitHub 側でインストール対象を選択
GitHub の画面で以下を選びます:
- どの Organization（または個人アカウント）にインストールするか
- どのリポジトリにアクセスを許可するか（All / Only select）
選択後、GitHub 側の 「Install」 をクリックするとインストールが実行されます。
③ AWS コンソールに戻って接続登録
GitHub から AWS コンソールにリダイレクトされ、登録名、アカウントタイプ等を入力して「接続」をクリックすれば完了です。
実行時の認証: 2段階トークンの仕組み
初回セットアップが終わった後、Security Agent がリポジトリにアクセスするたびに走る認証フロー（推定）です。
GitHub App の認証仕様上、Installation Access Token の取得には JWT 認証が必須です。
そのため AWS Security Agent の内部実装の詳細は非公開ですが、認証部分はこの流れに従うと考えられます。
図の各ステップを説明します。
JWT（JSON Web Token）は署名付きの JSON データ構造です。改ざん検知が可能なため、認証情報の受け渡しに広く使われています。
読み方は「ジョット」です。
| # | 図の位置 | やっていること | 補足 |
|---|---|---|---|
| ① | AWS → Security Agent | 秘密鍵で JWT を生成 | RS256 署名、寿命最大10分。GitHub App 作成時に生成された秘密鍵をサービス提供者（AWS）が保管し、JWT の署名に使う。公開鍵は GitHub 側に保管される |
| ② | Security Agent → GitHub | JWT を添えてアクセストークンをリクエスト |
POST /app/installations/{installation_id}/access_tokens を JWT の Bearer 認証で呼び出す |
| ③ | GitHub 側 | JWT の検証 | GitHub が公開鍵で署名を検証し、正規の App であることを確認 |
| ④ | GitHub → Security Agent | Installation Access Token を返却 | 寿命1時間。インストール時に選択したリポジトリへのアクセスのみ許可 |
| ⑤ | Security Agent → GitHub | アクセストークンで GitHub API を実行 | PR の diff 取得、コメント投稿等 |
なぜ2段階なのか
JWT は「自分が正規の App である」という身分証明書で、Installation Access Token は「この Org のこのリポジトリにアクセスしていい」という入場許可証です。
役割が異なるため、GitHub App では JWT と Installation Access Token が明確に分離されています。
| トークン | 寿命 | 用途 |
|---|---|---|
| JWT | 最大10分 | App 自身の証明。Installation Access Token の取得専用 |
| Installation Access Token | 1時間 | リポジトリへの実際の操作（diff 取得、コメント投稿等） |
PR コードレビューの自動トリガー
PR 作成時に自動でセキュリティレビューが走る仕組みについて説明します。
AWS 公式ドキュメントによると、コードレビューが有効なリポジトリで PR を Ready for review にすると、Security Agent が自動的に分析を開始します。
分析が始まると「AWS Security Agent is analyzing your code…」というコメントが投稿され、完了後にセキュリティ所見がまとめてレビューとして投稿されます。
GitHub App では通常 Webhook でイベントを受信しますが、AWS Security Agent が具体的にどの仕組み（Webhook / GitHub Event API 等）を使っているかは公開されていません。
コメントは aws-security-agent[bot] というボットアカウントから投稿されるため、操作主体が一目でわかります。
まとめ
「Install」の裏で動いている仕組みを振り返ります。
- 初回セットアップ: GitHub App を Org / 個人 にインストール
- JWT: 秘密鍵で署名した短命トークン（10分）で App 自身を証明
- Installation Access Token: JWT 認証を経て取得する1時間限定のリポジトリ操作トークン
- PR イベント受信: Ready for review をトリガーに自動レビューを起動
この方式の本質は 「短命・最小権限・ユーザー非依存」を同時に実現している ことです。
GitHub App の仕組みを理解しておけば、Security Agent に限らず、GitHub App を使う他のサービスの認証も同じフレームワークで説明できます。
参考リンク