0. Keycloak 한 번에 이해하기 (태생/역사/왜 인프라에 중요한가)

Keycloak 한 번에 이해하기 — 태생/역사/왜 인프라 운영자에게 중요한가

개요 — Keycloak은 OpenID Connect(OIDC) / OAuth2 / SAML 기반의 오픈소스 IAM/SSO 서버다. “로그인”을 중앙화하고, “권한(RBAC)”을 표준 토큰(JWT)으로 흘려보내서 리버스프록시/포털/대시보드/내부도구를 한 덩어리로 묶는다.

3분 요약

Keycloak = “사내 로그인/권한”의 중앙 서버(IdP)
앱이 비밀번호를 직접 관리하지 않고, 토큰(JWT)으로 인증/권한을 전달
운영자 관점에서 제일 큰 이점은 계정/권한/감사/정책을 “한 군데”에서 통제 가능

1) 내가 이걸 왜 도입했냐고?

인프라 운영을 하다 보면 내부에 툴이 계속 늘어난다.

대시보드(모니터링/리포트/캘린더)
자동화 포털(n8n, 배치/리포트, 시큐리티 조회)
운영 페이지(정책 생성, 배포, 승인 흐름)

문제는 툴이 늘어날수록 “계정/권한/감사”가 산으로 간다는 것.

✔️ Keycloak은 인증(누구냐)과 인가(뭘 할 수 있냐)를 표준 프로토콜(OIDC/OAuth2/SAML)로 중앙화한다.
✔️ 운영자는 “각 서비스별 로그인 구현” 대신, “권한 모델 설계 + 프록시/앱 연동”에 집중할 수 있다.

2) Keycloak의 태생/역사 (사람들이 궁금해하는 포인트까지)

2-1) 태생: “앱 보안(REST) + 로그인 연동(브로커)”에서 시작

Keycloak은 초기부터 “앱이 직접 비밀번호/인증 로직을 들고 있지 않게 하자”는 방향이었다. (초기에는 Java 생태계의 REST 보안 모듈 + 소셜 로그인/브로커 아이디어가 합쳐지며 성장)
운영자 관점으로 바꿔 말하면: 툴마다 로그인 붙이는 비용을 줄이고, 표준 토큰으로 묶는 쪽으로 진화했다.

2-2) PicketLink와의 관계: “JBoss/Red Hat 계열 SSO의 계보”

예전에는 Red Hat/JBoss 진영에서 PicketLink가 SSO/연합(SAML) 쪽을 많이 담당했는데, 시간이 지나며 기능/코드가 Keycloak 쪽으로 합쳐지는 흐름이 생겼다.
그래서 Keycloak을 보다 보면 “이름만 바뀐 제품인가?” 같은 질문이 나오는데, 결론적으로는 기존 계보의 경험이 Keycloak로 수렴한 케이스에 가깝다.

2-3) “왜 갑자기 설정법이 바뀌었지?” — Quarkus 전환(클라우드 네이티브화)

Keycloak은 한동안 WildFly 기반 배포가 중심이었는데, 컨테이너/쿠버네티스 시대에 맞춰 Quarkus 기반 배포(신 배포 방식)로 큰 전환을 했다.
체감 포인트: 부팅/메모리/운영 옵션이 컨테이너 친화적으로 바뀌면서, “start-dev(학습)”와 “start(운영)”의 구분이 더 명확해졌다.

2-4) “공식 어댑터(adapter) 왜 줄였어?” — 표준 스택으로 돌아가는 흐름

예전에는 각 언어/프레임워크용 “Keycloak 전용 어댑터”가 꽤 있었는데, 시간이 지나며 OIDC/OAuth2가 표준으로 굳어지고 프레임워크/미들웨어 자체 지원이 좋아지면서 전용 어댑터 의존도를 줄이는 방향이 생겼다.
운영자 입장에서는 오히려 장점이 될 때가 많다: 특정 벤더/라이브러리에 락인되는 대신 표준 OIDC 클라이언트(openid-client 등)로 정리 가능.

2-5) CNCF 합류: “중립 거버넌스 + 커뮤니티 확장”

Keycloak은 2023년 4월 CNCF(Cloud Native Computing Foundation)에 합류(Incubating)하면서 “특정 회사가 쥐고 있는 프로젝트” 느낌이 줄고, 커뮤니티/거버넌스가 더 강화되는 방향으로 갔다.

타임라인(아주 러프)

2014: 초기 공개/첫 안정 릴리즈 (프로젝트 본격 성장)
2015~2016: 기존 계보(PicketLink 등)와의 통합/수렴
2019~2022: Keycloak.X / Quarkus 기반 배포로 전환(클라우드 네이티브화)
2023: CNCF Incubating 합류

3) 그림으로 보는 Keycloak의 자리 (이번엔 안 깨지게)

아래 그림이 예전에 “한 줄로 뭉개져 보인” 이유는 줄바꿈/공백이 HTML에서 합쳐졌기 때문. <pre>로 감싸면 줄바꿈이 유지된다.

3-1) “Keycloak이 어디에 끼는가?” (인프라 운영자 관점)

┌──────────────────────────┐        ┌──────────────────────────┐        ┌──────────────────────────┐
│        사용자/브라우저     │  HTTPS │     Nginx / Reverse Proxy │  HTTP  │        내부 앱들          │
│  (운영자/사용자/개발자)    ├───────▶│  - TLS 종료 / 라우팅       ├───────▶│  React / Node API / 대시보드 │
└───────────────┬──────────┘        │  - auth_request 연동       │        └───────────────┬──────────┘
                │                   │  - (선택) OAuth2-Proxy     │                        │
         (1) 로그인 필요            └───────────────┬──────────┘                 (3) 토큰/헤더로 접근제어
                │                                   │
                ▼                                   │
┌──────────────────────────┐                        │
│         Keycloak          │◀───────────────────────┘
│  - OIDC / OAuth2 / SAML   │   (2) 로그인 성공 → 토큰(JWT) 발급
│  - SSO / RBAC / MFA       │       (id/access/refresh)
└──────────────────────────┘

Keycloak은 로그인/권한 “발급” 담당
Nginx는 경로 정책/차단/라우팅 “집행” 담당
앱은 “비즈니스 로직”에 집중 (로그인 구현 지옥 탈출)

3-2) OIDC 로그인 흐름(가장 흔한 형태: Authorization Code + PKCE)

[브라우저] ── (A) /portal 접속 ───────────────────────────────▶ [Nginx/앱]
   │                          (B) 로그인 필요(401/redirect)          │
   │◀───────────────────────────────────────────────────────────────┘
   │
   │  (C) Keycloak로 Redirect  (client_id, scope, redirect_uri, state, code_challenge)
   ├──────────────────────────────────────────────────────────────▶ [Keycloak]
   │  (D) 로그인 + MFA(필요시) 완료
   │◀──────────────────────────────────────────────────────────────┤
   │  (E) redirect_uri로 돌아오며 code 전달
   ├──────────────────────────────────────────────────────────────▶ [Nginx/앱]
   │  (F) 앱이 code + code_verifier로 토큰 교환
   ├──────────────────────────────────────────────────────────────▶ [Keycloak]
   │◀──────────────────────────────────────────────────────────────┤  (G) id/access/refresh 토큰 발급
   │
   └─ (H) 이후 요청은 쿠키/토큰(또는 헤더)로 접근 제어

운영자 관점 체크 포인트

Keycloak Realm/Client 구조를 “서비스 단위”로 어떻게 쪼갤지
RBAC는 Realm Role vs Client Role 어디에 둘지 + 토큰에 어떤 Claim으로 담을지
Nginx는 auth_request로 1차 게이트를 만들고, 앱은 “세부 권한”을 최종 체크

4) 이 시리즈에서 다룰 것 (인덱스)

TechNote 1 — 라이선스/배포판(Upstream vs Red Hat build) / 실무 체크
TechNote 2 — Docker로 start-dev(학습·검증) 올리기
TechNote 3 — 운영용 Docker Compose(Postgres, optimized, health/metrics)
TechNote 4 — Realm/Client/Role/Group/Mapper: “권한 토큰” 설계
TechNote 5 — 구성 사례: React+Node+Nginx(+OAuth2-Proxy)로 RBAC 붙이기
TechNote 6 — 운영 백업/복구: Realm export/import, DB 백업, 키 관리

참고

Last updated: 2025-12-29 (KST)

'Tech Note > 보안-Keycloak(인증)' 카테고리의 다른 글

5. 구성 사례: React + Node + Nginx (+OAuth2-Proxy)로 RBAC 붙이기 (0)	2025.12.28
4. Realm/Client/Role/Group/Mapper — “권한 토큰” 설계법 (0)	2025.12.28
3. 운영용 Docker Compose (Postgres + optimized + health/metrics) (0)	2025.12.28
2. Docker start-dev (학습/검증) (0)	2025.12.28
1. 라이선스/배포판/실무 체크 (Upstream vs Red Hat build) (0)	2025.12.28

Keycloak 한 번에 이해하기 — 태생/역사/왜 인프라 운영자에게 중요한가

1) 내가 이걸 왜 도입했냐고?

2) Keycloak의 태생/역사 (사람들이 궁금해하는 포인트까지)

2-1) 태생: “앱 보안(REST) + 로그인 연동(브로커)”에서 시작

2-2) PicketLink와의 관계: “JBoss/Red Hat 계열 SSO의 계보”

2-3) “왜 갑자기 설정법이 바뀌었지?” — Quarkus 전환(클라우드 네이티브화)

2-4) “공식 어댑터(adapter) 왜 줄였어?” — 표준 스택으로 돌아가는 흐름

2-5) CNCF 합류: “중립 거버넌스 + 커뮤니티 확장”

3) 그림으로 보는 Keycloak의 자리 (이번엔 안 깨지게)

3-1) “Keycloak이 어디에 끼는가?” (인프라 운영자 관점)

3-2) OIDC 로그인 흐름(가장 흔한 형태: Authorization Code + PKCE)

4) 이 시리즈에서 다룰 것 (인덱스)

참고

'Tech Note > 보안-Keycloak(인증)' 카테고리의 다른 글

티스토리툴바