Skip to content
Server Plugin

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 - 一種簡單的驗證方法,用戶端在標頭中傳遞秘密金鑰。

表單式驗證 ​

表單式驗證使用 Web 表單來收集憑據資訊並驗證使用者。

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 提供了兩種自訂驗證和授權行為的方法:

Experimental

型別安全的驗證配置 API

Ktor 還提供了型別安全的驗證配置 API,將配置繫結至主體型別。 在受保護的路由中,call.principal 即為主體型別,且保證為非 null,因此不需要進行轉換或 null 檢查。 該 API 還支援選擇性啟用的角色檢查、匿名備援、具型別的工作階段以及 OAuth 2.0 流程。

此 API 是本主題中所述具名提供者方法的替代方案。 兩種 API 可以在同一個應用程式中使用。如需更多資訊,請參閱型別安全驗證。

新增相依性 ​

若要使用 Authentication,請將 ktor-server-auth 產物新增至你的建置指令碼:

kotlin
implementation(ktorLibs.server.auth)
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.auth
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
xml
<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() 擴充函式中。
kotlin
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)
}
kotlin
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() 函式:

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

在此函式中,你可以進行設定專屬於此提供者的選項。

如果內建的提供者不符合你的需求,你可以實作自訂驗證提供者。

步驟 2:指定提供者名稱 ​

用於使用特定提供者的函式允許你選擇性地指定提供者名稱。以下程式碼範例分別使用 "auth-basic" 和 "auth-form" 名稱安裝 basic 與 form 提供者:

kotlin
install(Authentication) {
    basic("auth-basic") {
        // 設定 basic 驗證
    }
    form("auth-form") {
        // 設定 form 驗證
    }
    // ...
}

這些名稱稍後可用於使用不同的提供者來驗證不同的路由。

請注意,提供者名稱應是唯一的,且你只能定義一個未命名的提供者。

步驟 3:設定提供者 ​

每個提供者類型都有自己的設定。例如,BasicAuthenticationProvider.Config 類別為 .basic() 函式提供設定選項。此類別中的關鍵函式是 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() 函式如何運作,我們需要介紹兩個術語:

  • 主體 (Principal) 是一個可以被驗證的實體:使用者、電腦、服務等。在 Ktor 中,各種驗證提供者可能會使用不同的主體。例如,basic、digest 和 form 提供者驗證 UserIdPrincipal,而 jwt 提供者則驗證 JWTPrincipal。

    你也可以建立自訂主體。這在以下情況中可能會很有用:

    • 將憑據對應至自訂主體,可讓你在路由處理常式內取得關於已驗證主體的其他資訊。
    • 如果你使用工作階段驗證,主體可以是一個儲存工作階段資料的資料類別。
  • 憑據 (Credential) 是伺服器用於驗證主體的一組屬性:使用者名稱/密碼配對、API 金鑰等。例如,basic 和 form 提供者使用 UserPasswordCredential 來驗證使用者名稱和密碼,而 jwt 則驗證 JWTCredential。

因此,validate() 函式會檢查指定的憑據,在驗證成功時回傳主體 Any,若驗證失敗則回傳 null。

若要根據特定條件跳過驗證,請使用 skipWhen()。 例如,如果 工作階段 已存在,你可以跳過 basic 驗證:

kotlin
basic {
    skipWhen { call -> call.sessions.get<UserSession>() != null }
}

步驟 4:保護特定資源 ​

最後一步是保護應用程式中的特定資源。你可以使用 authenticate() 函式來完成此操作。此函式接受兩個選用參數:

  • 用於驗證巢狀路由的提供者名稱。 以下程式碼片段使用名稱為 auth-basic 的提供者來保護 /login 和 /orders 路由:

    kotlin
    routing {
        authenticate("auth-basic") {
            get("/login") {
                // ...
            }    
            get("/orders") {
                // ...
            }    
        }
        get("/") {
            // ...
        }
    }
  • 用於解析巢狀驗證提供者的策略。 此策略由 AuthenticationStrategy 列舉值表示。

    例如,用戶端應為所有使用 AuthenticationStrategy.Required 策略註冊的提供者提供驗證資料。 在以下程式碼片段中,只有通過工作階段驗證的使用者才能嘗試使用 basic 驗證存取 /admin 路由:

    kotlin
    routing {
        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 並獲取已驗證使用者的名稱。

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

如果你使用工作階段驗證,主體可以是一個儲存工作階段資料的資料類別。 因此,你需要將此資料類別傳遞給 call.principal():

kotlin
authenticate("auth-session") {
    get("/hello") {
        val userSession = call.principal<UserSession>()
    }
}

在巢狀驗證提供者的情況下,你可以將提供者名稱傳遞給 call.principal(),以取得所需提供者的主體。

在以下範例中,傳遞了 "auth-session" 值以取得最頂層工作階段提供者的主體:

kotlin
val required = AuthenticationStrategy.Required
authenticate("auth-session", strategy = required) {
    authenticate("auth-basic", strategy = required) {
        get("/admin") {
            val userSession =
                call.principal<UserSession>(
                    "auth-session"
                )
        }
    }
}

自訂驗證提供者 ​

當內建提供者不符合你的需求時,請使用 provider() 函式來實作自訂驗證邏輯:

kotlin
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 類別提供的選項來設定其他提供者行為。