Ktor Server의 폼 기반 인증
필수 의존성: io.ktor:ktor-server-auth
코드 예제: auth-form-html-dsl, auth-form-session
네이티브 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅
폼 기반 인증(Form-based authentication)은 웹 폼을 사용하여 자격 증명 정보를 수집하고 사용자를 인증합니다. Ktor에서 웹 폼을 생성하려면 HTML DSL을 사용하거나 FreeMarker, Velocity 등과 같은 JVM 템플릿 엔진 중 하나를 선택할 수 있습니다.
폼 기반 인증을 사용할 때 사용자 이름과 비밀번호는 평문(clear text)으로 전달되므로, 민감한 정보를 보호하려면 HTTPS/TLS를 사용해야 합니다.
의존성 추가
form 인증을 활성화하려면 빌드 스크립트에 ktor-server-auth 아티팩트를 포함해야 합니다:
implementation(ktorLibs.server.auth)implementation ktorLibs.server.auth<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>폼 기반 인증 흐름
폼 기반 인증 흐름은 다음과 같습니다:
인증되지 않은 클라이언트가 서버 애플리케이션의 특정 라우트로 요청을 보냅니다.
서버는 사용자에게 사용자 이름과 비밀번호를 입력하도록 요청하는 최소한의 HTML 기반 웹 폼으로 구성된 HTML 페이지를 반환합니다.
Ktor에서는 Kotlin DSL을 사용하여 폼을 작성할 수 있으며, FreeMarker, Velocity 등 다양한 JVM 템플릿 엔진 중에서 선택할 수도 있습니다.
사용자가 사용자 이름과 비밀번호를 제출하면 클라이언트는 웹 폼 데이터(사용자 이름과 비밀번호 포함)가 포함된 요청을 서버로 전송합니다.
kotlinPOST http://localhost:8080/login Content-Type: application/x-www-form-urlencoded username=jetbrains&password=foobarKtor에서는 사용자 이름과 비밀번호를 가져오는 데 사용되는 매개변수 이름을 지정해야 합니다.
서버는 클라이언트가 전송한 자격 증명을 검증하고 요청된 콘텐츠로 응답합니다.
form 인증 설치
form 인증 제공자를 설치하려면 install 블록 내에서 form 함수를 호출합니다:
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
form {
// form 인증 구성
}
}선택적으로 지정된 라우트를 인증하는 데 사용할 수 있는 제공자 이름을 지정할 수도 있습니다.
form 인증 구성
1단계: form 제공자 구성
form 인증 제공자는 FormAuthenticationProvider.Config 클래스를 통해 설정을 노출합니다. 아래 예제에서는 다음 설정들이 지정되어 있습니다:
userParamName및passwordParamName프로퍼티는 사용자 이름과 비밀번호를 가져오는 데 사용되는 매개변수 이름을 지정합니다.validate함수는 사용자 이름과 비밀번호를 검증합니다.validate함수는UserPasswordCredential을 확인하고 인증에 성공한 경우UserIdPrincipal을 반환하며, 인증에 실패한 경우null을 반환합니다.challenge함수는 인증에 실패했을 때 수행할 동작을 지정합니다. 예를 들어 로그인 페이지로 다시 리디렉션하거나 UnauthorizedResponse를 전송할 수 있습니다.
install(Authentication) {
form("auth-form") {
userParamName = "username"
passwordParamName = "password"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) {
UserIdPrincipal(credentials.name)
} else {
null
}
}
challenge {
val message = "Credentials are not valid"
val status = HttpStatusCode.Unauthorized
call.respond(status, message)
}
}
}타입 안전(type-safe) 인증 체계 API는 실험적(experimental) 기능입니다. 언제든지 제거되거나 변경될 수 있습니다. 사용하려면 옵트인(opt-in)이 필요합니다. 자세한 내용은 타입 안전 인증 문서를 참조하세요.
form() 함수는 선택한 principal 타입에 대한 스키마를 생성합니다. 별도의 install(Authentication) 단계는 없으며, 이 스키마는 해당 스키마가 필요한 라우트에 전달하는 값입니다.
data class User(val name: String)
val formAuth = form<User>("auth-form") {
usernameField = "username"
passwordField = "password"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) User(credentials.name) else null
}
onUnauthorized = {
val message = "Credentials are not valid"
call.respond(HttpStatusCode.Unauthorized, message)
}
}클래식 제공자와 비교해 두 가지 이름이 다릅니다. 폼 필드는 userParamName 및 passwordParamName 대신 usernameField와 passwordField를 사용합니다. 실패 핸들러는 challenge 대신 onUnauthorized를 사용합니다. 전체 API에 대해서는 타입 안전 인증을 참조하세요.
basic 인증과 마찬가지로, 사용자 이름과 비밀번호 해시를 보관하는 인메모리 테이블에 저장된 사용자를 검증하기 위해 UserHashedTableAuth를 사용할 수도 있습니다.
2단계: 특정 리소스 보호
form 제공자를 구성한 후 데이터가 전송될 post 라우트를 정의해야 합니다. 그런 다음 이 라우트를 authenticate 함수 내부에 추가합니다. 인증에 성공하면 라우트 핸들러 내에서 call.principal 함수를 사용하여 인증된 UserIdPrincipal을 가져오고 인증된 사용자의 이름을 얻을 수 있습니다.
routing {
authenticate("auth-form") {
post("/login") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}폼 데이터가 전송되는 post 라우트를 정의하고, 이를 authenticateWith()로 감쌉니다. 블록 내부에서 call.principal은 사용자가 정의한 principal 타입이며 절대 null이 되지 않습니다:
routing {
authenticateWith(formAuth) {
post("/login") {
call.respondText("Hello, ${call.principal.name}!")
}
}
}세션 인증을 사용하여 로그인한 사용자의 ID를 저장할 수 있습니다. 예를 들어 사용자가 웹 폼을 통해 처음 로그인할 때 사용자 이름을 쿠키 세션에 저장하고, 이후의 요청에서는 session 제공자를 사용하여 이 사용자를 인가할 수 있습니다.
