ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2020-11-12. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの改善、新機能のためには、最新バージョンのGitHub Enterpriseにアップグレードしてください。 アップグレードに関する支援については、GitHub Enterprise supportに連絡してください。

Identifying and authorizing users for GitHub Apps

Your GitHub App can perform actions on behalf of a user, like creating an issue, creating a deployment, and using other supported endpoints.

ここには以下の内容があります:

When your GitHub App acts on behalf of a user, it performs user-to-server requests. These requests must be authorized with a user's access token. User-to-server requests include requesting data for a user, like determining which repositories to display to a particular user. These requests also include actions triggered by a user, like running a build.

Identifying users on your site

To authorize users for standard apps that run in the browser, use the web application flow.

Web アプリケーションフロー

Using the web application flow, the process to identify users on your site is:

  1. ユーザはGitHubのアイデンティティをリクエストするためにリダイレクトされます
  2. ユーザはGitHubによってサイトにリダイレクトして戻されます
  3. Your GitHub App accesses the API with the user's access token

If you select Request user authorization (OAuth) during installation when creating or modifying your app, step 1 will be completed during app installation. For more information, see "Authorizing users during installation."

1. ユーザのGitHubアイデンティティのリクエスト

GET http(s)://[hostname]/login/oauth/authorize

GitHub Appがloginパラメータを指定すると、ユーザに対して利用できる特定のアカウントでサインインしてアプリケーションを認可するよう求めます。

パラメータ
名前種類説明
client_idstringRequired. The client ID for your GitHub App. You can find this in your GitHub App settings when you select your app.
redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 This must be an exact match to the URL you provided in the User authorization callback URL field when setting up your GitHub App and can't contain any additional parameters.
statestringThis should contain a random string to protect against forgery attacks and could contain any other arbitrary data.
loginstringサインインとアプリケーションの認可に使われるアカウントを指示します。

Note: You don't need to provide scopes in your authorization request. Unlike traditional OAuth, the authorization token is limited to the permissions associated with your GitHub App and those of the user.

2. ユーザはGitHubによってサイトにリダイレクトして戻されます

If the user accepts your request, GitHub redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don't match, the request was created by a third party and the process should be aborted.

Note: If you select Request user authorization (OAuth) during installation when creating or modifying your app, GitHub returns a temporary code that you will need to exchange for an access token. The state parameter is not returned when GitHub initiates the OAuth flow during app installation.

Exchange this code for an access token.

POST http(s)://[hostname]/login/oauth/access_token
パラメータ
名前種類説明
client_idstringRequired. The client ID for your GitHub App.
client_secretstringRequired. The client secret for your GitHub App.
コードstring必須。 ステップ1でレスポンスとして受け取ったコード。
redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 This must be an exact match to the URL you provided in the User authorization callback URL field when setting up your GitHub App and can't contain any additional parameters.
statestringステップ1で提供した推測できないランダムな文字列。
レスポンス

デフォルトでは、レスポンスは以下の形式になります。

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer

3. Your GitHub App accesses the API with the user's access token

The user's access token allows the GitHub App to make requests to the API on behalf of a user.

Authorization: token OAUTH-TOKEN
GET http(s)://[hostname]/api/v3/user

たとえば、curlでは以下のようにAuthorizationヘッダを設定できます。

curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/user

Check which installation's resources a user can access

Note: To access the API with your GitHub App, you must provide a custom media type in the Accept Header for your requests.

application/vnd.github.machine-man-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact your site administrator.

Once you have an OAuth token for a user, you can check which installations that user can access.

Authorization: token OAUTH-TOKEN
GET /user/installations

You can also check which repositories are accessible to a user for an installation.

Authorization: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

More details can be found in: List app installations accessible to the user access token and List repositories accessible to the user access token.

Handling a revoked GitHub App authorization

If a user revokes their authorization of a GitHub App, the app will receive the github_app_authorization webhook by default. GitHub Apps cannot unsubscribe from this event. Anyone can revoke their authorization of a GitHub App from their GitHub account settings page. Revoking the authorization of a GitHub App does not uninstall the GitHub App. You should program your GitHub App so that when it receives this webhook, it stops calling the API on behalf of the person who revoked the token. If your GitHub App continues to use a revoked access token, it will receive the 401 Bad Credentials error.

User-level permissions

You can add user-level permissions to your GitHub App to access user resources, such as user emails, that are granted by individual users as part of the user authorization flow. User-level permissions differ from repository and organization-level permissions, which are granted at the time of installation on an organization or user account.

You can select user-level permissions from within your GitHub App's settings in the User permissions section of the Permissions & webhooks page. For more information on selecting permissions, see "Editing a GitHub App's permissions."

When a user installs your app on their account, the installation prompt will list the user-level permissions your app is requesting and explain that the app can ask individual users for these permissions.

Because user-level permissions are granted on an individual user basis, you can add them to your existing app without prompting users to upgrade. You will, however, need to send existing users through the user authorization flow to authorize the new permission and get a new user-to-server token for these requests.

User-to-server requests

While most of your API interaction should occur using your server-to-server installation access tokens, certain endpoints allow you to perform actions via the API using a user access token. Your app can make the following requests using GraphQL v4 or REST v3 endpoints.

Supported endpoints

チェックラン
チェックスイート
Codes Of Conduct
Deployment Statuses
デプロイメント
イベント
フィード
Git Blobs
Git Commits
Git Refs
Git Tags
Git Trees
Gitignore Templates
Installations
Issue Assignees
Issue Comments
Issue Events
Issue Timeline
問題
ラベル
ライセンス
Markdown
メタ情報
マイルストーン
Organization Hooks
Organization Members
Organization Outside Collaborators
Organization Pre Receive Hooks
Organization Team Repositories
Organization Teams
Organization
Project Collaborators
プロジェクト
Pull Comments
Pull Request Review Events
Pull Request Review Requests
Pull Request Reviews
Pulls
リアクション
リポジトリ
Repository Activity
Repository Branches
Repository Collaborators
Repository Commit Comments
Repository Commits
Repository Community
Repository Contents
Repository Hooks
Repository Invitations
Repository Keys
Repository Pages
Repository Pre Receive Hooks
Repository Releases
Repository Stats
ルート
検索
ステータス
Team Discussions
Topics
User Emails
User Followers
User Gpg Keys
User Public Keys
ユーザ