# 오류 및 문제 해결 가이드 ### Keycloak이 구동되지 않는 경우 **증상** * `kc.sh start` 또는 서비스 실행 후 콘솔에 에러 메시지가 출력되며 Keycloak 프로세스가 시작되지 않음 * 로그에 “Failed to start server” 등의 문구가 반복 출력 **원인** * 호환되지 않는 Java 버전 사용 * 설치 디렉터리에 대한 권한 부족 * 환경변수(JAVA\_HOME, PATH 등)가 제대로 설정되지 않음 * 기존 포트가 이미 사용 중 **해결책** * Keycloak 호환 버전(일반적으로 Java 11 이상, 최신 버전은 Java 17 권장)이 설치되어 있는지 확인 * `JAVA_HOME` 환경변수가 올바른 경로를 가리키도록 재설정 * Keycloak 설치 폴더에 충분한 읽기·쓰기 권한이 있는지 확인 * `kc.sh start --debug` 혹은 `kc.sh start --log-level=DEBUG`로 실행해 자세한 로그 확인 * 서버 설정 파일(`.env`, `application.properties` 등)을 열어 포트가 충돌하는지 확인 후 다른 포트로 변경 *** ### 데이터베이스 연결 오류 **증상** * Keycloak 로그에 “Could not connect to database” 또는 “Database connection error” 메시지 출력 * Admin 콘솔 화면에서 DB 관련 예외 표시 **원인** * 데이터베이스가 실행 중이 아님 * JDBC URL, 사용자명 또는 비밀번호 오류 * 방화벽이나 네트워크 설정으로 DB 포트 접근 불가 **해결책** * 데이터베이스가 정상적으로 구동 중인지 확인(MariaDB, PostgreSQL 등 해당 DB 서비스 확인) * `KEYCLOAK_HOME/conf/keycloak.conf` 또는 유사한 설정 파일에서 JDBC URL, DB 사용자명/비밀번호가 올바른지 검증 * 방화벽 설정에서 DB 포트(예: 3306, 5432 등)가 열려 있는지 확인 * Docker, Kubernetes 등 컨테이너 환경 사용 시, DB 컨테이너와 Keycloak 컨테이너 간 네트워크 연결 설정 점검 *** ### Admin 콘솔 접근 오류 **증상** * 브라우저에서 `<서버주소>:8080/admin` 등으로 접속 시 “사이트에 연결할 수 없음” 또는 404 에러 * 접속은 되지만 Admin 계정으로 로그인할 수 없음 **원인** * 서버 포트 또는 주소 설정 오류 * 관리 콘솔에 대한 잘못된 URL 접속 * 관리자 계정 생성이 정상적으로 이루어지지 않음(초기 설정 에러) **해결책** * 기본 설치 후 `http://localhost:8080/`(또는 구성한 호스트와 포트)로 Keycloak 콘솔 접속 * 설치 시 지정한 관리자 계정이 실제로 생성되었는지 확인: 설치 마법사나 CLI를 통해 `--admin-username`, `--admin-password` 옵션을 사용해 다시 설정 * 방화벽, 리버스 프록시(Nginx, Apache 등) 사용 시 설정이 Keycloak 포트를 올바르게 라우팅하는지 검증 *** ### SSL 구성 문제 **증상** * HTTPS로 접속 시 브라우저에서 “이 사이트의 보안 인증서에 문제가 있다”와 같은 경고 * SSL 인증서 적용 후 Keycloak 서비스가 시작되지 않음 **원인** * 자체 서명 인증서(self-signed) 사용 시 브라우저가 신뢰하지 않음 * 인증서 경로(`.pem`, `.crt`, `.key` 등) 또는 KeyStore 비밀번호가 잘못됨 * Keycloak에서 HTTPS 리스너가 올바르게 설정되지 않음 **해결책** * 공인 인증서를 사용하거나 내부적으로 신뢰할 수 있는 CA를 통해 서명된 인증서 준비 * Keycloak 설정 파일 또는 환경 변수에 인증서 경로와 KeyStore 비밀번호를 정확히 기재 * `kc.sh start --https-key-store= --https-key-store-password=` 와 같은 방식으로 SSL 설정 확인 * 브라우저나 운영 체제의 신뢰 저장소에 인증 기관(CA) 추가 *** ### 포트 충돌 **증상** * Keycloak 실행 시 “Port already in use” 또는 바인딩 실패 관련 메시지 발생 * 같은 서버에서 이미 8080 포트를 다른 서비스가 사용 중인 경우 **원인** * Keycloak의 기본 포트(8080, 8443 등)와 타 서비스(WildFly, Tomcat, Jenkins 등)가 충돌 **해결책** * Keycloak 실행 포트를 변경: 예) `kc.sh start --http-port=8180 --https-port=8543` * 이미 사용 중인 서비스를 중지하거나 다른 포트로 재설정 *** ### 계정 잠금 또는 인증 문제 **증상** * 특정 사용자 계정으로 로그인 시도 시 “Invalid username or password” 오류 * 잘못된 비밀번호 입력 시도 후 계정이 잠기는 현상 **원인** * 비밀번호가 맞음에도 불구하고 해싱 알고리즘 문제로 인증 실패 * 잠금 정책(lockout policy)이 엄격하게 설정되어 여러 번 비밀번호 오류를 일으킨 사용자 계정이 자동으로 잠김 **해결책** * Keycloak의 암호 정책이나 해싱 알고리즘을 확인하고, 사용자 DB와 Keycloak 간 해싱 방식이 일치하는지 점검 * 관리자 콘솔의 “Authentication” → “Policies” 탭에서 Lockout 정책이 과도하게 적용되었는지 확인 후 조정 * 계정이 잠긴 경우, 관리자 권한으로 해당 계정을 활성화 *** ### 로그 활용 **주요 로그 파일 위치** * 전통적 WildFly 기반: `KEYCLOAK_HOME/standalone/log/server.log` * Quarkus 기반(Keycloak 최신 버전): 서비스 실행 터미널 출력 또는 `data/log/` 폴더 * Docker 환경: `docker logs <컨테이너 이름>` **로그 레벨 변경** * Quarkus 기반: `kc.sh start --log-level=DEBUG` 형태로 실행 옵션 지정 * WildFly 기반: `standalone.xml` 또는 `logging.properties` 수정하여 로그 레벨 조정 **로그 분석 및 에러 메시지 확인** * 특정 예외 스택 트레이스를 찾아 원인 파악: 예) `Caused by: org.hibernate.exception.SQLGrammarException` * 에러 발생 시점 전후 로그를 꼼꼼히 살펴 연관된 설정 오류나 예외가 있는지 확인 * 필요한 경우 DEBUG나 TRACE 레벨로 세분화된 로그를 활성화해 내부 동작 파악 이상의 방법을 통해 Keycloak 설치 및 초기 실행에서 발생할 수 있는 다양한 오류를 신속하게 진단하고 해결할 수 있다. 설치 환경에 따라 설정 파일 경로나 로그 파일 위치가 조금씩 달라질 수 있으므로, 사용 중인 Keycloak 버전과 운영 체제, 컨테이너 플랫폼에 맞춰 경로와 설정을 확인해야 한다.