Ktor Client における認証と認可
必要な依存関係: io.ktor:ktor-client-auth
Ktor は、クライアントアプリケーションで認証と認可を処理するための Auth プラグインを提供しています。一般的な使用シナリオには、ユーザーのログインや特定のリソースへのアクセス取得などがあります。
サーバー側では、Ktor は認証と認可を処理するための Authentication プラグインを提供しています。
サポートされている認証タイプ
HTTP はアクセス制御と認証のための一般的なフレームワークを提供しています。Ktor クライアントでは、以下の HTTP 認証スキームを使用できます:
- Basic -
Base64エンコーディングを使用してユーザー名とパスワードを提供します。HTTPS と組み合わせて使用しない限り、通常は推奨されません。 - Digest - ユーザー名とパスワードにハッシュ関数を適用することにより、暗号化された形式でユーザー認証情報を通信する認証方式です。
- Bearer - ベアラートークン(Bearer token)と呼ばれるセキュリティトークンを使用する認証スキームです。例えば、OAuth フローの一部としてこのスキームを使用し、Google、Facebook、X などの外部プロバイダーを利用してアプリケーションのユーザーを認可することができます。
依存関係の追加
認証を有効にするには、ビルドスクリプトに ktor-client-auth アーティファクトを含めます:
implementation(ktorLibs.client.auth)implementation ktorLibs.client.auth<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Auth のインストール
Auth プラグインをインストールするには、クライアント設定ブロック内の install() 関数に渡します:
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.auth.*
//...
val client = HttpClient(CIO) {
install(Auth) {
// 認証を設定
}
}認証の設定
認証プロバイダーの選択
特定の認証プロバイダー(basic、digest、または bearer)を使用するには、install {} ブロック内で対応する関数を呼び出します。
例えば、Basic 認証を設定するには、basic {} 関数を使用します:
install(Auth) {
basic {
// Basic 認証を設定
}
}ブロック内では、このプロバイダーに固有の設定を構成できます。
レルムの設定
必要に応じて、realm プロパティを使用してレルムを設定できます:
install(Auth) {
basic {
realm = "Access to the '/' path"
// ...
}
}異なるリソースにアクセスするために、異なるレルムを持つ複数のプロバイダーを作成できます:
install(Auth) {
basic {
realm = "Access to the '/' path"
// ...
}
basic {
realm = "Access to the '/admin' path"
// ...
}
}この場合、クライアントはレルムを含む WWW-Authenticate レスポンスヘッダーに基づいて必要なプロバイダーを選択します。
プロバイダーの選択
サーバーが 401 Unauthorized を返すと、クライアントは WWW-Authenticate レスポンスヘッダーに基づいて認証プロバイダーを選択します。このヘッダーは、サーバーが受け入れる認証スキームを指定します。
クライアントにインストールされている認証プロバイダーが1つだけの場合、Auth プラグインは、サーバーが 401 Unauthorized を返したときに、WWW-Authenticate ヘッダーが存在しないか異なるスキームを指定している場合でも、常にそのプロバイダーを試行します。
クライアントに複数の認証プロバイダーがインストールされている場合、クライアントは WWW-Authenticate ヘッダーに基づいてプロバイダーを選択します。
トークンのキャッシュとキャッシュ制御
Basic および Bearer 認証プロバイダーは、内部の認証情報またはトークンのキャッシュを保持します。このキャッシュにより、クライアントはリクエストごとに認証データを再ロードする代わりに、以前ロードした認証データを再利用できるため、パフォーマンスが向上し、認証情報が変更された場合の完全な制御も維持されます。
認証プロバイダーへのアクセス
クライアントセッション中に認証状態を動的に更新する必要がある場合は、authProvider 拡張機能を使用して特定のプロバイダーにアクセスできます:
val provider = client.authProvider<BearerAuthProvider>()インストールされているすべてのプロバイダーを取得するには、authProviders プロパティを使用します:
val providers = client.authProvidersこれらのユーティリティを使用すると、プロバイダーをインスペクトしたり、キャッシュされたトークンをプログラムでクリアしたりできます。
キャッシュされたトークンのクリア
単一プロバイダーのキャッシュされた認証情報をクリアするには、.clearToken() 関数を使用します:
val provider = client.authProvider<BasicAuthProvider>()
provider?.clearToken()キャッシュのクリアをサポートしているすべての認証プロバイダーにわたってキャッシュされたトークンをクリアするには、.clearAuthTokens() 関数を使用します:
client.clearAuthTokens()キャッシュされたトークンのクリアは、通常、次のようなシナリオで使用されます:
- ユーザーがログアウトしたとき。
- アプリケーションによって保存されている認証情報またはトークンが変更されたとき。
- 次回のリクエストでプロバイダーに認証状態を強制的に再ロードさせる必要があるとき。
以下は、ユーザーがログアウトしたときにキャッシュされたトークンをクリアする例です:
fun logout() {
client.clearAuthTokens()
storage.deleteCredentials()
}キャッシュ動作の制御
Basic 認証プロバイダーと Bearer 認証プロバイダーは両方とも、cacheTokens オプションを使用して、リクエスト間でトークンまたは認証情報をキャッシュするかどうかを制御できます。
例えば、認証情報が動的に提供される場合にキャッシュを無効化できます:
basic {
cacheTokens = false // リクエストごとに認証情報を再ロードする
credentials {
loadCurrentCredentials()
}
}トークンのキャッシュを無効にすることは、認証データが頻繁に変更される場合や、最新の状態を反映する必要がある場合に特に役立ちます。
