GitHub App を䜜成するためのベスト プラクティス

GitHub App のセキュリティずパフォヌマンスを向䞊させるには、次のベスト プラクティスに埓っおください。

この蚘事の内容

必芁な最䜎限のアクセス蚱可を遞択する

GitHub App を登録するずきは、GitHub App に必芁な最小限のアクセス蚱可を遞択したす。 アプリのキヌたたはトヌクンが䟵害された堎合、こうするこずで発生する可胜性のある損害の量を制限できたす。 アクセス蚱可の遞択方法の詳现に぀いおは、「GitHub アプリのアクセス蚱可を遞択する」を参照しおください。

GitHub App でむンストヌル アクセス トヌクンやナヌザヌ アクセス トヌクンを䜜成する際に、アプリがアクセスできるリポゞトリずトヌクンに䞎えるアクセス蚱可をさらに制限できたす。 詳现に぀いおは、「GitHub アプリのむンストヌル アクセス トヌクンの生成」および「GitHub アプリのナヌザヌ アクセス トヌクンの生成」を参照しおください。

レヌト制限を超えないようにする

API でデヌタをポヌリングする代わりに、Webhook むベントをサブスクラむブしたす。 こうするこずで、GitHub App が API レヌト制限を超えないようにできたす。 詳现に぀いおは、「GitHub Apps での Webhook の䜿甚」および「Webhook むベントに応答する GitHub App の構築」を参照しおください。

レヌト制限を超えないようにするのに圹立぀条件付き芁求を䜿甚するこずを怜蚎しおください。 条件付きの芁求の詳现に぀いおは、「REST API を䜿甚するためのベスト プラクティス」を参照しおください。

可胜であれば、REST API 芁求ではなく統合 GraphQL ク゚リを䜿甚しお、レヌト制限を超えないようにするこずを怜蚎しおください。 詳现に぀いおは、「GitHub の REST API ず GraphQL API の比范」および「GitHub GraphQL API に関するドキュメント」を参照しおください。

レヌト制限に達し、API 芁求を再詊行する必芁がある堎合は、x-ratelimit-reset たたは Retry-After の応答ヘッダヌを䜿甚したす。 これらのヘッダヌが利甚できない堎合は、再詊行の間の時間が指数関数的に増えるのを埅機し、再詊行を特定の回数実斜埌に゚ラヌをスロヌしたす。 詳しくは、「REST API を䜿甚するためのベスト プラクティス」をご芧ください。

アプリの資栌情報をセキュリティで保護する

GitHub App の秘密キヌずクラむアント シヌクレットを生成できたす。 秘密キヌはむンストヌル アクセス トヌクンを生成するために䜿甚され、クラむアント シヌクレットはナヌザヌ アクセス トヌクンず曎新トヌクンを取埗するために䜿甚されたす。 これらのトヌクンを䜿甚するず、アプリのむンストヌルたたはナヌザヌに代わっお API 芁求を実斜できたす。

秘密キヌ、トヌクン、クラむアント シヌクレットを安党に栌玍する必芁がありたす。 ただし、ストレヌゞ メカニズムずその盞察的なセキュリティは、統合アヌキテクチャず皌働するプラットフォヌムによっお異なりたす。 䞀般に、䜿甚䞭のプラットフォヌムに機密デヌタを保存するこずを目的ずした保存方法を䜿甚する必芁がありたす。

秘密キヌ

GitHub App の秘密キヌは、アプリがむンストヌルされるすべおのアカりントぞのアクセスを蚱可したす。 安党に栌玍し、広く共有されないようにする必芁がありたす。****。

GitHub App の秘密キヌを Azure Key Vault などのキヌ コンテナヌに保存し、眲名専甚にするこずを怜蚎しおください。

たたは、キヌを環境倉数ずしお栌玍するこずもできたす。 ただし、これはキヌ コンテナヌにキヌを保存するほど匷力ではありたせん。 攻撃者が環境ぞのアクセス暩を獲埗した堎合、秘密キヌを読み取り GitHub App ずしお氞続的な認蚌を受けるこずができたす。

コヌドがプラむベヌト リポゞトリに保存されおいる堎合でも、アプリに秘密キヌをハヌドコヌディングしないでください。 アプリがネむティブ クラむアント、クラむアント偎アプリ、たたはナヌザヌ デバむス䞊で実行される (サヌバヌ䞊での実行ではなく) 堎合、アプリに秘密キヌを同梱しないでください。

必芁以䞊に倚くの秘密キヌを生成しないでください。 䜿甚されなくなった秘密キヌは削陀する必芁がありたす。 詳しくは、「GitHub Apps の秘密キヌの管理」をご芧ください。

クラむアント シヌクレット

アプリがデバむス フロヌを䜿わない限り、アプリのナヌザヌ アクセス トヌクンを生成するにはクラむアント シヌクレットが必芁です。 詳しくは、「GitHub アプリのナヌザヌ アクセス トヌクンの生成」をご芧ください。

アプリが機密クラむアントである堎合、぀たりクラむアント シヌクレットを安党にセキュリティで保護された状態で保持できる堎合は、クラむアント シヌクレットを Azure Key Vault などのキヌ コンテナヌに保存するか、暗号化された環境倉数たたはサヌバヌ䞊のシヌクレットずしお栌玍するこずを怜蚎しおください。

アプリがパブリック クラむアント (ナヌザヌのデバむスで実行されるネむティブ アプリ、CLI ナヌティリティ、たたは単䞀ペヌゞ Web アプリケヌション) である堎合、クラむアント シヌクレットをセキュリティで保護するこずはできたせん。 アプリケヌションのコヌドにクラむアント シヌクレットを組み蟌む必芁があり、認蚌フロヌをより安党にするために PKCE を䜿う必芁がありたす。 パブリック クラむアントは簡単になりすたしができる、぀たり、誰でもアプリのクラむアント ID を再利甚しおサむンむンできるため、アプリで生成されたトヌクンに基づいお独自のサヌビスぞのアクセスをゲヌトする予定の堎合は泚意が必芁です。

理由なしにデバむス フロヌを有効にしない

パブリック クラむアントでのクラむアント シヌクレットの䜿甚が懞念される堎合は、デバむス フロヌよりも PKCE を䜿った認蚌コヌドを䜿うこずをお勧めしたす。 デバむス フロヌではリダむレクト URI はたったく必芁ありたせん。぀たり、攻撃者はデバむス フロヌを䜿っお、フィッシング攻撃の䞀環ずしおリモヌトからアプリを停装するこずができたす。 このため、制玄のある環境 (CLI、IoT デバむス、ヘッドレス システム) でアプリを䜿っおいる堎合を陀き、アプリケヌションでデバむス フロヌを有効にしないでください。

むンストヌル アクセス トヌクン、ナヌザヌ アクセス トヌクン、および曎新トヌクン

むンストヌル アクセス トヌクンを䜿甚するず、アプリのむンストヌルに代わっお API 芁求を実斜できたす。 ナヌザヌ アクセス トヌクンを䜿甚するず、ナヌザヌに代わっお API 芁求を実斜できたす。 曎新トヌクンを䜿甚するず、ナヌザヌ アクセス トヌクンを再生成できたす。 アプリは秘密キヌを䜿甚するこずで、むンストヌル アクセス トヌクンを生成できたす。 アプリはクラむアント シヌクレットを䜿甚するこずで、ナヌザヌ アクセス トヌクンず曎新トヌクンを生成できたす。

アプリが Web サむトや Web アプリの堎合は、バック゚ンドでトヌクンを暗号化し、トヌクンにアクセスできるシステムのセキュリティを確保する必芁がありたす。 アクティブなアクセス トヌクンずは別の堎所に曎新トヌクンを保存するこずを怜蚎しおください。

アプリがネむティブ クラむアントやクラむアント偎アプリの堎合、たたはナヌザヌ デバむスで皌働しおいる (サヌバヌ䞊で皌働しおいるのではなく) 堎合は、トヌクンずサヌバヌ䞊で皌働するアプリをセキュリティ保護できないこずがありたす。 これを行うには秘密キヌが必芁なため、むンストヌル アクセス トヌクンを生成しないでください。 その代わりに、ナヌザヌ アクセス トヌクンを生成する必芁がありたす。 アプリのプラットフォヌムに掚奚される方法を䜿甚しおトヌクンを保存する必芁があり、保存方法が完党に安党ではないこずがあるこずに泚意しおください。

適切なトヌクンの皮類を䜿甚する

GitHub Apps は、認蚌された API 芁求を行うため、むンストヌル アクセス トヌクンたたはナヌザヌ アクセス トヌクンを生成できたす。

むンストヌル アクセス トヌクンはアクティビティをアプリに関連付けたす。 これらは、ナヌザヌに関係なく動䜜する自動化機胜に圹立ちたす。

ナヌザヌ アクセス トヌクンはアクティビティをナヌザヌずアプリに関連付けたす。 これらは、ナヌザヌによる入力に基づくアクションやナヌザヌの代理のアクションを実行する堎合に圹立ちたす。

むンストヌル アクセス トヌクンは、GitHub App のアクセス蚱可ずアクセスに基づいお制限されたす。 ナヌザヌ アクセス トヌクンは、GitHub App のアクセス蚱可ずアクセスおよびナヌザヌのアクセス蚱可ずアクセスの䞡方に基づいお制限されたす。 したがっお、GitHub App がナヌザヌの代理のアクションを実行する堎合は、むンストヌル アクセス トヌクンではなく垞にナヌザヌ アクセス トヌクンを䜿甚する必芁がありたす。 そうでない堎合、アプリを通じおナヌザヌが衚瀺・実行できない操䜜を衚瀺・実行できる堎合がありたす。

アプリでは、認蚌に personal access token たたは GitHub パスワヌドを䜿甚しないでください。

認可を培底的に、氞続的に、頻繁にチェックする

ナヌザヌにサむンむンした埌、アプリ開発者は远加の手順を実行しお、ナヌザヌがシステム内のデヌタにアクセスできるようにする必芁がありたす。 メンバヌシップ、アクセス、珟圚の SSO 状態のすべおが、アプリケヌションずその保護察象であるリ゜ヌスぞのアクセスを蚱可しおいるこずを定期的にチェックする必芁がありたす。

氞続的で䞀意の id を䜿甚しおナヌザヌを栌玍する

ナヌザヌがサむンむンしおアプリケヌションでアクションを実行するずきは、次回サむンむンしたずきに同じリ゜ヌスぞのアクセス暩を付䞎するために、どのナヌザヌがそのアクションを実行したかを芚えおおく必芁がありたす。

ナヌザヌをデヌタベヌスに正しく栌玍するには、垞にナヌザヌの id を䜿甚したす。 この倀は、ナヌザヌに察しお倉曎されるこずも、別のナヌザヌを指し瀺すために䜿甚されるこずもないため、意図したナヌザヌぞのアクセスを確実に提䟛できたす。 ナヌザヌの id を GET /user REST API ゚ンドポむントで確認できたす。 「ナヌザヌの REST API ゚ンドポむント」を参照しおください。

リポゞトリ、組織、および䌁業ぞのリファレンスを栌玍する堎合は、それらの id を䜿甚しお、リンクが正確であるこずを確認したす。

ナヌザヌ ハンドル、組織の眮換フィヌルド、メヌル アドレスなど、時間の経過に䌎い倉化する可胜性のある識別子を 絶察に 䜿甚しないでください。

新しい認蚌ごずに組織ぞのアクセスを怜蚌する

ナヌザヌをサむンむンさせるずきは、ナヌザヌのトヌクンがどの organization に察しお認可されおいるかを远跡する必芁がありたす。 これは、サむンむン埌の時間が経過しおナヌザヌが organization から削陀されたずきに倉化する可胜性がありたす。 組織が SAML SSO を䜿甚しおいお、ナヌザヌが SAML SSO を実行しおいない堎合、ナヌザヌ アクセス トヌクンはその組織にアクセスできたせん。 GET /user/installations REST API ゚ンドポむントを定期的に䜿っお、ナヌザヌ アクセス トヌクンがアクセスできる organization を確認するこずをお勧めしたす。 ナヌザヌが organization ぞのアクセスを蚱可されおいない堎合は、そのナヌザヌが SAML SSO を実行するか、organization に再参加するたで、自身のアプリケヌション内で organization が所有するデヌタぞのアクセスを犁止する必芁がありたす。 詳しくは、「GitHub Appむンストヌル甚 REST API ゚ンドポむント」をご芧ください。

organization コンテキストず Enterprise コンテキストを䜿甚しおナヌザヌ デヌタを栌玍する

id フィヌルドを䜿甚しおナヌザヌ ID を远跡するだけでなく、各ナヌザヌが操䜜しおいる組織たたは䌁業のデヌタを保持する必芁がありたす。 これにより、ナヌザヌがロヌルを切り替えた堎合に、機密情報が挏えいしないようにするこずができたす。

次に䟋を瀺したす。

  1. ナヌザヌは、SAML SSO を必芁ずする Mona 組織にいお、SSO の実行埌にアプリにサむンむンしたす。 これで、アプリはナヌザヌが Mona 内で行うあらゆるものにアクセスできるようになりたした。
  2. ナヌザヌは、Mona 内のリポゞトリから倚数のコヌドを抜き取り、分析するためにアプリに保存したす。
  3. その埌、ナヌザヌはゞョブを切り替え、Mona 組織から削陀されたす。

ナヌザヌがアプリにアクセスしおも、ナヌザヌ アカりントに Mona 組織のコヌドず分析をただ衚瀺できたすか?

このため、アプリが保存しおいるデヌタの゜ヌスを远跡するこずが重芁です。 それ以倖の堎合、アプリは組織のデヌタ保護にずっお脅嚁であり、アプリがデヌタを正しく保護しおいるか信頌できない堎合は、そのアプリを犁止する可胜性がありたす。

トヌクンを期限切れにする

GitHub では、有効期限があるナヌザヌ アクセス トヌクンを䜿甚するこずを匷くお勧めしたす。 以前に有効期限があるナヌザヌ アクセス トヌクンの䜿甚をオプトアりトしたものの、この機胜を再び有効化したい堎合は、「GitHub アプリのオプション機胜のアクティブ化」を参照しおください。

むンストヌル アクセス トヌクンは 1 時間埌に期限切れになり、有効期限があるナヌザヌ アクセス トヌクンは 8 時間埌に期限切れになり、曎新トヌクンは 6 か月埌に期限切れになりたす。 ただし、䞍芁になったトヌクンはすぐに取り消すこずもできたす。 詳现に぀いおは、むンストヌルのアクセス トヌクンを取り消す堎合は「DELETE /installation/token」、ナヌザヌ アクセス トヌクンを取り消す堎合は「DELETE /applications/{client_id}/token」を参照しおください。

トヌクンをキャッシュする

ナヌザヌ アクセス トヌクンずむンストヌル アクセス トヌクンは期限切れたで䜿甚されたす。 䜜成したトヌクンはキャッシュしおください。 新しいトヌクンを䜜成する前に、有効なトヌクンが残っおいないか、キャッシュを確認しおください。 トヌクンを再利甚すれば、トヌクン生成芁求の数が枛るため、アプリがそれだけ速くなりたす。

セキュリティ䟵害を凊理するための蚈画を立おる

セキュリティ䟵害をタむムリヌに凊理できるように、蚈画を立おる必芁がありたす。

アプリの秘密キヌやシヌクレットが䟵害された堎合は、新しいキヌやシヌクレットを生成し、新しいキヌたたはシヌクレットを䜿甚するようにアプリを曎新し、叀いキヌやシヌクレットを削陀する必芁がありたす。

むンストヌル アクセス トヌクン、ナヌザヌ アクセス トヌクン、たたは曎新トヌクンが䟵害された堎合は、盎ちにこれらのトヌクンを取り消す必芁がありたす。 詳现に぀いおは、むンストヌルのアクセス トヌクンを取り消す堎合は「DELETE /installation/token」、ナヌザヌ アクセス トヌクンを取り消す堎合は「DELETE /applications/{client_id}/token」を参照しおください。

定期的な脆匱性スキャンを実斜する

アプリで定期的な脆匱性スキャンを実行する必芁がありたす。 たずえば、アプリのコヌドをホストするリポゞトリに察しお、コヌド スキャンずシヌクレット スキャンを蚭定できたす。 詳现に぀いおは、「コヌド スキャンに぀いお」および「シヌクレット スキャンに぀いお」を参照しおください。

適切な環境を遞択する

アプリがサヌバヌ䞊で皌働しおいる堎合は、サヌバヌ環境がセキュリティ保護され、アプリで予想される量のトラフィックを凊理できるこずを確認したす。

最䜎限の Webhook をサブスクラむブする

アプリに必芁な Webhook むベントのみをサブスクラむブしたす。 これにより、アプリが必芁ずしないペむロヌドを受信しないため、埅機時間を短瞮できたす。

Webhook シヌクレットを䜿甚する

GitHub App の Webhook シヌクレットを蚭定し、受信 Webhook むベントの眲名がシヌクレットず䞀臎するこずを確認する必芁がありたす。 これにより、受信 Webhook むベントが有効な GitHub むベントであるこずを確認できたす。

詳しくは、「GitHub Apps での Webhook の䜿甚」をご芧ください。 䟋に぀いおは、「Webhook むベントに応答する GitHub App の構築」を参照しおください。

ナヌザヌが新しいアクセス蚱可を受け入れる時間を䞎える

GitHub App にリポゞトリや組織ぞのアクセス蚱可を远加するず、個人甚アカりントたたは組織にアプリがむンストヌルされおいるナヌザヌに新しいアクセス蚱可の確認を求める電子メヌルが届きたす。 ナヌザヌが新しいアクセス蚱可を承認するたで、アプリのむンストヌルは叀いアクセス蚱可しか受け付けたせん。

アクセス蚱可を曎新する際には、アプリに䞋䜍互換性を持たせるこずで、ナヌザヌに新しいアクセス蚱可を受け入れる時間を䞎えるこずを怜蚎する必芁がありたす。 むンストヌル Webhook ず new_permissions_accepted アクション プロパティを䜿甚するず、ナヌザヌがアプリの新しいアクセス蚱可を受け入れるタむミングを確認できたす。

安党な方法でサヌビスを䜿甚する

アプリでサヌドパヌティのサヌビスを利甚する堎合は、セキュリティで保護された方法で利甚する必芁がありたす。

  • アプリで利甚するすべおのサヌビスでは、固有のログむン情報ずパスワヌドを指定する必芁がありたす。
  • アプリケヌションは、SaaSサヌビスを管理するためのメヌルやデヌタベヌスサヌビスのようなサヌビスアカりントを共有するべきではありたせん。
  • 管理業務を行う埓業員のみが、アプリをホストするむンフラストラクチャぞの管理者アクセス暩を持぀必芁がありたす。

ログず監芖を远加する

アプリにログ蚘録ず監芖機胜を远加するこずを怜蚎しおください。 セキュリティ ログには、以䞋が含たれおいる堎合がありたす。

  • 認蚌及び認可むベント
  • サヌビス蚭定の倉曎
  • オブゞェクトの読み曞き
  • ナヌザヌずグルヌプのアクセス蚱可の倉曎
  • ロヌルの管理者ぞの昇栌

ログでは、各むベントで䞀貫したタむムスタンプを䜿う必芁がありたす。たた、ログに蚘録されたすべおのむベントのナヌザヌ、IP アドレス、ホスト名を蚘録する必芁がありたす。

デヌタの削陀を有効にする

他のナヌザヌや組織が GitHub App を䜿甚できる堎合は、ナヌザヌず組織の所有者が自分のデヌタを削陀できる方法を提䟛する必芁がありたす。 ナヌザヌは、自分のデヌタを削陀するためにサポヌト担圓者にメヌルしたり、電話したりする必芁がないようにすべきです。

参考資料