この記事は、OAuth AppをGitHub Appに移行することを検討している既存のインテグレーターにガイドラインを提供します。
GitHub Appに切り替える理由
GitHub App は、GitHub との統合方法として公式に推奨されています。これは、純粋な OAuth ベースの統合と比べて多くの利点があるためです。
- GitHub App でアクセスできる特定の情報をターゲットにする詳細な権限。権限で制限できない OAuth App 以上のセキュリティ ポリシーの下で、より広範囲なユーザーや Organization にアプリケーションを利用してもらうことができる。
- 短時間有効なトークンによって、OAuth トークンよりもセキュアな認証方式を提供できる。 OAuthトークンは、OAuth Appを認可したユーザがトークンを取り消すまで、期限切れにならない。 GitHub Appsは素早く期限切れになるトークンを使用し、侵害されたトークンが利用される時間枠を小さくできる。
- ビルトインの集中型 Webhook は、アプリケーションでアクセスできるすべてのリポジトリと Organization に対するイベントを受信する。 逆に、OAuth AppはユーザがアクセスできるそれぞれのリポジトリとOrganizationに対してwebhookを設定する必要がある。
- ボット アカウントは GitHub AE のシートを消費せず、最初にアプリケーションをインストールしたユーザーが Organization を離れてもインストールされたままにしておける。
- OAuth の組み込みサポートは、ユーザー アクセス トークンを持つエンドポイントを使用して GitHub App で引き続き使用できます。
- ボット アカウント専用の API レート制限は、統合に合わせてスケーリングされる。
- リポジトリの所有者は、Organization のリポジトリに GitHub Apps をインストールできる。 GitHub Appの設定にOrganizationのリソースをリクエストする権限があれば、Organizaitionのオーナーはそのインストールを承認しなければならない。
- Octokit ライブラリ や Probot のような他のフレームワークを通じてオープン ソース コミュニティのサポートがある。
- GitHub Appを構築するインテグレーターは、APIへの早期アクセスを採用する機会がある。
OAuth AppからGitHub Appへの変換
以下のガイドラインは、登録済みの OAuth App があることを前提としています。 高いレベルでは、以下のステップに従う必要があります。
- GitHub App で利用できる API エンドポイントのレビュー
- API レート制限内に留まるための設計
- 新しい GitHub アプリの登録
- アプリケーションに必要な権限の決定
- Webhook のサブスクライブ
- 様々な認証方法の理解
- リポジトリに GitHub App をインストールするようにユーザーに指示
- 不必要なリポジトリ フックの削除
- OAuth App へのアクセスの取り消しをユーザーに促す
- OAuth App の削除
GitHub Appで利用できるAPIエンドポイントのレビュー
REST API エンドポイントと GraphQL クエリの大部分は、今日 GitHub App から利用できますが、まだいくつかのエンドポイントは有効にする過程にあります。 利用可能な REST エンドポイントをレビューして、必要なエンドポイントが GitHub App と互換性があることを確認してください。 GitHub Appで利用できるAPIエンドポイントの中には、ユーザの代わりにアプリケーションが動作できるようにするものがあることに注意してください。 GitHub App がユーザーとして認証されるようにするエンドポイントのリストについては、「ユーザーに代わって GitHub アプリで認証する」をご覧ください。
必要なAPIエンドポイントのリストのレビューは、できるだけ早く行うことをおすすめします。 まだGitHub Appsから利用できないエンドポイントで必要なものがある場合は、サポートにお知らせください。
APIレート制限内に留まるための設計
GitHub App ではレート制限に対するスライディング ルールを利用します。これは、Organization 中のリポジトリとユーザー数に基づいて増加できます。 GitHub App では GraphQL API を使用することで、条件付きリクエストまたは統合リクエストを利用することもできます。
新しいGitHub Appの登録
GitHub App へ切り替えることを決めたら、新しい GitHub App を作成しなければなりません。
アプリケーションが必要とする権限の決定
GitHub Appを登録する際には、アプリケーションのコードが使用する各エンドポイントが必要とする権限を選択しなければなりません。 GitHub アプリで利用できる各エンドポイントに必要な権限のリストについては、「GitHub Appに必要な権限」をご覧ください。
GitHub App の設定で、アプリケーションがそれぞれの権限の種類について No Access、Read-only、またはRead & Write アクセスを必要とするかを指定できます。 詳細な権限を使用することで、アプリケーションは必要なデータのサブセットにターゲットを絞ってアクセスできるようになります。 必要な機能を提供する、可能な限り最小の権限セットを指定することをおすすめします。
webhookのサブスクライブ
新しいGitHub Appを作成し、その権限を選択したら、サブスクライブさせたいwebhookイベントを選択できます。 Webhook をサブスクライブする方法については、「GitHub App の権限を編集する」をご覧ください。
様々な認証方法の理解
GitHub Appは、短時間で期限切れとなるトークンベースの認証を主に利用し、期限切れにならないOAuthトークンよりも高いセキュリティを提供します。 利用可能な様々な認証方法と、それらをいつ使う必要があるかを理解しておくことが重要です。
- JSON Web トークン (JWT) は、GitHub App として認証されます。 たとえば、JWT で認証を受けてアプリケーションのインストールの詳細をフェッチしたり、JWT をインストール アクセス トークンと交換したりできます。
- インストール アクセス トークンは、GitHub App の特定のインストールとして認証されます。 たとえば、インストール アクセス トークンで認証を受けて、Issue をオープンしたり、Pull Request にフィードバックを提供したりできます。
- ユーザー アクセス トークンは、GitHub App のユーザーとして認証できます。 たとえば、GitHub Appがユーザのアイデンティティを検証したり、ユーザの代わりに振る舞わなければならない場合に、OAuthアクセストークンを使ってユーザとして認証を受けることができます。
最も一般的なシナリオは、インストール アクセス トークンを使って特定のインストールとして認証を受けることです。
リポジトリにGitHub Appをインストールするようにユーザに指示
OAuth AppからGitHub Appへの移行をしたら、GitHub Appがインストールできるようになったことをユーザに知らせなければなりません。 たとえば、アプリケーション中の行動喚起のバナーに、GitHub Appのインストールリンクを含めることができます。 移行を容易にするために、GitHub Appのインストールフローを通じて存在する、ユーザもしくはOrganizationアカウントを特定するクエリパラメータを使い、OAuth Appがアクセスできた任意のリポジトリを事前選択しておけます。 こうすることで、ユーザはすでにアクセスできるリポジトリにGitHub Appを容易にインストールできるようになります。
クエリ パラメーター
| 名前 | 説明 |
|---|---|
suggested_target_id | 必須: GitHub App をインストールしようとしているユーザーまたは Organization の ID。 |
repository_ids[] | リポジトリIDの配列。 省略された場合、すべてのリポジトリが選択されます。 事前選択できるリポジトリ数は、最大で100です。 |
Example URL (URL の例)
https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID
YOUR_APP_NAME を GitHub App の名前で、ID_OF_USER_OR_ORG をターゲット ユーザーまたは Organization の ID で置き換え、最大で 100 個のリポジトリ ID (REPO_A_ID と REPO_B_ID) を含めなければなりません。 OAuth App でアクセスできるリポジトリのリストを取得するには、認証されたユーザーのためのリポジトリのリストと Organization のリポジトリのリストのエンドポイントを使用します。
不必要なリポジトリフックの削除
GitHub Appがリポジトリにインストールされたら、従来のOAuth Appによって作成された不要なwebhookを削除する必要があります。 どちらのアプリケーションも同じリポジトリにインストールされていると、ユーザにとっては機能が重複するかもしれません。 Webhook を削除するには、repositories_added アクションの installation_repositoriesWebhook を待ち受け、それらのリポジトリ上に OAuth App によって作成されたリポジトリ Webhook を削除できます。
OAuth Appへのアクセスの取り消しをユーザに促す
GitHub Appのインストールベースが増大してきたら、ユーザに従来のOAuthインテグレーションへのアクセスを取り消すように促すことを検討してください。 詳しくは、「OAuth アプリの承認」を参照してください。
OAuth Appの削除
OAuth App認証情報の不正利用を避けるには、OAuth Appの削除を検討してください。 このアクションは、OAuth Appの残りの権限もすべて取り消します。 詳しくは、「OAuth App を削除する」を参照してください。