Ktor Server 中的驗證與授權
必要相依性:io.ktor:ktor-server-auth
Ktor 提供了 Authentication 外掛程式來處理驗證與授權。常見的使用案例包括讓使用者登入、授予對特定資源的存取權限,以及在雙方之間安全地傳輸資訊。你也可以將 Authentication 與 工作階段 (Sessions) 搭配使用,以在不同請求之間保留使用者的資訊。
在用戶端上,Ktor 提供了 Authentication 外掛程式來處理驗證與授權。
支援的驗證類型
Ktor 支援以下驗證與授權配置:
HTTP 驗證
HTTP 提供了用於存取控制和驗證的通用架構。在 Ktor 中,你可以使用以下 HTTP 驗證配置:
- Basic - 使用
Base64編碼提供使用者名稱和密碼。若未與 HTTPS 結合使用,通常不建議採用。 - Digest - 一種透過對使用者名稱和密碼套用雜湊函式,以加密形式傳遞使用者憑據的驗證方法。
- Bearer - 一種涉及稱為 Bearer 權杖的安全權杖的驗證配置。Bearer 驗證配置通常作為 OAuth 或 JWT 的一部分使用,但你也可以提供自訂邏輯來授權 Bearer 權杖。
- API Key - 一種簡單的驗證方法,用戶端在標頭中傳遞秘密金鑰。
表單式驗證
JSON Web Tokens (JWT)
JSON Web Token 是一種開放標準,用於以 JSON 物件在雙方之間安全地傳輸資訊。你可以使用 JSON Web Token 進行授權:當使用者登入後,每個請求都會包含一個權杖,允許使用者存取該權杖所允許的資源。在 Ktor 中,你可以使用 jwt 驗證來驗證權杖並檢驗其中包含的宣告(claims)。
LDAP
LDAP 是一種開放且跨平台的通訊協定,用於目錄服務驗證。Ktor 提供了 ldapAuthenticate 函式,用於針對指定的 LDAP 伺服器驗證使用者憑據。
OAuth
OAuth 是一項用於保護 API 存取的開放標準。Ktor 中的 oauth 提供者允許你使用外部提供者(例如 Google、Facebook、Twitter 等)來實作驗證。
OpenID Connect
OpenID Connect 是建置在 OAuth 2.0 之上的身分層。Oidc 外掛程式會讀取提供者的探索文件(discovery document),因此你只需設定發行者 URL,而無需手動設定端點和簽署金鑰。它可以在 API 中驗證存取權杖,並執行瀏覽器登入,包括 PKCE、工作階段以及登出。
此外掛程式為實驗功能,且僅在 JVM 上可用。
Session
工作階段 (Sessions) 提供了一種在不同 HTTP 請求之間保留資料的機制。常見的使用案例包括儲存已登入使用者的 ID、購物車內容,或在用戶端保留使用者偏好設定。在 Ktor 中,已經擁有相關聯工作階段的使用者可以透過 session 提供者進行驗證。請參閱 Ktor Server 中的工作階段驗證以了解如何執行此操作。
自訂
Ktor 提供了兩種自訂驗證和授權行為的方法:
- 使用自訂驗證提供者。
- 使用自訂外掛程式來實作授權邏輯。例如,你可以使用
AuthenticationChecked掛鉤來驗證存取權限。如需更多資訊,請參閱 custom-plugin-authorization 範例。
型別安全的驗證配置 API
Ktor 還提供了型別安全的驗證配置 API,將配置繫結至主體型別。 在受保護的路由中,call.principal 即為主體型別,且保證為非 null,因此不需要進行轉換或 null 檢查。 該 API 還支援選擇性啟用的角色檢查、匿名備援、具型別的工作階段以及 OAuth 2.0 流程。
此 API 是本主題中所述具名提供者方法的替代方案。 兩種 API 可以在同一個應用程式中使用。如需更多資訊,請參閱型別安全驗證。
新增相依性
若要使用 Authentication,請將 ktor-server-auth 產物新增至你的建置指令碼:
implementation(ktorLibs.server.auth)implementation ktorLibs.server.auth<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>請注意,某些驗證提供者(例如 JWT 和 LDAP)需要額外的產物。
安裝 Authentication
若要將 Authentication 外掛程式安裝至你的應用程式, 請將其傳遞至指定模組模組可讓您透過對路由進行分組來建構應用程式。中的 install 函式。 以下範例展示了如何安裝 Authentication:
- 在
embeddedServer()函式呼叫中。 - 在
Application類別上明確定義的module()擴充函式中。
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.auth.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(Authentication)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
fun Application.module() {
install(Authentication)
// ...
}設定 Authentication
在安裝 Authentication 之後,你可以按照以下方式設定並使用 Authentication:
步驟 1:選擇驗證提供者
若要使用特定的驗證提供者,例如 basic、digest 或 form,你需要在 install 區塊中呼叫對應的函式。例如,若要使用 basic 驗證,請呼叫 .basic() 函式:
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
basic {
// 設定 basic 驗證
}
}在此函式中,你可以進行設定專屬於此提供者的選項。
如果內建的提供者不符合你的需求,你可以實作自訂驗證提供者。
步驟 2:指定提供者名稱
用於使用特定提供者的函式允許你選擇性地指定提供者名稱。以下程式碼範例分別使用 "auth-basic" 和 "auth-form" 名稱安裝 basic 與 form 提供者:
install(Authentication) {
basic("auth-basic") {
// 設定 basic 驗證
}
form("auth-form") {
// 設定 form 驗證
}
// ...
}這些名稱稍後可用於使用不同的提供者來驗證不同的路由。
請注意,提供者名稱應是唯一的,且你只能定義一個未命名的提供者。
步驟 3:設定提供者
每個提供者類型都有自己的設定。例如,BasicAuthenticationProvider.Config 類別為 .basic() 函式提供設定選項。此類別中的關鍵函式是 validate(),負責驗證使用者名稱和密碼。以下程式碼範例展示了其用法:
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() 函式如何運作,我們需要介紹兩個術語:
- 主體 (Principal) 是一個可以被驗證的實體:使用者、電腦、服務等。在 Ktor 中,各種驗證提供者可能會使用不同的主體。例如,
basic、digest和form提供者驗證UserIdPrincipal,而jwt提供者則驗證JWTPrincipal。 - 憑據 (Credential) 是伺服器用於驗證主體的一組屬性:使用者名稱/密碼配對、API 金鑰等。例如,
basic和form提供者使用UserPasswordCredential來驗證使用者名稱和密碼,而jwt則驗證JWTCredential。
因此,validate() 函式會檢查指定的憑據,在驗證成功時回傳主體 Any,若驗證失敗則回傳 null。
若要根據特定條件跳過驗證,請使用 skipWhen()。 例如,如果 工作階段 已存在,你可以跳過 basic 驗證:
basic {
skipWhen { call -> call.sessions.get<UserSession>() != null }
}步驟 4:保護特定資源
最後一步是保護應用程式中的特定資源。你可以使用 authenticate() 函式來完成此操作。此函式接受兩個選用參數:
用於驗證巢狀路由的提供者名稱。 以下程式碼片段使用名稱為 auth-basic 的提供者來保護
/login和/orders路由:kotlinrouting { authenticate("auth-basic") { get("/login") { // ... } get("/orders") { // ... } } get("/") { // ... } }用於解析巢狀驗證提供者的策略。 此策略由
AuthenticationStrategy列舉值表示。例如,用戶端應為所有使用
AuthenticationStrategy.Required策略註冊的提供者提供驗證資料。 在以下程式碼片段中,只有通過工作階段驗證的使用者才能嘗試使用 basic 驗證存取/admin路由:kotlinrouting { val required = AuthenticationStrategy.Required authenticate("auth-session", strategy = required) { get("/hello") { // ... } authenticate("auth-basic", strategy = required) { get("/admin") { // ... } } } }
完整範例請參閱 auth-form-session-nested。
步驟 5:在路由處理常式中取得主體
驗證成功後,你可以在路由處理常式中使用 call.principal() 函式擷取已驗證的主體。此函式接受由已設定的驗證提供者回傳的特定主體型別。在以下範例中,call.principal() 用於取得 UserIdPrincipal 並獲取已驗證使用者的名稱。
routing {
authenticate("auth-basic") {
get("/") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}如果你使用工作階段驗證,主體可以是一個儲存工作階段資料的資料類別。 因此,你需要將此資料類別傳遞給 call.principal():
authenticate("auth-session") {
get("/hello") {
val userSession = call.principal<UserSession>()
}
}在巢狀驗證提供者的情況下,你可以將提供者名稱傳遞給 call.principal(),以取得所需提供者的主體。
在以下範例中,傳遞了 "auth-session" 值以取得最頂層工作階段提供者的主體:
val required = AuthenticationStrategy.Required
authenticate("auth-session", strategy = required) {
authenticate("auth-basic", strategy = required) {
get("/admin") {
val userSession =
call.principal<UserSession>(
"auth-session"
)
}
}
}自訂驗證提供者
當內建提供者不符合你的需求時,請使用 provider() 函式來實作自訂驗證邏輯:
provider("custom") {
authenticate { context ->
val headers = context.call.request.headers
val exampleHeader = headers["Example-Header"]
if (exampleHeader == null) {
val message = "No example header found"
val cause = AuthenticationFailedCause.Error(message)
context.challenge(key = this, cause) { challenge, call ->
call.respondText("Challenge")
challenge.complete()
}
}
}
}在上述範例中,provider("custom") 函式註冊了一個具名驗證提供者,稍後可以使用 authenticate("custom") 將其套用至路由。
在提供者內部,系統會對每個傳入請求執行 authenticate {} 區塊,並透過 context 物件讓你完全掌控驗證流程。這包括存取目前呼叫(context.call)以及檢查標頭、參數或其他請求資料的能力。
你可以使用 DynamicProviderConfig 類別提供的選項來設定其他提供者行為。
