# 인증 이벤트 모니터링 및 로깅

Keycloak은 다양한 인증 이벤트를 기록하고 모니터링할 수 있는 기능을 제공한다. 사용자는 이러한 기능을 통해 로그인 성공, 로그인 실패, 토큰 갱신, 세션 종료 등 다양한 인증 관련 정보를 수집하고, 향후 보안 감사 또는 장애 조사에 활용할 수 있다. 인증 이벤트 모니터링 및 로깅을 올바르게 구성하면, 인증 흐름에서 발생하는 잠재적 위험 요소나 이상 징후를 조기에 파악할 수 있으며, 나아가 서비스의 신뢰도를 높일 수 있다. 아래에서는 Keycloak에서 인증 이벤트를 모니터링하고 로깅하는 방법, 그리고 관련 주요 설정들을 엄밀하게 살펴본다.

### 이벤트의 종류

Keycloak은 크게 \*\*이벤트(Event)\*\*와 **관리 이벤트(Admin Event)** 두 가지 유형으로 나누어 로깅을 수행한다. 일반적으로 인증 이벤트는 전자에 속한다.

* **이벤트(Event)** 로그인 성공, 실패, 로그아웃, 액션 토큰 사용 등의 사용자 관점에서 발생하는 이벤트다. 예: `LOGIN`, `LOGIN_ERROR`, `LOGOUT`, `TOKEN_EXCHANGE`, `CODE_TO_TOKEN`, `SEND_RESET_PASSWORD`, `SEND_VERIFY_EMAIL` 등.
* **관리 이벤트(Admin Event)** Keycloak Admin Console에서 사용자, 그룹, 클라이언트, 설정 등을 변경했을 때 발생한다. 예: `CREATE_USER`, `DELETE_CLIENT`, `UPDATE_REALM`, `CREATE_GROUP`, `UPDATE_USER` 등.

인증 이벤트 분석 목적으로는 주로 `Events` 탭에서 확인 가능한 사용자 관점 이벤트를 모니터링하면 된다.

### 이벤트 설정

Keycloak에서 이벤트를 기록하려면 우선 이벤트 로깅 기능을 활성화해야 한다. 이벤트 로깅은 Realm별로 설정 가능하므로, 특정 Realm에서만 로그를 남기거나 불필요한 Realm은 기록을 비활성화할 수도 있다.

1. **Realm 선택** Keycloak Admin Console에 접속한 뒤, 상단에서 이벤트 로깅을 설정하고자 하는 Realm을 선택한다.
2. **이벤트 설정 진입** 왼쪽 메뉴에서 “Events”를 클릭하면, 이벤트 관련 설정을 확인하고 편집할 수 있는 화면이 나타난다.
3. **Save Events 활성화** “Save Events” 옵션을 활성화하면 이벤트를 DB에 저장할 수 있다. 이 설정을 켜야 각종 이벤트가 기록된다.
4. **이벤트 종류 선택** “Event Types” 항목에서 저장하고자 하는 이벤트 유형들을 선택한다.
   * 모든 인증 이벤트를 기록하려면 `LOGIN`, `LOGIN_ERROR`, `LOGOUT`, `TOKEN_EXCHANGE` 등 관련 항목을 골라 활성화한다.
   * 응용에 따라 특정 이벤트만 기록해도 무방하다.
5. **로그 세부 정보 저장** “Save Event Details” 옵션을 활성화하면, 이벤트에 대한 구체적인 추가 정보(예: 요청 파라미터, 사용자 정보 등)가 함께 기록된다. 디버깅이나 분석 목적으로는 유용하지만, 민감한 데이터가 포함될 수 있으므로 보안 정책에 따라 사용해야 한다.
6. **보존 기간 설정** “Expiration” 옵션을 통해 이벤트를 저장할 기간(초 단위)을 지정할 수 있다. 기간이 만료된 이벤트는 자동으로 삭제되어 DB 용량을 관리한다.
7. **Event Listeners 구성** 이벤트를 실시간으로 다른 외부 시스템(예: Kafka, Elasticsearch)으로 전달하려면 “Event Listeners” 설정을 통해 필요한 SPI를 추가하거나 설정한다.
   * 기본적으로 `jboss-logging` 리스너가 제공되며, 이는 Keycloak 서버 로그에 정보를 남긴다.
   * 고급 로깅이 필요한 경우, 별도의 SPI나 커스텀 리스너를 구현해 이벤트를 타 시스템으로 전송할 수도 있다.

### 이벤트 확인 및 모니터링

이벤트 로깅이 활성화되면 Keycloak Admin Console 내부에서 발생한 이벤트들을 조회할 수 있다.

* **이벤트 조회** “Events” → “Event List” 화면에서 최신 이벤트를 확인할 수 있다. 이벤트 시각, 유형, 사용자 식별자 등이 표시되며, “Details”를 활성화했다면 추가 정보를 볼 수 있다.
* **필터 및 검색** 이벤트 유형, 사용자, 기간 등을 기준으로 필터링하여 특정 이벤트만 조회할 수 있다. 예를 들어, `LOGIN_ERROR` 이벤트만 선별해 보면 로그인 실패가 급격히 증가하는 패턴을 파악할 수 있다.
* **관리 이벤트 확인** “Admin Events” 탭에서는 관리자(또는 시스템)가 수행한 Realm 구성 변경, 클라이언트 등록/삭제, 사용자 생성/삭제, 권한 부여 등의 이벤트를 확인한다. 인증 이벤트와는 구분되지만, 보안 및 운영 관점에서 중요한 정보를 제공한다.

### 로깅 파일 및 로그 레벨

Keycloak 서버의 기본 로그(`standalone.log` 또는 별도의 로그 설정)는 이벤트 저장과는 별개로 서버 프로세스 레벨에서의 다양한 메시지를 출력한다. 이때 이벤트 정보 역시 JBoss Logging 레벨에 따라 일부 출력될 수 있다.

* **로깅 레벨 변경** Keycloak는 WildFly/JBoss 기반이므로, `log4j` 또는 `jboss-logging` 설정을 통해 INFO, DEBUG 등 로그 레벨을 변경할 수 있다. 디버깅이 필요한 경우 로그 레벨을 높이면 인증 이벤트 세부 흐름을 더 자세히 파악할 수 있으나, 과도한 로그가 쌓이지 않도록 주의해야 한다.
* **로그 파일 로테이션** 서버 로그가 너무 커지지 않도록 로테이션 정책을 적절히 설정한다. 운영 환경에서는 로그파일이 일정 크기를 초과하면 자동으로 분할 저장하도록 구성하여 디스크 용량 문제를 방지한다.

### 보안 및 감사 활용

인증 이벤트 로깅은 감사(Audit) 측면에서 중요한 근거 자료가 되며, 잠재적 침해 사례나 이상 징후를 빠르게 감지하도록 돕는다.

* **보안 모니터링** 로그인 실패(`LOGIN_ERROR`) 이벤트가 단기간에 비정상적으로 급증하면 무차별 대입 공격(Brute-Force Attack)을 의심해야 한다. 이때 Keycloak의 Brute Force Detection 기능과 연동해 방어 태세를 강화할 수 있다.
* **감사 추적** 중요한 시스템에서 사용자 활동이나 민감 데이터 접근 이력을 감사할 경우, 세부 이벤트 정보 저장이 유용하다. 어떠한 사용자가 언제 어떤 방법으로 로그인했는지, 2FA(이중 인증)를 통해 접근했는지 등 구체적 기록이 남는다.
* **서드파티 분석 도구 연계** Elasticsearch 같은 외부 로그 분석 시스템과 연동해 대량의 이벤트를 시각화하거나, SIEM(Security Information and Event Management) 솔루션에서 보안 이벤트를 중앙 집중 관리하기도 한다.

### 모범 사례

1. **중요 이벤트 선별** 모든 이벤트를 기록하면 DB 용량이 급격히 증가할 수 있다. 서비스 성격과 보안 수준에 따라 핵심 이벤트를 선별해 기록하고, 나머지는 분석 필요 시에만 일시적으로 활성화한다.
2. **로그 보존 정책 수립** 민감 정보가 로그에 포함될 수 있으므로, 필요한 기간만큼만 저장하고 적절히 폐기하거나 보존한다. 관련 규제(예: 개인정보 보호법, 금융 관련 규정 등)에 따라 보존 기간을 결정해야 한다.
3. **필요 시 익명화 처리** 실제 사용자 식별 정보가 포함된 이벤트 로그는 유출 시 위험도가 높으므로, 별도의 로깅 시스템으로 전달할 때는 식별자를 마스킹하거나 해시 처리하는 것도 고려해야 한다.
4. **외부 연동 시 암호화** 이벤트를 외부로 전송하거나 저장할 때는 TLS 등 안전한 암호화 채널을 통해 전달하고, 저장소에서도 암호화를 적용해 기밀성을 유지한다.
5. **모니터링 자동화** 단순 저장에 그치지 않고, 모니터링 시스템에서 임계값이나 이상 패턴(로그인 실패 급증, 특정 시간대 집중 로그인 등)을 실시간 감시하도록 구성해 운영 부담을 줄인다.

Keycloak의 인증 이벤트 모니터링 및 로깅 기능은 사용자 및 관리자 활동을 기록하고, 보안성을 높이는 핵심 요소다. 적절한 이벤트 선택, 로그 보존 정책, 외부 연동 방안을 통해 체계적인 접근 방안을 마련하면, 보다 안전하고 투명한 인증 환경을 운영할 수 있다.