OAuth AppをGitHub上でセットアップする際には、要求されたスコープが認可フォーム上でユーザに表示されます。
ノート: GitHub Appを構築しているなら、認可リクエストでスコープを提供する必要はありません。 このことに関する詳細については「GitHub Appのユーザの特定と認可」を参照してください、
CLIツールなど、OAuth Appがブラウザにアクセスできない場合、アプリケーションを認可するユーザのスコープを指定する必要はありません。 詳しい情報については「OAuth Appの認可」を参照してください。
どのOAuthスコープを所有しているか、そしてAPIアクションが何を受け付けるかを知るには、ヘッダを確認してください。
$ curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/users/codertocat -I
HTTP/2 200
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 | デプロイメントステータス for パブリックおよびプライベートリポジトリへのアクセスを許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなくデプロイメントステータスへのアクセスをユーザまたはサービスに許可する場合のみです。 |
public_repo | アクセスをパブリックリポジトリのみに制限します。 これには、コード、コミットステータス、リポジトリプロジェクト、コラボレータ、パブリックリポジトリ及びOrganizationのデプロイメントステータスへの読み書きアクセスが含まれます。 パブリックリポジトリにStarを付けるためにも必要です。 |
repo:invite | リポジトリでのコラボレーションへの招待の承認／拒否を許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなく招待へのアクセスをユーザあるいはサービスに許可する場合のみです。 |
security_events | code scanning API中のセキュリティイベントへの読み書きアクセスを許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザまたはサービスにセキュリティイベントへのアクセスを許可したい場合のみです。 |
admin:repo_hook | パブリックおよびプライベートリポジトリのリポジトリフックへの読み書き、ping、削除アクセスを許可します。 repoおよびpublic_repoスコープは、リポジトリフックを含むリポジトリへの完全なアクセスを許可します。 アクセスをリポジトリフックのみに限定するには、admin:repo_hookスコープを使ってください。 |
write:repo_hook | Grants read, write, and ping access to hooks in パブリックまたはプライベートリポジトリ内のフックへの読み書きおよびpigアクセスを許可します。 |
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: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は最初のリダイレクトでスコープをリクエストできます。 スコープは、%20を使って、空白で区切って複数指定できます。
https://github.com/login/oauth/authorize?
client_id=...&
scope=user%20repo_deployment
リクエストされたスコープと許可されたスコープ
scope属性は、トークンに添付された、ユーザが許可したスコープをリストします。 通常、これらのスコープはリクエストされたものと同じになります。 しかし、ユーザはスコープを編集でき、実質的にアプリケーションに対して元々リクエストされたよりも少ないアクセスだけを許可できます。 また、ユーザはOAuthフローが完了した後にトークンのスコープを編集することもできます。 この可能性を認識しておき、対応してアプリケーションの動作を調整しなければなりません。
元々リクエストされたよりも少ないアクセスをユーザが許可した場合のエラーケースを処理することは重要です。 たとえば、アプリケーションはユーザに対し、機能が低下したり、行えないアクションがでてくることを警告したり、知らせたりすることができます。
また、アプリケーションはいつでもユーザをフローに戻して追加の権限を得ようとすることができますが、ユーザは常に拒否できることを忘れないようにしてください。
変更できるトークンのスコープの扱いに関するヒントが提供亜sレテイル、認証の基礎ガイドを参照してください。
正規化されたスコープ
複数のスコープがリクエストされた場合、トークンは正規化されたスコープのリストとともに保存され、リクエストされた他のスコープに暗黙のうちに含まれているスコープは破棄されます。 たとえばuser,gist,user:emailをリクエストすると、トークンにはuserとgistスコープだけが含まれます。これは、user:emailスコープで許可されるアクセスはuserスコープに含まれているためです。