Ktor Client における認証と認可
必要な依存関係: io.ktor:ktor-client-auth
Ktor は、クライアントアプリケーションで認証と認可を処理するための Auth プラグインを提供しています。 典型的な使用シナリオには、ユーザーのログインや特定のリソースへのアクセス権の取得が含まれます。
サーバー側では、Ktor は認証と認可を処理するための
Authenticationプラグインを提供しています。
サポートされている認証タイプ
HTTP は、アクセス制御と認証のための一般的なフレームワークを提供しています。Ktor クライアントでは、以下の HTTP 認証スキームを使用できます。
- Basic -
Base64エンコーディングを使用してユーザー名とパスワードを提供します。通常、HTTPS と組み合わせて使用しない場合は推奨されません。 - Digest - ユーザー名とパスワードにハッシュ関数を適用し、暗号化された形式でユーザーのクレデンシャル（認証情報）を転送する認証方法です。
- Bearer - ベアラートークンと呼ばれるセキュリティトークンを使用する認証スキームです。たとえば、Google、Facebook、X などの外部プロバイダーを使用してアプリケーションのユーザーを認可するための OAuth フローの一部として、このスキームを使用できます。
依存関係の追加
認証を有効にするには、ビルドスクリプトに ktor-client-auth アーティファクトを含める必要があります。
TIP
Ktor クライアントに必要なアーティファクトの詳細については、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）を設定する
必要に応じて、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 つしかインストールされていない場合、WWW-Authenticate ヘッダーが欠落しているか別のスキームを指定していても、サーバーが 401 Unauthorized を返すと Auth プラグインは常にそのプロバイダーを試行します。
クライアントに複数の認証プロバイダーがインストールされている場合、クライアントは 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()
}
}トークンキャッシュの無効化は、認証データが頻繁に変更される場合や、最新の状態を反映させる必要がある場合に特に便利です。