GitHub App のユーザの特定と認可

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

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

サイト上のユーザを特定する
Web アプリケーションフロー
ユーザがアクセスできるインストールされたリソースの確認
GitHub App の認可の取り消し処理
ユーザレベルの権限
ユーザからサーバーへのリクエスト

GitHub App がユーザの代わりに動作すると、ユーザからサーバーに対するリクエストを実行します。こうしたリクエストは、ユーザのアクセストークンで承認される必要があります。ユーザからサーバーに対するリクエストには、特定のユーザに対してどのリポジトリを表示するか決定するなど、ユーザに対するデータのリクエストが含まれます。これらのリクエストには、ビルドの実行など、ユーザがトリガーしたアクションも含まれます。

サイト上のユーザを特定する

ブラウザで動作する標準的なアプリケーションでユーザを認可するには、Web アプリケーションフローを利用してください。

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

Web アプリケーションフローを利用して、サイト上のユーザを特定するプロセスは以下の通りです。

ユーザはGitHubのアイデンティティをリクエストするためにリダイレクトされます
ユーザはGitHubによってサイトにリダイレクトして戻されます
GitHub Appはユーザのアクセストークンで API にアクセスします

アプリケーションを作成または変更する際に [Request user authorization (OAuth) during installation] を選択した場合、アプリケーションのインストール中にステップ 1 が完了します。詳しい情報については、「インストール中のユーザの認可」を参照してください。

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

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

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

パラメータ

名前	種類	説明
`client_id`	`string`	必須。GitHub App のクライアント IDです。アプリケーションを選択したときに、GitHub App 設定に表示されます。
`redirect_uri`	`string`	認可の後にユーザが送られるアプリケーション中のURL。これは、GitHub App をセットアップする際に[User authorization callback URL] フィールドで指定された URL と一致させる必要があり、他の追加パラメータを含めることはできません。
`state`	`string`	これはフォージェリアタックを防ぐためにランダムな文字列を含める必要があり、あらゆる任意のデータを含めることができます。
`login`	`string`	サインインとアプリケーションの認可に使われるアカウントを指示します。

注釈: 認可リクエストにスコープを指定する必要はありません。従来の OAuth とは異なり、認証トークンはGitHub App に紐付けられた権限およびユーザの権限に限定されます。

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

ユーザがリクエストを受け付けると、GitHub は一時的なコードを code パラメータに、そして前のステップで渡された状態を state パラメータに入れてリダイレクトさせ、サイトに戻します。状態が一致しない場合、そのリクエストは第三者が作成したものであり、プロセスを中止する必要があります。

注釈: アプリケーションを作成または変更する際に [Request user authorization (OAuth) during installation] を選択した場合、GitHub はアクセストークンと交換する必要がある一時的な code を返します。アプリケーションのインストール中に GitHub が OAuth フローを開始した場合、state パラメータは返されません。

この code をアクセストークンと交換します。

POST http(s)://[hostname]/login/oauth/access_token

パラメータ

名前	種類	説明
`client_id`	`string`	必須。GitHub App のクライアント ID。
`client_secret`	`string`	必須。GitHub App のクライアントシークレット。
`コード`	`string`	必須。ステップ1でレスポンスとして受け取ったコード。
`redirect_uri`	`string`	認可の後にユーザが送られるアプリケーション中のURL。これは、GitHub App をセットアップする際に[User authorization callback URL] フィールドで指定された URL と一致させる必要があり、他の追加パラメータを含めることはできません。
`state`	`string`	ステップ1で提供した推測できないランダムな文字列。

レスポンス

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

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer

3. GitHub Appはユーザのアクセストークンで API にアクセスします

ユーザのアクセストークンを使用すると、GitHub App がユーザの代わりに API にリクエストを発行できます。

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

ユーザがアクセスできるインストールされたリソースの確認

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.

ユーザの OAuth トークンを取得したら、そのユーザがアクセスできるインストールされたアプリケーションを確認できます。

Authorization: token OAUTH-TOKEN
GET /user/installations

また、インストールされたアプリケーションでユーザがアクセスできるリポジトリも確認できます。

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

詳細については、ユーザアクセストークンがアクセスできるインストールされたアプリケーションの一覧表示およびユーザアクセストークンがアクセスできるリポジトリの一覧表示でご確認ください。

GitHub App の認可の取り消し処理

ユーザが GitHub App の認可を取り消した場合、アプリケーションはデフォルトで github_app_authorization webhook を受信します。 GitHub App は、このイベントをサブスクライブ解除できません。 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.

ユーザレベルの権限

ユーザ認可フローの一環として、個々のユーザに付与されたユーザのメールなどのユーザが所有するリソースにアクセスできる、ユーザレベルの権限を GitHub App に付与できます。ユーザレベルの権限は、Organization またはユーザアカウントにインストールされる際に付与される、リポジトリおよび Organization レベルの権限とは異なります。

ユーザレベルの権限は、[Permissions & webhooks] ページの [User permissions] セクションにある GitHub App の設定で選択できます。権限の選択に関する詳しい情報については、「GitHub Appの権限の編集」を参照してください。

ユーザが自分のアカウントにアプリケーションをインストールする時、インストールプロンプトは、アプリケーションがリクエストするユーザレベルの権限を一覧表示し、アプリケーションがこれらの権限を個々のユーザに求めることができるということを説明します。

ユーザレベルの権限は個々のユーザに付与されるため、ユーザにアップグレードを促すことなく、既存のアプリケーションに権限を追加できます。ただし、新しい権限を認可し、ユーザからサーバーに対するトークンを取得するため、ユーザ認可フローを通じて既存のユーザを送信する必要があります。

フィードの取得

ユーザアクセストークンでアクセスできるリポジトリの一覧表示

Issueイベントの一覧表示

Issueのタイムライン

Issueのタイムラインイベントの一覧表示

メタ情報

リポジトリの行動規範の取得

GitHub App のユーザの特定と認可

Still need help?