Ktor集成Keycloak时如何使用Access Token实现路由鉴权保护

你目前遇到的跳转问题核心原因是：你配置的keycloakOAuth认证器走的是OAuth2授权码流程，设计用途是为浏览器端用户触发重定向到Keycloak登录页，本身不会解析、校验请求头中携带的Bearer Token，所以哪怕你请求带了有效Token，还是会触发登录跳转逻辑。

要实现你要的API路由令牌校验能力，需要额外配置JWT认证能力，和你现有的OAuth授权码流配置共存即可，以下是具体实现步骤：

1. 引入依赖 #

首先添加Ktor JWT认证依赖（版本和你当前Ktor版本保持一致）：

implementation("io.ktor:ktor-server-auth-jwt:$ktor_version")

2. 配置双认证器 #

在Authentication配置块中，保留你原有用于登录、回调的OAuth认证器，新增一个专门用于Bearer Token校验的JWT认证器：

install(Authentication) {
    // 你原有用于授权码登录的OAuth配置，保持不变
    oauth("keycloakOAuth") {
        // 你原来的配置内容
    }

    // 新增JWT认证器，专门用于API路由校验
    jwt("keycloakJwt") {
        // 填你Keycloak中创建的Realm名称
        realm = "your_keycloak_realm"
        val keycloakIssuer = "http://你的Keycloak服务地址/realms/your_keycloak_realm"
        
        // 配置JWT校验规则
        verifier(keycloakIssuer) {
            // 可选：校验Audience，和你Keycloak客户端配置中的audience保持一致
            withAudience("your_client_audience")
        }

        // 自定义校验逻辑，校验通过返回JWTPrincipal即可
        validate { credential ->
            // 这里可以扩展校验逻辑，比如校验用户角色、账号状态等
            JWTPrincipal(credential.payload)
        }

        // 校验失败时直接返回401，不做登录重定向
        challenge { _, _ ->
            call.respond(HttpStatusCode.Unauthorized, "无效或已过期的Access Token")
        }
    }
}

3. 路由使用 #

需要保护的API路由用新增的keycloakJwt认证器包裹即可，原有登录、回调路由保持原有配置不变：

// 原有登录、回调路由，保持不变
authenticate("keycloakOAuth") {
    get("login") {}
    route("/callback") {
        handle {
            // 原有回调逻辑
        }
    }
}

// 受保护的API路由，使用JWT认证器
authenticate("keycloakJwt") {
    get("/testAuth") {
        val principal = call.principal<JWTPrincipal>()
        // 可直接从JWT载荷中获取用户信息，比如用户名、用户ID、角色等
        val username = principal?.payload?.getClaim("preferred_username")?.asString()
        call.respondText("Authenticated! 当前用户：$username")
    }
}

关于Token自动刷新说明 #

Ktor原生JWT认证能力本身不提供自动刷新Access Token的逻辑，因为Refresh Token按规范是存储在客户端侧的，常规实现逻辑是：

• 客户端收到401响应后，自行使用本地存储的Refresh Token调用Keycloak的刷新接口获取新的Access Token
• 重发原请求即可
  如果需要服务端处理刷新，可扩展JWT认证器的challenge逻辑，检测到Token过期时，读取请求中携带的Refresh Token，主动调用Keycloak刷新接口返回新的Token给客户端即可。

内容的提问来源于stack exchange，提问作者Danoctum