GitHub Enterprise Server のOAuthの実装は、標準の認可コード許可タイプおよびWebブラウザを利用できないアプリケーションのためのOAuth 2.0のDevice Authorization Grantをサポートしています。
アプリケーションをテストする場合のように、標準的な方法でのアプリケーションの認可をスキップしたい場合には非Webアプリケーションフローを利用できます。
OAuthアプリケーションを認可する場合は、そのアプリケーションにどの認可フローが最も適切かを考慮してください。
- Webアプリケーションフロー: ブラウザで実行される標準的なOAuthアプリケーションのためのユーザを認可するために使われます。 (暗黙の許可タイプはサポートされません)
- でバイスフロー: CLIツールなど、ヘッドレスアプリケーションに使われます。
Web アプリケーションフロー
ノート: GitHub Appを構築しているなら、OAuth Webアプリケーションフローを使うこともできますが、セットアップには多少の重要な違いがあります。 詳しい情報については「GitHub Appのユーザの特定と認可」を参照してください。
アプリケーションのユーザの認可のためのWebアプリケーションフローは以下のとおりです。
- ユーザはGitHubのアイデンティティをリクエストするためにリダイレクトされます
- ユーザはGitHubによってサイトにリダイレクトして戻されます
- アプリケーションはユーザのアクセストークンと共にAPIにアクセスします
1. ユーザのGitHubアイデンティティのリクエスト
GET http(s)://[hostname]/login/oauth/authorize
GitHub Appがlogin
パラメータを指定すると、ユーザに対して利用できる特定のアカウントでサインインしてアプリケーションを認可するよう求めます。
パラメータ
名前 | 種類 | 説明 |
---|---|---|
client_id | string | 必須。 ユーザが登録されたときに受け取るクライアントID。 |
redirect_uri | string | 認可の後にユーザが送られるアプリケーション中のURL。 リダイレクトURLに関する詳細については下を参照してください。 |
login | string | サインインとアプリケーションの認可に使われるアカウントを指示します。 |
scope | string | スペース区切りのスコープのリスト。 渡されなかった場合、ユーザのスコープ のデフォルトは空のリストになり、アプリケーションにはどのスコープも認可されません。 アプリケーションに対して認可したスコープがあるユーザに対しては、スコープのリストを含むOAuthの認可ページは示されません。 その代わりに、フローのこのステップはユーザがアプリケーションに認可したスコープ群で自動的に完了します。 たとえば、ユーザがすでにWebフローを2回行っており、1つのトークンでuser スコープを、もう1つのトークンでrepo スコープを認可している場合、3番目のWebフローでscope が渡されなければ、user 及びrepo スコープを持つトークンが返されます。 |
state | string | An unguessable random string. It is used to protect against cross-site request forgery attacks. |
allow_signup | string | OAuthフローの間に、認証されていないユーザに対してGitHubへのサインアップの選択肢が提示されるかどうか。 デフォルトは true です。 ポリシーでサインアップが禁止されている場合はfalse を使ってください。 |
2. GitHubによるサイトへのユーザのリダイレクト
ユーザがリクエストを受け付けると、GitHub Enterprise Serverは一時的なコード
をcodeパラメータに、そして前のステップで渡された状態をstate
パラメータに入れてリダイレクトさせ、サイトに戻します。 一時コードは10分後に期限切れになります。 状態が一致しない場合は、リクエストを作成したサードパーティとユーザはこのプロセスを中止しなければなりません。
このコード
のアクセストークンとの交換
POST http(s)://[hostname]/login/oauth/access_token
パラメータ
名前 | 種類 | 説明 |
---|---|---|
client_id | string | 必須。 OAuth Appに対してGitHub Enterprise Serverから受け取ったクライアントID。 |
client_secret | string | 必須。 OAuth Appに対してGitHub Enterprise Serverから受け取ったクライアントシークレット。 |
code | string | 必須。 ステップ1でレスポンスとして受け取ったコード。 |
redirect_uri | string | 認可の後にユーザが送られるアプリケーション中のURL。 |
state | string | ステップ1で提供した推測できないランダムな文字列。 |
レスポンス
デフォルトでは、レスポンスは以下の形式になります。
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認証情報マネージャーなどのヘッドレスアプリケーションのユーザを認可できます。
デバイスフローの概要
- アプリケーションはデバイスとユーザの検証コードをリクエストし、ユーザがユーザ検証コードを入力する認可URLを取得します。
- アプリケーションは
https://github.com/login/device
でユーザ検証コードを入力するようユーザに求めます。 - アプリケーションはユーザ認証のステータスをポーリングします。 ユーザがデバイスを認可すると、アプリケーションは新しいアクセストークンと共にAPIコールを発行できるようになります。
ステップ1: アプリケーションによるGitHubからのデバイス及びユーザ検証コードの要求
POST http(s)://[hostname]/login/device/code
アプリケーションは、次のステップでユーザに認可を求めるために使うユーザ検証コードと検証URLをリクエストしなければなりません。 このリクエストには、アプリケーションがアクセストークンの受け取りとユーザの認可のステータスチェックに使わなければならないデバイス検証コードも返されます。
入力パラメータ
名前 | 種類 | 説明 |
---|---|---|
client_id | string | 必須。 GitHub Enterprise Serverから受け取るアプリケーションのためのクライアントID。 |
scope | string | アプリケーションがアクセスをリクエストしているスコープ。 |
レスポンス
{
"device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
"user_code": "WDJB-MJHT",
"verification_uri": "http(s)://[hostname]/login/device",
"expires_in": 900,
"interval": 5
}
レスポンスのパラメータ
名前 | 種類 | 説明 |
---|---|---|
device_code | string | デバイス検証コードは40文字で、デバイスの検証に使われます。 |
user_code | string | ユーザ検証コードは、ユーザがブラウザに入力できるようにデバイスに表示されます。 このコードは8文字で、途中にハイフンがあります。 |
verification_uri | string | ユーザがuser_code を入力しなければならない検証URL: https://github.com/login/device 。 |
expires_in | integer | device_code 及びuser_code が期限切れになるまでの秒数。 デフォルトは900秒、すなわち15分です。 |
interval | integer | デバイスの認可を完了するための新しいアクセストークンのリクエスト(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_id | string | 必須。 OAuth Appに対してGitHub Enterprise Serverから受け取ったクライアントID。 |
device_code | string | 必須。 POST http(s)://[hostname]/login/device/code リクエストから受け取ったデバイス検証コード。 |
grant_type | string | 必須。 許可タイプはurn:ietf:params:oauth:grant-type:device_code でなければなりません。 |
レスポンス
{
"access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
"token_type": "bearer",
"scope": "user"
}
デバイスフローのレート制限
When a user submits the verification code on the browser, there is a rate limit of 50 submissions in an hour per application.
リクエスト間で要求される最小の時間間隔(あるいは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_down | slow_down エラーが返された場合、最小のinterval 、あるいはPOST http(s)://[hostname]/login/oauth/access_token を利用するリクエストの間に必要な時間間隔に5秒が追加されます。 たとえば、開始時のインターバルとしてリクエスト間に最小で5秒の間隔が必要だった場合に、slow_down エラーレスポンスが返されたなら、OAuthアクセストークンを求める新しいリクエストを発行するまでに最短でも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を渡さなければなりません。これは、アプリケーションの設定ページにあります。 デバイスフローでは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アプリケーションに許可する必要はありません。
ユーザ/アプリケーション/スコープの組み合わせごとに、発行できるトークン数には制限があります。 アプリケーションが制限のいずれかを超えるトークンをリクエストした場合、リクエストされたのと同じスコープを持つ古いトークンは働かなくなります。
Warning: Revoking all permission from an OAuth App deletes any SSH keys the application generated on behalf of the user, including deploy keys.
ユーザにアクセスをレビューしてもらう
OAuthアプリケーションへの認可情報へリンクし、ユーザがアプリケーションの認可をレビューし、取り消しできるようにすることができます。
このリンクを構築するには、アプリケーションを登録したときにGitHubから受け取ったOAuthアプリケーションのclient_id
が必要です。
http(s)://[hostname]/settings/connections/applications/:client_id
Tip: OAuthアプリケーションがユーザのためにアクセスできるリソースについてさらに学ぶには、「ユーザのためにリソースを見つける」を参照してください。