GitHub App がユーザの代わりに動作すると、ユーザからサーバーに対するリクエストを実行します。 こうしたリクエストは、ユーザのアクセストークンで承認される必要があります。 ユーザからサーバーに対するリクエストには、特定のユーザに対してどのリポジトリを表示するか決定するなど、ユーザに対するデータのリクエストが含まれます。 これらのリクエストには、ビルドの実行など、ユーザがトリガーしたアクションも含まれます。
ユーザからサーバーへのアクセストークンをさらにセキュアにするために、8時間後に期限切れとなるアクセストークンと、新しいアクセストークンと交換できるリフレッシュトークンを使用できます。 詳しい情報については「ユーザからサーバーへのアクセストークンのリフレッシュ」を参照してください。
サイト上のユーザを特定する
ブラウザで動作する標準的なアプリケーションでユーザを認可するには、Web アプリケーションフローを利用してください。
CLI ツールや Git 認証情報マネージャーなどの、ブラウザに直接アクセスしないヘッドレスアプリケーションでユーザを認可するには、デバイスフローを利用します。 デバイスフローは、OAuth 2.0 Device Authorization Grant を利用します。
Web アプリケーションフロー
Web アプリケーションフローを利用して、サイト上のユーザを特定するプロセスは以下の通りです。
- ユーザはGitHubのアイデンティティをリクエストするためにリダイレクトされます
- ユーザはGitHubによってサイトにリダイレクトして戻されます
- GitHub Appはユーザのアクセストークンで API にアクセスします
アプリケーションを作成または変更する際に [Request user authorization (OAuth) during installation] を選択した場合、アプリケーションのインストール中にステップ 1 が完了します。 詳しい情報については、「インストール中のユーザの認可」を参照してください。
1. ユーザのGitHubアイデンティティのリクエスト
ブラウザで次のURLに移動するようユーザに指示します。
GET https://github.com/login/oauth/authorize
GitHub Appがlogin
パラメータを指定すると、ユーザに対して利用できる特定のアカウントでサインインしてアプリケーションを認可するよう求めます。
パラメータ
名前 | 種類 | 説明 |
---|---|---|
client_id | string | 必須。GitHub App のクライアント IDです。 アプリケーションを選択したときに、GitHub App 設定に表示されます。 注釈: アプリケーション ID とクライアント ID は同一ではなく、お互いを置き換えることはできません。 |
redirect_uri | string | 認可の後にユーザが送られるアプリケーション中のURL。 This must be an exact match to one of the URLs you provided as a Callback URL when setting up your GitHub App and can't contain any additional parameters. |
state | string | これはフォージェリアタックを防ぐためにランダムな文字列を含める必要があり、あらゆる任意のデータを含めることができます。 |
login | string | サインインとアプリケーションの認可に使われるアカウントを指示します。 |
allow_signup | string | OAuthフローの間に、認証されていないユーザに対してGitHubへのサインアップの選択肢が提示されるかどうか。 デフォルトは true です。 ポリシーでサインアップが禁止されている場合はfalse を使ってください。 |
注釈: 認可リクエストにスコープを指定する必要はありません。 従来の OAuth とは異なり、認証トークンはGitHub App に紐付けられた権限およびユーザの権限に限定されます。
2. ユーザはGitHubによってサイトにリダイレクトして戻されます
ユーザがリクエストを受け付けると、GitHub は一時的なコードを code
パラメータに、そして前のステップで渡された状態を state
パラメータに入れてリダイレクトさせ、サイトに戻します。 状態が一致しない場合、そのリクエストは第三者が作成したものであり、プロセスを中止する必要があります。
注釈: アプリケーションを作成または変更する際に [Request user authorization (OAuth) during installation] を選択した場合、GitHub はアクセストークンと交換する必要がある一時的な code
を返します。 アプリケーションのインストール中に GitHub が OAuth フローを開始した場合、state
パラメータは返されません。
この code
をアクセストークンと交換します。 トークンの期限設定が有効になっている場合、アクセストークンは 8 時間で期限切れとなり、リフレッシュトークンは 6 か月で期限切れとなります。 トークンを更新するたびに、新しいリフレッシュトークンを取得します。 詳しい情報については、「ユーザからサーバーに対するアクセストークンをリフレッシュする」を参照してください。
ユーザトークンの期限設定は、現在のところオプション機能であり、変更される可能性があります。 To opt-in to the user-to-server token expiration feature, see "Activating optional features for apps."
アクセストークンを受け取るため、次のエンドポイントをリクエストします。
POST https://github.com/login/oauth/access_token
パラメータ
名前 | 種類 | 説明 |
---|---|---|
client_id | string | 必須。GitHub App のクライアント ID。 |
client_secret | string | 必須。GitHub App のクライアントシークレット。 |
コード | string | 必須。 ステップ1でレスポンスとして受け取ったコード。 |
redirect_uri | string | 認可の後にユーザが送られるアプリケーション中のURL。 This must be an exact match to one of the URLs you provided as a Callback URL when setting up your GitHub App and can't contain any additional parameters. |
state | string | ステップ1で提供した推測できないランダムな文字列。 |
レスポンス
デフォルトでは、レスポンスは以下の形式になります。 レスポンスパラメータの expires_in
、refresh_token
、refresh_token_expires_in
は、ユーザからサーバに対するアクセストークンの期限設定を有効にしている場合にのみ返されます。
{
"access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
"expires_in": 28800,
"refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
"refresh_token_expires_in": 15811200,
"scope": "",
"token_type": "bearer"
}
3. GitHub Appはユーザのアクセストークンで API にアクセスします
ユーザのアクセストークンを使用すると、GitHub App がユーザの代わりに API にリクエストを発行できます。
Authorization: token OAUTH-TOKEN
GET https://api.github.com/user
たとえば、curlでは以下のようにAuthorizationヘッダを設定できます。
curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/user
デバイスフロー
注釈: デバイスフローは現在パブリックベータであり、変更されることがあります。
デバイスフローを使えば、CLIツールやGit認証情報マネージャーなどのヘッドレスアプリケーションのユーザを認可できます。
Before you can use the device flow to identify and authorize users, you must first enable it in your app's settings. For more information on enabling device flow, see "Modifying a GitHub App." For more information about authorizing users using the device flow, see "Authorizing OAuth Apps."
ユーザがアクセスできるインストールされたリソースの確認
ユーザの 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 は、このイベントをサブスクライブ解除できません。 誰でも、自分のGitHubアカウント設定ページからGitHub Appの認可を取り消すことができます。 GitHub Appの認可を取り消しても、そのGitHub Appはアンインストールされません。 GitHub Appは、このwebhookを受信したら、トークンを取り返した人の代わりにAPIを呼ぶことを止めるようにプログラムしなければなりません。 取り消されたアクセストークンを使い続けると、GitHub Appは401 Bad Credentials
エラーを受け取ることになります。
ユーザレベルの権限
ユーザ認可フローの一環として、個々のユーザに付与されたユーザのメールなどのユーザが所有するリソースにアクセスできる、ユーザレベルの権限を GitHub App に付与できます。 User-level permissions differ from repository and organization-level permissions, which are granted at the time of installation on an organization or personal account.
ユーザレベルの権限は、[Permissions & webhooks] ページの [User permissions] セクションにある GitHub App の設定で選択できます。 権限の選択に関する詳しい情報については、「GitHub Appの権限の編集」を参照してください。
ユーザが自分のアカウントにアプリケーションをインストールする時、インストールプロンプトは、アプリケーションがリクエストするユーザレベルの権限を一覧表示し、アプリケーションがこれらの権限を個々のユーザに求めることができるということを説明します。
ユーザレベルの権限は個々のユーザに付与されるため、ユーザにアップグレードを促すことなく、既存のアプリケーションに権限を追加できます。 ただし、新しい権限を認可し、ユーザからサーバーに対するトークンを取得するため、ユーザ認可フローを通じて既存のユーザを送信する必要があります。
ユーザからサーバーへのリクエスト
While most of your API インタラクションのほとんどは、サーバーからサーバーへのインストールアクセストークンを用いて行われますが、一部のエンドポイントでは、ユーザアクセストークンを使用し、API 経由でアクションを実行できます。 Your app can make the following requests using GraphQL or REST endpoints.
対応しているエンドポイント
Actions ランナー
- リポジトリのランナーアプリケーションの一覧表示
- リポジトリのセルフホストランナーの一覧表示
- リポジトリのセルフホストランナーの取得
- リポジトリからのセルフホストランナーの削除
- リポジトリに対する登録トークンの作成
- リポジトリに対する削除トークンの作成
- Organization のランナーアプリケーションの一覧表示
- Organizationのセルフホストランナーの一覧表示
- Organizationのセルフホストランナーの取得
- Organizationのセルフホストランナーの削除
- Organizationの登録トークンの作成
- Organizationの削除トークンの作成
Actionsのシークレット
- リポジトリ公開鍵の取得
- リポジトリのシークレットの一覧表示
- リポジトリのシークレットの取得
- リポジトリのシークレットの作成もしくは更新
- リポジトリシークレットの削除
- Organizationの公開鍵の取得
- Organizationのシークレットの一覧表示
- Organizationのシークレットの取得
- Organizationのシークレットの作成もしくは更新
- Organizatinoの選択されたリポジトリのシークレットの一覧表示
- Organizationの選択されたリポジトリのシークレットの設定
- Organizationの選択されたリポジトリのシークレットの追加
- Organizationの選択されたリポジトリからのシークレットの削除
- Organizationのシークレットの削除
成果物
チェックラン
チェックスイート
行動規範
デプロイメントステータス
デプロイメント
イベント
フィード
Git Blob
Gitのコミット
Git参照
Gitタグ
Gitツリー
gitignoreテンプレート
インストール
インタラクションの制限
- Organizationのインタラクション制限の取得
- Organizationのインタラクション制限の設定
- Organizationのインタラクション制限の削除
- リポジトリのインタラクション制限の取得
- リポジトリのインタラクション制限の設定
- リポジトリのインタラクション制限の削除
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の外部コラボレータの削除
OrganizationのTeamのプロジェクト
OrganizationのTeamリポジトリ
Organization Team Sync
Organization Team
Organization
- Organizationの一覧表示
- Organizationの取得
- Organizationの更新
- 認証されたユーザのOrganizationメンバーシップの一覧表示
- 認証されたユーザのOrganizationメンバーシップの取得
- 認証されたユーザのOrganizationメンバーシップの更新
- 認証されたユーザのOrganizationの一覧表示
- ユーザのOrganizationの一覧表示
Organizationのクレデンシャルの認証
OrganizationのSCIM
- SCIMでプロビジョニングされたアイデンティティの一覧表示
- SCIMユーザのプロビジョニングと招待
- ユーザのSCIMプロビジョニング情報の取得
- プロビジョニングされたユーザのSCIM情報の設定
- SCIMユーザの属性の更新
- OrganizationからのSCIMユーザの削除
ソースのインポート
プロジェクトのコラボレータ
プロジェクト
- 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レビューのコメントの一覧表示
Pulls
- Pull Requestの一覧表示
- Pull Requestの作成
- Pull Requestの取得
- Pull Requestの更新
- Pull Requestのコミットの一覧表示
- Pull Requestのファイルの一覧表示
- Pull Requestがマージされたかをチェック
- Pull Requestをマージ(マージボタン)
リアクション
- Delete a reaction
- コミットコメントへのリアクションの一覧表示
- コミットコメントへのリアクションの作成
- Issueへのリアクションの一覧表示
- Issueへのリアクションの作成
- Issueコメントへのリアクションの一覧表示
- Issueコメントへのリアクションの作成
- Pull Requestのレビューコメントへのリアクションの一覧表示
- Pull Requestのレビューコメントへのリアクションの作成
- Teamディスカッションコメントへのリアクションの一覧表示
- Teamディスカッションコメントへのリアクションの作成
- Teamディスカッションへのリアクションの一覧表示
- Create reaction for a team discussion
- コミットコメントへのリアクションの削除
- Issueへのリアクションの削除
- コミットコメントへのリアクションの削除
- Pull Requestのコメントへのリアクションの削除
- Teamディスカッションへのリアクションの削除
- Delete team discussion comment reaction
リポジトリ
- 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のビルドの取得
リポジトリのリリース
- リリースの一覧表示
- リリースの作成
- リリースの取得
- リリースの更新
- リリースの削除
- リリースアセットの一覧表示
- リリースアセットの取得
- リリースアセットの更新
- リリースアセットの削除
- 最新リリースの取得
- タグ名によるリリースの取得
リポジトリ統計
リポジトリ脆弱性アラート
ルート
検索
ステータス
Teamディスカッション
- ディスカッションの一覧表示
- ディスカッションの作成
- ディスカッションの取得
- ディスカッションの更新
- ディスカッションの削除
- ディスカッションコメントの一覧表示
- ディスカッションコメントの作成
- ディスカッションコメントの取得
- ディスカッションコメントの更新
- ディスカッションコメントの削除
Topics
トラフィック
ユーザのブロック
- 認証されたユーザによってブロックされたユーザの一覧表示
- 認証されたユーザによってユーザがブロックされているかをチェック
- Organizationによってブロックされたユーザを一覧表示
- Organizationによってユーザがブロックされているかをチェック
- Organizationからユーザをブロック
- Oraganizationからのユーザのブロックを解除
- ユーザをブロック
- ゆーざのブロックを解除
ユーザのメール
ユーザのフォロワー
- ユーザのフォロワーの一覧表示
- ユーザがフォローしている人の一覧表示
- 認証されたユーザによって人がフォローされているかのチェック
- ユーザのフォロー
- ユーザのフォロー解除
- ユーザが他のユーザにフォローされているかのチェック
ユーザのGPGキー
ユーザの公開鍵
ユーザ
ワークフローラン
- リポジトリのワークフローランの一覧表示
- ワークフローランの取得
- ワークフローランのキャンセル
- ワークフローランのログのダウンロード
- ワークフローランのログの削除
- ワークフローの再実行
- ワークフローランの一覧表示
- ワークフローランの利用状況の取得