OAuth 2.0 流程
必需依赖项:io.ktor:ktor-server-auth, io.ktor:ktor-server-sessions
Ktor 在类型安全身份验证方案 API 中提供了两种类型化的 OAuth 2.0 流程:
oauth2Session用于让用户登录、存储会话,并为你提供用于保护应用程序路由的方案。除非有特殊理由,否则建议使用此方案。oauth2用于让用户登录并在回调中将令牌传递给你。它不会保护后续的路由。
流程并不是传递给 authenticateWith() 的方案。它是你 install() 到路由中的一个值,并且会自动为你创建登录和回调路由。
类型安全身份验证方案 API 为实验性功能。它可能随时被废弃或更改。需要显式选择启用(opt-in)。如需了解详情,请参阅 类型安全身份验证文档。
本文介绍类型化 API。关于传统的 oauth 提供程序,请参阅 OAuth。
流程工作原理
- 用户访问登录路径。Ktor 将其重定向到 OAuth 提供程序。
- 用户在提供程序处批准所请求的权限。
- 提供程序携带授权码重定向回你的回调路径。
- Ktor 使用该授权码交换访问令牌。
- 对于
oauth2Session,Ktor 会存储会话并解析主体 (principal),然后运行你的回调处理程序。
使用 oauth2Session 实现用户登录
流程需要一个 HttpClient 来调用提供程序的令牌端点,因此还需要添加一个客户端引擎依赖项,例如 io.ktor:ktor-client-cio。
声明两个类型:路由所使用的主体,以及 Ktor 为调用方存储的会话。
data class User(val id: String, val email: String)
data class UserSession(val accessToken: String)然后创建该流程。请注意类型实参的顺序:主体在前,会话在后。
val googleAuthorizeUrl =
"https://accounts.google.com/o/oauth2/auth"
val googleTokenUrl = "https://oauth2.googleapis.com/token"
val profileScope =
"https://www.googleapis.com/auth/userinfo.profile"
val googleAuth = oauth2Session<User, UserSession>("google") {
client = HttpClient(CIO)
settings = OAuthServerSettings.OAuth2ServerSettings(
name = "google",
authorizeUrl = googleAuthorizeUrl,
accessTokenUrl = googleTokenUrl,
requestMethod = HttpMethod.Post,
clientId = System.getenv("GOOGLE_CLIENT_ID"),
clientSecret = System.getenv("GOOGLE_CLIENT_SECRET"),
defaultScopes = listOf(profileScope)
)
loginPath = "/login"
callback("/callback") {
call.respondRedirect("/profile")
}
sessions {
sessionCreator = { token ->
UserSession(token.accessToken)
}
validate { session ->
userService.loadUser(session.accessToken)
}
}
}sessions 代码块承担两项工作:
sessionCreator将令牌响应转换为要存储的会话。它在完成令牌交换后立即运行一次。validate将存储的会话转换为主体。它会在每次对受保护路由发起请求时运行。
两者都是必需的。
安装该流程并使用 flow.session 保护你的路由:
routing {
install(googleAuth)
authenticateWith(googleAuth.session) {
get("/profile") {
val user = call.principal
val session = call.session
val token = session.accessToken
call.respondText("${user.email} ($token)")
}
}
}install() 会创建登录路由、创建回调路由,并为会话方案安装 Sessions 插件。你无需自行安装 Sessions。
在受保护的路由内部,call.principal 为你的 User,call.session 为你的 UserSession。有关可以对会话执行的所有操作,请参阅类型安全会话身份验证。
受保护的路由不会执行重定向
流程为你创建的路由(登录路径和回调路径)会将未通过身份验证的访客重定向到 OAuth 提供程序。而使用 authenticateWith(flow.session) 保护的路由不会这样做。缺少有效会话的请求将收到 401 Unauthorized。
你可以通过两种方式将用户引导至提供程序:
从登录页面链接到
loginPath。在缺少会话时自行重定向到该处:
kotlinval googleAuth = oauth2Session<User, UserSession>("google") { // ... sessions { sessionCreator = { token -> UserSession(token.accessToken) } validate { session -> userService.loadUser(session.accessToken) } onUnauthorized = { call.respondRedirect("/login") } } }
处理登录失败
两个处理程序分别涵盖了登录可能失败的两种情况。
流程上的 onUnauthorized 用于处理 OAuth 错误,例如用户拒绝授权、令牌交换失败、sessionCreator 或 validate 返回 null:
val googleAuth = oauth2Session<User, UserSession>("google") {
// ...
onUnauthorized = { cause ->
call.respondRedirect("/login?error=${cause}")
}
}使用多个提供程序
设置 providerLookup 而非 settings,可以根据每个请求选择相应的提供程序。该代码块在路由上下文中运行,因此你可以读取路径、查询参数或请求头:
val socialAuth = oauth2Session<User, UserSession>("social") {
client = HttpClient(CIO)
providerLookup = {
when (call.parameters["provider"]) {
"google" -> googleSettings
"github" -> githubSettings
else -> null
}
}
loginPath = "/login/{provider}"
callback("/callback/{provider}") {
call.respondRedirect("/profile")
}
sessions {
sessionCreator = { token ->
UserSession(token.accessToken)
}
validate { session ->
userService.loadUser(session.accessToken)
}
}
}请设置 settings 或 providerLookup 其中之一,切勿同时设置。
无会话登录
当你不需要 Ktor 保护后续路由时(例如,在登录后自行签发 JWT),请使用 oauth2。回调处理程序会接收令牌响应:
val githubAuthorizeUrl =
"https://github.com/login/oauth/authorize"
val githubTokenUrl =
"https://github.com/login/oauth/access_token"
val githubOAuth = oauth2("github") {
client = HttpClient(CIO)
settings = OAuthServerSettings.OAuth2ServerSettings(
name = "github",
authorizeUrl = githubAuthorizeUrl,
accessTokenUrl = githubTokenUrl,
requestMethod = HttpMethod.Post,
clientId = System.getenv("GITHUB_CLIENT_ID"),
clientSecret = System.getenv("GITHUB_CLIENT_SECRET")
)
loginPath = "/login"
callback("/callback") { token ->
val jwt = tokenService.issueToken(token.accessToken)
call.respondText(jwt)
}
}
routing {
install(githubOAuth)
}此处没有 flow.session,因此没有任何内容可传递给 authenticateWith()。请使用其他方案保护你的路由,例如 jwt。
安全注意事项
- 切勿将
clientSecret纳入源代码管理中。应从环境变量或你的配置文件中读取它。 - 回调会将该会话存储在一个新生成的会话 ID 下,并丢弃随回调请求一同传来的任何会话 ID。这可以防止会话固定(session fixation)攻击。
- 默认的会话传输机制会将会话数据保存在服务器端,且仅向客户端发送一个 ID。如果切换为按值传输(by-value transport),请添加一个转换器。参见选择传输机制。
后续步骤
- 类型安全身份验证涵盖了角色、可选身份验证以及该 API 的其余部分。
- 类型安全会话身份验证涵盖了会话、传输机制以及用户退出登录。
- OpenID Connect 可根据 OpenID Connect 签发者 URL 自动为你配置这些流程。
