Skip to content

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 アーティファクトを含める必要があります:

kotlin
implementation(ktorLibs.server.auth)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.server.auth
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

フォームベース認証のフロー ​

フォームベース認証のフローは次のようになります:

  1. 未認証のクライアントが、サーバーアプリケーション内の特定の ルート にリクエストを送信します。

  2. サーバーは、少なくともユーザーにユーザー名とパスワードを要求する HTML ベースの Web フォームを含む HTML ページを返します。

    Ktor では、Kotlin DSL を使用してフォームを構築することも、FreeMarker や Velocity などのさまざまな JVM テンプレートエンジンから選択することもできます。

  3. ユーザーがユーザー名とパスワードを送信すると、クライアントは Web フォームのデータ(ユーザー名とパスワードを含む)を含むリクエストをサーバーに送信します。

    kotlin
    POST http://localhost:8080/login
    Content-Type: application/x-www-form-urlencoded
    
    username=jetbrains&password=foobar

    Ktor では、ユーザー名とパスワードの取得に使用される パラメータ名を指定 する必要があります。

  4. サーバーはクライアントから送信された認証情報を 検証 し、要求されたコンテンツで応答します。

form 認証のインストール ​

form 認証プロバイダーをインストールするには、install ブロック内で form 関数を呼び出します:

kotlin
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 を送信したりできます。
kotlin
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) のステップはありません。スキームは、それを必要とするルートに渡す値です。

kotlin
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 を取得し、認証されたユーザーの名前を取得できます。

kotlin
routing {
    authenticate("auth-form") {
        post("/login") {
            val user = call.principal<UserIdPrincipal>()
            call.respondText("Hello, ${user?.name}!")
        }
    }
}

フォームデータが送信される post ルートを定義し、それを authenticateWith() でラップします。ブロック内では、call.principal は独自のプリンシパル型になり、null になることはありません:

kotlin
routing {
    authenticateWith(formAuth) {
        post("/login") {
            call.respondText("Hello, ${call.principal.name}!")
        }
    }
}

ログインしたユーザーの ID を保存するために、セッション認証 を使用できます。 たとえば、ユーザーが初めて Web フォームを使用してログインしたときに、ユーザー名を Cookie セッションに保存し、以降のリクエストでは session プロバイダーを使用してこのユーザーを認可できます。