OAuth AppをGitHub上でセットアップする際には、要求されたスコープが認可フォーム上でユーザに表示されます。
ノート: GitHub Appを構築しているなら、認可リクエストでスコープを提供する必要はありません。 このことに関する詳細については「GitHub Appのユーザの特定と認可」を参照してください、
CLIツールなど、OAuth Appがブラウザにアクセスできない場合、アプリケーションを認可するユーザのスコープを指定する必要はありません。 詳しい情報については「OAuth Appの認可」を参照してください。
どのOAuthスコープを所有しているか、そしてAPIアクションが何を受け付けるかを知るには、ヘッダを確認してください。
$ curl -H "Authorization: token OAUTH-TOKEN" https://[hostname]/api/v3/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
X-OAuth-Scopes
はトークンが認可したスコープをリストします。X-Accepted-OAuth-Scopes
は、アクションがチェックするスコープをリストします。
利用できるスコープ
名前 | 説明 |
---|---|
site_admin | サイト管理者にGitHub Enterprise Serverの管理APIエンドポイントへのアクセスを許可します。 |
repo | Grants full access to public, internal, and private repositories including read and write access to code, commit statuses, repository invitations, collaborators, deployment statuses, and repository webhooks. Note: In addition to repository related resources, the repo scope also grants access to manage organization-owned resources including projects, invitations, team memberships and webhooks. This scope also grants the ability to manage projects owned by users. |
repo:status | Grants read/write access to commit statuses in private and internal repositories. このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザあるいはサービスにプライベートリポジトリのコミットステータスへのアクセスを許可したい場合のみです。 |
repo_deployment | デプロイメントステータス for 内部およびプライベートリポジトリへのアクセスを許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなくデプロイメントステータスへのアクセスをユーザまたはサービスに許可する場合のみです。 |
repo:invite | リポジトリでのコラボレーションへの招待の承認/拒否を許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザまたはサービスに招待へのアクセスを許可する場合のみです。 |
admin:repo_hook | Grants read, write, ping, and delete access to repository hooks in private or internal repositories. repo リポジトリフックを含むリポジトリへの完全なアクセスを許可します。 アクセスをリポジトリフックのみに限定するには、admin:repo_hook スコープを使ってください。 |
write:repo_hook | Grants read, write, and ping access to hooks in private or internal repositories. |
read:repo_hook | Grants read and ping access to hooks in private or internal repositories. |
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 | Grants access to follow or unfollow other users. |
delete_repo | 管理可能なリポジトリの削除アクセスを許可します。 |
write:discussion | Teamのディスカッションの読み書きアクセスを許可します。 |
read:discussion | Allows read access for team discussions. |
write:packages | GitHub Packagesでのパッケージのアップロードあるいは公開のアクセスを許可します。 詳しい情報については「パッケージの公開」を参照してください。 |
read:packages | GitHub Packagesからのパッケージのダウンロードあるいはインストールのアクセスを許可します。 詳しい情報については「パッケージのインストール」を参照してください。 |
delete:packages | GitHub Packagesからのパッケージの削除アクセスを許可します。 詳しい情報については、「パッケージの削除とリストア」を参照してください。 |
admin:gpg_key | GPGキーを完全に管理できます。 |
write:gpg_key | GPGキーの作成、リスト、詳細の表示ができます。 |
read:gpg_key | GPGキーのリストと詳細を表示できます。 |
ワークフロー | GitHub Actionsのワークフローファイルの追加と更新機能を許可します。 同じリポジトリ内の他のブランチに同じファイル(パスと内容が同じ)が存在する場合、ワークフローファイルはこのスコープがなくてもコミットできます。 ワークフローファイルは、異なるスコープのセットを持ちうるGITHUB_TOKEN を公開できます。 詳しい情報については、「ワークフローでの認証」を参照してください。 |
ノート: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
スコープに含まれているためです。