この API には認証のための方法が複数用意されていますが、運用アプリケーションには OAuth を使用することを強くお勧めします。 他の方式は、スクリプトまたはテスト (完全な OAuth では過剰になる� �合) に使うために提供されています。 認証に GitHub Enterprise Server を使うサードパーティのアプリケーションでは、GitHub Enterprise Server の認証情� �を要求することも収集することもしてはなりません。 代わりに、OAuth Web フローを使う必要があります。
基本認証
API では、RFC2617 で定義されている基本認証がサポートされていますが、わずかな相違点があります。
主な相違点は、RFC では、認証されていないリクエストに 401 Unauthorized
レスポンスで応える必要があるという点です。 これにより、多くの� �所でユーザー データの存在が明らかになります。 その代わりに、GitHub Enterprise Server API は、404 Not Found
で応答します。
これにより、401 Unauthorized
を応答を想定する HTTP ライブラリに問題が発生する可能性があります。 解決策は、Authorization
ヘッダーを手動で作成することです。
personal access tokenの使用
personal access tokenを使って GitHub API に対する認証を行うことをお勧めします。
$ curl -u USERNAME:TOKEN http(s)://HOSTNAME/api/v3/user
この方法は、ツールは基本認証のみをサポートしているが、personal access tokenのセキュリティ機能を利用したい� �合に役立ちます。
ユーザ名とパスワードを使用する
GitHub Enterprise Server API で基本認証を使うには、アカウントに関連付けられているユーザー名とパスワードを送信する� けです。
たとえば、cURL を介して API にアクセスする� �合、<username>
を実際の GitHub Enterprise Server ユーザー名に置き換えて次のコマンドを実行すると、認証が行われます。
(cURL からパスワードの入力を求められます。)
$ curl -u USERNAME http(s)://HOSTNAME/api/v3/user
ご自分が 2 要� 認証を有効にしている� �合は、2 要� 認証の使用方法を理解していることを確認してく� さい。
2 要� 認証を使用する
2 要� 認証を有効にしている� �合、REST API での "ほとんどの" エンドポイントに対する基本認証では、personal access tokenまたはユーザー名とパスワードではなく OAuth トークンを使う必要があります。
新しいpersonal access tokenを生成できます。または、OAuth Authorizations API の「[新しい承認を作成する][/rest/reference/oauth-authorizations#create-a-new-authorization]」エンドポイントで新しい OAuth トークンを生成できます。 詳しくは、コマンド ライン用のpersonal access tokenの作成に関する記事をご覧く� さい。 そうすれば、それらのトークンを使用して、OAuth トークンを使用した認証を GitHub Enterprise Server API で行うことができます。ユーザー名とパスワードで認証する必要があるのは、OAuth トークンを作成するときまたは OAuth 認証 API を使用するときのみです。
2 要� 認証で OAuth Authorizations API を使用する
OAuth Authorizations API を呼び出す� �合、Basic 認証では、トークンの代わりにワンタイ� パスワード(OTP)とユーザ名とパスワードを使用する必要があります。 OAuth Authorizations API で認証しようとすると、サーバーは 401 Unauthorized
とこれらのヘッダーの 1 つで応答し、2 要� 認証コードが必要であることを通知します。
X-GitHub-OTP: required; SMS
または X-GitHub-OTP: required; app
。
このヘッダは、アカウントの 2 要� 認証コードの受け取り方法を示します。 アカウントの設定方法に応じて、SMS 経由で OTP コードを受け取るか、Google 認証システ� や 1Password などのアプリケーションを使用します。 詳細については、「2 要� 認証の構成」を参照してく� さい。 ヘッダーで次のように OTP を渡します。
$ curl --request POST \
--url https://api.github.com/authorizations \
--header 'authorization: Basic PASSWORD' \
--header 'content-type: application/json' \
--header 'x-github-otp: OTP' \
--data '{"scopes": ["public_repo"], "note": "test"}'