Ktor Server의 Bearer 인증
필수 종속성: io.ktor:ktor-server-auth
코드 예제: auth-bearer
네이티브 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅
Bearer 인증 스킴은 접근 제어와 인증에 사용되는 HTTP 프레임워크의 일부입니다. 이 스킴은 Bearer 토큰(bearer token)이라고 하는 보안 토큰을 포함합니다. Bearer 인증 스킴은 OAuth 또는 JWT의 일부로 사용되지만, Bearer 토큰을 인가하기 위한 커스텀 로직을 직접 제공할 수도 있습니다.
Ktor의 인증에 대한 일반적인 정보는 Ktor Server의 인증 및 인가 섹션에서 확인할 수 있습니다.
Bearer 인증은 반드시 HTTPS/TLS를 통해서만 사용해야 합니다.
종속성 추가
bearer 인증을 활성화하려면 빌드 스크립트에 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>Bearer 인증 흐름
일반적인 Bearer 인증 흐름은 다음과 같습니다:
- 사용자가 성공적으로 인증되고 접근 권한이 인가되면, 서버는 클라이언트에 액세스 토큰을 반환합니다.
- 클라이언트는
Bearer스킴을 사용하여Authorization헤더에 토큰을 전달함으로써 보호된 리소스에 요청을 보낼 수 있습니다.HTTPGET http://localhost:8080/ Authorization: Bearer abc123 - 서버가 요청을 수신하고 토큰을 검증합니다.
- 검증 후, 서버는 보호된 리소스의 내용으로 응답합니다.
Bearer 인증 설치
bearer 인증 제공자를 설치하려면 install 블록 내에서 bearer 함수를 호출합니다:
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
bearer {
// Configure bearer authentication
}
}선택적으로 특정 라우트를 인증하는 데 사용할 수 있는 제공자 이름을 지정할 수도 있습니다.
Bearer 인증 구성
Ktor에서 다양한 인증 제공자를 구성하는 방법에 대한 전반적인 내용은 인증 구성을 참조하세요. 이 섹션에서는 bearer 인증 제공자의 구체적인 구성 방법을 살펴봅니다.
1단계: Bearer 제공자 구성
bearer 인증 제공자는 BearerAuthenticationProvider.Configuration 클래스를 통해 설정을 노출합니다. 아래 예제에서는 다음과 같은 설정이 지정되었습니다:
realm속성은WWW-Authenticate헤더에 전달될 realm을 설정합니다.authenticate함수는 클라이언트가 전송한 토큰을 확인하고, 인증에 성공한 경우UserIdPrincipal을 반환하며 인증에 실패한 경우null을 반환합니다.
install(Authentication) {
bearer("auth-bearer") {
realm = "Access to the '/' path"
authenticate { tokenCredential ->
if (tokenCredential.token == "abc123") {
UserIdPrincipal("jetbrains")
} else {
null
}
}
}
}타입 안전(Type-safe) 인증 스킴 API는 실험적(experimental)입니다. 언제든지 제거되거나 변경될 수 있습니다. 사용을 위해서는 opt-in이 필요합니다. 자세한 내용은 타입 안전 인증 문서를 참조하세요.
bearer() 함수는 원하는 principal 타입에 대한 스킴을 생성합니다. 별도의 install(Authentication) 단계는 없으며, 스킴은 이를 필요로 하는 라우트에 전달하는 값입니다.
data class User(val name: String)
val bearerAuth = bearer<User>("auth-bearer") {
realm = "Access to the '/' path"
validate { tokenCredential ->
if (tokenCredential.token == "abc123") {
User("jetbrains")
} else {
null
}
}
}이름 변경에 유의하세요. 클래식 제공자는 authenticate를 사용하는 반면, 타입 안전 스킴은 다른 타입 안전 스킴과 마찬가지로 validate를 사용합니다. 이 함수는 지정한 principal 타입을 반환하거나, 인증에 실패하면 null을 반환합니다.
또한 Authorization 헤더가 아닌 다른 곳에서 토큰을 읽어오도록 authHeader를 설정할 수 있으며, Bearer 이외의 스킴을 허용하도록 authSchemes를 설정할 수도 있습니다. 전체 API에 대한 내용은 타입 안전 인증을 참조하세요.
2단계: 특정 리소스 보호
bearer 제공자를 구성한 후, authenticate 함수를 사용하여 애플리케이션의 특정 리소스를 보호할 수 있습니다. 인증에 성공한 경우, 라우트 핸들러 내에서 call.principal 함수를 사용하여 인증된 UserIdPrincipal을 가져오고 인증된 사용자의 이름을 가져올 수 있습니다.
routing {
authenticate("auth-bearer") {
get("/") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}스킴을 authenticateWith()에 전달합니다. 블록 내부에서 call.principal은 지정한 principal 타입이며 절대 null이 아니므로, 타입 캐스팅이나 널 체크(null check)가 필요하지 않습니다:
routing {
authenticateWith(bearerAuth) {
get("/") {
call.respondText("Hello, ${call.principal.name}!")
}
}
}