Skip to main content

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

アプリ アクティビティがユーザーに帰属することを示すために、GitHub App のユーザー アクセス トークンを生成できます。

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

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

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

同様に、ユーザー アクセス トークンでアクセスできるのは、ユーザーとアプリの両方でアクセスできるリソースのみです。 たとえば、アプリにリポジトリ AB へのアクセス権が付与されていて、ユーザーがリポジトリ BC にアクセスできる場合、ユーザー アクセス トークンでリポジトリ 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 を作成するためのベスト プラクティス」を参照してください。

: GitHub App を承認した後に自分の Organization で所有しているリソースを表示できないことがユーザーから報告され、その Organization で SAML SSO を使用している場合、再認証する前に、Organization のアクティブな SAML セッションを開始するようにユーザーに指示します。 詳しい情報については、GitHub Enterprise Cloud ドキュメントの「SAML と GitHub Apps」を参照してください。

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_idstring必須GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページに移動する方法について詳しくは、「GitHub App 登録の変更」を参照してください。
    redirect_uristring強く推奨認可の後にユーザが送られるアプリケーション中のURL。 これは、アプリの設定で "コールバック URL" として指定した URL のどれかと完全に一致している必要があり、追加のパラメーターを含めることはできません。
    statestring強く推奨指定する場合、値には偽造攻撃から保護するランダムな文字列が含まれている必要があります。また、他の任意のデータを含めることもできます。
    loginstring省略可能指定すると、サインインとアプリの承認に使用できる特定のアカウントを持つユーザーに Web アプリケーション フローでプロンプトが表示されます。
    allow_signupboolean省略可能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_idstring必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページに移動する方法について詳しくは、「GitHub App 登録の変更」を参照してください。
    client_secretstring必須。 GitHub App のクライアント シークレット。 アプリの設定ページでクライアント シークレットを生成できます。
    codestring必須。 前の手順で受け取ったコード。
    redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub App を設定するときに "コールバック URL" として指定した URL のいずれかと完全に一致する必要があり、追加のパラメーターを含めることはできません。
    repository_idstringユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。
  4. GitHub から、次のパラメーターを含む応答が提供されます。

    応答パラメーターType説明
    access_tokenstringユーザー アクセス トークン。 トークンは ghu_ で始まります。
    expires_inintegeraccess_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
    refresh_tokenstring更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
    refresh_token_expires_inintegerrefresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15897600 (6 か月) になります。
    scopestringトークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
    token_typestringトークンの種類。 値は常に bearer になります。
  5. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

    curl --request GET \
    --url "http(s)://HOSTNAME/api/v3/user" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer USER_ACCESS_TOKEN" \
    --header "X-GitHub-Api-Version: 2022-11-28"
    

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

: このデバイスは ベータ にあり、変更される可能性があります。

アプリがヘッドレスであるか、ブラウザーにアクセスできない場合は、デバイス フローを使用してユーザー アクセス トークンを生成する必要があります。 たとえば、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_codestringデバイスの検証に使用される確認コード。 このコードの長さは 40 文字です。
    user_codestringユーザーがブラウザーでコードを入力できるように、アプリケーションで表示する必要がある確認コード。 このコードは8文字で、途中にハイフンがあります。 たとえば、「 WDJB-MJHT 」のように入力します。
    verification_uristringユーザーが自分の user_code を入力する必要がある URL。 URL は http(s)://HOSTNAME/login/device です。
    expires_inintegerdevice_codeuser_code の有効期限か切れるまでの秒数。 既定値は 900 秒 (15 分) です。
    intervalintegerデバイスの認可を完了するために新しいアクセス トークンのリクエスト (POST http(s)://HOSTNAME/login/oauth/access_token) を発行する前に経過する必要がある最小秒数。 この間隔が経過する前に要求を行うと、レート制限に達して slow_down エラーが返されます。 既定値は 5 秒です。
  3. 前の手順の user_codehttp(s)://HOSTNAME/login/device で入力するようにユーザーに求めます。

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

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

    Query parameter (クエリ パラメーター)Type説明
    client_idstring必須。 GitHub App のクライアント ID。
    device_codestring必須。 前の手順で受け取ったデバイス確認コード。
    grant_typestring必須。 付与タイプは urn:ietf:params:oauth:grant-type:device_code でなければなりません。
    repository_idstringユーザー アクセス トークンでアクセスできる 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_downslow_down エラーが返された場合、最小の interval、あるいは POST http(s)://HOSTNAME/login/oauth/access_token を使用するリクエスト間に必要な時間間隔に 5 秒が追加されます。 たとえば、開始時の間隔として要求間に最小で 5 秒が必要だった場合に、slow_down エラー応答が返された場合、トークンを求める新しい要求を行うまで少なくとも 10 秒待たなければならなくなります。 エラー応答には、使用する必要がある新しい interval 情報が含まれます。
    expired_tokenデバイス コードの有効期限が切れた場合は、token_expired エラーが表示されます。 デバイスコードを求める新しいリクエストを発行しなければなりません。
    unsupported_grant_typeOAuth トークン リクエストの 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_tokenstringユーザー アクセス トークン。 トークンは ghu_ で始まります。
    expires_inintegeraccess_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
    refresh_tokenstring更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
    refresh_token_expires_inintegerrefresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15897600 (6 か月) になります。
    scopestringトークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
    token_typestringトークンの種類。 値は常に bearer になります。
  6. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

    curl --request GET \
    --url "http(s)://HOSTNAME/api/v3/user" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer USER_ACCESS_TOKEN" \
    --header "X-GitHub-Api-Version: 2022-11-28"
    

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

アプリ設定で [インストール時にユーザーの認可 (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_idstring必須。 GitHub App のクライアント ID。 クライアント ID は、アプリ ID とは異なります。 クライアント ID は、アプリの設定ページで確認できます。 GitHub App の [設定] ページに移動する方法について詳しくは、「GitHub App 登録の変更」を参照してください。
    client_secretstring必須。 GitHub App のクライアント シークレット。 アプリの設定ページでクライアント シークレットを生成できます。
    codestring必須。 前の手順で受け取ったコード。
    redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 これは、GitHub App を設定するときに "コールバック URL" として指定した URL のいずれかと完全に一致する必要があり、追加のパラメーターを含めることはできません。
    repository_idstringユーザー アクセス トークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。 ユーザー アクセス トークンのアクセスをさらに制限するには、このパラメーターを使います。
  4. GitHub から、次のパラメーターを含む応答が提供されます。

    応答パラメーターType説明
    access_tokenstringユーザー アクセス トークン。 トークンは ghu_ で始まります。
    expires_inintegeraccess_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 28800 (8 時間) になります。
    refresh_tokenstring更新トークン。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 トークンは ghr_ で始まります。
    refresh_token_expires_inintegerrefresh_token の有効期限が切れるまでの秒数。 ユーザー アクセス トークンの有効期限を無効にした場合、このパラメーターは省略されます。 値は常に 15897600 (6 か月) になります。
    scopestringトークンのスコープ。 この値は常に空の文字列になります。 従来の OAuth トークンとは異なり、ユーザー アクセス トークンは、アプリとユーザーの両方が持つアクセス許可に制限されます。
    token_typestringトークンの種類。 値は常に bearer になります。
  5. 前のステップのユーザー アクセス トークンを使って、ユーザーの代わりに API 要求を行います。 API 要求の Authorization ヘッダーにユーザー アクセス トークンを含めます。 次に例を示します。

    curl --request GET \
    --url "http(s)://HOSTNAME/api/v3/user" \
    --header "Accept: application/vnd.github+json" \
    --header "Authorization: Bearer USER_ACCESS_TOKEN" \
    --header "X-GitHub-Api-Version: 2022-11-28"
    

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

既定では、ユーザー アクセス トークンは 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 のドキュメントの「メールアドレスを検証する」をご覧ください。