Skip to content

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

kotlin
implementation(ktorLibs.server.auth)
上述程式碼片段使用 Ktor 版本目錄 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.auth
上述程式碼片段使用 Ktor 版本目錄 來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

Bearer 驗證流程 ​

一般而言,Bearer 驗證流程如下所示:

  1. 使用者成功通過驗證並獲取存取授權後,伺服器會向用戶端傳回存取權杖。
  2. 用戶端可以使用 Bearer 機制在 Authorization 標頭中傳遞權杖,向受保護的資源發出請求。
    HTTP
    GET http://localhost:8080/
    Authorization: Bearer abc123
  3. 伺服器接收請求並驗證權杖。
  4. 驗證通過後,伺服器回應受保護資源的內容。

安裝 Bearer 驗證 ​

若要安裝 bearer 驗證提供者,請在 install 區塊內呼叫 bearer 函式:

kotlin
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。
kotlin
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) 步驟:此機制是一個您可以傳遞給所需路由的值。

kotlin
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,並取得經過驗證的使用者名稱。

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

將機制傳遞給 authenticateWith()。在該區塊內,call.principal 即為您的主體型別且絕不為 null,因此不需要進行轉換或 null 檢查:

kotlin
routing {
    authenticateWith(bearerAuth) {
        get("/") {
            call.respondText("Hello, ${call.principal.name}!")
        }
    }
}