TL;DR

GitHub API (v3) を利用する際のスコープの一覧(Scopes)です。複数スコープを指定したい場合は、スペース区切りで指定します。(例:?scope=user%20public_repo

GitHub API で利用可能な "scope"

基本的に「scope」はホワイト・リスト方式で、scopeの指定がない場合は「自分(ユーザー)の公開情報の読み取り権限のみ許可」するようになっています。そのため、公開情報の閲覧以上の権限が必要な場合はユーザーにリクエストする際に scope を指定(「&scope=」クエリをリクエスト URL に追加)します。

以下は GitHub の Scopes 仕様ページから一部を抜粋して翻訳・加筆したものです。
(「Scope?」という方はこちら→ #TS;DR

スコープ名 スコープ対象 権限 備考
(指定なし) 公開ユーザープロファイル、公開リポジトリ情報、公開 gist 読み取りを許可
repo 公開/非公開/Organization リポジトリ 読み取り/書き込みを許可 コード/コミットステータス/招待/共同編集者、チームメンバーの追加/デプロイのステータス
repo:status 公開/非公開リポジトリ、コミットステータス 読み取り/書き込を許可 このスコープは、コードへのアクセスを許可しないで、他のユーザーまたはサービスに非公開リポジトリのコミット状況へのアクセスを許可する場合のみ必要です。
repo_deployment 公開/非公開リポジトリ、デプロイ・ステータス 読み取りを許可 このスコープは、コードへのアクセスを許可しないで、他のユーザーまたはサービスにデプロイ・ステータスへのアクセスを許可する場合のみ必要です。
public_repo 公開リポジトリおよび Organization 読み取り/書き込みを許可 公開リポジトリにスターを付ける場合にも必要です。
(コード、コミットステータス、共同作業者、およびデプロイ・ステータス)
repo:invite リポジトリでコラボレーションするための招待状 招待状の受け入れ/拒否の機能を許可 このスコープは、コードへのアクセスを許可しないで、招待へのアクセスを他のユーザーまたはサービスに許可する場合のみ必要です。
admin:org Organization、チーム、メンバーシップ 完全な管理を許可
write:org Organization のメンバーシップ 公開/非公開を許可
read:org Organization やチームのメンバーシップ 読み取りを許可
admin:public_key 公開鍵 完全な管理を許可
write:public_key 公開鍵 作成、一覧表示、および詳細表示を許可
read:public_key 公開鍵 一覧と詳細の表示を許可 (作成は含まない)
admin:repo_hook 公開/非公開リポジトリのフック 読み取り/書き込み/ping/削除を許可
write:repo_hook 公開/非公開リポジトリのフック 読み取り/書き込み/ping を許可 (削除以外を許可)
read:repo_hook 公開/非公開レポジトリのフック 読み取り/ping を許可 (書き込みと削除以外を許可)
admin:org_hook Organization のフック 読み取り/書き込み/ping/削除を許可 注: OAuth トークンは、OAuth アプリによって作成された Organization フックでのみ、これらのアクションを実行できます。個人のアクセストークンは、ユーザーが作成した組織のフックでのみ、これらの操作を実行できます。
gist Gist 書き込みを許可
notifications ユーザー通知 読み取りを許可 repoスコープもこれと同じアクセス権を提供します。
user ユーザーのプロファイル情報 読み取り/書き込みを許可 user:emailuser:followのスコープにも同じアクセス権が含まれます。
read:user ユーザーのプロファイル情報 読み取りを許可
user:email ユーザーの電子メールアドレス 読み取りを許可
user:follow 他のユーザー フォロー/アンフォローを許可
delete_repo 管理可能なリポジトリ 削除を許可
write:discussion チームディスカッション 読み取り/書き込みを許可
read:discussion チームディスカッション 読み取りを許可
admin:gpg_key GPGキー 完全な管理を許可
write:gpg_key GPGキー 作成/一覧表示/詳細表示を許可
read:gpg_key GPGキー 一覧/詳細表示を許可

TS;DR(スコープとは)

「顕微鏡のスコープ」よりはゴルゴ 13 が「ターゲットの狙いを定めるスコープ」のような意味合いに近いのですが、GitHub API における「スコープ」(Scope)とは、API で利用できる範囲を定めるために指定する項目、つまり実質的にはAPI 版のアクセス権のようなイメージが近いかと思います。

GitHub OAuth App や GitHub App といった、GitHub の API を使った自作アプリの場合、まずは、ユーザーに承認してもらいアクセストークンを取得します。以降は、このアクセストークンを使って、ユーザーに替わってリポジトリやアカウントの操作がアプリから行えます。

実は「GitHub ログイン」つまり GitHub のアカウントでログインできる仕組みですが、GitHub はダイレクトなログイン機能を提供しているわけではありません。上記の「アプリがアクセストークンを取得できた」ということは「ユーザーは無事に GitHub にログインできた」かつ「ユーザーはあなたのアプリを承認した」ということでログインしたとみなす応用技的な仕組みです。このタイプのログインの仕組みを「OAuth ログイン」と呼びます。

逆に言うと、自分のサイトやサービスのログイン・システムとして GitHub を利用したいだけなのに、ユーザーが GitHub で出来ることをアプリでも出来てしまうことでもあります。つまり、どこまであなたのアプリが操作させてもらえるかを提示して許可をもらうことが重要となります。この操作できる範囲が「スコープ」になります。

いずれの利用法にしても、提示したスコープの範囲にユーザーが同意し許可を得られるとアクセストークンの発行依頼が可能になり、アクセストークンが発行されると、スコープ内の範囲でユーザーの代理で GitHub の操作がアプリから可能になります。

スコープの指定の仕方

さて具体的なスコープの指定は、「GitHub ログインはこちら」や「(あなたの)GitHubアプリを利用」などのリンク先の URL に含めます。

以下は、あらかじめ GitHub 側で作成/登録した OAuth アプリもしくは GitHub アプリの設定にある「クライアントID」(=$OAUTH2_CLIENT_ID)を使い、スコープに「user」と「public_repo」を指定する例です。(スコープの権限は上記一覧をご覧ください)

https://github.com/login/oauth/authorize?client_id=$OAUTH2_CLIENT_ID&scope=user%20public_repo

上記 URL を分解すると以下のようになります。

  • endpoint: https://github.com/login/oauth/authorize
  • client_id: $OAUTH2_CLIENT_ID ← 自分のアプリの ClientID と置き換え
  • scope: user public_repo

このリンク先で、ユーザーは API のアクセス範囲(スコープ)を確認し、許可をすると、アプリ登録時にあらかじめ指定したリダイレクト先(コールバック先)の引数に code と呼ばれる暫定的な値が渡されます。すでに認証済みの場合はストレートにリダイレクト先に転送されます。

あとは、この code の値を再度 GitHub に POST するとアクセストークンが取得できます

(GitHub ログインやアクセストークンの具体的な取得については、この記事のスコープに関する範囲外なので割愛します)

注意

ちなみに取得したアクセストークンで API を叩いても取得できない場合、スコープの範囲外の API 内容をリクエストした可能性もありますが、まずは返されたヘッダ情報を確認してみてください。

例えば、他の記事にもあるように curl https://api.github.com/hogehoge_api/?access_token=XXXXXXXGET するだけでは実は取得できず、ヘッダをみると以下のような「ブラウザの User-Agent が抜けている」といったメッセージが返されていたりします。

Request forbidden by administrative rules. Please make sure your request has a User-Agent header (http://developer.github.com/v3/#user-agent-required). Check https://developer.github.com for other possible causes.

所感

とあるサイトで「GitHubアカウントでログインできるよ!」というのでログインしようとしたら、なんか「リポジトリの書き込み権限」とか聞かれて、「不審なモバイルアプリじゃないんだから、最低限の権限にしなさいよ」と、ログインするのをやめました。

「そもそも、アクセス権限の指定ってできないからなのかな?」と調べると「スコープ」で行えることがわかったのですが、GitHub API の使い方に関する Qiita 記事は多いのですが、まとまった GitHub のスコープ仕様の情報がなかなかなく、「他にスコープで設定できる項目はないの?」と思って調べようとしても、すぐにヒットしなかったので取りまとめて記事にしてみました。

Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account log in.