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の権限の編集」を参照してください。
ユーザが自分のアカウントにアプリケーションをインストールする時、インストールプロンプトは、アプリケーションがリクエストするユーザレベルの権限を一覧表示し、アプリケーションがこれらの権限を個々のユーザに求めることができるということを説明します。
ユーザレベルの権限は個々のユーザに付与されるため、ユーザにアップグレードを促すことなく、既存のアプリケーションに権限を追加できます。 ただし、新しい権限を認可し、ユーザからサーバーに対するトークンを取得するため、ユーザ認可フローを通じて既存のユーザを送信する必要があります。
ユーザからサーバーへのリクエスト
While most of your API インタラクションのほとんどは、サーバーからサーバーへのインストールアクセストークンを用いて行われますが、一部のエンドポイントでは、ユーザアクセストークンを使用し、API 経由でアクションを実行できます。 GraphQL v4 または REST v3 エンドポイントを使用して、アプリケーションは次のリクエストを行うことができます。
対応しているエンドポイント
チェックラン
チェックスイート
行動規範
デプロイメントステータス
デプロイメント
イベント
フィード
Git Blob
Gitのコミット
Git参照
Gitタグ
Gitツリー
gitignoreテンプレート
インストール
Issueにアサインされた人
Issueコメント
Issueイベント
Issueのタイムライン
Issue
- 認証されたユーザにアサインされたIssueの一覧表示
- アサインされた人の一覧表示
- ユーザにアサインできるかを確認
- リポジトリのIssueの一覧表示
- Issueの作成
- Issueの取得
- Issueの更新
- Issueのロック
- Issueのロック解除
ラベル
- Issueのラベルを一覧表示
- Issueにラベルを追加
- Issueにラベルを設定
- Issueからすべてのラベルを削除
- Issueからラベルを削除
- リポジトリのラベルを一覧表示
- ラベルを作成
- ラベルの取得
- ラベルの更新
- ラベルの削除
- マイルストーン中のすべてのIssueのラベルを取得
ライセンス
Markdown
メタ情報
マイルストーン
Organizationのフック
- Organizationのwebhookの一覧表示
- Organizationのwebhookの作成
- Organizationのwebhookの取得
- Organizationのwebhookの更新
- Organizationのwebhookの削除
- Organizationのwebhookのping
Organizationのメンバー
- Organizationのメンバーの一覧表示
- ユーザのOrganizationのメンバーシップのチェック
- Organizationのメンバーの削除
- ユーザのOrganizationのメンバーシップの取得
- ユーザのOrganizationのメンバーシップの設定
- ユーザのOrganizationのメンバーシップの削除
- パブリックなOrganizationのメンバーの一覧表示
- ユーザのパブリックなOrganizationのメンバーシップのチェック
- 認証されたユーザのパブリックなOrganizationのメンバーシップの設定
- 認証されたユーザのOrganizationのメンバーシップの削除
Organizationの外部コラボレータ
- OrganizationのOrganizationの外部コラボレータの一覧表示
- OrganizationのメンバーからOrganizationの外部コラボレータへの変換
- OrganizationからのOrganizationの外部コラボレータの削除
Organization pre-receive フック
- Organizationのためのpre-receiveフックの一覧表示
- Organizationのためのpre-receiveフックの取得
- Organizationのためのpre-receiveフックの強制の更新
- Organizationのためのpre-receiveフックの強制の削除
OrganizationのTeamリポジトリ
Organization Team
Organization
- Organizationの一覧表示
- Organizationの取得
- Organizationの更新
- 認証されたユーザのOrganizationメンバーシップの一覧表示
- 認証されたユーザのOrganizationメンバーシップの取得
- 認証されたユーザのOrganizationメンバーシップの更新
- 認証されたユーザのOrganizationの一覧表示
- ユーザのOrganizationの一覧表示
プロジェクトのコラボレータ
プロジェクト
- Organizationのプロジェクトの一覧表示
- Organizationのプロジェクトの作成
- プロジェクトの取得
- プロジェクトの更新
- プロジェクトの削除
- プロジェクトの列の一覧表示
- プロジェクトの列の作成
- プロジェクトの列の取得
- プロジェクトの列の更新
- プロジェクトの列の削除
- プロジェクトカードの一覧表示
- プロジェクトカードの作成
- プロジェクトの列の移動
- プロジェクトカードの取得
- プロジェクトカードの更新
- プロジェクトカードの削除
- プロジェクトカードの移動
- リポジトリプロジェクトの一覧表示
- リポジトリプロジェクトの作成
Pull Requestのコメント
- Pull Requestのレビューコメントの一覧表示
- Pull Requestのレビューコメントの作成
- リポジトリのレビューコメントの一覧表示
- Pull Requestのレビューコメントの取得
- Pull Requestのレビューコメントの更新
- Pull Requestのレビューコメントの削除
Pull Requestのレビューイベント
Pull Requestのレビューのリクエスト
Pull Requestのレビュー
- Pull Requestのレビューの一覧表示
- Pull Requestのレビューの作成
- Pull Requestのレビューの取得
- Pull Requestのレビューの更新
- Pull Requestレビューのコメントの一覧表示
Pull Request
- Pull Requestの一覧表示
- Pull Requestの作成
- Pull Requestの取得
- Pull Requestの更新
- Pull Requestのコミットの一覧表示
- Pull Requestのファイルの一覧表示
- Pull Requestがマージされたかをチェック
- Pull Requestをマージ(マージボタン)
リアクション
- リアクションの削除
- コミットコメントへのリアクションの一覧表示
- コミットコメントへのリアクションの作成
- Issueへのリアクションの一覧表示
- Issueへのリアクションの作成
- Issueコメントへのリアクションの一覧表示
- Issueコメントへのリアクションの作成
- Pull Requestのレビューコメントへのリアクションの一覧表示
- Pull Requestのレビューコメントへのリアクションの作成
- Teamディスカッションコメントへのリアクションの一覧表示
- Teamディスカッションコメントへのリアクションの作成
- Teamディスカッションへのリアクションの一覧表示
- Teamディスカッションへのリアクションの作成
リポジトリ
- Organization リポジトリの一覧表示
- 認証されたユーザにリポジトリを作成
- リポジトリの取得
- リポジトリの更新
- リポジトリの削除
- 2つのコミットの比較
- リポジトリのコントリビューターの一覧表示
- フォークの一覧表示
- フォークの作成
- リポジトリの言語の一覧表示
- リポジトリのタグの一覧表示
- リポジトリのTeamの一覧表示
- リポジトリの移譲
- パブリックリポジトリの一覧表示
- 認証されたユーザのリポジトリの一覧表示
- ユーザのリポジトリの一覧表示
- リポジトリのテンプレートを使ったリポジトリの作成
リポジトリのアクティビティ
- Starを付けたユーザの一覧表示
- Watchしているユーザの一覧表示
- ユーザがStarしたリポジトリの一覧表示
- 認証されたユーザによってリポジトリがStarされているかをチェック
- 認証されたユーザのためにリポジトリをStar
- 認証されたユーザのためにリポジトリをStar解除
- ユーザが Watch しているリポジトリの一覧表示
リポジトリのブランチ
- ブランチの一覧表示
- ブランチの取得
- ブランチの保護の取得
- ブランチの保護の更新
- ブランチの保護の削除
- 管理ブランチの保護の取得
- 管理ブランチの保護の設定
- 管理ブランチの保護の削除
- Pull Requestのレビュー保護の取得
- Pull Requestのレビュー保護の更新
- Pull Requestのレビュー保護の削除
- コミット署名の保護の取得
- コミット署名の保護の作成
- コミット署名の保護の削除
- ステータスチェックの保護の取得
- ステータスチェックの保護の更新
- ステータスチェックの保護の削除
- すべてのステータスチェックのコンテキストの取得
- ステータスチェックのコンテキストの追加
- ステータスチェックのコンテキストの設定
- ステータスチェックのコンテキストの削除
- アクセス制限の取得
- アクセス制限の削除
- 保護されたブランチへのアクセスを持つTeamの一覧表示
- Teamのアクセス制限の追加
- Teamのアクセス制限の設定
- Teamのアクセス制限の削除
- 保護されたブランチのユーザ制限の一覧表示
- ユーザアクセス制限の追加
- ユーザアクセス制限の設定
- ユーザアクセス制限の削除
- ブランチのマージ
リポジトリのコラボレータ
リポジトリのコミットコメント
リポジトリのコミット
リポジトリのコミュニティ
リポジトリのコンテンツ
リポジトリのフック
- リポジトリのwebhookの一覧表示
- リポジトリのwebhookの作成
- リポジトリのwebhookの取得
- リポジトリのwebhookの更新
- リポジトリのwebhookの削除
- リポジトリのwebhookのping
- プッシュリポジトリのwebhookのテスト
リポジトリの招待
リポジトリのキー
リポジトリのPages
- GitHub Pagesのサイトの取得
- GitHub Pagesのサイトの作成
- GitHub Pagesのサイトに関する情報の更新
- GitHub Pagesのサイトの削除
- GitHub Pagesのビルドの一覧表示
- GitHub Pagesのビルドのリクエスト
- GitHub Pagesのビルドの取得
- 最新のPagesのビルドの取得
リポジトリ pre-receive フック
- リポジトリのpre-receiveフックの一覧表示
- リポジトリのpre-receiveフックの取得
- リポジトリのpre-receiveフックの強制の更新
- リポジトリのpre-receiveフックの強制の削除
リポジトリのリリース
- リリースの一覧表示
- リリースの作成
- リリースの取得
- リリースの更新
- リリースの削除
- リリースアセットの一覧表示
- リリースアセットの取得
- リリースアセットの更新
- リリースアセットの削除
- 最新リリースの取得
- タグ名によるリリースの取得
リポジトリ統計
ルート
検索
ステータス
Teamディスカッション
- ディスカッションの一覧表示
- ディスカッションの作成
- ディスカッションの取得
- ディスカッションの更新
- ディスカッションの削除
- ディスカッションコメントの一覧表示
- ディスカッションコメントの作成
- ディスカッションコメントの取得
- ディスカッションコメントの更新
- ディスカッションコメントの削除
Topics
ユーザのメール
ユーザのフォロワー
- ユーザのフォロワーの一覧表示
- ユーザがフォローしている人の一覧表示
- 認証されたユーザによって人がフォローされているかのチェック
- ユーザのフォロー
- ユーザのフォロー解除
- ユーザが他のユーザにフォローされているかのチェック