Skip to content

Ktor Server 中的表單式身分驗證 ​

必要相依性: io.ktor:ktor-server-auth

程式碼範例: auth-form-html-dsl, auth-form-session

原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援: ✅

表單式身分驗證使用 Web 表單來收集憑據資訊並驗證使用者身分。 若要在 Ktor 中建立 Web 表單,你可以使用 HTML DSL,或者在 JVM 範本引擎(例如 FreeMarker、Velocity 等)中進行選擇。

鑑於使用表單式身分驗證時使用者名稱和密碼是以純文字傳遞,你需要使用 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 建構表單,或者你也可以在各種 JVM 範本引擎(例如 FreeMarker、Velocity 等)之間進行選擇。

  3. 當使用者提交使用者名稱和密碼時,用戶端會向伺服器發送一個包含 Web 表單資料(其中包含使用者名稱和密碼)的請求。

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

    在 Ktor 中,你需要指定參數名稱以用於擷取使用者名稱和密碼。

  4. 伺服器驗證用戶端傳送的憑據,並回應所請求的內容。

安裝表單身分驗證 ​

若要安裝 form 身分驗證提供者,請在 install 區塊內呼叫 form 函式:

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    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 為實驗功能。它可能隨時被移除或變更。 需要明確啟用(Opt-in)。如需更多詳細資訊,請參閱 型別安全身分驗證文件。

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)
    }
}

有兩個名稱與傳統提供者不同。表單欄位名稱是 usernameField 和 passwordField,而非 userParamName 和 passwordParamName。失敗處理常式是 onUnauthorized,而非 challenge。如需 完整的 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 提供者對該使用者進行授權。