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 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

TIP

若要進一步了解 Ktor 用戶端所需的構件，請參閱

新增用戶端相依性

了解如何將用戶端相依性新增到現有專案。

。

安裝 Auth

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

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 {} 函式：

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

在該區塊內，您可以配置此提供者特定的設定。

關於各提供者的特定設定，請參閱相應的主題：

• Basic 驗證
• Digest 驗證
• Bearer 驗證

配置 realm

(選用) 您可以使用 realm 屬性配置 realm：

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

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

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 擴充來存取特定的提供者：

val provider = client.authProvider<BearerAuthProvider>()

若要檢索所有已安裝的提供者，請使用 authProviders 屬性：

val providers = client.authProviders

這些公用程式允許您以程式化方式檢查提供者或清除快取的權杖。

清除快取的權杖

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

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

若要清除所有支援清除快取的驗證提供者中的快取權杖，請使用 .clearAuthTokens() 函式：

client.clearAuthTokens()

清除快取的權杖通常用於以下場景：

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

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

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

控制快取行為

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

例如，當動態提供憑據時，您可以停用快取：

basic {
    cacheTokens = false   // 為每個請求重新載入憑據
    credentials {
        loadCurrentCredentials()
    }
}

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