JSON Web Token
필수 종속성: io.ktor:ktor-server-auth, io.ktor:ktor-server-auth-jwt
코드 예제: auth-jwt-hs256, auth-jwt-rs256
Native 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✖️
JSON Web Token(JWT)은 당사자 간에 정보를 JSON 객체로 안전하게 전송하기 위한 방법을 정의하는 개방형 표준입니다. 이 정보는 공유 비밀 키(HS256 알고리즘) 또는 공개 키/개인 키 쌍(예: RS256)을 사용하여 서명되므로 검증하고 신뢰할 수 있습니다.
Ktor는 Bearer 스키마를 사용하여 Authorization 헤더로 전달된 JWT를 처리하며 다음과 같은 작업을 수행할 수 있습니다.
- JSON Web Token의 서명 검증
- JWT 페이로드에 대한 추가 유효성 검사 수행
Ktor의 인증 및 권한 부여에 관한 일반적인 정보는 Ktor Server의 인증 및 권한 부여 섹션에서 확인할 수 있습니다.
토큰이 OpenID Connect 제공자로부터 오는 경우, Oidc 플러그인이 발급자(issuer) URL에서 JWKS 엔드포인트를 확인하고 키가 교체될 때 이를 갱신하므로 JwkProvider를 직접 구성할 필요가 없습니다. 또한 액세스 토큰으로 제시된 ID 토큰을 거부합니다. 자세한 내용은 OpenID Connect 리소스 서버를 참조하세요.
종속성 추가
JWT 인증을 활성화하려면 빌드 스크립트에 ktor-server-auth 및 ktor-server-auth-jwt 아티팩트를 포함해야 합니다.
implementation("io.ktor:ktor-server-auth:$ktor_version")
implementation("io.ktor:ktor-server-auth-jwt:$ktor_version")implementation "io.ktor:ktor-server-auth:$ktor_version"
implementation "io.ktor:ktor-server-auth-jwt:$ktor_version"<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>
<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jwt-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>JWT 인증 흐름
Ktor에서의 JWT 인증 흐름은 다음과 같습니다.
- 클라이언트가 자격 증명(credentials)을 포함하여 서버 애플리케이션의 특정 인증 라우트로
POST요청을 보냅니다. 아래 예제는 JSON으로 전달된 자격 증명을 포함한 HTTP 클라이언트POST요청을 보여줍니다.HTTPPOST http://localhost:8080/login Content-Type: application/json { "username": "jetbrains", "password": "foobar" } - 자격 증명이 유효하면 서버는 JSON Web Token을 생성하고 지정된 알고리즘으로 서명합니다. 예를 들어 특정 공유 비밀 키를 사용하는
HS256이거나 공개 키/개인 키 쌍을 사용하는RS256일 수 있습니다. - 서버가 생성된 JWT를 클라이언트에 전송합니다.
- 이제 클라이언트는
Bearer스키마를 사용하여Authorization헤더에 JSON Web Token을 전달함으로써 보호된 리소스에 요청을 보낼 수 있습니다.HTTPGET http://localhost:8080/hello Authorization: Bearer {{auth_token}} - 서버가 요청을 수신하고 다음과 같은 검증을 수행합니다.
- 유효성 검사가 완료되면 서버는 보호된 리소스의 콘텐츠로 응답합니다.
JWT 설치
jwt 인증 제공자를 설치하려면 install 블록 내부에서 jwt 함수를 호출합니다.
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.auth.jwt.*
//...
install(Authentication) {
jwt {
// jwt 인증 구성
}
}선택적으로 지정된 라우트를 인증하는 데 사용할 수 있는 제공자 이름을 지정할 수 있습니다.
JWT 구성
이 섹션에서는 서버 Ktor 애플리케이션에서 JSON Web Token을 사용하는 방법을 살펴봅니다. 토큰을 검증하는 방식이 서로 다르기 때문에 토큰 서명에 대한 두 가지 접근 방식을 보여줍니다.
- 지정된 공유 비밀 키와 함께
HS256사용. - 공개 키/개인 키 쌍과 함께
RS256사용.
전체 프로젝트는 auth-jwt-hs256, auth-jwt-rs256에서 확인할 수 있습니다.
1단계: JWT 설정 구성
JWT 관련 설정을 구성하기 위해 구성 파일에 사용자 정의 jwt 그룹을 생성할 수 있습니다. 예를 들어 application.conf 파일은 다음과 같을 수 있습니다.
jwt {
secret = "secret"
issuer = "http://0.0.0.0:8080/"
audience = "http://0.0.0.0:8080/hello"
realm = "Access to 'hello'"
}jwt {
privateKey = "MIIBVQIBADANBgkqhkiG9w0BAQEFAASCAT8wggE7AgEAAkEAtfJaLrzXILUg1U3N1KV8yJr92GHn5OtYZR7qWk1Mc4cy4JGjklYup7weMjBD9f3bBVoIsiUVX6xNcYIr0Ie0AQIDAQABAkEAg+FBquToDeYcAWBe1EaLVyC45HG60zwfG1S4S3IB+y4INz1FHuZppDjBh09jptQNd+kSMlG1LkAc/3znKTPJ7QIhANpyB0OfTK44lpH4ScJmCxjZV52mIrQcmnS3QzkxWQCDAiEA1Tn7qyoh+0rOO/9vJHP8U/beo51SiQMw0880a1UaiisCIQDNwY46EbhGeiLJR1cidr+JHl86rRwPDsolmeEF5AdzRQIgK3KXL3d0WSoS//K6iOkBX3KMRzaFXNnDl0U/XyeGMuUCIHaXv+n+Brz5BDnRbWS+2vkgIe9bUNlkiArpjWvX+2we"
issuer = "http://0.0.0.0:8080/"
audience = "http://0.0.0.0:8080/hello"
realm = "Access to 'hello'"
}비밀 정보는 구성 파일에 일반 텍스트(plain text)로 저장해서는 안 됩니다. 이러한 매개변수를 지정할 때는 환경 변수를 사용하는 것을 고려하세요.
코드에서 이러한 설정에 액세스하려면 다음과 같이 합니다.
val jwtConfig = environment.config
val secret = jwtConfig.property("jwt.secret").getString()
val issuer = jwtConfig.property("jwt.issuer").getString()
val audience = jwtConfig
.property("jwt.audience").getString()
val myRealm = jwtConfig.property("jwt.realm").getString()val jwtConfig = environment.config
val privateKeyString = jwtConfig
.property("jwt.privateKey").getString()
val issuer = jwtConfig.property("jwt.issuer").getString()
val audience = jwtConfig
.property("jwt.audience").getString()
val myRealm = jwtConfig.property("jwt.realm").getString()2단계: 토큰 생성
JSON Web Token을 생성하려면 JWTCreator.Builder를 사용할 수 있습니다. 아래 코드 스니펫은 HS256 및 RS256 알고리즘 모두에 대해 이를 수행하는 방법을 보여줍니다.
post("/login") {
val user = call.receive<User>()
// 사용자 이름 및 비밀번호 확인
// ...
val expiresAt = System.currentTimeMillis() + 60000
val token = JWT.create()
.withAudience(audience)
.withIssuer(issuer)
.withClaim("username", user.username)
.withExpiresAt(Date(expiresAt))
.sign(Algorithm.HMAC256(secret))
call.respond(hashMapOf("token" to token))
}post("/login") {
val user = call.receive<User>()
// 사용자 이름 및 비밀번호 확인
// ...
val keyId = "6f8856ed-9189-488f-9011-0ff4b6c08edc"
val publicKey = jwkProvider.get(keyId).publicKey
val decoded = Base64.getDecoder()
.decode(privateKeyString)
val keySpecPKCS8 = PKCS8EncodedKeySpec(decoded)
val privateKey = KeyFactory.getInstance("RSA")
.generatePrivate(keySpecPKCS8)
val algorithm = Algorithm.RSA256(
publicKey as RSAPublicKey,
privateKey as RSAPrivateKey
)
val expiresAt = System.currentTimeMillis() + 60000
val token = JWT.create()
.withAudience(audience)
.withIssuer(issuer)
.withClaim("username", user.username)
.withExpiresAt(Date(expiresAt))
.sign(algorithm)
call.respond(hashMapOf("token" to token))
}post("/login")은POST요청을 수신하기 위한 인증 라우트를 정의합니다.call.receive<User>()는 JSON 객체로 전송된 사용자 자격 증명을 수신하여User클래스 객체로 변환합니다.JWT.create()는 지정된 JWT 설정으로 토큰을 생성하고, 수신된 사용자 이름을 담은 커스텀 클레임을 추가한 후 지정된 알고리즘으로 토큰을 서명합니다.HS256의 경우 공유 비밀 키를 사용하여 토큰을 서명합니다.RS256의 경우 공개 키/개인 키 쌍을 사용합니다.
call.respond는 토큰을 JSON 객체로 클라이언트에 전송합니다.
3단계: Realm 구성
realm 속성을 사용하면 보호된 라우트에 접근할 때 WWW-Authenticate 헤더에 전달될 realm을 설정할 수 있습니다.
val myRealm = jwtConfig.property("jwt.realm").getString()
install(Authentication) {
jwt("auth-jwt") {
realm = myRealm
}
}4단계: 토큰 검증자(Verifier) 구성
verifier 함수를 사용하면 토큰 형식과 서명을 검증할 수 있습니다.
HS256의 경우 토큰을 검증하기 위해 JWTVerifier 인스턴스를 전달해야 합니다.RS256의 경우 토큰 검증에 사용되는 공개 키에 접근하기 위한 JWKS 엔드포인트를 지정하는 JwkProvider를 전달해야 합니다. 본 예제에서는 발급자가http://0.0.0.0:8080이므로 JWKS 엔드포인트 주소는http://0.0.0.0:8080/.well-known/jwks.json이 됩니다.
val jwtConfig = environment.config
val secret = jwtConfig.property("jwt.secret").getString()
val issuer = jwtConfig.property("jwt.issuer").getString()
val audience = jwtConfig
.property("jwt.audience").getString()
val myRealm = jwtConfig.property("jwt.realm").getString()
install(Authentication) {
jwt("auth-jwt") {
realm = myRealm
verifier(JWT
.require(Algorithm.HMAC256(secret))
.withAudience(audience)
.withIssuer(issuer)
.build())
}
}val issuer = jwtConfig.property("jwt.issuer").getString()
val audience = jwtConfig
.property("jwt.audience").getString()
val myRealm = jwtConfig.property("jwt.realm").getString()
val jwkProvider = JwkProviderBuilder(issuer)
.cached(10, 24, TimeUnit.HOURS)
.rateLimited(10, 1, TimeUnit.MINUTES)
.build()
install(Authentication) {
jwt("auth-jwt") {
realm = myRealm
verifier(jwkProvider, issuer) {
acceptLeeway(3)
}
}
}5단계: JWT 페이로드 검증
validate함수를 사용하면 JWT 페이로드에 대한 유효성 검사를 수행할 수 있습니다. 이 함수는 필수 항목입니다. 이를 구성하지 않으면 제공자 초기화 시IllegalArgumentException이 발생합니다. JWTCredential 객체를 나타내며 JWT 페이로드를 포함하는credential매개변수를 확인하세요. 아래 예제에서는 커스텀username클레임의 값을 확인합니다.kotlininstall(Authentication) { jwt("auth-jwt") { validate { credential -> val payload = credential.payload val claim = payload.getClaim("username") if (claim.asString() != "") { JWTPrincipal(credential.payload) } else { null } } } }인증에 성공한 경우 JWTPrincipal을 반환합니다.
challenge함수를 사용하면 인증이 실패했을 때 전송할 응답을 구성할 수 있습니다.kotlininstall(Authentication) { jwt("auth-jwt") { challenge { defaultScheme, realm -> val text = "Token is not valid or has expired" val status = HttpStatusCode.Unauthorized call.respond(status, text) } } }
타입 안전(type-safe) 인증 스키마 API는 실험적(experimental) 기능입니다. 언제든지 제거되거나 변경될 수 있습니다. 선택적 활성화(Opt-in)가 필요합니다. 자세한 내용은 타입 안전 인증 문서를 참조하세요.
jwt() 함수는 원하는 프린시펄(principal) 타입에 대한 스키마를 생성합니다. install(Authentication) 단계가 필요하지 않으며, 스키마는 이를 필요로 하는 라우트에 전달하는 값입니다.
validate 내부에서 필요한 클레임을 읽고 자체 타입을 반환합니다. 그러면 라우트 핸들러는 JWTPrincipal 대신 해당 타입으로 작업합니다.
data class User(val username: String, val expiresAt: Long?)
val jwtAuth = jwt<User>("auth-jwt") {
realm = myRealm
verifier(
JWT.require(Algorithm.HMAC256(secret))
.withAudience(audience)
.withIssuer(issuer)
.build()
)
validate { credential ->
val payload = credential.payload
val username = payload.getClaim("username").asString()
if (username != "") {
User(username, credential.expiresAt?.time)
} else {
null
}
}
onUnauthorized = {
val message = "Token is not valid or has expired"
call.respond(HttpStatusCode.Unauthorized, message)
}
}실패 핸들러는 challenge 대신 onUnauthorized입니다. 전체 API는 타입 안전 인증을 참조하세요.
6단계: 특정 리소스 보호
jwt 제공자를 구성한 후에는 authenticate 함수를 사용하여 애플리케이션의 특정 리소스를 보호할 수 있습니다. 인증에 성공한 경우 라우트 핸들러 내부에서 call.principal 함수를 사용하여 인증된 JWTPrincipal을 검색하고 JWT 페이로드를 가져올 수 있습니다. 아래 예제에서는 커스텀 username 클레임의 값과 토큰 만료 시간을 검색합니다.
routing {
authenticate("auth-jwt") {
get("/hello") {
val principal = call.principal<JWTPrincipal>()
val payload = principal!!.payload
val username = payload.getClaim("username")
.asString()
val now = System.currentTimeMillis()
val expiresAt = principal.expiresAt?.time
?.minus(now)
call.respondText(
"Hello, $username! " +
"Token is expired at $expiresAt ms."
)
}
}
}스키마를 authenticateWith()에 전달합니다. 클레임은 이미 validate에서 읽었으므로 핸들러는 자체 타입으로 작동하며 null 체크가 필요하지 않습니다.
routing {
authenticateWith(jwtAuth) {
get("/hello") {
val user = call.principal
val now = System.currentTimeMillis()
val expiresIn = user.expiresAt?.minus(now)
call.respondText(
"Hello, ${user.username}! " +
"Token is expired at $expiresIn ms."
)
}
}
}