Skip to content

Ktor Server의 Basic 인증 ​

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

코드 예제: auth-basic, auth-basic-hash-table

네이티브 서버(Native server)Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅

Basic 인증(Basic authentication) 스킴은 접근 제어 및 인증에 사용되는 HTTP 프레임워크의 일부입니다. 이 스킴에서 사용자 자격 증명(credentials)은 Base64로 인코딩된 사용자 이름/비밀번호 쌍으로 전송됩니다.

Ktor를 사용하면 기본(basic) 인증을 통해 사용자를 로그인 처리하고 특정 라우트(route)를 보호할 수 있습니다. Ktor의 인증에 대한 일반적인 정보는 Ktor Server의 인증 및 인가 섹션에서 확인할 수 있습니다.

Basic 인증은 사용자 이름과 비밀번호를 평문으로 전달하므로, 민감한 정보를 보호하려면 반드시 HTTPS/TLS를 사용해야 합니다.

의존성 추가 ​

basic 인증을 활성화하려면 빌드 스크립트에 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>

Basic 인증 흐름 ​

Basic 인증 흐름은 다음과 같습니다.

  1. 클라이언트가 서버 애플리케이션의 특정 라우트로 Authorization 헤더 없이 요청을 보냅니다.

  2. 서버는 클라이언트에 401(Unauthorized) 응답 상태로 응답하며, 라우트를 보호하는 데 Basic 인증 스킴이 사용된다는 정보를 제공하기 위해 WWW-Authenticate 응답 헤더를 사용합니다. 일반적인 WWW-Authenticate 헤더는 다음과 같습니다.

    WWW-Authenticate: Basic realm="Access to the '/' path", charset="UTF-8"

    Ktor에서는 basic 인증 프로바이더를 구성할 때 해당 프로퍼티를 사용하여 realm과 charset을 지정할 수 있습니다.

  3. 일반적으로 클라이언트는 사용자가 자격 증명을 입력할 수 있는 로그인 대화 상자를 표시합니다. 그런 다음 클라이언트는 Base64로 인코딩된 사용자 이름과 비밀번호 쌍이 포함된 Authorization 헤더와 함께 요청을 보냅니다. 예를 들면 다음과 같습니다.

    Authorization: Basic amV0YnJhaW5zOmZvb2Jhcg
  4. 서버는 클라이언트가 보낸 자격 증명을 검증하고 요청된 콘텐츠로 응답합니다.

Basic 인증 설치 ​

basic 인증 프로바이더를 설치하려면 install 블록 내에서 basic 함수를 호출합니다.

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
// ...
install(Authentication) {
    basic {
        // Basic 인증 구성
    }
}

필요한 경우 특정 라우트를 인증하는 데 사용할 수 있는 프로바이더 이름을 지정할 수도 있습니다.

Basic 인증 구성 ​

Ktor에서 다양한 인증 프로바이더를 구성하는 방법에 대한 전반적인 내용은 인증 구성을 참조하세요. 이 섹션에서는 basic 인증 프로바이더의 구체적인 구성 방법을 살펴봅니다.

1단계: Basic 프로바이더 구성 ​

basic 인증 프로바이더는 BasicAuthenticationProvider.Configuration 클래스를 통해 설정을 노출합니다. 아래 예제에서는 다음 설정이 지정되어 있습니다.

  • realm 프로퍼티는 WWW-Authenticate 헤더에 전달될 realm을 설정합니다.
  • validate 함수는 사용자 이름과 비밀번호를 검증합니다.
kotlin
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 함수는 UserPasswordCredential을 확인하고 인증에 성공하면 UserIdPrincipal을 반환하며, 인증에 실패하면 null을 반환합니다.

사용자 이름과 비밀번호 해시를 보관하는 인메모리 테이블에 저장된 사용자를 검증하기 위해 UserHashedTableAuth를 사용할 수도 있습니다.

타입 안전(type-safe) 인증 스킴 API는 실험적 기능입니다. 언제든지 제거되거나 변경될 수 있습니다. 사용을 위해서는 opt-in이 필요합니다. 자세한 내용은 타입 안전 인증 문서를 참조하세요.

basic() 함수는 선택한 principal 타입에 대한 스킴을 생성합니다. install(Authentication) 단계가 필요하지 않으며, 이 스킴은 해당 스킴을 필요로 하는 라우트에 전달하는 값입니다.

kotlin
data class User(val name: String)

val basicAuth = basic<User>("auth-basic") {
    realm = "Access to the '/' path"
    validate { credentials ->
        val isValid = credentials.name == "jetbrains" &&
            credentials.password == "foobar"
        if (isValid) User(credentials.name) else null
    }
}

validate 함수는 UserPasswordCredential을 확인하고 지정한 principal 타입을 반환하거나, 인증에 실패하면 null을 반환합니다. 전체 API는 타입 안전 인증을 참조하세요.

2단계: 특정 리소스 보호 ​

basic 프로바이더를 구성한 후에는 authenticate 함수를 사용하여 애플리케이션의 특정 리소스를 보호할 수 있습니다. 인증에 성공한 경우 라우트 핸들러 내에서 call.principal 함수를 사용하여 인증된 UserIdPrincipal을 가져오고 인증된 사용자의 이름을 얻을 수 있습니다.

kotlin
routing {
    authenticate("auth-basic") {
        get("/") {
            val user = call.principal<UserIdPrincipal>()
            call.respondText("Hello, ${user?.name}!")
        }
    }
}

authenticateWith()에 스킴을 전달합니다. 블록 내에서 call.principal은 사용자가 정의한 principal 타입이며 절대 null이 아니므로 타입 캐스팅이나 null 체크가 필요하지 않습니다.

kotlin
routing {
    authenticateWith(basicAuth) {
        get("/") {
            call.respondText("Hello, ${call.principal.name}!")
        }
    }
}

UserHashedTableAuth로 검증 ​

Ktor에서는 UserHashedTableAuth를 사용하여 사용자 이름과 비밀번호 해시를 보관하는 인메모리 테이블에 저장된 사용자를 검증할 수 있습니다. 이를 통해 데이터 소스가 유출되더라도 사용자의 비밀번호가 노출되지 않도록 방지할 수 있습니다.

사용자 검증에 UserHashedTableAuth를 사용하려면 다음 단계를 따르세요.

  1. getDigestFunction 함수를 사용하여 지정된 알고리즘과 솔트(salt) 제공자로 다이제스트(digest) 함수를 생성합니다.

    kotlin
    val digestFunction = getDigestFunction("SHA-256") {
        "ktor${it.length}"
    }
  2. UserHashedTableAuth의 새 인스턴스를 초기화하고 다음 프로퍼티를 지정합니다.

    • table 프로퍼티를 사용하여 사용자 이름과 해시된 비밀번호 테이블을 제공합니다.
    • digester 프로퍼티에 다이제스트 함수를 할당합니다.
    kotlin
    val hashedUserTable = UserHashedTableAuth(
        table = mapOf(
            "jetbrains" to digestFunction("foobar"),
            "admin" to digestFunction("password")
        ),
        digester = digestFunction
    )
  3. validate 함수 내부에서 UserHashedTableAuth.authenticate 함수를 호출하여 사용자를 인증하고, 자격 증명이 유효한 경우 UserIdPrincipal 인스턴스를 반환하도록 합니다.

    kotlin
    install(Authentication) {
        basic("auth-basic-hashed") {
            realm = "Access to the '/' path"
            validate { credentials ->
                hashedUserTable.authenticate(credentials)
            }
        }
    }