GitHub アプリのユーザー アクセス トークンの生成

ユーザー アクセス トークンについて

ユーザー アクセス トークンは、OAuth トークンの一種です。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンにスコープは使用されません。 代わりに、きめ細かいアクセス許可が使用されます。 ユーザー アクセス トークンを使用すると、ユーザーとアプリの両方が持っているアクセス許可のみが付与されます。 たとえば、アプリにリポジトリの内容を書き込むアクセス許可が付与されていても、ユーザーにできることが内容の読み取りだけである場合、ユーザー アクセス トークンではコンテンツの読み取りのみを行うことができます。

同様に、ユーザー アクセス トークンでアクセスできるのは、ユーザーとアプリの両方でアクセスできるリソースのみです。 たとえば、アプリにリポジトリ A と B へのアクセス権が付与されていて、ユーザーがリポジトリ B と C にアクセスできる場合、ユーザー アクセス トークンでリポジトリ B にはアクセスできますが、A または C にはアクセスできません。 REST API を使用して、ユーザー アクセス トークンでアクセスできるインストールとインストール内のリポジトリを確認できます。 詳しくは、「GitHub Appインストール用 REST API エンドポイント」の「GET /user/installations」と「GET /user/installations/{installation_id}/repositories」を参照してください。

ユーザー アクセス トークンを使用して API 要求を行う場合、ユーザー アクセス トークンのレート制限が適用されます。 詳しくは、「Rate limits for GitHub Apps (GitHub アプリのレート制限)」を参照してください。

既定では、ユーザー アクセス トークンは 8 時間後に期限切れになります。 更新トークンを使用してユーザー アクセス トークンを再生成できます。 詳しくは、「ユーザー アクセス トークンを更新する」を参照してください。

ユーザーは、GitHub App の認可を取り消すことができます。 詳しくは、「トークンの有効期限と取り消し」を参照してください。 ユーザーが GitHub App の認可を取り消すと、アプリは github_app_authorization Webhook を受け取ります。 GitHub Apps は、このイベントをサブスクライブ解除できません。 アプリがこの Webhook を受け取った場合は、トークンを取り消したユーザーに代わって行う API の呼び出しを停止する必要があります。 取り消されたアクセス トークンを使い続けると、アプリは 401 Bad Credentials エラーを受け取ることになります。 この Webhook について詳しくは、「Webhook のイベントとペイロード」を参照してください。

ユーザー アクセス トークンと更新トークンはセキュリティ保護する必要があります。 詳しくは、「GitHub App を作成するためのベスト プラクティス」を参照してください。

Web アプリケーション フローを使用してユーザー アクセス トークンを生成する

アプリがブラウザーで実行されている場合は、Web アプリケーション フローを使用してユーザー アクセス トークンを生成する必要があります。 Web アプリケーション フローの使用に関するチュートリアルについては、「GitHub App を使って [Login with GitHub] ボタンを作成する」を参照してください。

1. この URL にユーザーを誘導し、次のパラメーターの一覧から必要なクエリ パラメーターを追加します: http(s)://HOSTNAME/login/oauth/authorize。 たとえば、この URL では、client_id パラメーターと state パラメーターを指定します: http(s)://HOSTNAME/login/oauth/authorize?client_id=12345&state=abcdefg。

   Query parameter (クエリ パラメーター)	Type	説明
   client_id	string	必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページにアクセスする方法について詳しくは、「GitHub App 登録の変更」を参照してください。
   redirect_uri	string	認可の後にユーザが送られるアプリケーション中のURL。 これは、アプリの設定で "コールバック URL" として指定した URL のどれかと完全に一致している必要があり、追加のパラメーターを含めることはできません。
   state	string	指定する場合、値には偽造攻撃から保護するランダムな文字列が含まれている必要があります。また、他の任意のデータを含めることもできます。
   login	string	指定すると、サインインとアプリの承認に使用できる特定のアカウントを持つユーザーに Web アプリケーション フローでプロンプトが表示されます。
   allow_signup	boolean	OAuth フローの間に、認証されていないユーザーに対してGitHub へのサインアップの選択肢が提示されるかどうか。 既定値は、true です。 ポリシーでサインアップが禁止されている場合は、false を使用します。

2. ユーザーが認可要求を受け入れた場合、ユーザーは GitHub でアプリ設定のコールバック URL のどれかにリダイレクトされ、次の手順でユーザー アクセス トークンを作成するために使用できる code クエリ パラメーターが提供されます。 前の手順で redirect_uri を指定した場合、そのコールバック URL が使用されます。 それ以外の場合は、アプリの設定ページの最初のコールバック URL が使用されます。

   前の手順で state パラメーターを指定した場合、GitHub にも state パラメーターが含まれます。 state パラメーターが前の手順で送信した state パラメーターと一致しない場合、要求を信頼できないため、Web アプリケーション フローを中止する必要があります。

3. 以下のクエリ パラメータと共に、次の URL に POST 要求を行うことにより、前の手順の code をユーザー アクセス トークンに交換します: http(s)://HOSTNAME/login/oauth/access_token

   Query parameter (クエリ パラメーター)	Type	説明
   client_id	string	必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページに移動する方法について詳しくは、「GitHub App 登録の変更」を参照してください。
   client_secret	string	必須。 GitHub App のクライアント シークレット。 アプリの設定ページでクライアント シークレットを生成できます。
   code	string	必須。 前の手順で受け取ったコード。
   redirect_uri	string	認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub App を設定するときに "コールバック URL" として指定した URL のいずれかと完全に一致する必要があり、追加のパラメーターを含めることはできません。
   repository_id	string	ユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。

4. GitHub から、次のパラメーターを含む応答が提供されます。

   応答パラメーター	Type	説明
   access_token	string	ユーザー アクセス トークン。 トークンは ghu_ で始まります。
   expires_in	integer	access_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
   refresh_token	string	更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
   refresh_token_expires_in	integer	refresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15897600 (6 か月) になります。
   scope	string	トークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
   token_type	string	トークンの種類。 値は常に bearer になります。

5. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

   curl --request GET \
   --url "http(s)://<em>HOSTNAME</em>/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"
   

デバイス フローを使用してユーザー アクセス トークンを生成する

アプリがヘッドレスであるか、ブラウザーにアクセスできない場合は、デバイス フローを使用してユーザー アクセス トークンを生成する必要があります。 たとえば、CLI ツール、シンプルな Raspberry Pis、デスクトップ アプリケーションでは、デバイス フローを使う必要があります。 デバイス フローを使用するチュートリアルについては、「GitHub アプリを使用して CLI を構築する」をご覧ください。

デバイス フローを使う前に、まずアプリの設定でこれを有効にする必要があります。 デバイス フローの有効化について詳しくは、「GitHub App 登録の変更」を参照してください。

デバイス フローでは、OAuth 2.0 デバイス認可付与を使用します。

1. POST 要求を client_id クエリ パラメーターと共に http(s)://HOSTNAME/login/device/code に送信します。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページにアクセスする方法について詳しくは、「GitHub App 登録の変更」を参照してください。

2. GitHub から、次のクエリ パラメーターを含む応答が提供されます。

   応答パラメーター	Type	説明
   device_code	string	デバイスの検証に使用される確認コード。 このコードの長さは 40 文字です。
   user_code	string	ユーザーがブラウザーでコードを入力できるように、アプリケーションで表示する必要がある確認コード。 このコードは8文字で、途中にハイフンがあります。 たとえば、「 WDJB-MJHT 」のように入力します。
   verification_uri	string	ユーザーが自分の user_code を入力する必要がある URL。 URL は http(s)://HOSTNAME/login/device です。
   expires_in	integer	device_code と user_code の有効期限か切れるまでの秒数。 既定値は 900 秒 (15 分) です。
   interval	integer	デバイスの認可を完了するために新しいアクセス トークンのリクエスト (POST http(s)://HOSTNAME/login/oauth/access_token) を発行する前に経過する必要がある最小秒数。 この間隔が経過する前に要求を行うと、レート制限に達して slow_down エラーが返されます。 既定値は 5 秒です。

3. 前の手順の user_code を http(s)://HOSTNAME/login/device で入力するようにユーザーに求めます。

   expires_in の時間が経過する前にユーザーがコードを入力しないと、コードは無効になります。 そうなった場合は、デバイス フローを再起動する必要があります。

4. デバイスおよびユーザー コードが期限切れになるか、ユーザーが user_code を入力してアプリが正常に承認されるまで、client_id、device_code、grant_type のクエリ パラメーター (後述) と共に POST http(s)://HOSTNAME/login/oauth/access_token をポーリングします。

   Query parameter (クエリ パラメーター)	Type	説明
   client_id	string	必須。 GitHub App のクライアント ID。
   device_code	string	必須。 前の手順で受け取ったデバイス確認コード。
   grant_type	string	必須。 付与タイプは urn:ietf:params:oauth:grant-type:device_code でなければなりません。
   repository_id	string	ユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。

   interval で示される頻度よりも高い頻度でこのエンドポイントをポーリングしないでください。 それを行うと、レート制限に達して slow_down エラーが返されます。 slow_down エラー応答によって、最後の interval に 5 秒が追加されます。

   ユーザーがコードを入力するまで、GitHub は 200 状態と error 応答クエリ パラメーターで応答します。

   エラー名	説明
   authorization_pending	このエラーコードは、認可リクエストが保留中で、ユーザがユーザコードをまだ入力していない場合に生じます。 アプリは、interval で指定された頻度を超えない頻度で POST http(s)://HOSTNAME/login/oauth/access_token をポーリングし続ける必要があります。
   slow_down	slow_down エラーが返された場合、最小の interval、あるいは POST http(s)://HOSTNAME/login/oauth/access_token を使用するリクエスト間に必要な時間間隔に 5 秒が追加されます。 たとえば、開始時の間隔として要求間に最小で 5 秒が必要だった場合に、slow_down エラー応答が返された場合、トークンを求める新しい要求を行うまで少なくとも 10 秒待たなければならなくなります。 エラー応答には、使用する必要がある新しい interval 情報が含まれます。
   expired_token	デバイス コードの有効期限が切れた場合は、token_expired エラーが表示されます。 デバイスコードを求める新しいリクエストを発行しなければなりません。
   unsupported_grant_type	OAuth トークン リクエストの POST http(s)://HOSTNAME/login/oauth/access_token でポーリングする際には、付与タイプを urn:ietf:params:oauth:grant-type:device_code として、入力パラメーターに含めなければなりません。
   incorrect_client_credentials	デバイスフローでは、アプリケーションのクライアントIDを渡さなければなりません。これは、アプリケーションの設定ページにあります。 クライアント ID が、アプリ ID およびクライアント シークレットと異なります。
   incorrect_device_code	指定された device_code が無効です。
   access_denied	認可プロセス中にユーザーがキャンセルをクリックした場合、access_denied エラーが返され、ユーザーは確認コードを再び利用することができなくなります。
   device_flow_disabled	アプリケーションの設定で、デバイス フローが有効になっていません。 デバイス フローについて詳しくは、「GitHub App 登録の変更」を参照してください。

5. ユーザーが user_code を入力すると、GitHub から、次のクエリ パラメーターを含む応答があります。

   応答パラメーター	Type	説明
   access_token	string	ユーザー アクセス トークン。 トークンは ghu_ で始まります。
   expires_in	integer	access_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
   refresh_token	string	更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
   refresh_token_expires_in	integer	refresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15897600 (6 か月) になります。
   scope	string	トークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
   token_type	string	トークンの種類。 値は常に bearer になります。

6. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

   curl --request GET \
   --url "http(s)://<em>HOSTNAME</em>/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"
   

ユーザーがアプリをインストールするときにユーザー アクセス トークンを生成する

アプリ設定で [インストール時にユーザーの認可 (OAuth) を要求する] を選んだ場合、GitHub により、ユーザーがアプリをインストールした直後に Web アプリケーション フローが開始されます。

アプリがユーザー アカウントと Organization アカウントのどちらにインストールされるかに関係なく、この方法でユーザー アクセス トークンを生成できます。 ただし、アプリが Organization アカウントにインストールされた場合は、Web アプリケーション フローまたはデバイス フローを使用して、Organization 内の他のユーザーのユーザー アクセス トークンを生成する必要があります。

1. ユーザーがアプリをインストールすると、GitHub でユーザーは http(s)://HOSTNAME/login/oauth/authorize?client_id=CLIENT_ID にリダイレクトされます。ここで、CLIENT_ID はアプリのクライアント ID です。

2. ユーザーが認可要求を受け入れた場合、ユーザーは GitHub でアプリ設定の最初のコールバック URL にリダイレクトされ、code クエリ パラメーターが提供されます。

   どのコールバック URL を使用するかを制御する場合は、 [インストール時にユーザーの認可 (OAuth) を要求する] を選ばないでください。 代わりに、完全な Web アプリケーション フローでユーザーを誘導し、redirect_uri パラメーターを指定します。

3. 以下のクエリ パラメータと共に、次の URL に POST 要求を行うことにより、前の手順の code をユーザー アクセス トークンに交換します: http(s)://HOSTNAME/login/oauth/access_token

   Query parameter (クエリ パラメーター)	Type	説明
   client_id	string	必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページに移動する方法について詳しくは、「GitHub App 登録の変更」を参照してください。
   client_secret	string	必須。 GitHub App のクライアント シークレット。 アプリの設定ページでクライアント シークレットを生成できます。
   code	string	必須。 前の手順で受け取ったコード。
   redirect_uri	string	認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub App を設定するときに "コールバック URL" として指定した URL のいずれかと完全に一致する必要があり、追加のパラメーターを含めることはできません。
   repository_id	string	ユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。

4. GitHub から、次のパラメーターを含む応答が提供されます。

   応答パラメーター	Type	説明
   access_token	string	ユーザー アクセス トークン。 トークンは ghu_ で始まります。
   expires_in	integer	access_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
   refresh_token	string	更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
   refresh_token_expires_in	integer	refresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15897600 (6 か月) になります。
   scope	string	トークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
   token_type	string	トークンの種類。 値は常に bearer になります。

5. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

   curl --request GET \
   --url "http(s)://<em>HOSTNAME</em>/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"
   

更新トークンを使用してユーザー アクセス トークンを生成する

既定では、ユーザー アクセス トークンは 8 時間後に期限切れになります。 有効期限があるユーザー アクセス トークンを受け取った場合は、更新トークンも受け取ります。 更新トークンの有効期限は 6 か月後です。 この更新トークンを使用して、ユーザー アクセス トークンを再生成できます。 詳しくは、「ユーザー アクセス トークンを更新する」を参照してください。

GitHub では、有効期限があるユーザー アクセス トークンを使用することを強くお勧めします。 以前に有効期限があるユーザー アクセス トークンの使用をオプトアウトしたものの、この機能を再び有効化したい場合は、「GitHub アプリのオプション機能のアクティブ化」を参照してください。

トラブルシューティング

次のセクションでは、ユーザー アクセス トークンの生成時に発生する可能性のあるエラーの概要について説明します。

不正なクライアント認識情報

指定した client_id または client_secret が正しくない場合は、incorrect_client_credentials エラーが発生します。

このエラーを解決するには、GitHub App の正しい認証情報を使っていることを確認します。 クライアント ID とクライアント シークレットは、GitHub App の設定ページで確認できます。 GitHub App の設定ページに移動する方法について詳しくは、「GitHub App 登録の変更」をご覧ください。

リダイレクトURIの不一致

GitHub App の登録に対するコールバック URL のいずれとも一致しない redirect_uri を指定すると、redirect_uri_mismatch エラーが発生します。

このエラーを解決するには、GitHub App の登録に対するコールバック URL のいずれかと一致する redirect_uri を指定するか、このパラメーターを省略して、GitHub App の登録に列記されているコールバック URL の最初のものを既定で使います。 詳しくは、「ユーザー承認コールバック URL について」を参照してください。

不正な検証コード

デバイス フローを使っていて、指定した検証コード (device_code) が正しくない場合、有効期限切れの場合、または http(s)://HOSTNAME/login/device/code への最初の要求から受け取った値と一致しない場合は、bad_verification_code エラーが発生します。

このエラーを解決するには、デバイス フローをもう一度開始して、新しいコードを取得する必要があります。 詳しくは、「デバイス フローを使用してユーザー アクセス トークンを生成する」をご覧ください。

更新トークンが正しくない

指定した更新トークンが無効または期限切れである場合は、bad_refresh_token エラーが発生します。

このエラーを解決するには、Web アプリケーション フローまたはデバイス フローを開始し直して、新しいユーザー アクセス トークンと更新トークンを取得する必要があります。 更新トークンを受け取るのは、GitHub App が期限切れのユーザー アクセス トークンをオプトインしている場合のみです。 詳しくは、「ユーザー アクセス トークンを更新する」を参照してください。

サポートされていない付与タイプ

デバイス フローを介してユーザー アクセス トークンを要求する場合は、grant_type パラメーターで urn:ietf:params:oauth:grant-type:device_code を指定する必要があります。 更新トークンを使ってユーザー アクセス トークンを更新する場合は、grant_type パラメーターで refresh_token を指定する必要があります。 正しい付与タイプを使わないと、unsupported_grant_type エラーが発生します。

未確認のユーザー メール

生成しようとしているユーザー アクセス トークンの対象ユーザーのプライマリ メール アドレスが、GitHub で検証されていない場合は、unverified_user_email エラーが発生します。

このエラーを解決するには、GitHub アカウントでプライマリ メール アドレスを検証するよう、ユーザーに求めます。 詳しくは、GitHub Free のドキュメントの「メールアドレスを検証する」をご覧ください。