GitHub Enterprise Server のOAuthの実装は、標準の認可コード許可タイプをサポートしています。
アプリケーションをテストする場合のように、標準的な方法でのアプリケーションの認可をスキップしたい場合には非Webアプリケーションフローを利用できます。
ブラウザ上で実行される標準的なアプリケーションでは、認可コードを取得してトークンと交換するためにWebアプリケーションフローを利用してください。 （暗黙の許可タイプはサポートされません）
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非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アプリケーションがユーザのためにアクセスできるリソースについてさらに学ぶには、「ユーザのためにリソースを見つける」を参照してください。