Skip to main content

Identifying and authorizing users for GitHub Apps (GitHub アプリのユーザーを特定および認可する)

GitHub Appは、Issueの作成、デプロイメントの作成、サポートされている他のエンドポイントの利用など、アクションをユーザの代わりに行うことができます。

注: 有効期限が切れるユーザー トークンは現在、オプションの機能であり、変更される可能性があります。 ユーザーからサーバーへのトークンの有効期限機能をオプトインまたはオプトアウトするには、「アプリケーションのオプション機能をアクティブにする」を参照してください。 詳細については、「GitHub App のユーザーからサーバーへのアクセストークンの期限切れ」を参照してください。

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

ユーザからサーバーへのアクセストークンをさらにセキュアにするために、8時間後に期限切れとなるアクセストークンと、新しいアクセストークンと交換できるリフレッシュトークンを使用できます。 詳細については、「ユーザーからサーバーへのアクセス トークンの更新」を参照してください。

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

ブラウザーで実行される標準アプリのユーザーを認可するには、Web アプリケーション フローを使用します。

CLI ツールや Git 資格情報マネージャーなど、ブラウザーに直接アクセスしないヘッドレス アプリのユーザーを認可するには、デバイス フローを使用します。 デバイス フローでは、OAuth 2.0 デバイス認可付与を使用します。

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

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

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

アプリを作成または変更するときに [インストール時にユーザーの認可 (OAuth) を要求する] を選択すると、アプリのインストール時に手順 1 が完了します。 詳細については、「インストール中のユーザーの認可」を参照してください。

1. ユーザーの GitHub ID を要求する

ブラウザで次のURLに移動するようユーザに指示します。

GET https://github.com/login/oauth/authorize

GitHub アプリで login パラメーターを指定すると、ユーザーは、使用できるアカウントでサインインしてアプリを認可するように求められます。

パラメーター

名前説明
client_idstring必須。 GitHub アプリのクライアント ID。 アプリを選択すると、GitHub アプリの設定でこれを確認できます。 注: アプリ ID とクライアント ID は異なり、交換はできません。
redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub アプリの設定時にコールバック URL として指定したいずれかの URL と完全に一致する必要があり、追加のパラメーターを含めることはできません。
statestringこれはフォージェリアタックを防ぐためにランダムな文字列を含める必要があり、あらゆる任意のデータを含めることができます。
loginstringサインインとアプリケーションの認可に使われるアカウントを指示します。
allow_signupstringOAuthフローの間に、認証されていないユーザに対してGitHubへのサインアップの選択肢が提示されるかどうか。 既定値は、true です。 ポリシーでサインアップが禁止されている場合は、false を使用します。

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

2. GitHub によってユーザーが元のサイトにリダイレクトされる

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

注: アプリを作成または変更するときに [インストール時にユーザーの認可 (OAuth) を要求する] を選択すると、GitHub はアクセス トークンとの交換に必要となる一時的な code を返します。 アプリのインストール時に GitHub が OAuth フローを開始した場合、state パラメーターは返されません。

この code をアクセス トークンと交換します。 トークンの期限設定が有効になっている場合、アクセストークンは 8 時間で期限切れとなり、リフレッシュトークンは 6 か月で期限切れとなります。 トークンを更新するたびに、新しいリフレッシュトークンを取得します。 詳細については、「ユーザーからサーバーへのアクセス トークンの更新」を参照してください。

ユーザトークンの期限設定は、現在のところオプション機能であり、変更される可能性があります。 ユーザーからサーバーへのトークンの期限設定機能をオプトインするには、「アプリケーションのオプション機能を有効化する」を参照してください。

アクセストークンを受け取るため、次のエンドポイントをリクエストします。

POST https://github.com/login/oauth/access_token

パラメーター

名前説明
client_idstring必須。 GitHub アプリのクライアント ID。
client_secretstring必須。 GitHub アプリのクライアント シークレット。
codestring必須。 手順 1 に対する応答として受け取ったコード。
redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub アプリの設定時にコールバック URL として指定したいずれかの URL と完全に一致する必要があり、追加のパラメーターを含めることはできません。
statestringステップ1で提供した推測できないランダムな文字列。

[応答]

デフォルトでは、レスポンスは以下の形式になります。 応答パラメーター expires_inrefresh_tokenrefresh_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 アプリがユーザーのアクセス トークンで API にアクセスする

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

Authorization: Bearer OAUTH-TOKEN
GET https://api.github.com/user

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

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/user

デバイスフロー

注: デバイス フローはパブリック ベータ版であり、変更される可能性があります。

デバイスフローを使えば、CLIツールやGit認証情報マネージャーなどのヘッドレスアプリケーションのユーザを認可できます。

デバイス フローを使用してユーザーを特定および認可するには、まずアプリの設定で有効にする必要があります。 デバイス フローを有効にする方法の詳細については、「GitHub アプリの変更」を参照してください。 デバイス フローを使用してユーザーを認可する方法の詳細については、「OAuth アプリの承認」を参照してください。

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

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

Authorization: Bearer OAUTH-TOKEN
GET /user/installations

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

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

詳細については、「ユーザー アクセス トークンでアクセスできるアプリのインストールの一覧表示」および「ユーザー アクセス トークンでアクセスできるリポジトリの一覧表示」を参照してください。

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

ユーザーが GitHub アプリの認可を取り消すと、アプリは既定で github_app_authorization Webhook を受け取ります。 GitHub App は、このイベントをサブスクライブ解除できません。 だれでも、GitHub アカウント設定ページから GitHub アプリの承認を取り消すことができます。 GitHub Appの認可を取り消しても、そのGitHub Appはアンインストールされません。 GitHub Appは、このwebhookを受信したら、トークンを取り返した人の代わりにAPIを呼ぶことを止めるようにプログラムしなければなりません。 取り消されたアクセス トークンを使い続けると、GitHub App は 401 Bad Credentials エラーを受け取ることになります。

ユーザレベルの権限

GitHub アプリにユーザー レベルのアクセス許可を追加すると、ユーザー認可フローの一部として個々のユーザーによって付与されるユーザー リソース (ユーザーのメールなど) にアクセスできます。 ユーザー レベルのアクセス許可は、インストール時に組織または個人アカウントで付与されるリポジトリおよび組織レベルのアクセス許可とは異なります。

ユーザー レベルのアクセス許可は、GitHub アプリの設定にある [アクセス許可と Webhook] ページの [ユーザーのアクセス許可] セクションから選択できます。 アクセス許可の選択の詳細については、「GitHub アプリのアクセス許可を編集する」を参照してください。

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

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

ユーザからサーバーへのリクエスト

While most of your API インタラクションのほとんどは、サーバーからサーバーへのインストールアクセストークンを用いて行われますが、一部のエンドポイントでは、ユーザアクセストークンを使用し、API 経由でアクションを実行できます。 アプリでは、GraphQL または REST エンドポイントを使用して以下の要求を行うことができます。

対応しているエンドポイント

Actions ランナー

Actionsのシークレット

Artifacts

チェックラン

チェックスイート

行動規範

デプロイメントステータス

デプロイメント

イベント

フィード

Git Blob

Git コミット

Git参照

Gitタグ

Gitツリー

gitignoreテンプレート

インストール

インタラクションの制限

Issueにアサインされた人

Issueコメント

Issueイベント

Issueのタイムライン

issue

ジョブ

ラベル

ライセンス

Markdown

Meta

マイルストーン

Organizationのフック

Organizationの招待

Organizationのメンバー

Organizationの外部コラボレータ

OrganizationのTeamのプロジェクト

OrganizationのTeamリポジトリ

Organization Team Sync

Organization Team

組織

Organizationのクレデンシャルの認証

OrganizationのSCIM

ソースのインポート

プロジェクトのコラボレータ

プロジェクト

Pull Requestのコメント

Pull Requestのレビューイベント

Pull Requestのレビューのリクエスト

Pull Requestのレビュー

Pulls

リアクション

リポジトリ

リポジトリのアクティビティ

リポジトリの自動化されたセキュリティ修正

リポジトリのブランチ

リポジトリのコラボレータ

リポジトリのコミットコメント

リポジトリのコミット

リポジトリのコミュニティ

リポジトリのコンテンツ

リポジトリのイベントのディスパッチ

リポジトリのフック

リポジトリの招待

リポジトリのキー

リポジトリのPages

リポジトリのリリース

リポジトリ統計

リポジトリ脆弱性アラート

Root

ステータス

Teamディスカッション

トピック

トラフィック

ユーザのブロック

ユーザーの電子メール

ユーザのフォロワー

ユーザのGPGキー

ユーザの公開鍵

ユーザー

ワークフローラン

Workflows

参考資料