ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

OAuth アプリケーションの認可

他のユーザがOAuthアプリケーションを認可できるようにすることができます。

GitHub Enterprise Server のOAuthの実装は、標準の認可コード許可タイプおよびWebブラウザを利用できないアプリケーションのためのOAuth 2.0のDevice Authorization Grantをサポートしています。

アプリケーションをテストする場合のように、標準的な方法でのアプリケーションの認可をスキップしたい場合には非Webアプリケーションフローを利用できます。

OAuthアプリケーションを認可する場合は、そのアプリケーションにどの認可フローが最も適切かを考慮してください。

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

ノート: GitHub Appを構築しているなら、OAuth Webアプリケーションフローを使うこともできますが、セットアップには多少の重要な違いがあります。 詳しい情報については「GitHub Appのユーザの特定と認可」を参照してください。

アプリケーションのユーザの認可のためのWebアプリケーションフローは以下のとおりです。

  1. ユーザはGitHubのアイデンティティをリクエストするためにリダイレクトされます
  2. ユーザはGitHubによってサイトにリダイレクトして戻されます
  3. アプリケーションはユーザのアクセストークンと共にAPIにアクセスします

1. ユーザのGitHubアイデンティティのリクエスト

GET http(s)://[hostname]/login/oauth/authorize

GitHub Appがloginパラメータを指定すると、ユーザに対して利用できる特定のアカウントでサインインしてアプリケーションを認可するよう求めます。

パラメータ
名前種類説明
client_idstring必須。 ユーザが登録されたときに受け取るクライアントID。
redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。 リダイレクトURLに関する詳細については下を参照してください。
loginstringサインインとアプリケーションの認可に使われるアカウントを指示します。
スコープstringスペース区切りのスコープのリスト。 渡されなかった場合、ユーザのスコープのデフォルトは空のリストになり、アプリケーションにはどのスコープも認可されません。 アプリケーションに対して認可したスコープがあるユーザに対しては、スコープのリストを含むOAuthの認可ページは示されません。 その代わりに、フローのこのステップはユーザがアプリケーションに認可したスコープ群で自動的に完了します。 たとえば、ユーザがすでにWebフローを2回行っており、1つのトークンでuserスコープを、もう1つのトークンでrepoスコープを認可している場合、3番目のWebフローでscopeが渡されなければ、user及びrepoスコープを持つトークンが返されます。
statestring推測不能なランダムの文字列。 クロスサイトリクエストフォージェリ攻撃に対する保護として使われます。
allow_signupstringOAuthフローの間に、認証されていないユーザに対してGitHubへのサインアップの選択肢が提示されるかどうか。 デフォルトは true です。 ポリシーでサインアップが禁止されている場合はfalseを使ってください。

2. ユーザはGitHubによってサイトにリダイレクトして戻されます

ユーザがリクエストを受け付けると、GitHub Enterprise Serverは一時的なコードをcodeパラメータに、そして前のステップで渡された状態をstateパラメータに入れてリダイレクトさせ、サイトに戻します。 一時コードは10分後に期限切れになります。 状態が一致しない場合は、リクエストを作成したサードパーティとユーザはこのプロセスを中止しなければなりません。

このコードのアクセストークンとの交換

POST http(s)://[hostname]/login/oauth/access_token
パラメータ
名前種類説明
client_idstring必須。 OAuth Appに対してGitHub Enterprise Serverから受け取ったクライアントID。
client_secretstring必須。 OAuth Appに対してGitHub Enterprise Serverから受け取ったクライアントシークレット。
コードstring必須。 ステップ1でレスポンスとして受け取ったコード。
redirect_uristring認可の後にユーザが送られるアプリケーション中のURL。
レスポンス

デフォルトでは、レスポンスは以下の形式になります。

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer

Acceptヘッダに応じて、異なる形式でコンテンツを受け取ることもできます。

Accept: application/json
{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a", "scope":"repo,gist", "token_type":"bearer"}

Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</access_token>
</OAuth>

3. アクセストークンを使ったAPIへのアクセス

このアクセストークンを使えば、ユーザの代わりにAPIへのリクエストを発行できます。

Authorization: token OAUTH-TOKEN
GET http(s)://[hostname]/api/v3/user

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

curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/user

デバイスフロー

注釈: デバイスフローは現在パブリックベータであり、変更されることがあります。

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

デバイスフローの概要

  1. アプリケーションはデバイスとユーザの検証コードをリクエストし、ユーザがユーザ検証コードを入力する認可URLを取得します。
  2. アプリケーションはhttps://github.com/login/deviceでユーザ検証コードを入力するようユーザに求めます。
  3. アプリケーションはユーザ認証のステータスをポーリングします。 ユーザがデバイスを認可すると、アプリケーションは新しいアクセストークンと共にAPIコールを発行できるようになります。

ステップ1: アプリケーションによるGitHubからのデバイス及びユーザ検証コードの要求

POST http(s)://[hostname]/login/device/code

アプリケーションは、次のステップでユーザに認可を求めるために使うユーザ検証コードと検証URLをリクエストしなければなりません。 このリクエストには、アプリケーションがアクセストークンの受け取りとユーザの認可のステータスチェックに使わなければならないデバイス検証コードも返されます。

入力パラメータ
名前種類説明
client_idstring必須。 GitHub Enterprise Serverから受け取るアプリケーションのためのクライアントID。
スコープstringアプリケーションがアクセスをリクエストしているスコープ。
レスポンス
{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJHT",
  "verification_uri": "http(s)://[hostname]/login/device",
  "expires_in": 900,
  "interval": 5
}
レスポンスのパラメータ
名前種類説明
device_codestringデバイス検証コードは40文字で、デバイスの検証に使われます。
user_codestringユーザ検証コードは、ユーザがブラウザに入力できるようにデバイスに表示されます。 このコードは8文字で、途中にハイフンがあります。
verification_uristringユーザがuser_codeを入力しなければならない検証URL: https://github.com/login/device
expires_inintegerdevice_code及びuser_codeが期限切れになるまでの秒数。 デフォルトは900秒、すなわち15分です。
intervalintegerデバイスの認可を完了するための新しいアクセストークンのリクエスト(POST http(s)://[hostname]/login/oauth/access_token)を発行できるようになるまでに経過しなければならない最小の秒数。 たとえばintervalが5であれば、5秒が経過するまでは新しいリクエストを発行できません。 5秒間に複数のリクエストを発行すると、レート制限に達してslow_downエラーが返されます。

ステップ2: ブラウザでユーザコードの入力をユーザに促す

デバイスはユーザ検証コードを表示し、ユーザに対してこのコードをhttps://github.com/login/deviceで入力するように求めます。

デバイスに表示されたユーザ検証コードの入力フィールド

ステップ3: ユーザがデバイスを認証したか、アプリケーションがGitHubをポーリング

POST http(s)://[hostname]/login/oauth/access_token

アプリケーションは、デバイス及びユーザコードが期限切れになるか、有効なユーザコードでアプリケーションが認可されるまで、POST http(s)://[hostname]/login/oauth/access_tokenをポーリングするデバイス認可リクエストを発行します。 アプリケーションは、レート制限エラーを避けるために、ステップ1で取得したポーリングの最小intervalを使います。 詳しい情報については「デバイスフローのためのレート制限」を参照してください。

ユーザは、15分(あるいは900秒)以内に有効なコードを入力しなければなりません。 15分が経過すると、新たなデバイス認可コードをPOST http(s)://[hostname]/login/device/codeでリクエストしなければなりません。

ユーザが認可されると、アプリケーションはユーザの代わりにAPIにリクエストを発行するために利用できるアクセストークンを受け取ります。

入力パラメータ
名前種類説明
client_idstring必須。 OAuth Appに対してGitHub Enterprise Serverから受け取ったクライアントID。
device_codestring必須。 POST http(s)://[hostname]/login/device/codeリクエストから受け取ったデバイス検証コード。
grant_typestring必須。 許可タイプはurn:ietf:params:oauth:grant-type:device_codeでなければなりません。
レスポンス
{
 "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
  "token_type": "bearer",
  "scope": "user"
}

デバイスフローのレート制限

ユーザがブラウザ上で検証コードをサブミットする場合、アプリケーションごとに1時間に50回のサブミットというレート制限があります。

リクエスト間で要求される最小の時間間隔(あるいはinterval)内で複数のアクセストークンリクエスト(POST http(s)://[hostname]/login/oauth/access_token)を発行すると、レート制限に達し、slow_downのエラーレスポンスが返されます。 slow_downエラーレスポンスは、最後のintervalに5秒を追加します。 詳しい情報についてはデバイスフローのエラーを参照してください。

デバイスフローのエラーコード

エラーコード説明
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エラーレスポンスが返されたなら、OAuthアクセストークンを求める新しいリクエストを発行するまでに最短でも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を渡さなければなりません。これは、アプリケーションの設定ページにあります。 デバイスフローではclient_secretは必要ありません。
incorrect_device_code渡されたdevice_codeが有効ではありません。
access_denied認可プロセスの間でユーザがキャンセルをクリックした場合、access_deniedエラーが返され、ユーザは検証コードを再度利用することができなくなります。

詳しい情報については、「OAuth 2.0デバイス認可の許可」を参照してください。

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

テストのような限定的な状況では、非Web認証が利用できます。 必要な場合は、個人アクセストークン設定ページを使い、Basic認証を利用して個人アクセストークンを作成できます。 この手法を使えば、ユーザはいつでもアクセスを取り消せます。

ノート: 非Webアプリケーションフローを使ってOAuth2トークンを作成する場合で、ユーザが2要素認証を有効化しているなら2要素認証の利用方法を必ず理解しておいてください。

リダイレクトURL

redirect_uriパラメータはオプションです。 指定しなかった場合、GitHubはOAuthアプリケーションで設定されているコールバックURLにユーザをリダイレクトさせます。 指定する場合、リダイレクトURLのホストとポートはコールバックURLと完全に一致していなければなりません。 リダイレクトURLのパスは、コールバックURLのサブディレクトリを参照していなければなりません。

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

ローカルホストのリダイレクトURL

オプションのredirect_uriパラメータは、ローカルホストURLにも使用できます。 アプリケーションがローカルホストのURLとポートを指定した場合、アプリケーションを認可した後ユーザは渡されたURLとポートにリダイレクトされます。 redirect_uriは、アプリケーションのコールバックURLで指定されたポートにマッチしている必要はありません。

http://localhost/pathというコールバックURLに対して、以下のredirect_uriが利用できます。

http://localhost:1234/path

OAuthアプリケーションに複数のトークンを作成する

ユーザ/アプリケーション/スコープの組み合わせに対して複数のトークンを作成し、特定のユースケースに対応できます。

OAuthアプリケーションが、サインインにGitHubを利用し、基本的なユーザ情報しか必要としないワークフローを1つサポートするだけであれば、これは有益です。 別のワークフローはユーザのプライベートリポジトリへのアクセスを必要としていてもかまいません。 複数のトークンを使えば、OAuthアプリケーションはそれぞれのユースケースに対してWebフローを実行でき、必要なスコープだけをリクエストします。 ユーザがサインインにアプリケーションだけを使うなら、ユーザは自分のプライベートリポジトリへのアクセスをOAuthアプリケーションに許可する必要はありません。

ユーザ/アプリケーション/スコープの組み合わせごとに、発行できるトークン数には10という上限があります。 アプリケーションが制限のいずれかを超えるトークンをリクエストした場合、リクエストされたのと同じスコープを持つ古いトークンは働かなくなります。

警告: OAuth Appからすべての権限を取り消すと、デプロイキーを含めてユーザの代わりにアプリケーションが生成したすべてのSSHキーは削除されます。

ユーザにアクセスをレビューしてもらう

OAuthアプリケーションへの認可情報へリンクし、ユーザがアプリケーションの認可をレビューし、取り消しできるようにすることができます。

このリンクを構築するには、アプリケーションを登録したときにGitHubから受け取ったOAuthアプリケーションのclient_idが必要です。

http(s)://[hostname]/settings/connections/applications/:client_id

Tip: OAuthアプリケーションがユーザのためにアクセスできるリソースについてさらに学ぶには、「ユーザのためにリソースを見つける」を参照してください。

トラブルシューティング

参考リンク

このドキュメントは役立ちましたか? プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?

GitHubコミュニティで質問する サポートへの連絡