GitHub Enterprise Cloud でのプログラムによるアクセスおよび統合
GitHub Enterprise Cloud (GHEC) では、API とコマンド ライン アクセスにいくつかの方法が用意されており、それぞれの長所、短所、制限を知ることをお勧めします。他のツールを GitHub に統合しようとする場合、またはオートメーションを構築しようとする場合、これらのプログラムによるアクセスのオプションを GitHub のアプリケーション プラットフォームと webhook を使用して拡張し確保する必要もあります。
Philips 社と Figma 社からはオンボーディングの自動化とポリシーの誤用防止に webhook を活用した事例について、SoftwareTesting.ai 社からは GitHub App を構築する利点について、それぞれお話を伺います。
このガイドの学習内容
個人アクセストークン (PAT) と SSH キーを使って GitHub API とコマンド ラインにアクセスする方法
自動化や、API アクセスを繰り返す必要のあるインテグレーションに GitHub App を利用するメリット
SaaS とセルフホステッドのツール導入が混在していても、インテグレーションを保護する方法
インテグレーションにポーリングではなく webhook を使用するベスト プラクティス
API とコマンド ライン アクセス
GitHub には API やコマンド ラインへのアクセスをユーザーに代わって認証するための主要な方法として、personal access token (個人アクセストークン、PAT)、SSH キー、IP 許可リストの 3 つがあります。各方法にはそれぞれ特徴があり、特定のシナリオへの向き不向きがあります。それでは、それぞれ方法を詳しく見ていきましょう。
個人アクセストークン (PAT)
PAT は GitHub API やコマンド ライン インターフェイス (CLI) を経由し、個々のユーザーに代わって GitHub Resources にアクセスします。Organization に代わってリソースにアクセスする場合や、長期的なインテグレーションのリソースにアクセスする場合には、Enterprise レベルのスケーラビリティとコントロールを提供できる GitHub App のほうが適しています。このアプローチについては後述します。
PAT は常にユーザーによって作成、管理され、所有されます。PAT にはユーザー自身が持つ特定のリソースや権限の種類に範囲設定されたアクセス権を付与できます。
SAML が有効化または強制されている Enterprise や Organization では、PAT がリソースにアクセスする前に、ユーザーがブラウザーで SAML シングル サインオン (SSO) 認証を完了して PAT を承認する必要があります。そうすることにより、SAML で認証された PAT を Enterprise または Organization の管理者が監査できるようになります。管理者はユーザー インターフェイスや API を通じて、いつでもその認証を取り消すことができます。管理者が取り消し操作を行わなければ、ユーザーが Organization から削除されるか、PAT のスコープが編集されるか、トークンが再生成されるか、期限が切れるまで、認証されたトークンは認証されたままになります。
GitHub は現在、細かい制御の PAT と従来の PAT の 2 種類の PAT をサポートしています。細かい制御の PAT では、有効期限を必須にしたりアクセス スコープを細かく設定したりできるなどの追加機能によってセキュリティが強化されます。従来の PAT はレガシー機能や、細かい制御の PAT にまだ対応していないエンドポイントをサポートするために残されています。拡張機能を利用できるように、可能な限り細かい制御の PAT を使用することをお勧めします。Enterprise および Organization のオーナーは、従来の PAT のアクセスを Enterprise または Enterprise が所有する Organization に制限するポリシーを設定できます。
SSH キーと認証局
SSH キーは個人が GitHub CLI に安全にアクセスできるようにするためのものです。SSH キーはコマンド ラインのみに使用されるため、PAT が必要とする他のリソースへのアクセスのスコープ タイプの追加制御は SSH キーでは考慮されません。
ただし、PAT と同様に、ブラウザーでの SAML SSO 認証によって SAML が有効化または強制される Enterprise や Organization では、SSH キーも SAML 認証を受ける必要があります。Enterprise または Organization の管理者は SAML で認証されたキーを監査し、ユーザー インターフェイスまたは API 経由でいつでもその認証を取り消すことができます。管理者が取り消し操作を行わなければ、認証されたキーは、ユーザーが Organization から削除されるか、キーが削除または無効化されるまで、認証されたままになります。
ユーザーは、新しい SSH キーペアを生成して公開キーを GitHub アカウントに追加すると、SSH キーを設定できます。ただし、SSH 認証局 (CA) を設定すれば、Enterprise または Organization で SSH キーを一元的にプロビジョニングして管理することもできます。一旦 SSH CA を設定すれば、Enterprise または Organization でプログラムによるアクセスに SSH キーのみを使用するよう要求することもできます。コマンド ライン アクセス全体で PAT の管理をなくしたい場合に便利です。個別に管理される SSH キーと同様、CA 署名された証明書には SAML 認証は必要ありません。
API と IP 許可リストに関する注意事項
GitHub とのインテグレーションを正しく機能させるには、GitHub の API を呼び出す必要があります。Enterprise または Organization に IP 許可リストを設定してある場合は、インストールするインテグレーション機能の IP 範囲を追加する必要があります。IP 許可リストを設定する際には、インストールするインテグレーションにリストの更新をオプションで許可できます。アプリケーションの許可リストがインテグレーションの作成者から提供されている場合は、自動的に許可リストに追加されます。提供されていない場合は、許可リストを手動で管理する必要があります。
Enterprise Managed User (EMU) の IP 許可リストと条件付きアクセスポリシー
OIDC SSO で EMU を使用する場合は、IdP の条件付きアクセス ポリシー (CAP) の IP 条件を使用してユーザーとのやり取りを検証するように GitHub を設定できます。また、全てのアプリケーションとインテグレーションの IP 範囲を IdP の CAP に追加しておく必要があります。
IP 許可リスト、CAP、Actions ランナーへのアクセス
GitHub には、ビルド、デプロイ、静的分析スキャン、その他必要な自動化を実行できる、ホステッド Actions ランナーが備わっています。GitHub のホステッド ランナーを 4 つ以上の vCPU で使用する場合、ランナー用に静的 IP アドレスを受け取ることができます。この IP アドレスは Enterprise 固有のものであり、IP 許可リストや IdP CAP に追加することによってランナーにコードへのアクセス権を付与できます。
App
GitHub API を繰り返し使用する場合は、API に直接アクセスするのではなく、アプリケーションを使用して API を操作することをお勧めします。特に、アプリケーションのインテグレーションには OAuth フレームワークよりも GitHub App フレームワークが推奨されます。GitHub App には、OAuth アプリや PAT ベースの API アクセスに比べて以下のように多くの利点があります。
きめ細かい権限、リポジトリ アクセスの選択肢、短時間有効なトークンなど、セキュリティ機能の強化
ユーザーから独立して、またはユーザーに代わって行動する機能
拡張性の高いレート制限
組み込みの webhook
GitHub は、GitHub App と OAuth の両方のインターフェイスを使用する既存のインテグレーションを取り扱う、信頼性の高いコミュニティもサポートしています。開発ツールチェインに他のツールとのインテグレーションを考えている場合は、アプリケーション ベースの GitHub インテグレーション機能を利用できる場合があります。
管理者は Organization にどのアプリケーションをインストールし、どのリポジトリと権限を付与するかを制御します。インストールを完全に制限したり、アプリケーションのインストールに管理者の承認を必要としたりするポリシーを設定することもできます。管理者はアプリケーション固有の管理権限をユーザーに委譲して、GitHub App の管理を手伝ってもらうこともできます。
アプリケーションは Organization (または個々のユーザー) レベルにのみインストールできます。
ワークフローを改善し、コードを構築して出荷するまでの非効率性に対処する上で、開発者ができることはたくさんあります。GitHub は Octokit で一連の堅牢な API と SDK を提供していますが、これらを利用すると、日常業務を改善するためのツールを非常に簡単に構築**できます。**他の開発者にも使ってもらえるように GitHub Marketplace に簡単に公開できるため、より幅広い開発者コミュニティがその恩恵を受けることができます。
webhook
webhook を使用すると、スケジュールに沿って API をポーリングして特定のイベントが発生したかどうかをチェックする代わりに、GitHub で特定のイベントが発生した時点で外部 Web サーバーに通知を配信できます。JSON ペイロードを HTTPS POST で安全に配信します。インテグレーションでは webhook が作成され、通知を配信するイベントが選択されて、GitHub がペイロードを配信する公開ルーティング可能なエンドポイントが提供されます。また、オプションで、GitHub がペイロードに暗号を使用して署名するためのシークレットの値を指定できます。 オンプレミスのリソースに webhook を配信する GHEC デプロイの一環として、ファイアウォールの背後にホストされ、GitHub と統合するアプリケーションに通知を配信するための webhook が必要になる場合があります。
ネットワークを適切に設定すれば、以下のような一種のリバース プロキシを実装することによって、GHEC からこれらのシステムに通知を配信できます。
GitHub が HTTPS POST を送信できる、一般にルーティング可能な完全修飾ドメイン名 (FQDN) URL の書き換えと適切なアプリケーションへのポート転送
このようなパターンは、ngrok のようなベンダーの既製のコンポーネントを使用したり、NGINX のような既存の Web サーバーを設定したり、WAF や API ゲートウェイのような商用製品を使用したりすることによって実装できます。
当社では webhook を使用して GitHub イベントを監視しています。そうすることで、新しいユーザーが組織に加わったときに自動的に問題を作成して割り当て、ユーザーのオンボーディングを支援することができます。
オンプレミスのリソースへの webhook の配信を保護する
リバース プロキシを実装して webhook の配信を処理する場合、GitHub では以下の方法を推奨しています。
FQDN に対するポート 443 での受信 HTTPS トラフィックのみを許可する
https://api.github.com/meta の hooks セクションに記載されている IP 範囲からのトラフィックのみを許可する
FQDN で SSL を終了し、JSON ペイロードを検査して、適切にフォーマットされた JSON が存在するかどうかを確認する
統合するソリューションが webhook 署名をサポートし、使用していること確認する
当社の変更管理ポリシーは、効率性を高めるように設計されています。プルリクエストのマージには他のメンバーによる承認が必要ですが、旧式の承認がなくなったわけではありません。**当社では、レビュー担当者はプルリクエストの詳細ではなく全体的な意図を承認するというアプローチを採用しています。**例えば、承認にスタイルに関する簡単なコメントがいくつかある場合、通常、コメントに対処し、2 回目の承認を得ることなくプルリクエストをマージすることを送信者に許可します。
同時に、このポリシーが悪用されないようにするため、AWS Lambda 上に構築したカスタムの自動化にフィードされる Organization レベルの webhook を使用して自動化を構築し、それをセキュリティ情報およびイベント管理 (SIEM) プラットフォームにフィードしました。これにより、このポリシーが悪用されていると思われるケース (承認後の大幅な変更とともにマージされたプルリクエスト) にフラグを立て、アラートを出して対処できるようになりました。
ポーリング
GitHub API を使用するインテグレーションや自動化を作成する場合は、API ポーリングを使用しないでください。全てのシステム利用者にパフォーマンスと信頼性を保証できるよう、GitHub では個人利用の API のアクティビティには厳しいレート制限を設けており、アプリケーションにはさらに高い制限を設けています。API を定期的にポーリングすると、特に大規模な Organization の場合、レート制限に達してしまいます。
定期的に API をポーリングするのではなく、webhook を使用して GitHub のイベントを通知するようにしてください。インテグレーションは、サブスクライブしている全ての webhook イベントを受け取り、何らかのアクションを必要とする認証済みのリクエストを GitHub に送信します。
次の項目: 監査ログにアクセス、キャプチャ、使用する
このモジュールの締めくくりとして、最後にもうひとつトピック「監査ログ」を取り上げます。規制遵守のためであれ、トラブルシューティングのためであれ、監査ログは Enterprise 内のさまざまな行動に関する書面での証跡として利用できます。監査ログの内容とアクセス方法を理解するまでは、最初のオンボーディングは完了しません。