Ktor ServerにおけるBasic認証
必要な依存関係: io.ktor:ktor-server-auth
コード例: auth-basic, auth-basic-hash-table
NativeサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
Basic認証スキームは、アクセス制御と認証に使用されるHTTPフレームワークの一部です。このスキームでは、ユーザーの認証情報(クレデンシャル)はBase64でエンコードされたユーザー名/パスワードのペアとして送信されます。
Ktorを使用すると、Basic認証を利用してユーザーのログインや特定のルートの保護を行うことができます。Ktorにおける認証全般に関する情報は、Ktor Serverにおける認証と認可セクションを参照してください。
Basic認証ではユーザー名とパスワードが平文で送信されるため、機密情報を保護するにはHTTPS/TLSを使用する必要があります。
依存関係の追加
basic認証を有効にするには、ビルドスクリプトにktor-server-authアーティファクトを含める必要があります。
implementation(ktorLibs.server.auth)implementation ktorLibs.server.auth<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Basic認証のフロー
Basic認証のフローは以下のようになります。
クライアントがサーバーアプリケーションの特定のルートに対して、
Authorizationヘッダーなしでリクエストを送信します。サーバーはクライアントに対して
401(Unauthorized)レスポンスステータスで応答し、WWW-Authenticateレスポンスヘッダーを使用してルートの保護にBasic認証スキームが使用されていることを伝えます。典型的なWWW-Authenticateヘッダーは次のようになります。WWW-Authenticate: Basic realm="Access to the '/' path", charset="UTF-8"Ktorでは、
basic認証プロバイダーの設定時に関連するプロパティを使用してレルム(realm)と文字セット(charset)を指定できます。通常、クライアントはユーザーが認証情報を入力できるログインダイアログを表示します。その後、クライアントはBase64でエンコードされたユーザー名とパスワードのペアを含む
Authorizationヘッダーを付与してリクエストを送信します。例:Authorization: Basic amV0YnJhaW5zOmZvb2Jhcgサーバーはクライアントから送信された認証情報を検証し、リクエストされたコンテンツを応答します。
Basic認証のインストール
basic認証プロバイダーをインストールするには、installブロック内でbasic関数を呼び出します。
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
basic {
// Basic認証の設定
}
}オプションで、指定したルートを認証するために使用できるプロバイダー名を指定することもできます。
Basic認証の設定
Ktorでさまざまな認証プロバイダーを設定する一般的な方法については、認証の設定を参照してください。このセクションでは、basic認証プロバイダー固有の設定について見ていきます。
ステップ1: basicプロバイダーを設定する
basic認証プロバイダーは、BasicAuthenticationProvider.Configurationクラスを介して設定を公開します。以下の例では、次の設定が指定されています。
realmプロパティは、WWW-Authenticateヘッダーで渡されるレルムを設定します。validate関数は、ユーザー名とパスワードを検証します。
install(Authentication) {
basic("auth-basic") {
realm = "Access to the '/' path"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) {
UserIdPrincipal(credentials.name)
} else {
null
}
}
}
}validate関数はUserPasswordCredentialをチェックし、認証に成功した場合はUserIdPrincipalを返し、認証に失敗した場合はnullを返します。
また、ユーザー名とパスワードハッシュを保持するインメモリテーブルに格納されたユーザーを検証するために、UserHashedTableAuthを使用することもできます。
タイプセーフな認証スキームAPIは実験的(Experimental)です。いつでも廃止または変更される可能性があります。 使用にはオプトインが必要です。詳細については、 タイプセーフ認証のドキュメントを参照してください。
basic()関数は、任意のプリンシパル型に対するスキームを作成します。install(Authentication)ステップは不要です。スキームは、それを必要とするルートに渡す値となります。
data class User(val name: String)
val basicAuth = basic<User>("auth-basic") {
realm = "Access to the '/' path"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) User(credentials.name) else null
}
}validate関数はUserPasswordCredentialをチェックし、プリンシパル型を返します。認証に失敗した場合はnullを返します。完全なAPIについては、タイプセーフ認証を参照してください。
ステップ2: 特定のリソースを保護する
basicプロバイダーを設定した後、authenticate関数を使用してアプリケーション内の特定のリソースを保護できます。認証に成功した場合、ルートハンドラー内でcall.principal関数を使用して認証済みのUserIdPrincipalを取得し、認証されたユーザーの名前を取得できます。
routing {
authenticate("auth-basic") {
get("/") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}スキームをauthenticateWith()に渡します。ブロック内ではcall.principalが指定したプリンシパル型となり、決してnullにはならないため、キャストやnullチェックは不要です。
routing {
authenticateWith(basicAuth) {
get("/") {
call.respondText("Hello, ${call.principal.name}!")
}
}
}UserHashedTableAuthによる検証
Ktorでは、UserHashedTableAuthを使用して、ユーザー名とパスワードハッシュを保持するインメモリテーブルに保存されたユーザーを検証できます。これにより、データソースが漏洩した場合でもユーザーのパスワードが漏洩するのを防ぐことができます。
UserHashedTableAuthを使用してユーザーを検証するには、以下の手順に従います。
getDigestFunction関数を使用して、指定したアルゴリズムとソルトプロバイダーでダイジェスト関数を作成します。
kotlinval digestFunction = getDigestFunction("SHA-256") { "ktor${it.length}" }UserHashedTableAuthの新しいインスタンスを初期化し、次のプロパティを指定します。tableプロパティを使用して、ユーザー名とハッシュ化されたパスワードのテーブルを提供します。digesterプロパティにダイジェスト関数を割り当てます。
kotlinval hashedUserTable = UserHashedTableAuth( table = mapOf( "jetbrains" to digestFunction("foobar"), "admin" to digestFunction("password") ), digester = digestFunction )validate関数の内部でUserHashedTableAuth.authenticate関数を呼び出してユーザーを認証し、認証情報が有効な場合はUserIdPrincipalのインスタンスを返します。kotlininstall(Authentication) { basic("auth-basic-hashed") { realm = "Access to the '/' path" validate { credentials -> hashedUserTable.authenticate(credentials) } } }
