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

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

メモ

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

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

ユーザーアクセストークンは、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] ボタンを作成する」を参照してください。

この 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 の [Settings] ページに移動する方法の詳細については、「GitHub App 登録の変更」を参照してください。
`redirect_uri`	`string`	強く推奨	認可の後にユーザが送られるアプリケーション中のURL。これは、アプリの設定で "コールバック URL" として指定した URL のどれかと完全に一致している必要があり、追加のパラメーターを含めることはできません。
`state`	`string`	強く推奨	指定する場合、値には偽造攻撃から保護するランダムな文字列が含まれている必要があります。また、他の任意のデータを含めることもできます。

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

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

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

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

repository_id | string | ユーザーアクセストークンでアクセスできる 1 つのリポジトリの ID。 GitHub App またはユーザーがリポジトリにアクセスできない場合、これは無視されます。ユーザーアクセストークンのアクセスをさらに制限するには、このパラメーターを使います。

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` になります。

前のステップのユーザーアクセストークンを使って、ユーザーの代わりに 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 デバイス認可付与を使用します。

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

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 秒です。

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

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

デバイスおよびユーザーコードが期限切れになるか、ユーザーが 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 登録の変更」を参照してください。

ユーザーが 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` になります。

前のステップのユーザーアクセストークンを使って、ユーザーの代わりに 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 内の他のユーザーのユーザーアクセストークンを生成する必要があります。

ユーザーがアプリをインストールすると、GitHub でユーザーは http(s)://HOSTNAME/login/oauth/authorize?client_id=CLIENT_ID にリダイレクトされます。ここで、CLIENT_ID はアプリのクライアント ID です。
ユーザーが認可要求を受け入れた場合、ユーザーは GitHub でアプリ設定の最初のコールバック URL にリダイレクトされ、code クエリパラメーターが提供されます。

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

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

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` になります。

前のステップのユーザーアクセストークンを使って、ユーザーの代わりに 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"
```

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

この記事の内容

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

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

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

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

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

トラブルシューティング

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

リダイレクトURIの不一致

不正な検証コード

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

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

未確認のユーザーメール

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

この記事の内容

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