Ktor Server でのフォームベース認証
必要な依存関係: io.ktor:ktor-server-auth
コード例: auth-form-html-dsl, auth-form-session
Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
フォームベース認証は、Web フォーム を使用して認証情報を収集し、ユーザーを認証します。 Ktor で Web フォームを作成するには、HTML DSL を使用するか、FreeMarker や Velocity などの JVM テンプレートエンジン から選択できます。
フォームベース認証を使用する場合、ユーザー名とパスワードは平文で送信されるため、機密情報を保護するには HTTPS/TLS を使用する必要があります。
依存関係の追加
form 認証を有効にするには、ビルドスクリプトに 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>フォームベース認証のフロー
フォームベース認証のフローは次のようになります:
未認証のクライアントが、サーバーアプリケーション内の特定の ルート にリクエストを送信します。
サーバーは、少なくともユーザーにユーザー名とパスワードを要求する HTML ベースの Web フォームを含む HTML ページを返します。
Ktor では、Kotlin DSL を使用してフォームを構築することも、FreeMarker や Velocity などのさまざまな JVM テンプレートエンジンから選択することもできます。
ユーザーがユーザー名とパスワードを送信すると、クライアントは Web フォームのデータ(ユーザー名とパスワードを含む)を含むリクエストをサーバーに送信します。
kotlinPOST http://localhost:8080/login Content-Type: application/x-www-form-urlencoded username=jetbrains&password=foobarKtor では、ユーザー名とパスワードの取得に使用される パラメータ名を指定 する必要があります。
サーバーはクライアントから送信された認証情報を 検証 し、要求されたコンテンツで応答します。
form 認証のインストール
form 認証プロバイダーをインストールするには、install ブロック内で form 関数を呼び出します:
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
form {
// フォーム認証の設定
}
}オプションで、指定したルートの認証 に使用できる プロバイダー名 を指定することもできます。
form 認証の設定
ステップ 1: フォームプロバイダーの設定
form 認証プロバイダーは、FormAuthenticationProvider.Config クラスを通じてその設定を公開します。以下の例では、次の設定が指定されています:
userParamNameおよびpasswordParamNameプロパティは、ユーザー名とパスワードを取得するために使用されるパラメータ名を指定します。validate関数はユーザー名とパスワードを検証します。validate関数はUserPasswordCredentialをチェックし、認証に成功した場合はUserIdPrincipalを、認証に失敗した場合はnullを返します。challenge関数は、認証に失敗した場合に実行されるアクションを指定します。たとえば、ログインページにリダイレクトしたり、UnauthorizedResponse を送信したりできます。
install(Authentication) {
form("auth-form") {
userParamName = "username"
passwordParamName = "password"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) {
UserIdPrincipal(credentials.name)
} else {
null
}
}
challenge {
val message = "Credentials are not valid"
val status = HttpStatusCode.Unauthorized
call.respond(status, message)
}
}
}タイプセーフな認証スキーム API は実験的なものです。いつでも削除または変更される可能性があります。 オプトインが必要です。詳細については、 タイプセーフ認証のドキュメント を参照してください。
form() 関数は、選択したプリンシパル型用のスキームを作成します。install(Authentication) のステップはありません。スキームは、それを必要とするルートに渡す値です。
data class User(val name: String)
val formAuth = form<User>("auth-form") {
usernameField = "username"
passwordField = "password"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) User(credentials.name) else null
}
onUnauthorized = {
val message = "Credentials are not valid"
call.respond(HttpStatusCode.Unauthorized, message)
}
}クラシックなプロバイダーとは2つの名称が異なります。フォームフィールドは userParamName や passwordParamName ではなく、usernameField と passwordField になります。失敗ハンドラーは challenge ではなく onUnauthorized です。完全な API については、タイプセーフ認証 を参照してください。
basic 認証と同様に、ユーザー名とパスワードハッシュを保持するインメモリテーブルに保存されたユーザーを検証するために、UserHashedTableAuth を使用することもできます。
ステップ 2: 特定のリソースの保護
form プロバイダーを設定した後、データが送信される post ルートを定義する必要があります。 次に、このルートを authenticate 関数の内部に追加します。 認証に成功した場合、ルートハンドラー内で call.principal 関数を使用して認証済みの UserIdPrincipal を取得し、認証されたユーザーの名前を取得できます。
routing {
authenticate("auth-form") {
post("/login") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}フォームデータが送信される post ルートを定義し、それを authenticateWith() でラップします。ブロック内では、call.principal は独自のプリンシパル型になり、null になることはありません:
routing {
authenticateWith(formAuth) {
post("/login") {
call.respondText("Hello, ${call.principal.name}!")
}
}
}ログインしたユーザーの ID を保存するために、セッション認証 を使用できます。 たとえば、ユーザーが初めて Web フォームを使用してログインしたときに、ユーザー名を Cookie セッションに保存し、以降のリクエストでは session プロバイダーを使用してこのユーザーを認可できます。
