Skip to content
Experimental

타입 안전한 인증

필수 의존성: io.ktor:ktor-server-auth

Ktor는 인증 스킴을 프린시펄 타입에 바인딩하는 타입 안전한 인증 스킴 API를 제공합니다. 스킴을 한 번 생성한 후 라우트에 전달하면, 타입 캐스팅이나 null 검사 없이 프린시펄을 읽을 수 있습니다.

이 API는 install(Authentication) 방식의 대안입니다. 동일한 애플리케이션에서 두 API를 모두 사용할 수 있으며, 한 API를 사용하는 라우트를 다른 API를 사용하는 라우트 안에 중첩할 수도 있습니다.

의존성 추가 ​

타입 기반 인증을 사용하려면 빌드 스크립트에 ktor-server-auth 아티팩트를 추가하세요.

kotlin
implementation(ktorLibs.server.auth)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.server.auth
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

jwt 스킴을 사용하는 경우, ktor-server-auth-jwt 아티팩트를 추가하세요.

kotlin
implementation(ktorLibs.server.auth.jwt)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.server.auth.jwt
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth-jwt-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

apiKey 스킴을 사용하는 경우, ktor-server-auth-api-key 아티팩트를 추가하세요.

kotlin
implementation(ktorLibs.server.auth.apiKey)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.server.auth.apiKey
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-auth-api-key-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

API 활성화 ​

이 API에는 @ExperimentalKtorApi가 지정되어 있으므로 명시적으로 opt-in해야 합니다.

kotlin
@OptIn(ExperimentalKtorApi::class)
fun Application.module() {
    // ...
}

라우트 빌더는 Kotlin 컨텍스트 파라미터(context parameters)를 사용합니다. Kotlin 2.4.0부터는 컨텍스트 파라미터가 기본적으로 활성화되어 있습니다. Kotlin 2.2.x 또는 2.3.x를 사용하는 경우 빌드 스크립트에서 활성화하세요.

kotlin
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xcontext-parameters")
    }
}

프린시펄 정의 ​

프린시펄(principal)은 애플리케이션이 인증된 호출자와 연결하는 신원(identity) 또는 기타 정보를 나타냅니다. 프린시펄 타입은 null을 허용하지 않는(non-null) 타입이어야 합니다.

kotlin
data class User(
    val id: String,
    val email: String
)

스킴 생성 ​

각 인증 방식은 프린시펄 타입, 이름, 설정 블록을 인자로 받는 팩토리 함수를 제공합니다. validate {} 블록은 자격 증명이 유효하면 프린시펄 타입을 반환하고, 거부되면 null을 반환합니다.

kotlin
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-authKtor Server의 Basic 인증 참조
digest<P>()ktor-server-authJVM 전용. Ktor Server의 Digest 인증 참조
bearer<P>()ktor-server-authKtor Server의 Bearer 인증 참조
form<P>()ktor-server-authKtor Server의 Form 기반 인증 참조
session<S, P>()ktor-server-auth타입 안전한 세션 인증 참조
apiKey<P>()ktor-server-auth-api-keyAPI Key 인증 참조
jwt<P>()ktor-server-auth-jwtJVM 전용. JSON Web Tokens 참조
oauth2(), oauth2Session<P, S>()ktor-server-authOAuth 2.0 플로우 참조

스킴 이름은 고유해야 합니다. 동일한 이름으로 서로 다른 두 스킴을 생성하면 라우트에서 해당 스킴을 사용하려고 할 때 두 번째 스킴에서 오류가 발생합니다.

라우트 보호 ​

라우트를 보호하려면 authenticateWith() 함수에 스킴을 전달하세요. 해당 블록 내에서 call.principal은 스킴에서 정의한 프린시펄 타입을 가지며, null이 아님이 보장됩니다.

kotlin
routing {
    authenticateWith(jwtAuth) {
        get("/profile") {
            val user: User = call.principal
            call.respondText(user.email)
        }
    }
}

인증을 선택 사항으로 만들기 ​

로그인한 호출자와 익명 호출자 모두에게 라우트를 제공해야 하는 경우 authenticateWithOptional() 함수를 사용하세요. 블록 내부에서는 call.principalOrNull을 사용하여 프린시펄에 접근합니다.

kotlin
routing {
    authenticateWithOptional(jwtAuth) {
        get("/me") {
            val user = call.principalOrNull
            call.respondText(user?.email ?: "anonymous")
        }
    }
}

자격 증명이 없는 요청은 성공하며 call.principalOrNull은 null이 됩니다. 유효하지 않은 자격 증명이 포함된 요청은 여전히 실패합니다.

여러 스킴 허용 ​

동일한 라우트에서 둘 이상의 스킴을 허용하려면 authenticateWithAnyOf() 함수를 사용하세요. Ktor는 나열된 순서대로 스킴을 시도하며, 가장 먼저 성공한 스킴이 프린시펄을 제공합니다.

모든 스킴은 호출 시 선언한 공통 타입에 맞는 프린시펄을 생성해야 합니다.

kotlin
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() 함수를 사용하세요. 자격 증명이 없는 요청은 블록이 반환하는 프린시펄을 받게 됩니다. 유효하지 않은 자격 증명이 포함된 요청은 여전히 실패합니다.

그 결과 두 타입의 공통 상위 타입을 프린시펄 타입으로 갖는 스킴이 생성됩니다.

kotlin
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() 함수를 사용하세요.

kotlin
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()를 사용하여 역할을 인식하는 스킴을 만드세요.

kotlin
enum class Role : AuthenticationRole {
    User, Admin, Moderator
}

val roleAuth = jwtAuth.withRoles { user ->
    roleService.resolveRoles(user.id)
}

withRoles {} 블록은 인증이 성공한 후 모든 요청마다 실행됩니다. 이를 사용하여 데이터베이스, 캐시 또는 프린시펄 자체에서 역할을 로드할 수 있습니다.

roles 파라미터를 사용하여 라우트에 필요한 역할을 선언하세요.

kotlin
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을 전달하세요. 이는 핸들러 자체에서 판단해야 할 때 유용합니다.

kotlin
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입니다.

스킴에 핸들러를 설정하여 해당 스킴을 사용하는 모든 라우트에 적용할 수 있습니다.

kotlin
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)할 수도 있습니다.

kotlin
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) 핸들러를 찾습니다.

  1. authenticateWith()에 전달된 핸들러.
  2. 스킴에 구성된 onUnauthorized 핸들러.
  3. 프로바이더의 기본 챌린지.

아무것도 응답하지 않으면 요청은 401 Unauthorized로 실패합니다.

authenticateWithAnyOf()의 경우, 핸들러가 스킴 이름과 실패 원인의 맵(map)을 수신하므로 각 스킴이 실패한 이유를 알릴 수 있습니다.

kotlin
authenticateWithAnyOf<AppUser>(
    jwtScheme,
    apiKeyScheme,
    onUnauthorized = { failures ->
        val schemes = failures.keys.joinToString()
        call.respond(HttpStatusCode.Unauthorized, schemes)
    }
) {
    get("/profile") { /* ... */ }
}

기존 API와 결합하기 ​

두 인증 API를 동일한 애플리케이션에서 함께 사용할 수 있습니다. 이름 기반 프로바이더 API로 보호되는 라우트 안에 타입 안전한 라우트를 중첩하거나, 타입 안전한 라우트 안에 프로바이더 기반 라우트를 중첩할 수 있습니다.

kotlin
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()를 호출하세요.