OAuth AppからGitHub Appへの移行

この記事は、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 アクセスを必要とするかを指定できます。詳細な権限を使用することで、アプリケーションは必要なデータのサブセットにターゲットを絞ってアクセスできるようになります。必要な機能を提供する、可能な限り最小の権限セットを指定することをおすすめします。

新しい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 の削除」を参照してく� さい。

この記事では、次の� �目が扱われます。