Keycloak 26.6.2 공식 가이드(https://www.keycloak.org/guides) 78개 문서를 1:1 완역한 한국어 번역 모음입니다.
Spring Cloud Gateway + Keycloak 기반 인증 시스템을 설계·구현하면서 공식 문서를 한국어로 정독하기 위해 만들었고, 같은 주제를 공부하는 분들에게도 도움이 될 것 같아 별도 저장소로 공개합니다.
비공식 번역입니다. 내용이 원문과 다르면 항상 원문이 우선합니다. 원문: https://www.keycloak.org/guides · 원본 소스: keycloak/keycloak (태그
26.6.2,docs/guides)
| 항목 | 내용 |
|---|---|
| 기준 버전 | Keycloak 26.6.2 ("Nightly 26.6.2" 렌더링본 기준) |
| 번역일 | 2026-06-03 |
| 범위 | 공식 Guides 전체 78편 — Getting started(6) · Server(25) · Securing applications(25) · Observability(9) · Operator(6) · High availability(3) · UI Customization(8) · Migration(1) |
| 번역 방식 | 전 문서 1:1 완역 (요약·발췌 아님) |
- 산문은 한국어로, 코드·CLI 명령·옵션명(
--db등)·환경변수·파일경로·URL·제품명은 원문 그대로 보존 - 기술용어는 첫 등장 시 영어 병기
NOTE/WARNING은> **참고(NOTE):**형태의 블록인용으로 표기
getting-started/ 시작하기 (6) — OpenJDK·Docker·Podman·K8s·OpenShift·스케일링
server/ 서버 설정 (25) — 구성·TLS·호스트명·프록시·DB·캐시·로깅·전체 옵션 레퍼런스
securing-apps/ 애플리케이션 보안 (25) — OIDC·토큰 교환·DPoP·클라이언트 등록·어댑터·정책 실행자
observability/ 관측성 (9) — 헬스·메트릭·SLI·OTel·트레이싱·Grafana
operator/ Kubernetes Operator (6) — 설치·배포·렐름 임포트·롤링 업데이트
high-availability/ 고가용성 (3) — 단일/멀티 클러스터 HA
ui-customization/ UI 커스터마이징 (8) — 테마·현지화·콘솔 커스텀
migration/ 마이그레이션 (1) — WildFly→Quarkus
Spring Cloud Gateway + Keycloak(Docker) + 게이트웨이 JWT 로컬 검증 구조를 기준으로 정리한 우선순위입니다. (연관도: ◎ 필수 · △ 상황에 따라 · ✕ 해당 구조와 무관, 참고용)
- OpenID Connect으로 애플리케이션 및 서비스 보호하기 — 엔드포인트,
.well-known, 토큰 검증의 출발점 ◎ - Keycloak 구성하기 — 4가지 구성 소스, 개발/프로덕션 모드,
--optimized◎ - 프로덕션 환경을 위한 Keycloak 설정 — TLS/호스트명/프록시/DB 체크리스트 ◎
- 컨테이너에서 Keycloak 실행하기 — Docker 이미지·실행·Realm 임포트 ◎
- 역방향 프록시 구성 — 게이트웨이/프록시 뒤에 둘 때
proxy-headers, 호스트명 ◎ - 호스트명(Hostname) 설정 (v2) — 프론트엔드/백채널 엔드포인트 호스트명 ◎
- 데이터베이스 구성 — PostgreSQL 등 연결·드라이버·TLS ◎
- 토큰 교환(Token Exchange) 설정 및 사용 — 서비스 간 토큰 위임 △
- DPoP으로 애플리케이션 보안 적용 — 토큰 탈취/재전송 방지 △
- 헬스 체크로 인스턴스 상태 추적하기 — 컨테이너 readiness/liveness ◎
| 문서 | 요약 |
|---|---|
| OpenJDK | 물리/가상 서버(OpenJDK)에서 Keycloak을 처음 시작하는 입문 가이드 |
| Docker | Docker로 Keycloak 시작 — 컨테이너 실행부터 렐름·사용자·클라이언트 생성, 첫 앱 보안까지 |
| Podman | Podman으로 Keycloak 컨테이너 시작 및 첫 앱 보안 적용 입문 |
| Kubernetes | Minikube 환경에서 StatefulSet 배포, Ingress 설정, 첫 앱 보호 |
| OpenShift | CodeReady Containers로 로컬 OpenShift에 배포하고 첫 앱 보호 |
| 스케일링 | 수직/수평 스케일링·튜닝(스레드, DB 연결, HPA) |
| 문서 | 요약 |
|---|---|
| Keycloak 구성하기 | 4가지 구성 소스, 개발/프로덕션 모드, 초기 관리자, --optimized 빌드 |
| 지원 구성 | 지원 플랫폼·Java·DB·브라우저 요구사항 개요 |
| 프로덕션 환경을 위한 Keycloak 설정 | TLS/호스트명/프록시/DB/클러스터링 프로덕션 핵심 영역 |
| 관리자 계정 부트스트랩 및 복구 | 임시 관리자 생성 및 관리자 접근 복구 |
| 디렉터리 구조 | bin/conf/data/lib/providers/themes 역할 |
| 컨테이너에서 Keycloak 실행하기 | 커스텀 Containerfile, 개발/프로덕션 실행, 메모리, Realm 임포트 |
| TLS 구성하기 | HTTPS/TLS 인증서(PEM/Keystore), 프로토콜, 자동 재로드 |
| 호스트명(Hostname) 설정 (v2) | 프론트엔드/백채널 엔드포인트 호스트명, 프록시 연동, 관리 콘솔 분리 |
| 역방향 프록시 구성 | 프록시/게이트웨이/LB 통합, proxy-headers, 스티키 세션 |
| 데이터베이스 구성 | 관계형 DB(PostgreSQL/MySQL/MariaDB/Oracle/MSSQL) 드라이버·연결·TLS·XA |
| 분산 캐시 구성하기 | Infinispan 분산 캐시, 캐시 유형/스택, mTLS, 네트워크 |
| 발신 HTTP 요청 구성 | 발신 HTTP 클라이언트, 커넥션 풀, 프록시 매핑, 재시도/타임아웃 |
| 신뢰할 수 있는 인증서 구성 | 시스템 트러스트스토어, 클러스터 CA 자동 포함, 호스트명 검증 |
| mTLS를 위한 신뢰 인증서 구성 | 상호 TLS(mTLS) 활성화 및 클라이언트 인증서 검증 트러스트스토어 |
| 기능 활성화 및 비활성화 | 지원/프리뷰/사용중단 기능 토글, 버전 관리 |
| 프로바이더 설정하기 | SPI/프로바이더 설정, 빌드 시 옵션, 설치/제거, 서드파티 의존성 |
| 로깅 설정 | Console/File/Syslog 핸들러, 레벨, 비동기, JSON/ECS, MDC, OTel 로그 |
| FIPS 140-2 지원 | BouncyCastle FIPS, 키스토어, 엄격 모드, 컨테이너 실행 |
| 관리 인터페이스(Management Interface) 구성 | 메트릭/헬스용 분리 HTTP 서버(포트 9000) 구성 |
| 렐름(Realm) 가져오기 및 내보내기 | JSON import/export, 시작 시 가져오기, 부분 export/import |
| 볼트(Vault) 사용하기 | 파일 기반 볼트 및 Java KeyStore 볼트 구성 |
| 전체 구성(All configuration) | ⚙️ 자동생성 — 25개 카테고리 233개 전체 옵션 레퍼런스 |
| 모든 프로바이더 구성 | ⚙️ 자동생성 — 37개 SPI, 60개 프로바이더, 197개 옵션 레퍼런스 |
| 롤링 업데이트 가능 여부 확인 | update-compatibility 명령으로 무중단 업데이트 가능 여부 점검 |
| Keycloak를 Windows 서비스로 실행하기 | Procrun으로 Windows 서비스 설치/운영 ✕ |
| 문서 | 요약 |
|---|---|
| 애플리케이션 및 서비스 보안 계획 | OAuth2/OIDC/SAML 기반 보안 기본 개념·단계·용어 |
| OpenID Connect으로 애플리케이션 및 서비스 보호하기 | 엔드포인트, 그랜트 유형, FAPI/OAuth2.1, 액세스 토큰 검증 ◎ |
| 구현된 명세(Specifications) | 지원 OIDC/OAuth/FAPI/SAML/UMA 명세 목록·적합성 |
| 토큰 교환(Token Exchange) 설정 및 사용 | 표준(V2)/레거시(V1) 토큰 교환, 사용 사례별 요청 |
| JWT 인가 그랜트(JWT Authorization Grant) | JWT 베어러 토큰 그랜트(RFC 7521/7523) |
| 도메인 간 OAuth 아이덴티티 및 권한 부여 체이닝 | 토큰 교환(RFC8693)+JWT 그랜트(RFC7523) 체이닝 |
| DPoP으로 애플리케이션 보안 적용 | DPoP(RFC 9449)로 토큰을 키 쌍에 바인딩, 탈취 방지 |
| Model Context Protocol(MCP) 통합하기 | Keycloak을 MCP 서버의 인가 서버로 설정 |
| 클라이언트 등록 서비스 사용하기 | Client Registration Service 인증 방식·프로바이더·정책 |
| CLI를 이용한 클라이언트 등록 자동화 | kcreg CLI로 클라이언트 CRUD·토큰 관리 |
| Distribution Registry 설정하기 | 컨테이너 레지스트리 인증 서버로 Keycloak 설정(Docker Compose 예시 포함) |
| Keycloak JavaScript 어댑터 | keycloak-js 클라이언트 라이브러리 설치·API 레퍼런스 |
| Keycloak Node.js 어댑터 | Connect 기반 Node.js 어댑터로 서버사이드 앱 보호 |
| Keycloak 관리자 클라이언트 | Admin REST API용 Java 관리자 클라이언트 라이브러리 |
| Keycloak 인가 클라이언트 | Java Authorization Client로 토큰/리소스/권한 관리 |
| Keycloak 정책 실행자(Policy Enforcer) | Java 앱에서 PEP, CIP, 인가 컨텍스트, TLS 구성 |
| Keycloak 클라이언트 라이브러리 업그레이드 | Java 클라이언트 라이브러리 버전 지원 정책 |
| mod_auth_openidc Apache HTTPD 모듈 설정 | Apache mod_auth_openidc를 OIDC로 Keycloak 연동 △ |
| mod_auth_mellon Apache 모듈 설정 | Apache mod_auth_mellon SAML 인증 연동 ✕ |
| WildFly 및 EAP를 위한 Keycloak SAML Galleon 피처 팩 | WildFly/EAP SAML Galleon 피처 팩 ✕ |
| 문서 | 요약 |
|---|---|
| 헬스 체크로 인스턴스 상태 추적하기 | /health, /health/ready 등 헬스 엔드포인트·K8s 연동 ◎ |
| 메트릭으로 인사이트 얻기 | /metrics 활성화·조회, 히스토그램/SLO 옵션 |
| 이벤트 메트릭으로 사용자 활동 모니터링하기 | 사용자 이벤트 메트릭, 차원 태그, 필터링 |
| 서비스 수준 지표(SLI)를 통한 성능 모니터링 | SLI/SLO 정의, PromQL로 가용성/지연/오류율 |
| 메트릭을 활용한 문제 해결 | DB 풀·캐시 적중률 등으로 성능 진단 |
| OpenTelemetry로 옵저버빌리티 스택 중앙화하기 | OTel로 로그/메트릭/트레이스 중앙화 |
| 트레이싱을 활용한 근본 원인 분석 | OTel 트레이싱으로 요청 생명주기·지연 분석 |
| 대시보드에서 활동 시각화하기 | Grafana 대시보드 설치·시각화 |
| 예시(Exemplar)로 이상값과 오류 분석하기 | 메트릭↔트레이스 연결(exemplar) 설정 |
| 문서 | 요약 |
|---|---|
| Keycloak Operator 설치 | K8s/OpenShift에 Operator 설치(OLM/kubectl) |
| 기본 Keycloak 배포 | Operator로 기본 배포(DB/호스트명/TLS/Ingress) |
| 고급 설정 | Keycloak CR 고급 설정(Secret, 스케줄링, 트레이싱 등) |
| 렐름 임포트 자동화 | KeycloakRealmImport CR로 렐름 자동 임포트 |
| 롤링 업데이트로 다운타임 방지하기 | Operator 롤링 업데이트 전략 |
| 사용자 정의 Keycloak 이미지 사용하기 | 커스텀 이미지 지정·최적화 |
| 문서 | 요약 |
|---|---|
| 고가용성(High Availability) 개요 | 단일/멀티 클러스터 HA 아키텍처 선택 기준 |
| 단일 클러스터 배포 | 단일 클러스터 다중 AZ 배포 개요 |
| 멀티 클러스터 배포 | 독립 K8s 클러스터 간 멀티 클러스터 연결 |
| 문서 | 요약 |
|---|---|
| 소개(Introduction) | 로그인/관리/계정 콘솔 커스터마이징 개요 |
| 테마 사용하기 | 테마 유형·생성·배포·테마 SPI |
| 현지화(Localization) | 메시지 번들 기반 UI 현지화·언어 추가 |
| Quick Theme로 커스터마이징하기 | 로고·색상 테마 빠른 적용(실험적) |
| 아바타 사용하기 | OIDC picture 클레임 기반 아바타 |
| 환영 테마(Welcome Theme) 커스터마이징 | 환영 페이지 테마 적용 |
| 나만의 콘솔 만들기 | React npm 패키지로 콘솔 커스텀 버전 제작 |
| npm UI 패키지 사용하기 | @keycloak/keycloak-*-ui npm 패키지 사용 |
| 문서 | 요약 |
|---|---|
| Quarkus 배포판으로 마이그레이션 | 레거시 WildFly→Quarkus 배포판 마이그레이션 |
server/all-config.md(75KB),server/all-provider-config.md(70KB): Keycloak 빌드 시 자동 생성되는 대형 옵션 레퍼런스 테이블. 옵션 키·CLI 플래그·환경변수명·타입·기본값은 원문 그대로 유지하고, 설명(description) 셀의 영문 산문만 한국어로 번역함. 일부 확장 설명은 코드 참조가 많아 영문 유지.- 1KB 미만의 짧은 문서(예:
ui-customization/introduction.md,securing-apps/upgrading.md,ui-customization/welcome-theme.md)는 원문 자체가 짧은 소개/인덱스 페이지이며 누락 없이 전량 번역됨. - 문서 내 상대 링크는 원문 URL(절대경로)로 유지되어 있어, 로컬 문서 간 이동이 필요하면 추후 일괄 변환 가능.
- 원문: Keycloak Guides — keycloak/keycloak 저장소
docs/guides(태그26.6.2) - 원문 라이선스: Apache License 2.0 — 본 번역은 그 파생 저작물로 동일 라이선스를 따릅니다.
- Keycloak은 CNCF 인큐베이팅 프로젝트입니다. 이 저장소는 Keycloak 프로젝트와 무관한 개인 학습용 비공식 번역입니다.