Ktor Server 中的 Bearer 驗證
必要相依性:io.ktor:ktor-server-auth
程式碼範例: auth-bearer
原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援:✅
Bearer 驗證機制是用於存取控制與驗證的 HTTP 架構 的一部分。此機制涉及稱為 Bearer 權杖的安全權杖。Bearer 驗證機制常作為 OAuth 或 JWT 的一部分使用,但您也可以為授權 Bearer 權杖提供自訂邏輯。
您可以在 Ktor Server 中的驗證與授權 章節中取得有關 Ktor 驗證的一般資訊。
Bearer 驗證應僅透過 HTTPS/TLS 使用。
新增相依性
若要啟用 bearer 驗證,您需要在建置指令碼中包含 ktor-server-auth 構件:
Bearer 驗證流程
一般而言,Bearer 驗證流程如下所示:
- 使用者成功通過驗證並獲取存取授權後,伺服器會向用戶端傳回存取權杖。
- 用戶端可以使用
Bearer機制在Authorization標頭中傳遞權杖,向受保護的資源發出請求。HTTPGET http://localhost:8080/ Authorization: Bearer abc123 - 伺服器接收請求並驗證權杖。
- 驗證通過後,伺服器回應受保護資源的內容。
安裝 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
}
}
}
}型別安全驗證機制 API 為實驗功能。它隨時可能被移除或變更。 需要明確選擇採用 (Opt-in)。如需更多詳細資訊,請參閱 型別安全驗證文件。
bearer() 函式會為您選擇的主體型別建立機制。不需要 install(Authentication) 步驟:此機制是一個您可以傳遞給所需路由的值。
data class User(val name: String)
val bearerAuth = bearer<User>("auth-bearer") {
realm = "Access to the '/' path"
validate { tokenCredential ->
if (tokenCredential.token == "abc123") {
User("jetbrains")
} else {
null
}
}
}請注意名稱的變更:傳統提供者使用 authenticate,而型別安全機制與其他型別安全機制一樣,使用 validate。它會傳回您的主體型別,若驗證失敗則傳回 null。
您也可以設定 authHeader 以從 Authorization 標頭以外的位置讀取權杖,並設定 authSchemes 以接受 Bearer 以外的機制。如需完整的 API,請參閱型別安全驗證。
步驟 2:保護特定資源
設定 bearer 提供者後,您可以使用 authenticate 函式保護應用程式中的特定資源。在驗證成功的情況下,您可以在路由處理常式內使用 call.principal 函式擷取經過驗證的 UserIdPrincipal,並取得經過驗證的使用者名稱。
routing {
authenticate("auth-bearer") {
get("/") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}將機制傳遞給 authenticateWith()。在該區塊內,call.principal 即為您的主體型別且絕不為 null,因此不需要進行轉換或 null 檢查:
routing {
authenticateWith(bearerAuth) {
get("/") {
call.respondText("Hello, ${call.principal.name}!")
}
}
}