GitHub Apps と OAuth apps について
通常、GitHub Apps が OAuth apps より優先されます。 GitHub Apps では、きめ細かいアクセス許可が使われ、アプリでアクセスできるリポジトリをより細かく制御でき、有効期間の短いトークンが使われます。 これらの特徴により、アプリの資格情報が漏洩した場合に発生する可能性のある損害を制限することで、アプリのセキュリティを強化できます。
OAuth apps と同様に、GitHub Apps でも引き続き OAuth 2.0 を使って、OAuth トークンの種類 (別名、ユーザー アクセス トークン) を生成し、ユーザーに代わってアクションを実行できます。 ただし、GitHub Apps は、ユーザーとは関係なく動作することもできます。 これは、ユーザー入力を必要としない自動化に役立ちます。 アプリを Organization にインストールしたユーザーが Organization からいなくなった場合でも、アプリは引き続き機能します。
GitHub Apps には、一元化された Webhook が組み込まれています。 GitHub Apps は、アプリでアクセスできるすべてのリポジトリおよび組織の Webhook イベントを受け取ることができます。 逆に、OAuth apps では、リポジトリと組織ごとに個別に Webhook を構成する必要があります。
インストール アクセス トークンを使う GitHub Apps のレート制限は、リポジトリの数と組織のユーザーの数に応じてスケーリングされます。 逆に、OAuth apps のレート制限は低く、スケーリングされません。
GitHub App より OAuth app の方が推奨されるケースが 1 つあります。 Enterprise オブジェクトなど、Enterprise レベルのリソースにアプリからアクセスする必要がある場合、GitHub App ではまだ Enterprise に対してアクセス許可を付与できないため、OAuth app を使う必要があります。 GitHub Apps では、エンタープライズが所有する組織とリポジトリ リソースに引き続きアクセスできます。
GitHub Apps について詳しくは、「GitHub App の作成について」をご覧ください。
既存の OAuth app の GitHub App への移行について詳しくは、「OAuth アプリからGitHub Appへの移行」をご覧ください。
GitHub Apps をインストールし、OAuth appsを承認できるのは誰ですか?
GitHub App は、個人アカウントおよび自分が所有する Organization にインストールできます。 リポジトリの管理者権限がある場合には、GitHub App を Organization のアカウントにインストールできます。 GitHub App がリポジトリにインストールされていて、Organization の権限を要求している場合、Organization のオーナーはアプリケーションを承認する必要があります。
デフォルトでは、Organization内のGitHub Appsの設定を管理できるのはOrganizationのオーナーだけです。 組織が所有する GitHub Apps の開発者設定を追加ユーザーが変更できるようにするため、所有者は GitHub App マネージャーのアクセス許可を付与できます。 GitHub App マネージャーは、サード パーティのアプリケーションを管理できません。 組織での GitHub App マネージャーの追加と削除の詳細については、「Organizationのロール」を参照してください。
一方、ユーザーが OAuth appsを承認すると、認証されたユーザーとして動作する機能がアプリに提供されます。 たとえば、認証済みのユーザーに対するすべての通知を検索する OAuth appを承認できます。 アクセス許可は、OAuth appからいつでも取り消すことができます。
Organization の所有者は、外部コラボレーターが承認されていない OAuth apps と GitHub Apps へのアクセスを要求できるようにするかどうかを選べます。 詳しくは、「OAuth アプリと GitHub App のアクセス要求を制限する」を参照してください。
警告: OAuth app からすべてのアクセス許可を取り消すと、ユーザーの代わりにアプリケーションで生成されたすべての SSH キー (デプロイ キーを含む) が削除されます。
| GitHub アプリ | OAuth apps |
|---|---|
| Organization に GitHub App をインストールするには、Organization のオーナーであるか管理者権限を所有している必要があります。 GitHub App がリポジトリにインストールされていて、Organization の権限を要求している場合、Organization のオーナーはアプリケーションを承認する必要があります。 | OAuth appにリソースへのアクセス権を承認できます。 |
| GitHub App は個人のリポジトリにインストールできます。 | OAuth appにリソースへのアクセス権を承認できます。 |
| GitHub App をアンインストールしてアクセス権限を削除するには、Organization のオーナーであるか、個人リポジトリの所有者であるか、リポジトリの管理者権限を所有している必要があります。 | OAuth アクセストークンを削除して、アクセス権限を削除することができます。 |
| GitHub App のインストールを要求するには、Organization のオーナーであるかリポジトリの管理者権限を所有している必要があります。 | Organization のアプリケーション ポリシーが有効な場合、その Organization のすべてのメンバーが、Organization への OAuth appのインストールを要求できます。 Organization のオーナーは、その要求を承認または拒否する必要があります。 |
GitHub Apps と OAuth appsがアクセスできる内容
アカウントの所有者は、別のアカウントにアクセス権限を与えることなく GitHub App を使用できます。 たとえば、サードパーティ製のビルドサービスを従業員の Organization にインストールしつつ、そのビルドサービスに個人アカウントにあるリポジトリへのアクセスを許可しないことができます。 GitHub App をセットアップした人が Organization から離れても、その GitHub App はインストールされたままになります。
"承認済み" の OAuth appには、ユーザーまたは Organization の所有者がアクセス可能なすべてのリソースへのアクセス権があります。__
| GitHub アプリ | OAuth apps |
|---|---|
| GitHub アプリをインスールすると、アプリはユーザーまたは組織アカウントの選択されたリポジトリにアクセスできるようになります。 | OAuth appを承認すると、ユーザーがアクセスできるリソースへのアクセスがアプリに付与されます。 たとえば、リポジトリにアクセスできます。 |
| 管理者がインストールからリポジトリを削除した場合、GitHub App のインストールトークンはリソースにアクセスできなくなります。 | リポジトリへの書き込みアクセスを失ったときなど、ユーザがアクセスを失ったとき、OAuth アクセストークンはリソースにアクセスできなくなります。 |
| インストール アクセス トークンは、アプリケーションの作成者が選択したアクセス許可を所有する、指定されたリポジトリに制限されます。 | OAuth アクセス トークンは、スコープで制限されます。 |
| GitHub App は、リポジトリの実際のコンテンツにアクセスすることなく、Issue やプルリクエストへの個別のアクセスを要求できます。 | OAuth appsは、issue、pull request、またはリポジトリが所有するすべてのものにアクセスするために、repo スコープを要求する必要があります。 |
| GitHub アプリは組織のアプリケーション ポリシーの対象ではありません。 GitHub アプリは組織の所有者が許可したリポジトリにのみアクセスできます。 | Organization のアプリケーション ポリシーがアクティブな場合、Organization の所有者のみが OAuth appのインストールを認可できます。 インストールされている場合、OAuth appは承認された Organization 内で Organization の所有者が所持しているトークンで表示できるすべてのものにアクセスできます。 |
| GitHub App は、インストールが変更または削除されると webhook イベントを受信します。 これにより、アプリケーションの作者は、GitHub App の Organization のリソースに対するアクセス権が変更されたことがわかります。 | OAuth appsは、許可ユーザーのアクセス権が変更されると、それに基づき、組織やリポジトリへのアクセス権を失う場合があります。 リソースへのアクセスを失った場合、OAuth appにより通知はされません。 |
トークンベースの識別
注: GitHub アプリでは、ユーザー ベースのトークンを使用することもできます。 詳しくは、「ユーザーに代わって GitHub アプリで認証する」を参照してください。
| GitHub アプリ | OAuth apps |
|---|---|
| GitHub App は、JSON Web トークンフォーマットのアウトオブバンドで秘密鍵を使用することにより、インストールアクセストークンをリクエストできます。 | OAuth appは、Web リクエストを通じたリダイレクトの後に要求トークンをアクセス トークンに交換できます。 |
| インストール トークンは、アプリを GitHub アプリのボット (@jenkins-bot など) として識別します。 | アクセス トークンは、アプリをそのアプリにトークンを付与したユーザー (@octocat など) として識別します。 |
| インストール アクセス トークンは、事前に定義された時間 (現在は 1 時間) が経過すると期限切れになります。 | OAuth トークンは、顧客によって取り消されるまで有効となります。 |
| Organization またはリポジトリにインストールされた GitHub Appsは、インストール数に応じてスケーリングされるレート制限の対象となります。 詳しくは、「Rate limits for GitHub Apps (GitHub アプリのレート制限)」を参照してください。 | OAuth トークンでは、1 時間あたり要求 5,000 件というユーザーのレート制限が使用されます。 |
| レート制限の増加は、GitHub アプリ レベル (すべてのインストールに影響) と個々のインストール レベルの両方で許可できます。 | レート制限の引き上げは、OAuth appごとに付与されます。 その OAuth appに付与されたすべてのトークンの制限が引き上げられます。 |
| GitHub Apps では、ユーザーの代わりに認証を行うことができます。 認可するフローは OAuth app の認可フローと同じです。 ユーザー アクセス トークンは期限切れになることがあり、更新トークンで更新できます。 詳細については、「ユーザー アクセス トークンを更新する」および「ユーザーに代わって GitHub アプリで認証する」を参照してください。 | OAuth apps により使用される OAuth フローでは、ユーザの代わりに OAuth app を承認します。 これは、GitHub App ユーザー アクセス トークンの生成に使用されるフローと同じです。 |
リソースに対する権限レベルのリクエスト
OAuth appsとは異なり、GitHub App には必要なアクセス権のみをリクエストできる、ターゲットを絞った権限があります。 たとえば、継続的インテグレーション (CI) GitHub App は、リポジトリコンテンツへの読み取りアクセスと、ステータス API への書き込みアクセスをリクエストできます。 別の GitHub App では、コードへの読み取りおよび書き込みアクセスを持たせずに、Issue、ラベル、マイルストーンを管理させることが可能です。 OAuth appsでは詳しいアクセス許可は使えません。
| Access | GitHub アプリ (read または write アクセス許可) | OAuth apps |
|---|---|---|
| パブリック リポジトリへのアクセス | パブリックリポジトリはインストール中に選択する必要があります。 | public_repo スコープ。 |
| リポジトリ コード/コンテンツへのアクセス | リポジトリコンテンツ | repo スコープ。 |
| イシュー、ラベル、マイルストーンへのアクセス | 発行 | repo スコープ。 |
| pull request、ラベル、マイルストーンへのアクセス | Pull Request | repo スコープ。 |
| (CI ビルドの) コミットの状態へのアクセス | コミットのステータス | repo:status スコープ。 |
| デプロイおよびデプロイの状態へのアクセス | デプロイメント | repo_deployment スコープ。 |
| Webhook 経由によるイベントの受信 | GitHub App には、デフォルトで webhook が含まれています。 | write:repo_hook または write:org_hook スコープ。 |
リポジトリの確認
| GitHub アプリ | OAuth apps |
|---|---|
GitHub アプリでは /installation/repositories を参照して、インストール時にアクセスできるリポジトリを確認できます。 | OAuth apps では、アクセス可能なリポジトリの /user/repos (ユーザー ビューの場合) または/orgs/:org/repos (組織ビューの場合) を参照できます。 |
| GitHub App は、リポジトリがインストールから追加または削除されたときに webhook を受信します。 | OAuth appsでは、組織内に新しいリポジトリが作成されたときに通知用の組織 Webhook が作成されます。 |
Webhooks
| GitHub アプリ | OAuth apps |
|---|---|
| デフォルトでは、GitHub App には webhook が 1 つあり、その webhook は、アクセス権のあるすべてのリポジトリにおいて、受信するよう設定されたイベントを受信します。 | OAuth appsは、イベントを受信する必要がある各リポジトリのリポジトリ Webhook を作成するため、Webhook スコープを要求します。 |
| GitHub App は、Organization メンバーの権限で、特定の Organization レベルのイベントを受信します。 | OAuth apps は、組織レベルのイベントを受信する必要がある各組織に対し、組織 Webhook を作成するため組織 Webhook スコープを要求します。 |
| Webhook は、GitHub アプリがアンインストールされると自動的に無効になります。 | OAuth appのアクセス トークンが削除される場合、Webhook は自動的に無効にならず、それらを自動的にクリーンアップする方法はありません。 手動で行うようにユーザーに依頼する必要があります。 |
Git アクセス
| GitHub アプリ | OAuth apps |
|---|---|
| GitHub アプリはリポジトリの内容へのアクセス許可を要求し、インストール アクセス トークンを使用して、HTTP ベースの Git 経由で認証を行います。 詳細については、「GitHub アプリのインストール アクセス トークンの生成」を参照してください | OAuth apps は、write:public_key スコープを要求し、API を介してデプロイ キーを作ります。 その後、そのキーを使用して Git コマンドを実行できます。 |
| トークンは、HTTP パスワードとして使用されます。 | トークンは、HTTP ユーザ名として使用されます。 |
マシンアカウントとボットアカウントの比較
マシン ユーザー アカウントは、GitHub のユーザー システムを使用して自動システムを分離する OAuth ベースの個人用アカウントです。
ボットアカウントは GitHub App 固有のもので、すべての GitHub App に組み込まれています。
| GitHub アプリ | OAuth apps |
|---|---|
| GitHub App ボットは GitHub Enterprise シートを消費しません。 | マシンユーザアカウントは GitHub Enterprise シートを消費します。 |
| GitHub App ボットにはパスワードが付与されないため、顧客は GitHub App に直接サインインできません。 | マシンユーザアカウントには、ユーザ名およびパスワードが付与されます。顧客はそれらを管理および保護します。 |