Ktor 伺服器中的 Bearer 驗證

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

程式碼範例： auth-bearer

原生伺服器

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

支援：✅

Bearer 驗證方案是 HTTP 架構 用於存取控制和驗證的一部分。此方案涉及稱為 Bearer 權杖的安全權杖。Bearer 驗證方案通常作為 OAuth 或 JWT 的一部分使用，但您也可以為授權 Bearer 權杖提供自訂邏輯。

您可以在 Ktor 伺服器中的驗證與授權 章節中獲取有關 Ktor 驗證的一般資訊。

Bearer 驗證應僅透過 HTTPS/TLS 使用。

新增相依性

若要啟用 bearer 驗證，您需要在建置指令碼中包含 ktor-server-auth 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

Bearer 驗證流程

一般而言，Bearer 驗證流程可能如下所示：

1. 在使用者成功驗證並授權存取後，伺服器會向用戶端傳回一個存取權杖。
2. 用戶端可以使用 Bearer 方案，透過在 Authorization 標頭中傳遞權杖，向受保護的資源發出請求。

   GET http://localhost:8080/
   Authorization: Bearer abc123

3. 伺服器接收請求並驗證權杖。
4. 驗證後，伺服器會回應受保護資源的內容。

安裝 Bearer 驗證

若要安裝 bearer 驗證提供者，請在 install 區塊內呼叫 bearer 函式：

import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    bearer {
        // 配置 Bearer 驗證
    }
}

您可以選擇性地指定一個提供者名稱，該名稱可用於驗證指定的路由。

配置 Bearer 驗證

若要瞭解如何在 Ktor 中配置不同驗證提供者的一般概念，請參閱配置驗證。在本節中，我們將探討 bearer 驗證提供者的配置細節。

步驟 1：配置 Bearer 提供者

bearer 驗證提供者透過 BearerAuthenticationProvider.Configuration 類別公開其設定。在下方的範例中，指定了以下設定：

• realm 屬性設定了要在 WWW-Authenticate 標頭中傳遞的領域 (realm)。
• authenticate 函式會檢查用戶端傳送的權杖，並在驗證成功時傳回 UserIdPrincipal，若驗證失敗則傳回 null。

install(Authentication) {
    bearer("auth-bearer") {
        realm = "Access to the '/' path"
        authenticate { tokenCredential ->
            if (tokenCredential.token == "abc123") {
                UserIdPrincipal("jetbrains")
            } else {
                null
            }
        }
    }
}

步驟 2：保護特定資源

配置 bearer 提供者後，您可以使用 authenticate 函式保護應用程式中的特定資源。在驗證成功的情況下，您可以在路由處理常式中使用 call.principal 函式擷取已驗證的 UserIdPrincipal，並獲取已驗證使用者的名稱。

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