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 构件:
安装 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 {} 函数:
install(Auth) {
basic {
// 配置基本身份验证
}
}在该代码块内,你可以配置特定于此提供程序的设置。
有关特定于提供程序的设置,请参阅相应的主题:
配置 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()
}
}当身份验证数据频繁更改或必须反映最新状态时,禁用令牌缓存尤其有用。
