타입 안전한 인증
필수 의존성: io.ktor:ktor-server-auth
Ktor는 인증 스킴을 프린시펄 타입에 바인딩하는 타입 안전한 인증 스킴 API를 제공합니다. 스킴을 한 번 생성한 후 라우트에 전달하면, 타입 캐스팅이나 null 검사 없이 프린시펄을 읽을 수 있습니다.
이 API는 install(Authentication) 방식의 대안입니다. 동일한 애플리케이션에서 두 API를 모두 사용할 수 있으며, 한 API를 사용하는 라우트를 다른 API를 사용하는 라우트 안에 중첩할 수도 있습니다.
의존성 추가
타입 기반 인증을 사용하려면 빌드 스크립트에 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>jwt 스킴을 사용하는 경우, ktor-server-auth-jwt 아티팩트를 추가하세요.
implementation(ktorLibs.server.auth.jwt)implementation ktorLibs.server.auth.jwt<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-jwt-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>apiKey 스킴을 사용하는 경우, ktor-server-auth-api-key 아티팩트를 추가하세요.
implementation(ktorLibs.server.auth.apiKey)implementation ktorLibs.server.auth.apiKey<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-auth-api-key-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>API 활성화
이 API에는 @ExperimentalKtorApi가 지정되어 있으므로 명시적으로 opt-in해야 합니다.
@OptIn(ExperimentalKtorApi::class)
fun Application.module() {
// ...
}라우트 빌더는 Kotlin 컨텍스트 파라미터(context parameters)를 사용합니다. Kotlin 2.4.0부터는 컨텍스트 파라미터가 기본적으로 활성화되어 있습니다. Kotlin 2.2.x 또는 2.3.x를 사용하는 경우 빌드 스크립트에서 활성화하세요.
kotlin {
compilerOptions {
freeCompilerArgs.add("-Xcontext-parameters")
}
}프린시펄 정의
프린시펄(principal)은 애플리케이션이 인증된 호출자와 연결하는 신원(identity) 또는 기타 정보를 나타냅니다. 프린시펄 타입은 null을 허용하지 않는(non-null) 타입이어야 합니다.
data class User(
val id: String,
val email: String
)스킴 생성
각 인증 방식은 프린시펄 타입, 이름, 설정 블록을 인자로 받는 팩토리 함수를 제공합니다. validate {} 블록은 자격 증명이 유효하면 프린시펄 타입을 반환하고, 거부되면 null을 반환합니다.
val jwtAuth = jwt<User>("my-jwt") {
realm = "my-app"
verifier(jwkProvider, issuer)
validate { credential ->
val payload = credential.payload
User(
id = payload.subject,
email = payload.getClaim("email").asString()
)
}
}팩토리는 값을 반환합니다. 이 값을 저장해 두고 해당 인증이 필요한 라우트에 전달하세요.
| 팩토리 | 아티팩트 | 참고 사항 |
|---|---|---|
basic<P>() | ktor-server-auth | Ktor Server의 Basic 인증 참조 |
digest<P>() | ktor-server-auth | JVM 전용. Ktor Server의 Digest 인증 참조 |
bearer<P>() | ktor-server-auth | Ktor Server의 Bearer 인증 참조 |
form<P>() | ktor-server-auth | Ktor Server의 Form 기반 인증 참조 |
session<S, P>() | ktor-server-auth | 타입 안전한 세션 인증 참조 |
apiKey<P>() | ktor-server-auth-api-key | API Key 인증 참조 |
jwt<P>() | ktor-server-auth-jwt | JVM 전용. JSON Web Tokens 참조 |
oauth2(), oauth2Session<P, S>() | ktor-server-auth | OAuth 2.0 플로우 참조 |
스킴 이름은 고유해야 합니다. 동일한 이름으로 서로 다른 두 스킴을 생성하면 라우트에서 해당 스킴을 사용하려고 할 때 두 번째 스킴에서 오류가 발생합니다.
라우트 보호
라우트를 보호하려면 authenticateWith() 함수에 스킴을 전달하세요. 해당 블록 내에서 call.principal은 스킴에서 정의한 프린시펄 타입을 가지며, null이 아님이 보장됩니다.
routing {
authenticateWith(jwtAuth) {
get("/profile") {
val user: User = call.principal
call.respondText(user.email)
}
}
}인증을 선택 사항으로 만들기
로그인한 호출자와 익명 호출자 모두에게 라우트를 제공해야 하는 경우 authenticateWithOptional() 함수를 사용하세요. 블록 내부에서는 call.principalOrNull을 사용하여 프린시펄에 접근합니다.
routing {
authenticateWithOptional(jwtAuth) {
get("/me") {
val user = call.principalOrNull
call.respondText(user?.email ?: "anonymous")
}
}
}자격 증명이 없는 요청은 성공하며 call.principalOrNull은 null이 됩니다. 유효하지 않은 자격 증명이 포함된 요청은 여전히 실패합니다.
여러 스킴 허용
동일한 라우트에서 둘 이상의 스킴을 허용하려면 authenticateWithAnyOf() 함수를 사용하세요. Ktor는 나열된 순서대로 스킴을 시도하며, 가장 먼저 성공한 스킴이 프린시펄을 제공합니다.
모든 스킴은 호출 시 선언한 공통 타입에 맞는 프린시펄을 생성해야 합니다.
interface AppUser {
val email: String
}
data class JwtUser(
override val email: String,
val id: String
) : AppUser
data class ApiUser(override val email: String) : AppUser
val jwtScheme = jwt<JwtUser>("my-jwt") { /* ... */ }
val apiKeyScheme = apiKey<ApiUser>("my-api-key") { /* ... */ }
routing {
// AppUser is
authenticateWithAnyOf<AppUser>(jwtScheme, apiKeyScheme) {
get("/profile") {
call.respondText(call.principal.email)
}
}
}authenticateWithAnyOf() 내부에서는 call.principal만 사용할 수 있습니다. 세션 스킴의 call.session과 같이 단일 스킴에만 속한 추가 속성은 사용할 수 없습니다.
익명 호출자 허용
자격 증명이 없는 호출자에게 서비스를 제공하는 스킴을 구성하려면 orAnonymous() 함수를 사용하세요. 자격 증명이 없는 요청은 블록이 반환하는 프린시펄을 받게 됩니다. 유효하지 않은 자격 증명이 포함된 요청은 여전히 실패합니다.
그 결과 두 타입의 공통 상위 타입을 프린시펄 타입으로 갖는 스킴이 생성됩니다.
interface Identity
data class AuthenticatedUser(val id: String) : Identity
data class GuestUser(val label: String = "guest") : Identity
val feedAuth = jwt<AuthenticatedUser>("my-jwt") {
verifier(jwkProvider, issuer)
validate { credential ->
AuthenticatedUser(credential.payload.subject)
}
}.orAnonymous { GuestUser() }
routing {
authenticateWith(feedAuth) {
get("/feed") {
when (val user = call.principal) {
is AuthenticatedUser ->
call.respondText(user.id)
is GuestUser ->
call.respondText(user.label)
}
}
}
}프린시펄 변환
데이터베이스에서 사용자 레코드를 로드하는 등의 작업을 통해 프린시펄을 다른 타입으로 변환하려면 mapPrincipal() 함수를 사용하세요.
data class AppUser(val id: String, val email: String)
val appAuth = jwtAuth.mapPrincipal { jwtUser ->
userDirectory.find(jwtUser.id)?.let { row ->
AppUser(id = row.id, email = row.email)
}
}변환은 스킴이 프린시펄을 성공적으로 생성한 후에만 실행됩니다. 변환 결과가 null을 반환하면 요청은 401 Unauthorized로 거부됩니다.
역할 확인
역할(role) 확인은 선택적으로 활성화(opt-in)할 수 있습니다. AuthenticationRole을 구현하는 역할 타입을 정의한 후, withRoles()를 사용하여 역할을 인식하는 스킴을 만드세요.
enum class Role : AuthenticationRole {
User, Admin, Moderator
}
val roleAuth = jwtAuth.withRoles { user ->
roleService.resolveRoles(user.id)
}withRoles {} 블록은 인증이 성공한 후 모든 요청마다 실행됩니다. 이를 사용하여 데이터베이스, 캐시 또는 프린시펄 자체에서 역할을 로드할 수 있습니다.
roles 파라미터를 사용하여 라우트에 필요한 역할을 선언하세요.
routing {
authenticateWith(roleAuth, roles = setOf(Role.Admin)) {
get("/admin") {
val userRoles: Set<Role> = call.principal.roles
call.respondText(userRoles.joinToString { it.name })
}
}
}인증에는 성공했지만 필수 역할이 없는 호출자는 403 Forbidden을 받습니다. 호출자는 집합에 포함된 역할 중 하나만이 아니라 모든 역할을 가지고 있어야 합니다.
역할을 필수로 요구하지 않고 확인(해결)만 하려면 roles = null을 전달하세요. 이는 핸들러 자체에서 판단해야 할 때 유용합니다.
authenticateWith(roleAuth, roles = null) {
get("/dashboard") {
if (Role.Admin in call.principal.roles) {
call.respondText("admin view")
} else {
call.respondText("user view")
}
}
}roles 프로퍼티는 역할을 인식하는 라우트 내부에서만 존재합니다. 일반 스킴으로 보호되는 라우트에서는 컴파일되지 않습니다.
실패 처리
발생할 수 있는 오류는 두 가지가 있으며, 각각 별도로 처리됩니다.
onUnauthorized: 인증에 실패할 때 실행됩니다. 기본 응답은401 Unauthorized입니다.onForbidden: 인증에는 성공했지만 호출자에게 필수 역할이 없을 때 실행됩니다. 기본 응답은403 Forbidden입니다.
스킴에 핸들러를 설정하여 해당 스킴을 사용하는 모든 라우트에 적용할 수 있습니다.
val jwtAuth = jwt<User>("my-jwt") {
verifier(jwkProvider, issuer)
validate { credential -> /* ... */ }
onUnauthorized = { cause ->
val message = cause.toString()
call.respond(HttpStatusCode.Unauthorized, message)
}
}
val roleAuth = jwtAuth.withRoles(
onForbidden = {
val forbidden = HttpStatusCode.Forbidden
call.respondText("Not allowed", status = forbidden)
}
) { user ->
roleService.resolveRoles(user.id)
}또는 단일 라우트에 핸들러를 설정하여 스킴 수준의 핸들러를 재정의(override)할 수도 있습니다.
authenticateWith(
roleAuth,
roles = setOf(Role.Admin),
onUnauthorized = { call.respondRedirect("/login") },
onForbidden = {
val forbidden = HttpStatusCode.Forbidden
call.respondText("Admins only", status = forbidden)
},
) {
get("/admin") {
call.respondText(call.principal.email)
}
}Ktor는 다음 순서대로 인증되지 않음(unauthorized) 핸들러를 찾습니다.
authenticateWith()에 전달된 핸들러.- 스킴에 구성된
onUnauthorized핸들러. - 프로바이더의 기본 챌린지.
아무것도 응답하지 않으면 요청은 401 Unauthorized로 실패합니다.
authenticateWithAnyOf()의 경우, 핸들러가 스킴 이름과 실패 원인의 맵(map)을 수신하므로 각 스킴이 실패한 이유를 알릴 수 있습니다.
authenticateWithAnyOf<AppUser>(
jwtScheme,
apiKeyScheme,
onUnauthorized = { failures ->
val schemes = failures.keys.joinToString()
call.respond(HttpStatusCode.Unauthorized, schemes)
}
) {
get("/profile") { /* ... */ }
}기존 API와 결합하기
두 인증 API를 동일한 애플리케이션에서 함께 사용할 수 있습니다. 이름 기반 프로바이더 API로 보호되는 라우트 안에 타입 안전한 라우트를 중첩하거나, 타입 안전한 라우트 안에 프로바이더 기반 라우트를 중첩할 수 있습니다.
routing {
authenticate("auth-session") {
authenticateWith(basicAuth) {
get("/admin") {
val basicUser = call.principal
val sessionUser =
checkNotNull(call.principal<SessionUser>())
if (basicUser.name == sessionUser.name) {
call.respondText("You are ${basicUser.name}!")
} else {
call.respondText("Who are you?")
}
}
}
}
authenticate(basicAuth.name) {
get("/hello") {
val user = checkNotNull(call.principal<BasicUser>())
call.respondText("Hello ${user.name}!")
}
}
}중첩된 인증 레이어는 순서대로 적용됩니다.
제한 사항
- 이 API는 실험적(experimental)입니다. 마이너 릴리스에서 변경될 수 있습니다.
- 이 API는 Kotlin 컨텍스트 파라미터를 사용하므로 Kotlin 2.4.0 또는
-Xcontext-parameters컴파일러 옵션이 필요합니다. authenticateWithAnyOf()함수는call.principal만 제공합니다.call.session과 같은 스킴 전용 프로퍼티는 그 내부에서 사용할 수 없습니다.- LDAP 프로바이더에 해당하는 타입 안전한 대체 기능은 없습니다. 대신 타입 기반
validate {}블록 내부에서ldapAuthenticate()를 호출하세요.
