この記事は、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 Enterprise Server のシートを消費せず、最初にアプリケーションをインストールしたユーザーが 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 がユーザーとして認証されるようにするエンドポイントのリストについては、「ユーザーからサーバーへのリクエスト」を参照してく� さい。
必要なAPIエンドポイントのリストのレビューは、できる� け早く行うことをおすすめします。 ま� GitHub Appsから利用できないエンドポイントで必要なものがある� �合は、サポートにお知らせく� さい。
APIレート制限内に留まるための設計
GitHub App ではレート制限に対するスライディング ルールを利用します。これは、Organization 中のリポジトリとユーザー数に基づいて増� できます。 GitHub App では GraphQL API を使用することで、条件付きリクエストまたは統合リクエストを利用することもできます。
新しいGitHub Appの登録
GitHub App へ切り替えることを決めたら、新しい GitHub App を作成しなければなりません。
アプリケーションが必要とする権限の決定
GitHub Appを登録する際には、アプリケーションのコードが使用する各エンドポイントが必要とする権限を選択しなければなりません。 GitHub App で利用できる各エンドポイントに必要な権限のリストについては、「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 にフィードバックを提供したりできます。
- OAuth アクセス トークン は、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インテグレーションへのアクセスを取り消すように促すことを検討してく� さい。 詳細については、「Authorizing OAuth Apps (OAuth アプリの認可)」を参照してく� さい。
OAuth Appの削除
OAuth App認証情� �の不正利用を避けるには、OAuth Appの削除を検討してく� さい。 このアクションは、OAuth Appの残りの権限もすべて取り消します。 詳細については、「OAuth App の削除」を参照してく� さい。