Skip to content

Ktor Server 中的基本驗證 ​

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

程式碼範例:auth-basic、auth-basic-hash-table

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

Basic 驗證機制是 HTTP 架構的一部分,用於存取控制與驗證。在此機制中,使用者憑據會以使用 Base64 編碼的使用者名稱/密碼配對形式傳輸。

Ktor 允許您使用基本驗證來登入使用者並保護特定路由。您可以在 Ktor Server 中的驗證與授權章節中取得關於 Ktor 驗證的一般資訊。

鑑於基本驗證以明文形式傳遞使用者名稱和密碼,您需要使用 HTTPS/TLS 來保護敏感資訊。

新增相依性 ​

若要啟用 basic 驗證,您需要在組建指令碼中包含 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. 用戶端向伺服器應用程式中的特定路由發出未包含 Authorization 標頭的請求。

  2. 伺服器向用戶端回應 401(Unauthorized)回應狀態,並使用 WWW-Authenticate 回應標頭提供資訊,指出該路由受基本驗證機制保護。典型的 WWW-Authenticate 標頭如下所示:

    WWW-Authenticate: Basic realm="Access to the '/' path", charset="UTF-8"

    在 Ktor 中,您可以在設定 basic 驗證提供程式時,使用對應的屬性來指定 realm 與 charset。

  3. 通常,用戶端會顯示登入對話方塊供使用者輸入憑據。接著,用戶端發出包含以 Base64 編碼的使用者名稱和密碼配對之 Authorization 標頭的請求,例如:

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

安裝基本驗證 ​

若要安裝 basic 驗證提供程式,請在 install 區塊內呼叫 basic 函式:

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    basic {
        // 設定基本驗證
    }
}

您可以選擇性指定提供程式名稱,該名稱可用於驗證指定的路由。

設定基本驗證 ​

若要整體了解如何在 Ktor 中設定不同的驗證提供程式,請參閱設定驗證。在本節中,我們將介紹 basic 驗證提供程式的具體設定方式。

步驟 1:設定 basic 提供程式 ​

basic 驗證提供程式透過 BasicAuthenticationProvider.Configuration 類別公開其設定。在以下範例中,指定了下列設定:

  • realm 屬性設定要在 WWW-Authenticate 標頭中傳遞的 realm。
  • validate 函式驗證使用者名稱與密碼。
kotlin
install(Authentication) {
    basic("auth-basic") {
        realm = "Access to the '/' path"
        validate { credentials ->
            val isValid = credentials.name == "jetbrains" &&
                credentials.password == "foobar"
            if (isValid) {
                UserIdPrincipal(credentials.name)
            } else {
                null
            }
        }
    }
}

validate 函式會檢查 UserPasswordCredential,並在驗證成功時傳回 UserIdPrincipal,若驗證失敗則傳回 null。

您也可以使用 UserHashedTableAuth 來驗證儲存在保存使用者名稱與密碼雜湊值的記憶體內部表格中的使用者。

型別安全驗證方案 API 處於實驗階段。它可能會隨時被棄用或變更。需要明確選擇加入(Opt-in)。如需更多詳細資訊,請參閱 型別安全驗證文件。

basic() 函式會為您所選擇的主體(principal)型別建立配置。不需要 install(Authentication) 步驟:該配置是一個值,您只需將其傳遞給需要的路由即可。

kotlin
data class User(val name: String)

val basicAuth = basic<User>("auth-basic") {
    realm = "Access to the '/' path"
    validate { credentials ->
        val isValid = credentials.name == "jetbrains" &&
            credentials.password == "foobar"
        if (isValid) User(credentials.name) else null
    }
}

validate 函式檢查 UserPasswordCredential 並傳回您的主體型別,若驗證失敗則傳回 null。如需完整的 API,請參閱型別安全驗證。

步驟 2:保護特定資源 ​

設定 basic 提供程式後,您可以使用 authenticate 函式來保護應用程式中的特定資源。在驗證成功的情況下,您可以在路由處理常式內使用 call.principal 函式擷取經過驗證的 UserIdPrincipal,並取得經過驗證的使用者名稱。

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

將配置傳遞給 authenticateWith()。在區塊內,call.principal 即為您的主體型別且絕不為 null,因此不需要轉換或 null 檢查:

kotlin
routing {
    authenticateWith(basicAuth) {
        get("/") {
            call.respondText("Hello, ${call.principal.name}!")
        }
    }
}

使用 UserHashedTableAuth 進行驗證 ​

Ktor 允許您使用 UserHashedTableAuth 來驗證儲存在保存使用者名稱和密碼雜湊值的記憶體內部表格中的使用者。即使您的資料來源外洩,這也能確保使用者的密碼不會外洩。

若要使用 UserHashedTableAuth 來驗證使用者,請依照下列步驟操作:

  1. 使用 getDigestFunction 函式建立具有指定演算法和 salt 提供程式的摘要函式:

    kotlin
    val digestFunction = getDigestFunction("SHA-256") {
        "ktor${it.length}"
    }
  2. 初始化 UserHashedTableAuth 的新執行個體,並指定下列屬性:

    • 使用 table 屬性提供包含使用者名稱與雜湊密碼的表格。
    • 將摘要函式指派給 digester 屬性。
    kotlin
    val hashedUserTable = UserHashedTableAuth(
        table = mapOf(
            "jetbrains" to digestFunction("foobar"),
            "admin" to digestFunction("password")
        ),
        digester = digestFunction
    )
  3. 在 validate 函式內,呼叫 UserHashedTableAuth.authenticate 函式來驗證使用者,並在憑據有效時傳回 UserIdPrincipal 的執行個體:

    kotlin
    install(Authentication) {
        basic("auth-basic-hashed") {
            realm = "Access to the '/' path"
            validate { credentials ->
                hashedUserTable.authenticate(credentials)
            }
        }
    }