Ktor 是 JetBrains 开发的一款轻量级的后端框架，下面讲述如何在 Ktor 中配置 JWT。

一、导入依赖

/** Ktor JWT 核心依赖 **/
implementation("io.ktor:ktor-server-auth-jvm")
implementation("io.ktor:ktor-server-auth-jwt-jvm")

/** Ktor 序列化依赖，也可以使用 Gson **/
implementation("io.ktor:ktor-serialization-kotlinx-json-jvm")

/** 用于加密、编码、进制转换等操作 **/
implementation("commons-codec:commons-codec:1.16.0")

二、配置插件

1. 项目结构

在开始之前，首先在 security/token 包中新建 TokenConfig 数据类。

package cc.loac.security.token

data class TokenConfig(
    /** 令牌发行者 **/
    val issuer: String,
    /** 令牌受众 **/
    val audience: String,
    /** 令牌有效期 **/
    val expiresIn: Long,
    /** 令牌 **/
    val secret: String
)

本项目使用 EngineMain 方式启用服务，application.conf 中的配置如下。

ktor {
    deployment {
        port = 8090
    }

    application {
        modules = [cc.loac.ApplicationKt.module]
    }
}

/** 配置了 JWT 的一些默认设置 **/
jwt {
    issuer = "http://0.0.0.0:8090"
    domain = "http://0.0.0.0:8090"
    audience = "users"
    realm = "Nola"
}

2. JWT 插件

在 plugins 包中新建 Authentication.kt 文件，并写入以下内容，完成 JWT 配置。

package cc.loac.plugins

fun Application.configureSecurity(
    config: TokenConfig
) {
    // 配置应用的安全认证模块
    authentication {
        // 配置JWT（JSON Web Token）认证方式
        jwt {
            // 从 application.conf 中读取 realm 并设为当前 JWT 的 realm
            realm = this@configureSecurity.environment.config.property("jwt.realm").getString()
            // JWT 验证器
            verifier(
                JWT
                	// 使用 HMAC256 算法，并设置秘钥
                    .require(Algorithm.HMAC256(config.secret))
                    .withAudience(config.audience)
                    .withIssuer(config.issuer)
                    .build()
            )
            
		   // JWT 的有效性验证
            validate { credential ->
                // 检查 JWT 载荷中的 audience 是否包含 config.audience
                if (credential.payload.audience.contains(config.audience)) {
                    // 如果包含，则创建并返回一个对象，该对象封装了 JWT 的有效载荷信息
                    JWTPrincipal(credential.payload)
                    // 否则，返回null表示验证失败
                } else null
            }
        }
    }
}

3. 序列化插件

在 plugins 包中新建 Serialization.kt 文件，写入以下代码来配置序列化插件。

/** Serialization.kt **/
fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json()
    }
}

同时在 Application.kt 中启用该插件。

/** Application.kt **/
fun Application.module() {
    /** ... **/
    configureSerialization()
}

三、Token

在 security/token 包中新建 TokenClaim 数据类，用于存放令牌声明。

package cc.loac.security.token

data class TokenClaim(
    val name: String,
    val value: String
)

同时，在相同包下新建 TokenService 接口，里面有一个用于生成 Token 的抽象方法。

package cc.loac.security.token

interface TokenService {
    fun generate(config: TokenConfig, vararg claims: TokenClaim): String
}

最后，在当前包下新建 JwtTokenService 类，并实现 TokenService 接口。

package cc.loac.security.token

class JwtTokenService: TokenService {
    /**
     * 生成 JWT 令牌
     * @param config 令牌配置
     * @param claims Token Claim
     */
    override fun generate(config: TokenConfig, vararg claims: TokenClaim): String {
        // 初始化一个新的 JWT 实例
        var token = JWT.create()
            .withAudience(config.audience)
            .withIssuer(config.issuer)
            .withExpiresAt(Date(System.currentTimeMillis() + config.expiresIn))
        // 遍历所有自定义声明，并将它们添加到 JWT 中
        claims.forEach { claim ->
            token = token.withClaim(claim.name, claim.value)
        }
        // 使用 HMAC-SHA256 算法以及配置提供的密钥对 JWT 进行签名
        return token.sign(Algorithm.HMAC256(config.secret))
    }
}

四、盐值与哈希

在计算机科学，特别是在密码学和网络安全领域中，"salt"（盐）是一种用于增强密码哈希安全性的方式。当用户设置密码时，系统会生成一个唯一的随机字符串（即盐），并将这个盐与用户的原始密码进行混合（如拼接或使用特定算法处理），然后再通过哈希函数生成最终的哈希值存储在数据库中。

盐的主要作用有两点：

1. 防止彩虹表攻击：由于每个用户的密码哈希都添加了独一无二的盐，即使两个用户设置了相同的密码，其对应的哈希值也会因为盐的不同而不同，这样攻击者就无法直接利用预先计算好的哈希-密码对应表（即彩虹表）进行破解。
2. 增加预计算攻击难度：即使攻击者获取了所有加盐后的哈希值，为了破解每一个密码，他们必须对每一个单独的哈希值进行暴力破解或者字典攻击，因为盐的存在使得批量破解变得极其困难。

因此，在现代密码系统中，为用户密码添加盐是提高系统安全性的常见做法。

首先，在 security/hasing 包中新建 SaltedHash 数据类。

package cc.loac.security.hashing

/**
 * 盐、哈希数据类
 */
data class SaltedHash(
    val hash: String,
    val salt: String
)

而后，在当前包新建 HashingService 接口，该接口中有两个抽象方法，分别用于生成加盐哈希，和验证哈希。

package cc.loac.security.hashing

interface HashingService {
    fun generatedSaltedHash(value: String, saltLength: Int = 32): SaltedHash
    fun verify(value: String, saltedHash: SaltedHash): Boolean
}

最后，在当前包新建 SHA256HashingService 类，并实现 HashingService 接口。

package cc.loac.security.hashing

import org.apache.commons.codec.binary.Hex
import org.apache.commons.codec.digest.DigestUtils
import java.security.SecureRandom

class SHA256HashingService: HashingService {
    /**
     * 生成加盐哈希
     * @param value 待哈希的原始字符串数据
     * @param saltLength 盐的字节长度
     * @return 返回一个包含哈希值与盐值的 SaltedHash 对象
     */
    override fun generatedSaltedHash(value: String, saltLength: Int): SaltedHash {
        // 使用 SecureRandom 实例生成指定长度的安全随机盐值
        val salt = SecureRandom
        	// "SHA1PRNG" 是 Java 中的一个伪随机数生成器算法的名称
            .getInstance("SHA1PRNG")
            .generateSeed(saltLength)
        // 将盐值转换为十六进制字符串表示形式
        val saltAsHex = Hex.encodeHexString(salt)
        // 将盐值与原始数据拼接，并使用 SHA-256 算法计算其哈希值
        val hash = DigestUtils.sha256Hex("$saltAsHex$value")
        // 创建并返回包含哈希值与盐值的SaltedHash对象
        return SaltedHash(
            hash = hash,
            salt = saltAsHex
        )
    }

    /**
     * 验证哈希值是否匹配
     * @param value 待验证的原始字符串数据
     * @param saltedHash 包含已知哈希值与盐值的 SaltedHash 对象
     * @return 如果重新计算的哈希值与给定的哈希值一致，则返回 true，否则返回 false
     */
    override fun verify(value: String, saltedHash: SaltedHash): Boolean {
        // 将存储的盐值与待验证的数据拼接，再次计算哈希值并与原哈希比较
        return DigestUtils.sha256Hex("${saltedHash.salt}$value") == saltedHash.hash
    }
}

五、用户数据表

由于本文主要关注 JWT，故这里只简述一下用户表的字段和对用户表操作的方法。

当前项目采用 Exposed 框架作为 ORM，下面的单例类 User 即为用户表。

/**
 * 用户表
 * @author Loac
 * @version 1.0, 2024-01-08
 */
object Users : Table("user") {
    /** 用户 ID **/
    val id = integer("id").autoIncrement()
    /** 用户名 **/
    val name = varchar("name", 50)
    /** 电子邮箱 **/
    val email = varchar("email", 50)
    /** 显示名称 **/
    val displayName = varchar("display_name", 100)
    /** 密码 **/
    val password = varchar("password", 100)
    /** 盐值，用于加密密码 **/
    val salt = varchar("salt", 100)
    /** 描述 **/
    val description = varchar("description", 1000).nullable()
    /** 注册日期 **/
    val createDate = datetime("create_date")
    /** 头像地址 URL **/
    val avatar = varchar("avatar", 100).nullable()
    /** 用户角色 [UserRole] **/
    val role = enumerationByName<UserRole>("role", 20)
    override val primaryKey = PrimaryKey(id)
}

下面的接口展示了对用户表的几个操作。

interface UserDao {
    suspend fun allUsers(): List<User>
    suspend fun user(id: Int): User?
    suspend fun user(name: String): User?
    suspend fun addUser(user: User): User?
    suspend fun editUser(user: User): Boolean
    suspend fun deleteUser(id: Int): Boolean
}

六、后端接口

下面仅展示对应的登录、注册等操作具体操作的代码，不关注 Ktor 的路由配置。

1. 响应与请求

首先在 data/requests 与 data/responses 两个包中分别新建 AuthRequest 和 AuthResponse 数据类，方便 Ktor 将调用接口的参数直接包装为对象，以及返回 Token。

package cc.loac.data.requests

/**
* 验证请求数据类
* 相当于注册或登录请求接受 username 和 password 作为参数
*/
@Serializable
data class AuthRequest(
    val username: String,
    val password: String
)

package cc.loac.data.responses

@Serializable
data class AuthResponse(
    val token: String
)

2. 注册

fun Routing.userRouting(
    hashingService: HashingService,
    tokenService: TokenService,
    tokenConfig: TokenConfig
) {
    /** ... **/
    route("/user") {
        post {
            // 判断接口调用方是否正确传参 username 和 password
            val request = runCatching {
                call.receiveNullable<AuthRequest>()
            }.getOrNull() ?: run {
                // 参数有误，返回 Code 400 BadRequest
                call.respond(HttpStatusCode.BadRequest)
                return@post
            }
			
            // 对 username 和 password 进行合法性判断
            val areFieldsBlank = request.username.isBlank() ||
                    request.password.isBlank()
            val isPwTooShort = request.password.length < 8
            if (areFieldsBlank || isPwTooShort) {
                call.respond(HttpStatusCode.Conflict)
                return@post
            }

            // 将 password 进行加密操作
            val saltHash = hashingService.generatedSaltedHash(request.password)
            // 封装用户对象，包含了盐值和经过加密后的密码哈希
            val user = User(
                name = request.username,
                password = saltHash.hash,
                salt = saltHash.salt,
                email = "admin@loac.cc",
                displayName = "Loac",
                role = UserRole.SUPER_ADMIN
            )

            // 往数据库添加用户
            val wasAcknowledged = userDao.addUser(user)
            if (wasAcknowledged == null) {
                call.respond(HttpStatusCode.Conflict)
                return@post
            }

            call.respond(HttpStatusCode.OK)
        }
    }
}

3. 登录

fun Routing.userRouting(
    hashingService: HashingService,
    tokenService: TokenService,
    tokenConfig: TokenConfig
) {
    /** ... **/
    route("/user") {
        post("/login") {
            // 判断接口调用方是否正确传参 username 和 password
            val request = runCatching {
                call.receiveNullable<AuthRequest>()
            }.getOrNull() ?: run {
                // 参数有误，返回 Code 400 BadRequest
                call.respond(HttpStatusCode.BadRequest)
                return@post
            }

            // 根据 username 检索用户
            val user = userDao.user(request.username)
            // 用户不存在
            if (user == null) {
                call.respond(HttpStatusCode.Conflict, "非法用户名或密码")
                return@post
            }

            // 验证密码是否合法
            // 将 user.salt 和调用方传来的密码拼接哈希与 user.password 比对
            val isValidPassword = hashingService.verify(
                value = request.password,
                saltedHash = SaltedHash(
                    salt = user.salt,
                    hash = user.password
                )
            )

            // 密码错误
            if (!isValidPassword) {
                call.respond(HttpStatusCode.Conflict, "非法用户名或密码")
                return@post
            }

            // 密码正确，生成 Token 并签名
            val token = tokenService.generate(
                // 这里是一些 Token 配置，稍后会讲到配置内容
                config = tokenConfig,
                // 将 user.id 作为一个自定义声明与生成的 Token 绑定
                // 方便后面根据 Token 获取到对应的用户
                TokenClaim(
                    name = "userId",
                    value = user.id.toString()
                )
            )

            // 返回生成的 Token
            call.respond(
                status = HttpStatusCode.OK,
                message = AuthResponse(
                    token = token
                )
            )
        }
    }
}

4. 验证

这里再添加一个接口，用于测试调用方是否已经登录（传来的 Token 是否合法），如果调用方未登录，则响应 Code 401 Unauthorized，否则响应与当前 Token 绑定的用户 ID。

fun Routing.userRouting(...) {
    // 进行身份验证（是否携带合法 Token，验证方法看上面 JWT 插件配置）
    // 只有经过验证的请求才能访问此路由下的资源
    authenticate {
        // 没有经过验证的请求，无法访问此接口
        get("/secret") {
            // 从当前请求上下文中获取已验证用户的主体信息
            val principal = call.principal<JWTPrincipal>()
            // 检查并提取 JWT 令牌中的 userId 声明，如果存在则转换为 String 类型。
            val userId = principal?.getClaim("userId", String::class)
            // 如果 userId 存在，则返回一个包含消息的 HTTP 响应，状态码为 200 OK。
            call.respond(HttpStatusCode.OK, "Your userId is $userId")
        }
    }
}

七、启用插件和路由

下面将在 Ktor 服务入口处，启用 JWT 插件和路由。

/** Application.kt **/
package cc.loac

fun main(args: Array<String>): Unit = EngineMain.main(args)

fun Application.module() {
    // 初始化数据库
    DatabaseSingleton.init()

    // 用于生成 Token 令牌
    val tokenService = JwtTokenService()
    
    // 令牌配置
    val tokenConfig = TokenConfig(
        // 此处的 jwt.issuer、jwt.audience 为 application.conf 中的参数，请看上面 二、配置插件
        issuer = environment.config.property("jwt.issuer").getString(),
        audience = environment.config.property("jwt.audience").getString(),
        // Token 过期时间 24 小时
        expiresIn = 24 * 1000 * 60 * 60,
        // 秘钥通过环境变量的方式传入，例如：JWT_SECRET=test
        secret = System.getenv("JWT_SECRET")
    )
    
    // 用于生成和验证加盐哈希
    val hashingService = SHA256HashingService()

    // 配置 JWT 插件
    configureSecurity(tokenConfig)
    // 配置序列化插件
    configureSerialization()
    // 配置 Ktor 路由
    configureRouting(hashingService, tokenService, tokenConfig)
}

八、测试

1. 注册用户

2. 尝试调用需验证的接口

可以看到，在还没有登录的情况下，访问 /secret 响应了 Code 401 Unauthorized，提示未经授权。

3. 登录

在用户名和密码正确的情况下，Ktor 响应了 Code 200 OK 并返回了 Token。

4. 携 Token 调用需要验证的接口

在 Header 中填写了正确的 Token，调用 /secret 接口成功返回了当前 Token 绑定的用户的用户 ID。