Skip to content

mutual-tls.md

Latest commit

 

History

History
64 lines (42 loc) · 5.43 KB

mutual-tls.md

File metadata and controls

64 lines (42 loc) · 5.43 KB
Raw
source https://www.keycloak.org/server/mutual-tls
keycloak_version 26.6.2
translated 2026-06-03
category server

mTLS를 위한 신뢰 인증서 구성

원문 제목(EN): Configuring trusted certificates for mTLS 원문: https://www.keycloak.org/server/mutual-tls

클라이언트 인증서를 올바르게 검증하고 양방향 TLS(two-way TLS) 또는 mTLS와 같은 특정 인증 방법을 활성화하려면, 서버가 신뢰해야 하는 모든 인증서(및 인증서 체인)를 포함하는 트러스트스토어(truststore)를 설정할 수 있습니다. 상호 TLS(Mutual TLS) 및 X.509 인증과 같이 인증서를 사용하여 클라이언트를 인증하는 여러 기능이 이 트러스트스토어에 의존합니다.

mTLS 활성화

mTLS를 사용한 인증은 기본적으로 비활성화되어 있습니다. Keycloak이 서버로서 Keycloak 엔드포인트에 대한 요청에서 인증서를 검증해야 할 때 mTLS 인증서 처리를 활성화하려면, 적절한 인증서를 트러스트스토어에 넣고 다음 명령어를 사용하여 mTLS를 활성화하십시오:

bin/kc.[sh|bat] start --https-client-auth=<none|request|required>

required 값을 사용하면 Keycloak이 항상 인증서를 요청하고, 요청에 인증서가 제공되지 않으면 실패하도록 설정됩니다. request 값으로 설정하면 Keycloak은 인증서 없는 요청도 수락하며, 인증서가 존재할 경우에만 그 유효성을 검증합니다.

경고(WARNING): mTLS 구성 및 트러스트스토어는 모든 렐름(Realm)에서 공유됩니다. 렐름별로 서로 다른 트러스트스토어를 구성하는 것은 불가능합니다.

참고(NOTE): 관리 인터페이스(management interface)의 속성은 mTLS 설정을 포함하여 기본 HTTP 서버로부터 상속됩니다. 즉, mTLS가 설정되면 관리 인터페이스에도 활성화됩니다. 이 동작을 재정의하려면 https-management-client-auth 속성을 사용하십시오.

mTLS 전용 트러스트스토어 사용

기본적으로 Keycloak은 인증서 검증 시 시스템 트러스트스토어(System Truststore)를 사용합니다. 자세한 내용은 신뢰 인증서 구성(Configuring trusted certificates)을 참조하십시오.

mTLS에 전용 트러스트스토어를 사용해야 하는 경우, 다음 명령어를 실행하여 트러스트스토어의 위치를 구성할 수 있습니다:

bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file --https-trust-store-password=<value>

트러스트스토어에서 인식되는 파일 확장자:

  • .p12, .pkcs12, .pfx — pkcs12 파일
  • .jks, .truststore — jks 파일
  • .ca, .crt, .pem — pem 파일

트러스트스토어의 확장자가 파일 형식과 일치하지 않는 경우, https-key-store-type 옵션도 함께 설정해야 합니다.

추가 리소스

아웃고잉 HTTP 요청에 mTLS 사용

이것은 Keycloak이 서버 역할을 하는 mTLS 사용 사례에 대한 기본 인증서 구성임을 유의하십시오. Keycloak이 클라이언트 역할을 할 때(예: Keycloak이 mTLS로 보호된 브로커 아이덴티티 프로바이더(brokered identity provider)의 토큰 엔드포인트에서 토큰을 얻으려는 경우), 아웃고잉 요청에 올바른 인증서를 키스토어에 제공하도록 HttpClient를 설정해야 합니다. 이러한 시나리오에서 mTLS를 구성하려면 아웃고잉 HTTP 요청 구성(Configuring outgoing HTTP requests)을 참조하십시오.

X.509 인증 구성

X.509 인증 구성 방법에 대한 자세한 내용은 X.509 클라이언트 인증서 사용자 인증 섹션을 참조하십시오.

관련 옵션

타입 또는 값 기본값
https-client-auth (빌드 옵션)

서버가 클라이언트 인증을 요구(require)/요청(request)하도록 구성합니다.

CLI: --https-client-auth
Env: KC_HTTPS_CLIENT_AUTH		 none, request, required none
https-trust-store-file

신뢰할 인증서 정보를 보유하는 트러스트스토어입니다.

CLI: --https-trust-store-file
Env: KC_HTTPS_TRUST_STORE_FILE		 File
https-trust-store-password

트러스트스토어 파일의 비밀번호입니다.

CLI: --https-trust-store-password
Env: KC_HTTPS_TRUST_STORE_PASSWORD		 String
https-trust-store-type

트러스트스토어 파일의 유형입니다.

지정하지 않으면 파일 확장자를 기반으로 유형이 자동 감지됩니다. fips-mode가 strict로 설정되어 있고 값이 지정되지 않은 경우 기본값은 BCFKS입니다.

CLI: --https-trust-store-type
Env: KC_HTTPS_TRUST_STORE_TYPE		 String
https-management-client-auth (빌드 옵션)

관리 인터페이스가 클라이언트 인증을 요구(require)/요청(request)하도록 구성합니다.

지정하지 않으면 HTTP 옵션에서 값을 상속합니다. 관리 인터페이스에 노출된 항목이 있는 경우에만 관련됩니다 — 자세한 내용은 가이드를 참조하십시오.

CLI: --https-management-client-auth
Env: KC_HTTPS_MANAGEMENT_CLIENT_AUTH		 none, request, required none