OAuth AppをGitHub上でセットアップする際には、要求されたスコープが認可フォーム上でユーザに表示されます。
ノート: GitHub Appを構築しているなら、認可リクエストでスコープを提供する必要はありません。 このことに関する詳細については「GitHub Appのユーザの特定と認可」を参照してください、
どのOAuthスコープを所有しているか、そしてAPIアクションが何を受け付けるかを知るには、ヘッダを確認してください。
$ curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/users/codertocat -I
HTTP/1.1 200 OK
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: userX-OAuth-Scopesはトークンが認可したスコープをリストします。X-Accepted-OAuth-Scopesは、アクションがチェックするスコープをリストします。
利用できるスコープ
| 名前 | 説明 |
|---|---|
(スコープなし) | パブリックな情報への読み取りのみのアクセスを許可します（パブリックなユーザのプロフィール情報、パブリックリポジトリの情報、Gist）。 |
site_admin | サイト管理者にGitHub Enterprise Serverの管理APIエンドポイントへのアクセスを許可します。 |
repo | プライベート及びパブリックなリポジトリへの完全なアクセスを許可します。 これにはコード、コミットのステータス、リポジトリ及びOrganizationのプロジェクト、招待、コラボレータ、Teamのメンバーシップの追加、デプロイメントのステータス、パブリック及びプライベートのリポジトリとOrganizationのためのリポジトリwebhookが含まれます。 また、ユーザプロジェクトを管理する機能も許可します。 |
repo:status | パブリック及びプライベートのリポジトリのコミットステータスの読み書きアクセスを許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザあるいはサービスにプライベートリポジトリのコミットステータスへのアクセスを許可したい場合のみです。 |
repo_deployment | パブリック及びプライベートのリポジトリに対するデプロイメントステータスへのアクセスを許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザあるいはサービスにデプロイメントステータスへのアクセスを許可したい場合のみです。 |
public_repo | アクセスをパブリックリポジトリのみに制限します。 これには、コード、コミットステータス、リポジトリプロジェクト、コラボレータ、パブリックリポジトリ及びOrganizationのデプロイメントステータスへの読み書きアクセスが含まれます。 パブリックリポジトリにStarするためにも必要です。 |
repo:invite | リポジトリでのコラボレーションへの招待の承認／拒否を許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなく招待へのアクセスをユーザあるいはサービスに許可する場合のみです。 |
admin:repo_hook | パブリック及びプライベートリポジトリのリポジトリフックへの読み書き、ping、削除アクセスを許可します。 repo及びpublic_repoスコープは、リポジトリフックを含むリポジトリへの完全なアクセスを許可します。 アクセスをリポジトリフックのみに限定するには、admin:repo_hookスコープを使ってください。 |
write:repo_hook | パブリック及びプライベートリポジトリ内のフックへの読み書き及びpingアクセスを許可します。 |
read:repo_hook | パブリック及びプライベートリポジトリ内のフックへの読み取り及びpingアクセスを許可します。 |
admin:org | OrganizationとそのTeam、プロジェクト、メンバーシップを完全に管理できます。 |
write:org | Organizationのメンバーシップ、Organizationのプロジェクト、Teamのメンバーシップへの読み書きアクセス。 |
read:org | Organizationのメンバーシップ、Organizationのプロジェクト、Teamのメンバーシップへの読み取りのみのアクセス。 |
admin:public_key | 公開鍵を完全に管理できます。 |
write:public_key | 公開鍵の作成、リスト、詳細の表示。 |
read:public_key | 公開鍵のリストと詳細の表示。 |
admin:org_hook | Organizationフックへの読み書き、ping、削除アクセスを許可します。 ノート: OAuthトークンがこれらのアクションを行えるのは、OAuth Appが作成したOrganizationフックに対してのみです。 個人アクセストークンがこれらのアクションを行えるのは、ユーザが作成したOrganizationフックに対してのみです。 |
gist | Gistへの書き込みアクセスを許可します。 |
notifications | 許可するアクセス: ユーザの通知に対する読み取りアクセス スレッドへの既読アクセス リポジトリへのWatch及びWatch解除のアクセス スレッドのサブスクリプションに対する読み書き及び削除アクセス。 |
user | プロフィール情報にのみ読み書きアクセスを許可します。 このスコープにはuser:emailとuser:followが含まれることに注意してください。 |
read:user | ユーザのプロフィールデータへの読み取りアクセスを許可します。 |
user:email | ユーザのメールアドレスへの読み取りアクセスを許可します。 |
user:follow | 他のユーザのフォローあるいはフォロー解除のアクセスを許可します。 |
delete_repo | 管理可能なリポジトリの削除アクセスを許可します。 |
write:discussion | Teamのディスカッションの読み書きアクセスを許可します。 |
read:discussion | Teamのディスカッションの読み取りアクセスを許可します。 |
admin:gpg_key | GPGキーを完全に管理できます。 |
write:gpg_key | GPGキーの作成、リスト、詳細の表示ができます。 |
read:gpg_key | GPGキーのリストと詳細の表示ができます。 |
ノート:OAuth Appは最初のリダイレクトでスコープをリクエストできます。 スコープは、空白で区切って複数指定できます。
https://github.com/login/oauth/authorize?
client_id=...&
scope=user%20public_repo
リクエストされたスコープと許可されたスコープ
scope属性は、トークンに添付された、ユーザが許可したスコープをリストします。 通常、これらのスコープはリクエストされたものと同じになります。 しかし、ユーザはスコープを編集でき、実質的にアプリケーションに対して元々リクエストされたよりも少ないアクセスだけを許可できます。 また、ユーザはOAuthフローが完了した後にトークンのスコープを編集することもできます。 この可能性を認識しておき、対応してアプリケーションの動作を調整しなければなりません。
元々リクエストされたよりも少ないアクセスをユーザが許可した場合のエラーケースを処理することは重要です。 たとえば、アプリケーションはユーザに対し、機能が低下したり、行えないアクションがでてくることを警告したり、知らせたりすることができます。
また、アプリケーションはいつでもユーザをフローに戻して追加の権限を得ようとすることができますが、ユーザは常に拒否できることを忘れないようにしてください。
変更できるトークンのスコープの扱いに関するヒントが提供亜sレテイル、認証の基礎ガイドを参照してください。
正規化されたスコープ
複数のスコープがリクエストされた場合、トークンは正規化されたスコープのリストとともに保存され、リクエストされた他のスコープに暗黙のうちに含まれているスコープは破棄されます。 たとえばuser,gist,user:emailをリクエストすると、トークンにはuserとgistスコープだけが含まれます。これは、user:emailスコープで許可されるアクセスはuserスコープに含まれているためです。