Ktor Server 中的工作階段驗證
必要相依性: io.ktor:ktor-server-auth, io.ktor:ktor-server-sessions
程式碼範例: auth-form-session
Native 伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援: ✖️
工作階段 (Session) 提供了一種在不同 HTTP 請求之間保留資料的機制。常見的使用案例包括儲存已登入使用者的 ID、購物籃的內容,或在用戶端保留使用者偏好設定。
在 Ktor 中,已具有關聯工作階段的使用者可以使用 session 提供者進行驗證。例如,當使用者第一次使用 Web 表單登入時,您可以將使用者名稱儲存到 Cookie 工作階段中,並在後續請求中使用 session 提供者對此使用者進行授權。
您可以在 Ktor Server 中的驗證與授權章節中取得關於 Ktor 驗證與授權的一般資訊。
Ktor 還提供了一種型別安全的工作階段驗證配置。它為路由處理常式提供非 null 的 principal 以及對已儲存工作階段的讀寫存取權限,並將工作階段型別與 principal 型別分開。請參閱 型別安全的工作階段驗證。
新增相依性
若要啟用 session 驗證,您需要在建置指令碼中包含以下構件:
新增用於使用工作階段的
ktor-server-sessions相依性:kotlinimplementation(ktorLibs.server.sessions)上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。groovyimplementation ktorLibs.server.sessions上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。xml<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-sessions-jvm</artifactId> <version>${ktor_version}</version> </dependency>新增用於驗證的
ktor-server-auth相依性:
工作階段驗證流程
使用工作階段的驗證流程可能會有所不同,取決於使用者在您的應用程式中如何進行驗證。讓我們看看它在表單型驗證中的運作方式:
- 用戶端向伺服器發送包含 Web 表單資料(包括使用者名稱與密碼)的請求。
- 伺服器驗證用戶端傳送的憑據,將使用者名稱儲存到 Cookie 工作階段中,並回傳請求的內容以及包含使用者名稱的 Cookie。
- 用戶端攜帶 Cookie 對受保護的資源發送後續請求。
- 根據接收到的 Cookie 資料,Ktor 會檢查該使用者是否存在 Cookie 工作階段,並可選擇對接收到的工作階段資料執行額外驗證。在驗證成功的情況下,伺服器會回傳請求的內容。
安裝工作階段驗證
若要安裝 session 驗證提供者,請在 install 區塊中以所需的工作階段型別呼叫 session 函式:
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.sessions.*
//...
install(Authentication) {
session<UserSession> {
// 設定工作階段驗證
}
}設定工作階段驗證
本節示範如何透過表單型驗證對使用者進行驗證、將該使用者的資訊儲存到 Cookie 工作階段中,然後在後續請求中使用 session 提供者授權此使用者。
如需完整範例,請參閱 auth-form-session。
步驟 1:建立資料類別
首先,您需要建立一個用於儲存工作階段資料的資料類別:
@Serializable
data class UserSession(val name: String, val count: Int)步驟 2:安裝並設定工作階段
建立資料類別後,您需要安裝並設定 Sessions 外掛程式。以下範例安裝並設定具有指定 Cookie 路徑與過期時間的 Cookie 工作階段。
install(Sessions) {
cookie<UserSession>("user_session") {
cookie.path = "/"
cookie.maxAgeInSeconds = 60
}
}若要進一步了解如何設定工作階段,請參閱工作階段設定概觀。
步驟 3:設定工作階段驗證
session 驗證提供者透過 SessionAuthenticationProvider.Config 類別公開其設定。在以下範例中,指定了以下設定:
validate()函式會檢查工作階段執行個體,並在驗證成功的情況下傳回型別為Any的 principal。challenge()函式指定了驗證失敗時執行的操作。例如,您可以重新導向回登入頁面或傳送UnauthorizedResponse。
install(Authentication) {
session<UserSession>("auth-session") {
validate { session ->
if(session.name.startsWith("jet")) {
session
} else {
null
}
}
challenge {
call.respondRedirect("/login")
}
}
}步驟 4:將使用者資料儲存於工作階段中
若要將已登入使用者的資訊儲存到工作階段,請使用 call.sessions.set() 函式。
以下範例展示了使用 Web 表單的簡單驗證流程:
authenticate("auth-form") {
post("/login") {
val principal =
call.principal<UserIdPrincipal>()
val userName = principal?.name.toString()
val session = UserSession(
name = userName,
count = 1
)
call.sessions.set(session)
call.respondRedirect("/hello")
}
}有關表單型驗證流程的詳細資訊,請參閱表單型驗證文件。
步驟 5:保護特定資源
設定好 session 提供者後,您可以使用 authenticate() 函式來保護應用程式中的特定資源。
驗證成功後,您可以在路由處理常式中使用 call.principal() 函式來擷取已驗證的 principal(在此例中為 UserSession 執行個體):
authenticate("auth-session") {
get("/hello") {
val userSession = call.principal<UserSession>()
val next = userSession?.copy(
count = userSession.count + 1
)
call.sessions.set(next)
call.respondText(
"Hello, ${userSession?.name}! " +
"Visit count is ${userSession?.count}."
)
}
}如需完整範例,請參閱 auth-form-session。
