この記事は、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 Appをインストールできる。 GitHub Appの設定にOrganizationのリソースをリクエストする権限があれば、Organizaitionのオーナーはそのインストールを承認しなければならない。
- Octokitライブラリや、Robotのような他のフレームワークを通じてオープンソースコミュニティのサポートがある。
- GitHub Appを構築するインテグレーターは、APIへの早期アクセスを採用する機会がある。
OAuth AppからGitHub Appへの変換
以下のガイドラインは、登録済みのOAuth Appがあることを前提としています。 高いレベルでは、以下のステップに従う必要があります。
- GitHub Appで利用できるAPIエンドポイントのレビュー
- APIレート制限内に留まるための設計
- 新しいGitHub Appの登録
- アプリケーションが必要とする権限の決定
- webhookのサブスクライブ
- 様々な認証方法の理解
- リポジトリにGitHub Appをインストールするようにユーザに指示
- 不必要なリポジトリフックの削除
- OAuth Appへのアクセスの取り消しをユーザに促す
GitHub Appで利用できるAPIエンドポイントのレビュー
REST APIエンドポイントとGraphQLクエリの大部分は、今日GitHub Appから利用できますが、まだいくつかのエンドポイントは有効にする過程にあります。 利用可能なRESTエンドポイントをレビューして、必要なエンドポイントがGitHub Appと互換性があることを確認してください。 GitHub Appで利用できるAPIエンドポイントの中には、ユーザの代わりにアプリケーションが動作できるようにするものがあることに注意してください。 GitHub Appがユーザとして認証されるようにするエンドポイントのリストについては、「ユーザからサーバーへのリクエスト」を参照してください。
必要なAPIエンドポイントのリストのレビューは、できるだけ早く行うことをおすすめします。 まだGitHub Appから利用できないエンドポイントで必要なものがある場合は、サポートにお知らせください。
APIレート制限内に留まるための設計
GitHub Appはレート制限に対するスライディングルールを利用します。これは、Organization中のリポジトリ及びユーザ数に基づいて増加できます。 また、GitHub AppはGraphQL V4を利用することで、条件リクエストあるいは統合リクエストを利用することもできます。
新しいGitHub Appの登録
Once you've decided to make the switch to GitHub Apps, you'll need to create a new GitHub App.
アプリケーションが必要とする権限の決定
GitHub Appを登録する際には、アプリケーションのコードが使用する各エンドポイントが必要とする権限を選択しなければなりません。 GitHub Appで利用できる各エンドポイントが必要とする権限のリストについては「GitHub Appの権限」を参照してください。
GitHub Appの設定で、アプリケーションがそれぞれの権限の種類についてNo Access、Read-only、Read & Writeアクセスを必要とするかを指定できます。 詳細な権限を使用することで、アプリケーションは必要なデータのサブセットにターゲットを絞ってアクセスできるようになります。 必要な機能を提供する、可能な限り最小の権限セットを指定することをおすすめします。
webhookのサブスクライブ
新しいGitHub Appを作成し、その権限を選択したら、サブスクライブさせたいwebhookイベントを選択できます。 See "Editing a GitHub App's permissions" to learn how to subscribe to webhooks.
様々な認証方法の理解
GitHub Appは、短時間で期限切れとなるトークンベースの認証を主に利用し、期限切れにならないOAuthトークンよりも高いセキュリティを提供します。 利用可能な様々な認証方法と、それらをいつ使う必要があるかを理解しておくことが重要です。
- JSON Web Token (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です。 |
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_repositories webhookを待ち受け、それらのリポジトリ上にOAuth Appによって作成されたリポジトリwebhookを削除できます。
OAuth Appへのアクセスの取り消しをユーザに促す
GitHub Appのインストールベースが増大してきたら、ユーザに従来のOAuthインテグレーションへのアクセスを取り消すように促すことを検討してください。