Ktor 伺服器中的工作階段驗證

必備依賴項: io.ktor:ktor-server-auth, io.ktor:ktor-server-sessions

程式碼範例: auth-form-session

原生伺服器

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

支援: ✖️

工作階段提供了一種在不同 HTTP 請求之間持久化資料的機制。典型的用例包括儲存已登入使用者的 ID、購物車內容，或在用戶端保留使用者偏好設定。

在 Ktor 中，已關聯工作階段的使用者可以使用 session 提供者進行驗證。例如，當使用者首次使用網頁表單登入時，您可以將使用者名稱儲存到 Cookie 工作階段，並在後續請求中使用 session 提供者授權此使用者。

您可以在Ktor 伺服器中的驗證與授權區段中獲取關於 Ktor 中驗證與授權的一般資訊。

添加依賴項

要啟用 session 驗證，您需要在建置腳本中包含以下構件：

• 添加 ktor-server-sessions 依賴項以使用工作階段：

  Gradle (Kotlin)Gradle (Groovy)Maven

• 添加 ktor-server-auth 依賴項以進行驗證：

  Gradle (Kotlin)Gradle (Groovy)Maven

工作階段驗證流程

使用工作階段的驗證流程可能會有所不同，並取決於您的應用程式中如何驗證使用者。讓我們看看表單驗證可能如何實作：

1. 用戶端向伺服器發出包含網頁表單資料（包括使用者名稱和密碼）的請求。
2. 伺服器驗證用戶端傳送的憑證，將使用者名稱儲存到 Cookie 工作階段，並回應請求的內容以及包含使用者名稱的 Cookie。
3. 用戶端帶著 Cookie 向受保護的資源發出後續請求。
4. 根據收到的 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 工作階段。

    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() 函數。

以下範例展示了使用網頁表單的簡單驗證流程：

authenticate("auth-form") {
    post("/login") {
        val userName = call.principal<UserIdPrincipal>()?.name.toString()
        call.sessions.set(UserSession(name = userName, count = 1))
        call.respondRedirect("/hello")
    }
}

有關表單驗證流程的更多詳細資訊，請參閱表單驗證文件。

步驟 5：保護特定資源

配置 session 提供者後，您可以使用 authenticate() 函數保護應用程式中的特定資源。

成功驗證後，您可以透過在路由處理常式內使用 call.principal() 函數來檢索已驗證的 principal (在此情況下為 UserSession 實例)：

authenticate("auth-session") {
    get("/hello") {
        val userSession = call.principal<UserSession>()
        call.sessions.set(userSession?.copy(count = userSession.count + 1))
        call.respondText("Hello, ${userSession?.name}! Visit count is ${userSession?.count}.")
    }
}

如需完整範例，請參閱 auth-form-session。