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

GitHub Enterprise Server's OAuth implementation supports the standard authorization code grant type and the OAuth 2.0 Device Authorization Grant for apps that don't have access to a web browser.

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

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

• Webアプリケーションフロー: ブラウザで実行される標準的なOAuthアプリケーションのためのユーザを認可するために使われます。 (The implicit grant type is not supported.)

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

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

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

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

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

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

パラメータ

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

レスポンス

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

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&scope=repo%2Cgist&token_type=bearer

You can also receive the response in different formats if you provide the format in the Accept header. For example, Accept: application/json or Accept: application/xml:

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

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

ユーザ／アプリケーション／スコープの組み合わせごとに、発行できるトークン数には10という上限があります。 If an application creates more than 10 tokens for the same user and the same scopes, the oldest tokens with the same user/application/scope combination will be revoked.

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

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

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

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

トラブルシューティング

• 「認可リクエストエラーのトラブルシューティング」
• 「OAuthアプリケーションのアクセストークンのリクエストエラー」

参考リンク

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