# Apache Tomcat, WildFly 등과의 연동

Keycloak은 다양한 애플리케이션 서버와 손쉽게 통합할 수 있는 어댑터(Adapters)를 제공한다. 특히 Java 기반 서버인 Apache Tomcat과 WildFly는 Keycloak 측에서 공식 어댑터를 제공하고 있어, 이를 활용하면 효율적으로 SSO(Single Sign-On) 환경을 구축할 수 있다. 다음에서는 각 서버별 연동 방식과 주의할 점을 구체적으로 살펴본다.

Apache Tomcat과의 연동

* 어댑터 설치
  * Keycloak 공식 사이트에서 Tomcat용 어댑터를 다운로드한 뒤, Tomcat의 `lib` 디렉터리에 관련 라이브러리를 추가한다.
  * 일반적으로 `keycloak-tomcat-adapter-dist-x.y.z.zip` 파일 내부에 있는 `.jar` 파일들을 복사하여 Tomcat에 배치한다.
* Keycloak 구성 파일 준비
  * 어댑터가 동작하기 위해서는 `keycloak.json`이라는 설정 파일이 필요하다. Keycloak 관리 콘솔에서 Client를 생성하면, 해당 Client 설정을 JSON 형태로 다운로드받을 수 있다.
  * 이 `keycloak.json` 파일을 웹 애플리케이션의 `WEB-INF` 또는 Tomcat이 인식할 수 있는 위치(예: `/conf`)에 배치한다.
* 애플리케이션 보안 구성
  * Tomcat에서는 `web.xml`에 보안 관련 설정을 추가하거나, 서블릿 필터를 등록해 Keycloak 인증을 수행할 수 있다.
  * `org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve`를 사용하면 Tomcat Valve 레벨에서 인증을 처리할 수 있다. 혹은 `org.keycloak.adapters.servlet.KeycloakOIDCFilter`를 사용해 서블릿 필터 차원에서 적용하는 방법도 존재한다.
  * Keycloak의 Client 설정에서 “Root URL”, “Valid Redirect URI” 등을 올바르게 설정해야 리다이렉트 인증 과정에서 문제가 발생하지 않는다.
* 주의사항
  * Tomcat 버전에 따라 호환되는 Keycloak 어댑터 버전이 다를 수 있으므로, Keycloak 공식 문서에서 Tomcat과의 호환성을 먼저 확인한다.
  * 애플리케이션이 SSL/TLS를 사용한다면, Keycloak 측에서도 프로토콜이 일치하도록 설정해야 한다. 예를 들어 HTTPS로 요청을 받을 경우, Keycloak 관리 콘솔에서 Client의 “Access Type”을 `confidential`로 설정하고 “Admin URL”, “Redirect URI” 등을 HTTPS로 기재해야 한다.

WildFly와의 연동

* 어댑터 모듈 설치
  * WildFly에는 Keycloak 어댑터를 모듈(Module) 형태로 추가하여 서버 전체에서 SSO 기능을 활용할 수 있다.
  * Keycloak에서 제공하는 `keycloak-wildfly-adapter-dist-x.y.z.zip`을 다운로드하여, 내부의 모듈 디렉터리를 WildFly의 `modules` 폴더에 복사한다.
* 서브시스템(subsystem) 설정
  * WildFly는 `standalone.xml`(또는 도메인 모드의 경우 `domain.xml`)에서 Keycloak 서브시스템을 설정할 수 있다.
  * `<subsystem xmlns="urn:jboss:domain:keycloak:...">` 형태의 설정 블록을 추가하거나, 기존 설정을 변경해 Keycloak과 관련된 자원을 등록한다.
  * 서브시스템 내에 Realm, Resource, Credential 등의 설정이 포함되며, 이는 `keycloak.json`과 유사한 역할을 한다.
* 애플리케이션 보안 구성
  * WildFly는 일반적으로 `WEB-INF/jboss-web.xml` 또는 `WEB-INF/web.xml` 파일을 통해 보안 도메인(Security Domain)이나 자격 검증 방식을 정의한다.
  * Keycloak 어댑터를 설치하면 Keycloak 보안 도메인을 지정할 수 있으며, 설정된 도메인을 통해 인증 요청이 Keycloak 서버로 연동된다.
  * Hot-deploy가 가능하더라도, Keycloak과의 초기 통신 설정에는 서버 재시작이 필요한 경우가 많다.
* 주의사항
  * WildFly 버전에 맞춰 제공되는 어댑터 모듈 버전을 사용해야 한다. 구버전 WildFly에서는 특정 Keycloak 버전 이상이 호환되지 않거나 추가 설정이 필요할 수 있다.
  * WildFly에 내장된 Elytron 보안 프레임워크를 사용 중이라면, Elytron과 Keycloak 어댑터 간 연동을 위해 추가 설정이 필요할 수 있다.
  * WildFly 도메인 모드 환경에서는 각 호스트마다 어댑터 설정을 배포해야 하므로, 도메인 컨트롤러에서 모듈 및 서브시스템 설정을 전체적으로 관리할 수 있도록 구성한다.

공통 고려사항

* Keycloak 인증 흐름
  * 브라우저 기반 애플리케이션은 일반적으로 OpenID Connect(OIDC) 리다이렉트 방식을 통해 인증한다.
  * 사용자 요청 → Keycloak 로그인 페이지 리다이렉트 → 인증 성공 시 액세스 토큰/세션 부여 → 애플리케이션으로 돌아옴 순서로 진행된다.
  * 인증 성공 후 토큰 갱신, 세션 관리는 Keycloak 어댑터가 자동으로 처리하지만, 세션 관리 정책(세션 타임아웃, 토큰 만료 등)은 Keycloak 콘솔에서 적절히 설정해야 한다.
* 로그 확인 및 트러블슈팅
  * Keycloak 연동 과정에서 문제가 발생할 경우, Tomcat이나 WildFly의 로그와 Keycloak 서버 로그를 동시에 확인해야 원인을 명확히 파악할 수 있다.
  * 보안 설정 오류, 리다이렉트 URI 불일치, SSL/TLS 설정 누락 등이 대표적인 문제 원인이다.
* 성능 및 확장성
  * Keycloak은 클러스터링 기능을 제공하므로, 높은 트래픽 환경에서는 Keycloak 서버를 클러스터링하여 사용한다.
  * 애플리케이션 서버도 로드밸런서 또는 클러스터 구성을 통해 확장성을 높일 수 있으며, Keycloak 측과의 세션 동기화가 원활하도록 설정해야 한다.

Keycloak 어댑터를 활용하면 Apache Tomcat과 WildFly 모두에서 간편하게 OIDC 기반 인증을 구현할 수 있다. 각 애플리케이션 서버별 요구사항과 버전 호환성을 정확히 확인하고, 인증 흐름 전반에서 발생할 수 있는 보안 이슈나 리다이렉트 설정 문제를 사전에 점검하는 것이 중요하다.