Skip to content

Ktor Client의 기본 인증 ​

필수 종속성: io.ktor:ktor-client-auth

코드 예제: client-auth-basic

기본 인증 체계(authentication scheme)는 사용자 로그인에 사용할 수 있습니다. 이 체계에서는 사용자 자격 증명(credentials)이 Base64로 인코딩된 사용자 이름/비밀번호 쌍으로 전송됩니다.

서버 측에서 Ktor는 기본 인증(basic authentication)을 처리하기 위한 Authentication 플러그인을 제공합니다.

종속성 추가 ​

인증을 활성화하려면 빌드 스크립트에 ktor-client-auth 아티팩트를 포함합니다:

kotlin
implementation(ktorLibs.client.auth)
위 코드 스니펫은 Ktor 종속성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.client.auth
위 코드 스니펫은 Ktor 종속성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-auth-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
Ktor 클라이언트에 필요한 아티팩트에 대한 자세한 내용은 클라이언트 종속성 추가기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아봅니다.를 참조하세요.

기본 인증 흐름 ​

기본 인증 흐름은 다음과 같습니다:

  1. 클라이언트가 Authorization 헤더 없이 서버 애플리케이션의 보호된 리소스에 요청을 보냅니다.

  2. 서버는 401 Unauthorized 응답 상태로 응답하며, WWW-Authenticate 응답 헤더를 사용하여 기본 인증이 필요함을 알립니다. 일반적인 WWW-Authenticate 헤더는 다음과 같습니다:

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

    Ktor 클라이언트를 사용하면 sendWithoutRequest() 함수를 통해 WWW-Authenticate 헤더를 기다리지 않고 선제적(preemptively)으로 자격 증명을 보낼 수 있습니다.

  3. 클라이언트는 일반적으로 사용자에게 자격 증명을 요청합니다. 그런 다음 Base64로 인코딩된 사용자 이름과 비밀번호 쌍이 포함된 Authorization 헤더를 사용하여 요청을 보냅니다. 예를 들면 다음과 같습니다:

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

기본 인증 구성 ​

Basic 스키마를 사용하여 Authorization 헤더에 사용자 자격 증명을 전송하려면 basic 인증 공급자(provider)를 구성해야 합니다:

  1. install(Auth) 블록 내부에서 basic 함수를 호출합니다.

  2. BasicAuthCredentials를 사용하여 필요한 자격 증명을 제공하고, 이 객체를 credentials 함수에 전달합니다.

  3. realm 속성을 사용하여 렐름(realm)을 구성합니다.

    kotlin
    val client = HttpClient(CIO) {
        install(Auth) {
            basic {
                credentials {
                    BasicAuthCredentials(username = "jetbrains", password = "foobar")
                }
                realm = "Access to the '/' path"
            }
        }
    }
  4. (선택 사항) sendWithoutRequest 함수를 사용하여 선제적 인증(preemptive authentication)을 활성화합니다. 이 함수는 요청 매개변수를 확인하고 초기 요청에 자격 증명을 첨부할지 여부를 결정합니다.

    kotlin
    install(Auth) {
        basic {
            // ...
            sendWithoutRequest { request ->
                request.url.host == "0.0.0.0"
            }
        }
    }
  5. (선택 사항) 자격 증명 캐싱을 비활성화합니다. 기본적으로 credentials {} 공급자가 반환한 자격 증명은 요청 간 재사용을 위해 캐시됩니다. cacheTokens 옵션을 사용하여 캐싱을 비활성화할 수 있습니다:

    kotlin
    basic {
        cacheTokens = false   // 모든 요청에 대해 자격 증명을 다시 로드합니다
        // ...
    }

    캐싱 비활성화는 클라이언트 세션 중에 자격 증명이 변경될 수 있거나 최신 저장 상태를 반영해야 하는 경우에 유용합니다.

    프로그래밍 방식으로 캐시된 자격 증명을 지우는 방법에 대한 자세한 내용은 일반적인 토큰 캐싱 및 캐시 제어(Token caching and cache control) 섹션을 참조하세요.

Ktor Client의 기본 인증에 대한 전체 예제는 client-auth-basic을 참조하세요.