Ktor 伺服器中的基本認證

所需依賴項: io.ktor:ktor-server-auth

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

原生伺服器

Ktor 支援 Kotlin/Native，讓您無需額外的執行時或虛擬機器即可執行伺服器。

支援: ✅

基本認證方案是 HTTP 框架 的一部分，用於存取控制與認證。在此方案中，使用者憑證以 Base64 編碼的使用者名稱/密碼對形式傳輸。

Ktor 允許您使用基本認證來登入使用者並保護特定的 路由。您可以在 Ktor 伺服器中的認證與授權 區段中取得關於 Ktor 認證的一般資訊。

鑑於基本認證以明文傳輸使用者名稱和密碼，您需要使用 HTTPS/TLS 來保護敏感資訊。

新增依賴項

若要啟用 basic 認證，您需要在建置腳本中包含 ktor-server-auth artifact：

Gradle (Kotlin)Gradle (Groovy)Maven

基本認證流程

基本認證流程如下：

1. 用戶端向伺服器應用程式中的特定 路由 發出不帶 Authorization 標頭的請求。

2. 伺服器以 401 (未授權) 回應狀態回應用戶端，並使用 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 函數：

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

您可以選擇性地指定一個 供應器名稱，該名稱可用於 認證指定的路由。

設定基本認證

若要了解如何在 Ktor 中設定不同的認證供應器，請參閱 設定認證。在本節中，我們將看到 basic 認證供應器的特定設定。

步驟 1：設定基本供應器

basic 認證供應器透過 BasicAuthenticationProvider.Configuration 類別公開其設定。在下面的範例中，指定了以下設定：

• realm 屬性設定要在 WWW-Authenticate 標頭中傳遞的 realm。
• validate 函數驗證使用者名稱和密碼。

install(Authentication) {
    basic("auth-basic") {
        realm = "Access to the '/' path"
        validate { credentials ->
            if (credentials.name == "jetbrains" && credentials.password == "foobar") {
                UserIdPrincipal(credentials.name)
            } else {
                null
            }
        }
    }
}

validate 函數檢查 UserPasswordCredential，並在認證成功時返回 UserIdPrincipal，如果認證失敗則返回 null。

您也可以使用 UserHashedTableAuth 來驗證儲存在記憶體內表格中的使用者，該表格會儲存使用者名稱和密碼雜湊。

步驟 2：保護特定資源

設定 basic 供應器後，您可以使用 authenticate 函數保護應用程式中的特定資源。在成功認證的情況下，您可以使用 call.principal 函數在路由處理常式中擷取已認證的 UserIdPrincipal，並取得已認證使用者的名稱。

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

使用 UserHashedTableAuth 驗證

Ktor 允許您使用 UserHashedTableAuth 來 驗證 儲存在記憶體內表格中的使用者，該表格會儲存使用者名稱和密碼雜湊。這讓您可以避免在資料來源洩露時危及使用者密碼。

若要使用 UserHashedTableAuth 驗證使用者，請按照以下步驟操作：

1. 使用 getDigestFunction 函數，建立具有指定演算法和鹽值供應器的摘要函數：

   val digestFunction = getDigestFunction("SHA-256") { "ktor${it.length}" }

2. 初始化 UserHashedTableAuth 的新實例，並指定以下屬性：

   • 使用 table 屬性提供一個使用者名稱和雜湊密碼的表格。
   • 將摘要函數指派給 digester 屬性。

   val hashedUserTable = UserHashedTableAuth(
       table = mapOf(
           "jetbrains" to digestFunction("foobar"),
           "admin" to digestFunction("password")
       ),
       digester = digestFunction
   )

3. 在 validate 函數內部，呼叫 UserHashedTableAuth.authenticate 函數來認證使用者，並在憑證有效時返回 UserIdPrincipal 的實例：

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