HTTPS 및 인증

HTTPS 및 인증 (HTTPS and authentication)

Prometheus는 basic authentication과 TLS를 지원해요. 이것은 실험적이고 미래에 바뀔 수 있어요. 이 기능은 현재 개발 중이에요. 이 문서는 --web.config.file 플래그로 로드하는 웹 구성 파일을 통해 TLS 서버 구성(tls_server_config), 기본 인증 사용자(basic_auth_users), 그리고 HTTP 서버 구성(http_server_config)을 설정하는 방법을 설명해 드려요.

이 구성 파일은 매 HTTP 요청마다 다시 읽히므로, 구성과 인증서의 변경이 즉시 반영돼요. YAML 옵션 이름과 값은 그대로 두고, 각 설정의 의미를 한국어로 풀어드릴게요.

출처: 문서

본문

Prometheus는 basic authentication과 TLS를 지원해요. 이것은 실험적이고 미래에 바뀔 수 있어요. 이 기능은 현재 개발 중이에요.

어떤 웹 구성 파일을 로드할지 지정하려면 --web.config.file 플래그를 사용하세요.

파일은 아래 설명된 스키마로 정의된 YAML 형식으로 작성돼요. 대괄호는 파라미터가 선택 사항임을 나타내요. 리스트가 아닌 파라미터의 값은 지정된 기본값으로 설정돼요.

파일은 매 HTTP 요청마다 읽히므로, 구성과 인증서의 변경이 즉시 반영돼요.

일반 자리표시자(placeholder)는 다음과 같이 정의돼요.

  • <boolean>: true 또는 false 값을 가질 수 있는 불리언

  • <path>: 현재 작업 디렉터리의 유효한 경로

  • <secret>: 비밀번호 같은 시크릿인 일반 문자열

  • <string>: 일반 문자열

유효한 예제 파일은 여기에서 찾을 수 있어요.

tls_server_config:
  # 서버가 클라이언트에 인증하기 위해 사용할 인증서와 키 파일.
  cert_file:
  key_file:

  # 클라이언트 인증을 위한 서버 정책. ClientAuth 정책에 매핑.
  # clientAuth 옵션에 대한 자세한 내용:
  # https://golang.org/pkg/crypto/tls/#ClientAuthType
  #
  # 참고: 클라이언트 인증을 활성화하려면 RequireAndVerifyClientCert를 사용해야 함.
  # 다른 값은 안전하지 않음.
  [ client_auth_type: <string> | default = "NoClientCert" ]

  # 서버에 대한 클라이언트 인증서 인증용 CA 인증서.
  [ client_ca_file: <string> ]

  # 클라이언트 인증서가 이 목록의 항목과 정확히 일치하는
  # Subject Alternate Name(SAN)을 가졌는지 검증. 아니면 연결 종료.
  # SAN 일치는 다음 중 하나 이상일 수 있음: https://pkg.go.dev/crypto/x509#Certificate의
  # DNS, IP, e-mail 또는 URI 주소.
  [ client_allowed_sans:
    [ - <string> ] ]

  # 허용되는 최소 TLS 버전.
  [ min_version: <string> | default = "TLS12" ]

  # 허용되는 최대 TLS 버전.
  [ max_version: <string> | default = "TLS13" ]

  # 사용할 암호 스위트. 기본값은 Go TLS 라이브러리의 선호 암호 스위트를 사용.
  [ cipher_suites:
    [ - <string> ] ]

  # prefer_server_cipher_suites는 레거시 플래그이며 이제 무시됨.
  # prefer_server_cipher_suites: false

  # ECDHE 핸드셰이크에서 사용하는 곡선에 대한 곡선 선호도 설정.
  [ curve_preferences:
    [ - <string> ] ]

  # 클라이언트가 연결을 유지할 수 있는 최소 시간.
  [ client_timeout: <duration> | default = 0s ]

basic_auth_users:
  # 각 사용자에 대해 '<password_hash>'는 비밀번호의 bcrypt 해시.
  # 비밀번호 해싱에 대한 자세한 내용:
  # https://en.wikipedia.org/wiki/Bcrypt
  #
  # 해시 생성:
  #     htpasswd -nbBC 12 <user> <password>
  #
  <username>: <password_hash>

http_server_config:
  # HTTP/2 지원 활성화 (기본 = true).
  [ http2: <boolean> | default = true ]

  # 허용된 헤더 목록 (기본 = 모두). 특수 값 "*"는 모든 헤더를 허용.
  [ http_headers:
    [ - <string> ] ]

  # true로 설정하면 서버는 예상치 못한 "Origin" 헤더가 있는 모든 요청을 거부.
  [ reject_origin: <boolean> | default = false ]

  # 허용된 오리진 목록. true로 설정되고 reject_origin도 true면,
  # 목록에 없는 "Origin" 헤더를 포함한 요청은 거부됨.
  [ allowed_origins:
    [ - <string> ] ]

  # 모든 응답에 추가할 추가 응답 헤더.
  [ response_headers:
    [ - <string> ] ]

  # keep-alive로 유지할 최대 요청 수. 기본값 0은 이전 동작과
  # 일치하는 방식으로 모든 요청을 유지.
  [ max_keep_alive_requests: <int> | default = 0 ]

basic_auth_users 섹션은 사용자 이름을 비밀번호의 bcrypt 해시에 매핑해요.

예제 (Example)

TLS와 basic authentication을 활성화한 웹 구성 파일의 예:

# Enable TLS
tls_server_config:
  cert_file: "/path/to/cert.crt"
  key_file: "/path/to/key.pem"

# Enable basic authentication
basic_auth_users:
  alice: $2y$10$kFQEeFnSx9/vR.com/hhL2eW3NbDvOl2ZKTZ1QBV2uSw1ZvZWmgNi
  bob: $2y$10$lGyz5DjSx9/Cq4.0hhenE2F1Od.2V5G8EbxA1F1Dc1WY9WUy4Pkq

TLS 구성 (TLS configuration)

TLS 서버 구성은 웹 구성 파일의 tls_server_config 블록으로 지정해요.

구성 (Configuration)

서버를 다음으로 시작하세요.

./prometheus --web.config.file=web-config.yml

TLS를 완전히 비활성화하려면 client_auth_type을 NoClientCert(기본)로 설정하고 모든 cert_file과 key_file 항목을 제거하세요.

TLS 구성은 다음 Go crypto/tls 서버 구성 옵션을 사용해요. HTTP/2는 기본적으로 활성화돼요.

TLS 버전 (TLS versions)

기본 TLS 버전은 TLS 1.2와 TLS 1.3이에요. HTTP/2를 활성화하려면 TLS 1.2(또는 그 이상)가 필요해요. HTTP/2는 ECDHE로 ALPN 자격을 활성화하려면 TLS 1.3이 필요해요. TLS 없이 클라이언트를 구성하는 것은 불가능해요.

암호 스위트 (Cipher suites)

특정 암호 스위트 집합만 사용할 수 있어요. 목록은 https://golang.org/pkg/crypto/tls/#pkg-constants에서 확인할 수 있어요. TLS 1.3을 사용할 때 암호 스위트는 Go TLS 라이브러리가 협상하며 구성할 수 없어요.

곡선 (Curves)

특정 곡선 선호도 집합만 사용할 수 있어요. 목록은 https://golang.org/pkg/crypto/tls/#CurveID에서 확인할 수 있어요. 기본 곡선 선호도는 Go 기본값(X25519)이에요.

기본 인증 (Basic authentication)

기본 인증은 웹 구성 파일의 basic_auth_users 섹션으로 설정할 수 있어요.

사용자와 비밀번호는 웹 구성 파일에서 관리하며, 보통 htpasswd 유틸리티의 출력을 통해 관리돼요:

htpasswd -nbBC 12 admin mypassword

이상적으로는 더 강하고 무작위한 비밀번호를 사용해야 해요:

htpasswd -nbBC 12 admin "SGVsbG8sIFdvcmxkIQ=="

이 명령의 출력은 대략 이렇게 보일 거예요:

admin:$2y$10$cOkabGl8qwFHQ7xL219Viv.5CXJ93SnrMxfbAcqZqC/A3P0Q14.3G

비밀번호 해시가 bcrypt로 생성된다는 점에 주목하세요.

HTTP 서버 구성 (HTTP server config)

HTTP 서버 구성은 웹 구성 파일의 http_server_config 블록으로 지정해요.

클라이언트 타임아웃 (Client Timeout)

client_timeout은 tls_server_config의 일부예요.

Keep-alive

max_keep_alive_requests 설정은 서버가 연결을 닫기 전에 서빙할 keep-alive 요청 수를 제어해요. 한도에 도달하면 연결이 닫히고 새 연결을 맺어야 해요.

배포를 위한 추가 보안 고려사항 (Additional security considerations for deployment)

Web Config는 basic authentication과 TLS를 지원해요. 하나의 웹 구성 파일만 두는 것을 권장하지만, 웹 구성은 임의의 수의 사용자와 규칙을 지원할 수 있어요. 런타임에 TLS 인증서를 다루는 것이 지원돼요.

Web Config 인증서 처리 (Web Config certificate handling)

Web Config는 런타임에 경로에서 TLS 인증서를 읽어요. 즉 cert/key 쌍이 원자적으로 갖춰지고, 쌍이 업데이트된 후 prometheus 서버의 리로드가 수행된다면(예: SIGHUP을 보내서) 어떤 인증서 핫스왑이나 로테이션 도구도 사용할 수 있어요.

여러 사용자 관리 (Managing multiple users)

여러 사용자는 고유한 사용자 이름으로 여러 basic_auth_users 항목을 추가해 관리할 수 있어요. 각 사용자는 basic_auth_users 섹션에서 사용자 이름으로 키가 정해져요. basic_auth_users는 임의의 수의 사용자를 포함할 수 있고, 웹 구성 파일 변경이 감지되면 동적으로 편집될 수 있다는 점에 주목하세요. 웹 구성 리로드에 대한 자세한 내용은 다음을 참조하세요.

더 알아보기 (Learn more)