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 構件:
表單式身分驗證流程
表單式身分驗證流程大致如下:
未經身分驗證的用戶端向伺服器應用程式中的特定路由發出請求。
伺服器傳回一個至少包含 HTML 式 Web 表單的 HTML 頁面,提示使用者輸入使用者名稱和密碼。
Ktor 允許你使用 Kotlin DSL 建構表單,或者你也可以在各種 JVM 範本引擎(例如 FreeMarker、Velocity 等)之間進行選擇。
當使用者提交使用者名稱和密碼時,用戶端會向伺服器發送一個包含 Web 表單資料(其中包含使用者名稱和密碼)的請求。
kotlinPOST http://localhost:8080/login Content-Type: application/x-www-form-urlencoded username=jetbrains&password=foobar在 Ktor 中,你需要指定參數名稱以用於擷取使用者名稱和密碼。
伺服器驗證用戶端傳送的憑據,並回應所請求的內容。
安裝表單身分驗證
若要安裝 form 身分驗證提供者,請在 install 區塊內呼叫 form 函式:
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。
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) 步驟:該方案是一個值,你可以將其傳遞給需要的路由。
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,並取得該已驗證使用者的名稱。
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 提供者對該使用者進行授權。
