Skip to content
Client Plugin

Ktor Client 中的身份驗證與授權

必要相依性: io.ktor:ktor-client-auth

Ktor 提供 Auth 外掛程式來處理用戶端應用程式中的身份驗證與授權。典型使用情境包括使用者登入以及取得特定資源的存取權限。

在伺服器端,Ktor 提供 Authentication 外掛程式來處理身份驗證與授權。

支援的身份驗證類型 ​

HTTP 為存取控制與身份驗證提供了一個通用架構。Ktor 用戶端允許你使用以下 HTTP 身份驗證機制:

  • Basic - 使用 Base64 編碼提供使用者名稱與密碼。如果未搭配 HTTPS 使用,通常不建議採用。
  • Digest - 一種身份驗證方法,透過對使用者名稱和密碼套用雜湊函式,以加密形式傳輸使用者憑據。
  • Bearer - 一種涉及稱為 Bearer 權杖的安全權杖的身份驗證機制。例如,你可以將此機制用作 OAuth 流程的一部分,透過 Google、Facebook 和 X 等外部提供者來為應用程式的使用者進行授權。

新增相依性 ​

若要啟用身份驗證,請在建置指令碼中加入 ktor-client-auth 構件:

kotlin
implementation(ktorLibs.client.auth)
上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。
groovy
implementation ktorLibs.client.auth
上述程式碼片段使用 Ktor 版本目錄 (version catalog) 來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-auth-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
若要進一步了解 Ktor 用戶端所需的構件,請參閱 新增用戶端相依性了解如何將用戶端相依性新增至現有專案中。。

安裝 Auth ​

若要安裝 Auth 外掛程式,請將其傳遞給 用戶端配置區塊 內的 install() 函式:

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.auth.*
//...
val client = HttpClient(CIO) {
    install(Auth) {
        // 配置身份驗證
    }
}

設定身份驗證 ​

選擇身份驗證提供者 ​

若要使用特定的身份驗證提供者(basic、digest 或 bearer),請在 install {} 區塊內呼叫對應的函式。

例如,若要配置 basic 身份驗證,請使用 basic {} 函式:

kotlin
install(Auth) {
    basic {
        // 配置 basic 身份驗證
    }
}

在此區塊內,你可以配置該提供者的專屬設定。

關於特定提供者的詳細設定,請參閱對應的主題:

配置 realm ​

你可以選擇使用 realm 屬性來配置 realm:

kotlin
install(Auth) {
    basic {
        realm = "Access to the '/' path"
        // ...
    }
}

你可以建立多個具有不同 realm 的提供者來存取不同的資源:

kotlin
install(Auth) {
    basic {
        realm = "Access to the '/' path"
        // ...
    }
    basic {
        realm = "Access to the '/admin' path"
        // ...
    }
}

在這種情況下,用戶端會根據包含 realm 的 WWW-Authenticate 回應標頭來選擇所需的提供者。

提供者選擇 ​

當伺服器回傳 401 Unauthorized 時,用戶端會根據 WWW-Authenticate 回應標頭選擇身份驗證提供者。此標頭指定了伺服器接受哪些身份驗證機制。

如果用戶端只安裝了一個身份驗證提供者,則當伺服器回傳 401 Unauthorized 時,Auth 外掛程式一律會嘗試該提供者,即使缺少 WWW-Authenticate 標頭或指定了不同的機制也是如此。

如果用戶端安裝了多個身份驗證提供者,用戶端將根據 WWW-Authenticate 標頭來選擇提供者。

權杖快取與快取控制 ​

basic 和 bearer 身份驗證提供者會維護內部憑據或權杖快取。此快取允許用戶端重複使用先前載入的身份驗證資料,而不是在每個請求中重新載入,從而在提高效能的同時,仍可在憑據變更時保有完整控制權。

存取身份驗證提供者 ​

當用戶端工作階段期間需要動態更新身份驗證狀態時,你可以使用 authProvider 擴充功能存取特定的提供者:

kotlin
val provider = client.authProvider<BearerAuthProvider>()

若要擷取所有已安裝的提供者,請使用 authProviders 屬性:

kotlin
val providers = client.authProviders

這些實用工具可讓你以程式化方式檢查提供者或清除快取的權杖。

清除快取的權杖 ​

若要清除單一提供者快取的憑據,請使用 .clearToken() 函式:

kotlin
val provider = client.authProvider<BasicAuthProvider>()
provider?.clearToken()

若要清除所有支援快取清除的身份驗證提供者的快取權杖,請使用 .clearAuthTokens() 函式:

kotlin
client.clearAuthTokens()

清除快取的權杖通常用於以下情境:

  • 使用者登出時。
  • 應用程式儲存的憑據或權杖發生變更時。
  • 需要強制提供者在下一次請求時重新載入身份驗證狀態時。

以下是使用者登出時清除快取權杖的範例:

kotlin
fun logout() {
    client.clearAuthTokens()
    storage.deleteCredentials()
}

控制快取行為 ​

Basic 和 Bearer 身份驗證提供者都允許你使用 cacheTokens 選項來控制是否在請求之間快取權杖或憑據。

例如,當動態提供憑據時,你可以停用快取:

kotlin
basic {
    cacheTokens = false   // 每次請求都會重新載入憑據
    credentials {
        loadCurrentCredentials()
    }
}

當身份驗證資料頻繁變更或必須反映最新狀態時,停用權杖快取特別有用。