Keycloak과 어플리케이션 통합
1️⃣ Spring Boot, Node.js, React 등과의 연동
1. Keycloak 연동 개요
Keycloak은 다양한 언어나 프레임워크와 연동이 가능합니다.
| 기술스택 | 통합 방식 | 사용 기술 |
|---|---|---|
| Spring Boot | 서버 사이드 인증 | Spring Security Adapter |
| Node.js | 미들웨어 인증 | Express + keycloak-connect |
| React | 프론트엔드 인증 | OIDC Client(JS) + Redirect Flow |
2. Spring Boot 연동 예시
의존성 추가 (build.gradle):
implementation 'org.keycloak:keycloak-spring-boot-starter:22.0.1'application.yml:
keycloak:
realm: myrealm
auth-server-url: http://localhost:8080
resource: spring-app
credentials:
secret: YOUR_CLIENT_SECRET
bearer-only: true보안 설정 (SecurityConfig.java):
@EnableWebSecurity
public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
super.configure(http);
http.authorizeRequests()
.antMatchers("/admin/*").hasRole("admin")
.anyRequest().permitAll();
}
}3. Node.js 연동 예시
npm install keycloak-connect express-sessionconst session = require('express-session');
const Keycloak = require('keycloak-connect');
const express = require('express');
const app = express();
const memoryStore = new session.MemoryStore();
const keycloak = new Keycloak({ store: memoryStore });
app.use(session({ secret: 'secret', resave: false, saveUninitialized: true, store: memoryStore }));
app.use(keycloak.middleware());
app.get('/admin', keycloak.protect('realm:admin'), (req, res) => {
res.send('관리자만 접근 가능');
});4. React 연동 예시
React는 클라이언트에서 OIDC Redirect Flow를 사용합니다. 예:
npm install keycloak-jsimport Keycloak from 'keycloak-js';
const keycloak = new Keycloak({
url: "http://localhost:8080/",
realm: "myrealm",
clientId: "frontend-app"
});
keycloak.init({ onLoad: 'login-required' }).then(authenticated => {
console.log("authenticated", authenticated);
});📌 통합 아키텍처 다이어그램
+---------+ +-------------+ +-------------+
| Browser | <----> | React 앱 | <----> | Keycloak |
+---------+ +-------------+ +-------------+
↑
↓
+------------------+
| Spring Boot API |
+------------------+2️⃣ Keycloak Adapter 사용법
1. Keycloak Adapter란?
Keycloak이 제공하는 공식 연동 라이브러리입니다. OIDC 기반 보안을 프레임워크에 쉽게 붙일 수 있게 해줍니다.
| 플랫폼 | 어댑터 |
|---|---|
| Java/Spring | keycloak-spring-boot-starter |
| Node.js | keycloak-connect |
| WildFly | keycloak-wildfly-adapter |
2. Keycloak Adapter 동작 원리
[ 요청 ]
↓
[ Keycloak Adapter ]
→ 유효한 토큰인가? 아니면 로그인 리다이렉션
→ 토큰 파싱 → 권한 체크 → 사용자 정보 주입예를 들어 keycloak.protect('realm:admin')은 토큰 안에 realm_access.roles에 "admin"이 있는지 확인합니다.
3️⃣ Keycloak Gateway 패턴 적용
1. Gateway 아키텍처 구성
Keycloak은 API Gateway 패턴에서 인증 관문 역할로 사용됩니다.
[ Client ]
↓
[ API Gateway (Ingress / Nginx / Kong 등) ]
↓ ↑
[ Service1 ] [ Service2 ] ←→ [ Keycloak ]2. 실전 예: NGINX + Keycloak
OIDC 플러그인을 사용한 인증 프록시 구성:
location /api/ {
auth_request /auth;
proxy_pass http://backend/;
}
location = /auth {
internal;
proxy_pass http://keycloak/auth/realms/myrealm/protocol/openid-connect/userinfo;
proxy_set_header Authorization $http_authorization;
}3. Keycloak Gatekeeper (구버전)
과거에는 keycloak-gatekeeper라는 독립 리버스 프록시를 사용했으며, 현재는 oauth2-proxy를 대체로 사용합니다.
4️⃣ 리버스 프록시와 함께 쓰는 Best Practice
1. HTTPS + Reverse Proxy
Keycloak은 인증 정보를 주고받기 때문에 반드시 HTTPS 사용을 권장합니다.
[ 사용자의 브라우저 ]
↓ HTTPS
[ NGINX / HAProxy ]
↓ HTTP (내부 통신)
[ Keycloak Server ]2. 프록시 헤더 전달 설정
Keycloak 뒤에 프록시가 있을 경우 X-Forwarded-* 헤더를 반드시 설정해야 합니다.
standalone.conf:
-Dkeycloak.proxy=edge3. 토큰 전달 전략
API 서버는 일반적으로 프론트엔드에서 받은 토큰을 헤더에 넣고 전달받습니다:
Authorization: Bearer eyJhbGciOi...4. Best Practice 요약
| 항목 | 권장 사항 |
|---|---|
| HTTPS 사용 | OIDC 보안성 확보 |
| Reverse Proxy | 프론트 + 인증 라우팅 분리 |
| 토큰 캐시 | Redis나 클러스터 캐시 활용 |
| 세션 저장 | Stateless 방식 권장 (Access Token 기반) |
✅ 마무리 요약
- Spring Boot, Node.js, React 등 다양한 기술과 쉽게 통합 가능
- Keycloak Adapter는 역할 기반 권한 인증을 쉽게 구현할 수 있도록 도와줌
- Gateway 패턴에서 인증을 분리하여 구조적이고 보안성 높은 구성 가능
- 리버스 프록시와 함께 사용할 경우 HTTPS 및 헤더 전달에 유의해야 함
마지막 수정일자