# API Gateway와의 통합

API Gateway는 내부 서비스들에 대한 단일 진입점을 제공하고, 요청 라우팅이나 로드 밸런싱, 인증·인가 등의 공통 기능을 중앙집중화하여 관리할 수 있게 해준다. Keycloak과의 통합은 API Gateway를 거치는 모든 서비스에 대해 통합 인증·인가를 적용하고, 보안 토큰을 일관성 있게 다루도록 하는 핵심적인 구성 요소다. 여기서는 API Gateway를 통해 Keycloak과 연동하는 일반적인 방식을 살펴본다.

### API Gateway 역할과 Keycloak 연동 개요

API Gateway는 클라이언트로부터의 요청을 수신한 뒤, 내부 서비스에 요청을 라우팅하거나 필요한 전·후처리를 수행한다. 통상적으로는 다음과 같은 인증·인가 시나리오가 가능하다.

* **클라이언트가 Keycloak으로부터 토큰을 발급받아 API Gateway에 전달** 이미 인증 과정을 마친 클라이언트가 Gateway에 접근할 때, Authorization 헤더 또는 쿠키 등을 통해 보안 토큰을 전달한다. Gateway는 전달받은 토큰을 검증한 뒤 백엔드 서비스로 요청을 라우팅한다.
* **API Gateway가 토큰 검증 로직을 직접 수행** Gateway는 Keycloak에서 발급된 토큰을 직접 검증하거나, 필요한 경우 Keycloak의 토큰 인트로스펙션(Introspection) 엔드포인트를 통해 유효성을 확인한다.

이러한 구조를 통해, API Gateway가 모든 요청에 대해 일관된 인증 정책을 적용함으로써 보안성을 높이고, 서비스 내부에 중복되는 인증 로직을 제거할 수 있다.

### Keycloak과의 연동 방식

API Gateway에서 Keycloak을 연동하는 방식은 주로 다음과 같은 단계를 거친다.

#### 1) OpenID Connect 또는 OAuth 2.0 설정

Keycloak은 OpenID Connect와 OAuth 2.0을 기반으로 인증·인가를 처리한다. Gateway 측에서 지원하는 인증 플러그인(예: OIDC 플러그인)이 있다면, 해당 프로토콜과 Keycloak을 연동해야 한다. 기본적으로 다음 정보를 Gateway 플러그인에 설정한다.

* **Keycloak의 발급자(issuer) URL**: `https://<keycloak-server>/realms/<realm-name>`
* **클라이언트 ID**와 **클라이언트 시크릿(Secret)**
* **리다이렉트 URI(필요한 경우)**: 인증 후 되돌아올 주소

#### 2) 토큰 발급 및 검증

클라이언트가 처음 API Gateway에 접근할 때 인증이 필요한 경로라면, Gateway는 Keycloak에 인증을 위임하거나 클라이언트에 인증 요청을 보낸다.

* **인증 후 토큰 발급**: Keycloak은 사용자를 인증한 뒤, Access Token과(Optional) Refresh Token을 발급한다.
* **토큰 검증**: 발급된 토큰을 API Gateway가 검증한다. 이때 토큰이 유효한지, 만료되지는 않았는지, 필요한 스코프(scope)나 권한이 있는지를 확인한다.

#### 3) 토큰 인트로스펙션(Introspection)

토큰 내부의 서명(JSON Web Signature)을 통해 직접 검증하는 방식 외에도, Keycloak의 인트로스펙션 엔드포인트(`/realms/<realm-name>/protocol/openid-connect/token/introspect`)를 호출하여 토큰의 상태가 유효한지 확인할 수 있다.

* **장점**: Gateway에서 모든 JWT 서명 로직을 구현하지 않아도 되며, Keycloak이 토큰의 사용 여부·만료 여부·유효성 등을 일관되게 관리한다.
* **단점**: 각 요청마다 네트워크 호출이 발생하므로 트래픽이 많으면 성능 부담이 커질 수 있다.

#### 4) 액세스 정책 및 사용자 정보 연계

Keycloak에서 사용자 정보를 확장하거나, 역할(Role), 그룹(Group) 정보를 매핑해 둔 경우, API Gateway에서 이 정보를 활용해 요청을 필터링할 수 있다. 예를 들어, 특정 역할을 가진 사용자만 접근할 수 있는 경로를 Gateway 레벨에서 제한할 수도 있다.

* **속성 매핑**: Keycloak의 클라이언트 스코프(Client Scope)를 통해 추가적인 클레임(Claim)을 토큰에 실어 보낼 수 있다.
* **역할 기반 접근 제어(RBAC)**: Keycloak의 역할 정보가 토큰에 포함되면, Gateway에서 HTTP 헤더 혹은 토큰에서 해당 정보를 읽어 역할 기반 제어를 수행한다.

### 구현 시 고려 사항

#### 성능 최적화

API Gateway와 Keycloak 간 토큰 검증 과정을 매 요청마다 수행하면 시스템 부하가 커질 수 있다. 다음과 같은 최적화 방안을 고려한다.

* **JWT 캐싱**: 토큰이 서명된 JWT(JSON Web Token) 형태라면, Gateway에서 자체적으로 캐시를 두고 서명을 검증해 트래픽 부담을 줄일 수 있다.
* **인트로스펙션 호출 최소화**: 필요한 경우에만 인트로스펙션 엔드포인트를 호출하거나, 응답 결과를 캐시에 저장하는 방안을 적용한다.

#### 보안 정책

API Gateway에서 HTTPS를 통한 암호화 통신이 권장되며, 특히 Keycloak과의 토큰 교환 시 중요한 정보(클라이언트 시크릿 등)가 노출되지 않도록 유의해야 한다.

* **TLS 구성**: Gateway와 Keycloak 서버 간 통신에도 TLS가 적용되도록 설정한다.
* **임시 자격 증명**: 클라이언트 시크릿 등은 최소한의 기간에만 유효하도록 설정하거나, Keycloak에서 롤링(rolling) 기법을 사용해 주기적으로 변경한다.

#### 장애 대응 및 로깅

Keycloak과 연결이 원활하지 않을 경우, API Gateway를 통한 트래픽 흐름에 지장이 생길 수 있다. 높은 안정성을 위해 다음과 같은 전략을 적용한다.

* **고가용성 구성(HA)**: Keycloak을 클러스터링하거나 복제하여 단일 장애 지점을 제거한다.
* **로깅 및 모니터링**: API Gateway가 토큰 검증 단계에서 문제를 일으킬 경우, 해당 오류를 로깅하고 모니터링 시스템에 지표를 전송해 장애를 신속하게 파악할 수 있도록 한다.

***

API Gateway와 Keycloak을 통합하면, 다양한 마이크로서비스에서 일관된 인증·인가 정책을 손쉽게 적용할 수 있으며, 확장성 높은 보안 아키텍처를 마련할 수 있다. 토큰 검증·인트로스펙션·역할 기반 접근 제어 등 Keycloak이 제공하는 기능을 Gateway에서 적극 활용함으로써, 기존 애플리케이션 코드를 수정하지 않고도 통합 인증 구조를 구축하는 데에 큰 이점을 얻을 수 있다.