Ktor Clientにおけるベーシック認証

必要となる依存関係: io.ktor:ktor-client-auth

コード例: client-auth-basic

ベーシック認証スキームは、ユーザーのログインに使用できます。このスキームでは、ユーザーの認証情報は、Base64を使用してエンコードされたユーザー名とパスワードのペアとして送信されます。

サーバー側では、Ktorはベーシック認証を処理するためのAuthenticationプラグインを提供しています。

ベーシック認証のフロー

ベーシック認証のフローは以下の通りです：

1. クライアントは、Authorizationヘッダーなしでサーバーアプリケーションの保護されたリソースにリクエストを送信します。

2. サーバーは401 Unauthorizedレスポンスステータスで応答し、WWW-Authenticateレスポンスヘッダーを使用して、ベーシック認証が必要であることを示します。典型的なWWW-Authenticateヘッダーは以下のようになります：

   WWW-Authenticate: Basic realm="Access to the '/' path", charset="UTF-8"

   Ktorクライアントでは、sendWithoutRequest()関数を使用することで、WWW-Authenticateヘッダーを待たずに、あらかじめ（先制的に）認証情報を送信することができます。

3. 通常、クライアントはユーザーに認証情報の入力を求めます。その後、Base64でエンコードされたユーザー名とパスワードのペアを含むAuthorizationヘッダーを付けてリクエストを送信します。例：

   Authorization: Basic amV0YnJhaW5zOmZvb2Jhcg

4. サーバーはクライアントから送信された認証情報を検証し、要求されたコンテンツを返します。

ベーシック認証の設定

Basicスキームを使用してAuthorizationヘッダーでユーザーの認証情報を送信するには、basic認証プロバイダーを設定する必要があります：

1. install(Auth)ブロック内でbasic関数を呼び出します。

2. BasicAuthCredentialsを使用して必要な認証情報を指定し、このオブジェクトをcredentials関数に渡します。

3. realmプロパティを使用してレルムを設定します。

   val client = HttpClient(CIO) {
       install(Auth) {
           basic {
               credentials {
                   BasicAuthCredentials(username = "jetbrains", password = "foobar")
               }
               realm = "Access to the '/' path"
           }
       }
   }

4. （オプション）sendWithoutRequest関数を使用して、リクエストパラメータをチェックし、最初のリクエストに認証情報を付加するかどうかを決定する先制的（preemptive）認証を有効にします。

   install(Auth) {
       basic {
           // ...
           sendWithoutRequest { request ->
               request.url.host == "0.0.0.0"
           }
       }
   }

5. （オプション）認証情報のキャッシュを無効にします。デフォルトでは、credentials {}プロバイダーによって返された認証情報は、リクエスト間で再利用するためにキャッシュされます。cacheTokensオプションでキャッシュを無効にできます。

   basic {
       cacheTokens = false   // すべてのリクエストで認証情報をリロードする
       // ...
   }

   キャッシュの無効化は、クライアントセッション中に認証情報が変更される可能性がある場合や、最新の保存状態を反映する必要がある場合に役立ちます。

   プログラムでキャッシュされた認証情報をクリアする方法の詳細については、一般的なトークンのキャッシュとキャッシュ制御セクションを参照してください。

Ktor Clientにおけるベーシック認証の完全な例については、client-auth-basicを参照してください。