Keycloak으로 구현하는 엔터프라이즈 인증·인가 아키텍처 (SSO, OAuth2, OIDC 완전 정리)

현대 백엔드 시스템에서 인증(Authentication)과 인가(Authorization)는 더 이상 단순 로그인 기능이 아니다.
MSA, SaaS, 멀티 디바이스 환경에서는 중앙 집중형 IAM(Identity and Access Management)이 필수다.

이때 사용할 수 있는 대표적인 오픈소스가 바로 Keycloak이다.

---

📌 Keycloak이란?

Keycloak은 Red Hat에서 만든 오픈소스 IAM 솔루션으로,
다음 기능을 기본 제공한다.

• SSO (Single Sign-On)
• OAuth2 / OpenID Connect / SAML 지원
• 사용자/권한 관리 UI
• 소셜 로그인 (Google, Kakao 등)
• MFA (OTP, SMS 등)
• RBAC / 그룹 기반 권한 관리

👉 즉, 인증/인가를 직접 구현하지 않고 외부화(Externalization) 하는 전략이다.

---

📌 왜 Keycloak을 써야 하는가

1. 인증 로직 제거 (Auth Server 분리)

기존 구조:

User Service → 로그인/토큰/세션 직접 구현

 

Keycloak 도입:

Client → Keycloak (인증)
→ Service (인가 기반 API 처리)

 

👉 서비스는 비즈니스 로직에만 집중 가능

---

2. 표준 기반 (OAuth2 / OIDC)

• Access Token (JWT)
• Refresh Token
• Authorization Code Flow
• PKCE 지원

👉 클라이언트(Web, Mobile, SPA) 확장성 확보

---

3. MSA에 최적화

• API Gateway + Keycloak 조합
• 서비스별 Resource Server 구성
• 토큰 기반 Stateless 인증

👉 세션 공유 문제 제거

---

📌 핵심 개념 정리

1. Realm

• Keycloak의 최상위 격리 단위
• 하나의 서비스/조직 단위

회사 A → Realm A
회사 B → Realm B

 

---

2. Client

• 인증을 요청하는 애플리케이션
• 예: frontend, backend, mobile app

---

3. User / Role

• User: 사용자
• Role: 권한 (RBAC)

ADMIN
RESEARCHER
USER

 

---

4. Token 구조

Keycloak은 JWT 기반 토큰을 발급한다.

 

{
"sub": "userId",
"realm_access": {
"roles": ["ADMIN"]
},
"exp": 1710000000
}

 

👉 서비스는 이 토큰을 검증하여 인가 처리

---

📌 아키텍처 예시 (MSA 기준)

[ Client (React / App) ]
↓
[ API Gateway ]
↓
[ Keycloak ]
↓
┌───────────────┐
│ Auth Server │
└───────────────┘
↓
┌───────────────┬───────────────┬───────────────┐
│ User Service │ Order Service │ Payment │
└───────────────┴───────────────┴───────────────┘

 

👉 흐름

1. Client → Keycloak 로그인
2. Access Token 발급
3. API 호출 시 토큰 포함
4. Gateway / Service에서 JWT 검증

---

📌 장점

• 인증 로직 제거 → 개발 생산성 증가
• 보안 표준 준수 → 취약점 감소
• SSO 구현 가능
• 관리자 UI 제공 → 운영 편리
• 확장성 (멀티 서비스, 멀티 클라이언트)

---

📌 단점 / 고려사항

• 초기 러닝커브 존재
• 운영 복잡도 증가 (Auth 서버 관리 필요)
• 토큰 설계 잘못하면 보안 이슈 발생
• 커스터마이징 시 난이도 높음

👉 특히 Role/Scope 설계가 핵심

---

📌 언제 도입해야 하는가

✔ 추천 상황

• MSA 구조
• 여러 서비스에서 로그인 공유 필요
• OAuth2 기반 API 설계
• 외부 사용자 대상 서비스

❌ 비추천

• 단일 서비스 (Monolith)
• 단순 내부 시스템

---

📌 실무 적용 포인트

• API Gateway에서 JWT 검증 1차 처리
• 서비스에서는 Role 기반 Authorization만 수행
• Refresh Token 전략 분리 (보안 중요)
• Keycloak과 User DB 동기화 전략 필요

---

📌 결론

Keycloak은 단순 인증 도구가 아니라,
시스템 전체의 보안 아키텍처를 재정의하는 IAM 플랫폼이다.

잘 도입하면
👉 인증/인가 = 외부 위임
👉 서비스 = 비즈니스 집중

이라는 구조를 만들 수 있다.

---

📌 한 줄 정리

👉 “인증은 Keycloak에 맡기고, 서비스는 비즈니스에 집중하라”