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

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

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

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

• Webアプリケーションフロー: ブラウザで実行される標準的なOAuthアプリケーションのためのユーザを認可するために使われます。 （暗黙の許可タイプはサポートされません）
• でバイスフロー: CLIツールなど、ヘッドレスアプリケーションに使われます。

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

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

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

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

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

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

パラメータ

2. GitHubによるサイトへのユーザのリダイレクト

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

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

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

パラメータ

レスポンス

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

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をリクエストしなければなりません。 このリクエストには、アプリケーションがアクセストークンの受け取りとユーザの認可のステータスチェックに使わなければならないデバイス検証コードも返されます。

入力パラメータ

レスポンス

{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJHT",
  "verification_uri": "http(s)://[hostname]/login/device",
  "expires_in": 900,
  "interval": 5
}

レスポンスのパラメータ

ステップ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にリクエストを発行するために利用できるアクセストークンを受け取ります。

入力パラメータ

レスポンス

{
 "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秒を追加します。 詳しい情報についてはデバイスフローのエラーを参照してください。

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

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

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

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

リダイレクト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アプリケーションに許可する必要はありません。

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

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

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

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

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

トラブルシューティング

• 「認可リクエストエラーのトラブルシューティング」

• 「OAuthアプリケーションのアクセストークンのリクエストエラー」

• 「デバイスフローのエラー」

参考リンク

• "GitHub への認証について"