Skip to content

Ktor Client での Basic 認証 ​

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

コード例: client-auth-basic

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

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

依存関係の追加 ​

認証を有効にするには、ビルドスクリプトに ktor-client-auth アーティファクトを含めます。

kotlin
implementation(ktorLibs.client.auth)
上記コードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.client.auth
上記コードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-auth-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
Ktor クライアントに必要なアーティファクトの詳細については、クライアントの依存関係の追加既存のプロジェクトにクライアントの依存関係を追加する方法を学びます。 を参照してください。

Basic 認証のフロー ​

Basic 認証のフローは次のようになります。

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

  2. サーバーは 401 Unauthorized レスポンスステータスを返し、WWW-Authenticate レスポンスヘッダーを使用して Basic 認証が必要であることを示します。一般的な WWW-Authenticate ヘッダーは次のようになります。

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

    Ktor クライアントでは、sendWithoutRequest() 関数 を使用することで、WWW-Authenticate ヘッダーを待たずに事前に(preemptively)認証情報を送信できます。

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

    Authorization: Basic amV0YnJhaW5zOmZvb2Jhcg
  4. サーバーはクライアントから送信された認証情報を検証し、リクエストされたコンテンツを返します。

Basic 認証の設定 ​

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

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

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

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

    kotlin
    val client = HttpClient(CIO) {
        install(Auth) {
            basic {
                credentials {
                    BasicAuthCredentials(username = "jetbrains", password = "foobar")
                }
                realm = "Access to the '/' path"
            }
        }
    }
  4. (オプション)sendWithoutRequest 関数を使用してプリエンプティブ認証を有効にします。この関数はリクエストパラメータを確認し、最初のリクエストに認証情報を付加するかどうかを決定します。

    kotlin
    install(Auth) {
        basic {
            // ...
            sendWithoutRequest { request ->
                request.url.host == "0.0.0.0"
            }
        }
    }
  5. (オプション)認証情報のキャッシュを無効にします。デフォルトでは、credentials {} プロバイダーによって返された認証情報はリクエスト間で再利用できるようにキャッシュされます。cacheTokens オプションを使用してキャッシュを無効にできます。

    kotlin
    basic {
        cacheTokens = false   // リクエストごとに認証情報を再読み込みします
        // ...
    }

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

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

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