Ktor Server의 인증 및 인가
필수 의존성: io.ktor:ktor-server-auth
Ktor는 인증(authentication) 및 인가(authorization)를 처리하기 위해 Authentication 플러그인을 제공합니다. 일반적인 사용 시나리오에는 사용자 로그인, 특정 리소스에 대한 접근 권한 부여, 당사자 간의 안전한 정보 전송 등이 포함됩니다. 또한 Authentication을 Sessions와 함께 사용하여 요청 간에 사용자 정보를 유지할 수도 있습니다.
클라이언트 측에서 Ktor는 인증 및 인가를 처리하기 위한 Authentication 플러그인을 제공합니다.
지원되는 인증 유형
Ktor는 다음과 같은 인증 및 인가 스키마를 지원합니다.
HTTP 인증
HTTP는 접근 제어와 인증을 위한 일반적인 프레임워크를 제공합니다. Ktor에서는 다음과 같은 HTTP 인증 스키마를 사용할 수 있습니다.
- Basic -
Base64인코딩을 사용하여 사용자 이름과 비밀번호를 제공합니다. 일반적으로 HTTPS와 함께 사용하지 않는 한 권장되지 않습니다. - Digest - 사용자 이름과 비밀번호에 해시 함수를 적용하여 암호화된 형태로 사용자 자격 증명(credentials)을 전달하는 인증 방식입니다.
- Bearer - 베어러 토큰(bearer token)이라 불리는 보안 토큰을 사용하는 인증 스키마입니다. Bearer 인증 스키마는 OAuth 또는 JWT의 일부로 사용되지만, 베어러 토큰을 인가하기 위한 커스텀 로직을 직접 제공할 수도 있습니다.
- API Key - 클라이언트가 헤더에 비밀 키(secret key)를 전달하는 간단한 인증 방식입니다.
폼 기반 인증
폼 기반(Form-based) 인증은 웹 폼을 사용하여 자격 증명 정보를 수집하고 사용자를 인증합니다.
JSON 웹 토큰 (JWT)
JSON Web Token은 당사자 간에 정보를 JSON 객체로 안전하게 전송하기 위한 개방형 표준입니다. JSON Web Token을 인가(authorization)에 사용할 수 있습니다. 사용자가 로그인하면 이후 각 요청에 토큰이 포함되어 사용자가 해당 토큰으로 허용된 리소스에 접근할 수 있게 됩니다. Ktor에서는 jwt 인증을 사용하여 토큰을 검증하고 토큰에 포함된 클레임(claim)의 유효성을 검사할 수 있습니다.
LDAP
LDAP는 디렉터리 서비스 인증에 사용되는 개방형 크로스 플랫폼 프로토콜입니다. Ktor는 지정된 LDAP 서버에 대해 사용자 자격 증명을 인증하는 ldapAuthenticate 함수를 제공합니다.
OAuth
OAuth는 API 접근 보안을 위한 개방형 표준입니다. Ktor의 oauth 프로바이더를 사용하면 Google, Facebook, Twitter 등과 같은 외부 프로바이더를 이용한 인증을 구현할 수 있습니다.
OpenID Connect
OpenID Connect는 OAuth 2.0 위에 구축된 아이덴티티 계층(identity layer)입니다. Oidc 플러그인은 프로바이더의 디스커버리 문서(discovery document)를 읽으므로 엔드포인트 및 서명 키 대신 발급자(issuer) URL을 구성합니다. API에서 액세스 토큰을 검증하고, PKCE, 세션, 로그아웃을 포함한 브라우저 로그인을 실행할 수 있습니다.
이 플러그인은 실험적(experimental)이며 JVM에서만 사용할 수 있습니다.
세션
Sessions는 서로 다른 HTTP 요청 간에 데이터를 유지하는 메커니즘을 제공합니다. 일반적인 사용 사례로는 로그인한 사용자의 ID 저장, 장바구니 내용 보관 또는 클라이언트의 사용자 환경설정 유지 등이 있습니다. Ktor에서는 이미 연결된 세션이 있는 사용자를 session 프로바이더를 사용하여 인증할 수 있습니다. 자세한 방법은 Ktor Server의 세션 인증에서 확인할 수 있습니다.
커스텀
Ktor는 인증 및 인가 동작을 커스터마이즈하는 두 가지 방법을 제공합니다.
- 커스텀 인증 프로바이더를 사용합니다.
- 커스텀 플러그인을 사용하여 인가 로직을 구현합니다. 예를 들어, 접근 권한을 확인하기 위해
AuthenticationChecked훅(hook)을 사용할 수 있습니다. 자세한 내용은 custom-plugin-authorization 예제를 참조하십시오.
타입 세이프 인증 스키마 API
Ktor는 스키마를 프린시펄(principal) 타입에 바인딩하는 타입 세이프(type-safe) 인증 스키마 API도 제공합니다. 보호된 라우트 내부에서 call.principal은 해당 프린시펄 타입이며 non-null임이 보장되므로 캐스팅이나 null 검사가 필요하지 않습니다. 이 API는 선택적 역할 검사, 익명 대체(anonymous fallback), 타입이 지정된 세션, 그리고 OAuth 2.0 플로우도 지원합니다.
이 API는 본 문서에서 설명하는 명명된 프로바이더(named provider) 방식의 대안입니다. 두 API는 동일한 애플리케이션에서 함께 사용할 수 있습니다. 자세한 내용은 타입 세이프 인증을 참조하십시오.
의존성 추가
Authentication을 사용하려면 빌드 스크립트에 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 및 LDAP와 같은 일부 인증 프로바이더는 추가 아티팩트가 필요하다는 점에 유의하십시오.
Authentication 설치
애플리케이션에 Authentication 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 플러그인을 전달합니다. 다음 예제는 Authentication을 설치하는 방법을 보여줍니다.
embeddedServer()함수 호출 내부에서 설치Application클래스에 명시적으로 정의된module()확장 함수 내부에서 설치
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.auth.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(Authentication)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
fun Application.module() {
install(Authentication)
// ...
}Authentication 구성
Authentication을 설치한 후 다음과 같이 Authentication을 구성하고 사용할 수 있습니다.
1단계: 인증 프로바이더 선택
basic, digest, form과 같은 특정 인증 프로바이더를 사용하려면 install 블록 내부에서 해당 함수를 호출해야 합니다. 예를 들어 기본(basic) 인증을 사용하려면 .basic() 함수를 호출합니다.
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
basic {
// 기본 인증 구성
}
}이 함수 내부에서 해당 프로바이더에 특화된 설정을 구성할 수 있습니다.
내장 프로바이더가 요구사항에 맞지 않는 경우, 커스텀 인증 프로바이더를 구현할 수 있습니다.
2단계: 프로바이더 이름 지정
특정 프로바이더를 사용하는 함수에는 선택적으로 프로바이더 이름을 지정할 수 있습니다. 아래 코드 샘플은 각각 "auth-basic" 및 "auth-form"이라는 이름으로 basic 및 form 프로바이더를 설치합니다.
install(Authentication) {
basic("auth-basic") {
// 기본 인증 구성
}
form("auth-form") {
// 폼 인증 구성
}
// ...
}이 이름들은 나중에 서로 다른 프로바이더를 사용하여 서로 다른 라우트를 인증하는 데 사용할 수 있습니다.
프로바이더 이름은 고유해야 하며, 이름이 없는 프로바이더는 하나만 정의할 수 있습니다.
3단계: 프로바이더 구성
각 프로바이더 유형은 고유한 구성을 가집니다. 예를 들어, BasicAuthenticationProvider.Config 클래스는 .basic() 함수에 대한 옵션을 제공합니다. 이 클래스의 핵심 함수는 사용자 이름과 비밀번호의 유효성을 검사하는 validate()입니다. 다음 코드 예제는 이 함수의 사용법을 보여줍니다.
install(Authentication) {
basic("auth-basic") {
realm = "Access to the '/' path"
validate { credentials ->
val isValid = credentials.name == "jetbrains" &&
credentials.password == "foobar"
if (isValid) {
UserIdPrincipal(credentials.name)
} else {
null
}
}
}
}validate() 함수가 어떻게 작동하는지 이해하려면 두 가지 용어를 알아야 합니다.
- _프린시펄(Principal)_은 인증될 수 있는 주체(entity)를 의미합니다. 사용자, 컴퓨터, 서비스 등이 될 수 있습니다. Ktor에서 다양한 인증 프로바이더는 서로 다른 프린시펄을 사용할 수 있습니다. 예를 들어
basic,digest,form프로바이더는UserIdPrincipal을 인증하는 반면,jwt프로바이더는JWTPrincipal을 검증합니다. - _자격 증명(Credential)_은 서버가 프린시펄을 인증하기 위한 속성 집합입니다. 사용자/비밀번호 쌍, API 키 등이 있습니다. 예를 들어
basic및form프로바이더는UserPasswordCredential을 사용하여 사용자 이름과 비밀번호를 검증하며,jwt는JWTCredential을 검증합니다.
따라서 validate() 함수는 지정된 자격 증명을 확인하고 인증에 성공하면 프린시펄 Any를 반환하며, 인증에 실패하면 null을 반환합니다.
특정 기준에 따라 인증을 건너뛰려면 skipWhen()을 사용하십시오. 예를 들어 세션이 이미 존재하는 경우 basic 인증을 건너뛸 수 있습니다:
basic {
skipWhen { call -> call.sessions.get<UserSession>() != null }
}4단계: 특정 리소스 보호
마지막 단계는 애플리케이션의 특정 리소스를 보호하는 것입니다. 이는 authenticate() 함수를 사용하여 수행할 수 있습니다. 이 함수는 두 개의 선택적 매개변수를 받습니다.
중첩된 라우트를 인증하는 데 사용되는 프로바이더의 이름입니다. 아래 코드 스니펫은 _auth-basic_이라는 이름의 프로바이더를 사용하여
/login및/orders라우트를 보호합니다.kotlinrouting { authenticate("auth-basic") { get("/login") { // ... } get("/orders") { // ... } } get("/") { // ... } }중첩된 인증 프로바이더를 해결(resolve)하는 데 사용되는 전략입니다. 이 전략은
AuthenticationStrategy열거형(enumeration) 값으로 표시됩니다.예를 들어, 클라이언트는
AuthenticationStrategy.Required전략으로 등록된 모든 프로바이더에 대한 인증 데이터를 제공해야 합니다. 아래 코드 스니펫에서는 세션 인증을 통과한 사용자만이 기본 인증을 사용하여/admin라우트에 접근을 시도할 수 있습니다.kotlinrouting { val required = AuthenticationStrategy.Required authenticate("auth-session", strategy = required) { get("/hello") { // ... } authenticate("auth-basic", strategy = required) { get("/admin") { // ... } } } }
전체 예제는 auth-form-session-nested를 참조하십시오.
5단계: 라우트 핸들러 내부에서 프린시펄 가져오기
인증에 성공하면 call.principal() 함수를 사용하여 라우트 핸들러 내부에서 인증된 프린시펄을 가져올 수 있습니다. 이 함수는 구성된 인증 프로바이더가 반환하는 특정 프린시펄 타입을 매개변수로 받습니다. 다음 예제에서는 call.principal()을 사용하여 UserIdPrincipal을 가져오고 인증된 사용자의 이름을 얻습니다.
routing {
authenticate("auth-basic") {
get("/") {
val user = call.principal<UserIdPrincipal>()
call.respondText("Hello, ${user?.name}!")
}
}
}세션 인증을 사용하는 경우, 프린시펄은 세션 데이터를 저장하는 데이터 클래스일 수 있습니다. 따라서 이 데이터 클래스를 call.principal()에 전달해야 합니다.
authenticate("auth-session") {
get("/hello") {
val userSession = call.principal<UserSession>()
}
}중첩된 인증 프로바이더의 경우, 원하는 프로바이더의 프린시펄을 가져오기 위해 call.principal()에 프로바이더 이름을 전달할 수 있습니다.
아래 예제에서는 최상위 세션 프로바이더의 프린시펄을 가져오기 위해 "auth-session" 값을 전달합니다.
val required = AuthenticationStrategy.Required
authenticate("auth-session", strategy = required) {
authenticate("auth-basic", strategy = required) {
get("/admin") {
val userSession =
call.principal<UserSession>(
"auth-session"
)
}
}
}커스텀 인증 프로바이더
내장 프로바이더가 요구사항에 맞지 않을 때 커스텀 인증 로직을 구현하려면 provider() 함수를 사용합니다.
provider("custom") {
authenticate { context ->
val headers = context.call.request.headers
val exampleHeader = headers["Example-Header"]
if (exampleHeader == null) {
val message = "No example header found"
val cause = AuthenticationFailedCause.Error(message)
context.challenge(key = this, cause) { challenge, call ->
call.respondText("Challenge")
challenge.complete()
}
}
}
}위 예제에서 provider("custom") 함수는 나중에 authenticate("custom")을 사용하여 라우트에 적용할 수 있는 이름이 지정된 인증 프로바이더를 등록합니다.
프로바이더 내부의 authenticate {} 블록은 들어오는 모든 요청에 대해 실행되며, 컨텍스트 객체를 통해 인증 프로세스에 대한 완전한 제어를 제공합니다. 여기에는 현재 호출에 대한 접근(context.call)과 헤더, 매개변수 또는 기타 요청 데이터를 검사하는 기능이 포함됩니다.
DynamicProviderConfig 클래스에서 제공하는 옵션을 사용하여 추가적인 프로바이더 동작을 구성할 수 있습니다.
