Skip to main content

このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2022-10-12. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせく� さい

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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/api/v3/user

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

curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user

デバイスフロー

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

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

デバイス フローを使用してユーザーを認可する方法の詳細については、「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 エンドポイントを使用して以下の要求を行うことができます。

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

チェックラン

チェックスイート

行動規範

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

デプロイメント

イベント

フィード

Git Blob

Git コミット

Git参照

Gitタグ

Gitツリー

gitignoreテンプレート

インストール

Issueにアサインされた人

Issueコメント

Issueイベント

Issueのタイ� ライン

issue

ラベル

ライセンス

Markdown

Meta

マイルストーン

Organizationのフック

Organizationのメンバー

Organizationの外部コラボレータ

Organization pre-receive フック

OrganizationのTeamのプロジェクト

OrganizationのTeamリポジトリ

Organization Team

組織

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

プロジェクト

Pull Requestのコメント

Pull Requestのレビューイベント

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

Pull Requestのレビュー

Pulls

リアクション

リポジトリ

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

リポジトリのブランチ

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

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

リポジトリのコミット

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

リポジトリのコンテンツ

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

リポジトリのフック

リポジトリの招待

リポジトリのキー

リポジトリのPages

リポジトリ pre-receive フック

リポジトリのリリース

リポジトリ統計

Root

ステータス

Teamディスカッション

トピック

ユーザーの電子メール

ユーザのフォロワー

ユーザのGPGキー

ユーザの公開鍵

ユーザー

参考資料