Keycloak 학습 마무리

결론부터

Keycloak을 이해했다는 것은 로그인 화면을 띄운 것이 아니라 신원 원본에서 token claim과 최종 API 결정까지 각 경계를 설명하고 재현할 수 있다는 뜻이다.

전체 흐름

사용자/서비스
  -> 로컬 계정 | LDAP Federation | 외부 IdP Brokering | Service Account
  -> Keycloak 인증 flow와 realm SSO session
  -> client scope + protocol mapper
  -> 서명된 access token
  -> API의 iss/aud/exp/서명 검증
  -> role 검사: 401 / 403 / 200

사용자 password는 Keycloak 또는 연결된 원본에서만 검증하고 앱 A/B와 API에는 전달하지 않는다. LDAP group은 Keycloak group/role로 가져온 뒤 별도 protocol mapper를 통해 token claim이 된다. API는 token을 받았다는 이유만으로 허용하지 않고 발급자·대상·시간·서명과 endpoint 권한을 모두 검사한다.

실제로 재현한 범위

범위	상태	근거
macOS/Colima 빈 Compose 시작·보존 재개	비브라우저 통과	P11: kind·kubectl 없이 6 service healthy
macOS 실제 Chrome 대표 로그인	통과	Admin Console·Account Console, 앱 A Code + PKCE
기존 완성 환경의 guided 공개 설정·검사	통과	app-a/app-b/api/ldap/groups 재적용과 다섯 로그인 검사
빈 상태 guided 단계별 시작·재개	미실행	기존 volume·CA·secret 초기화 승인 필요
local-user 앱 A→B SSO와 API	HTML form 진단 통과	credential 1회, API 401/403/200
Samba LDAPS Federation과 group 권한	통과	alice/bob 로그인, group→role→claim→API
변경·disable·LDAP 장애 시간축	통과	새 로그인/refresh/기존 JWT/app session 분리
복제 flow의 OTP 등록·실패·복구	HTML form 진단 통과	전용 client/user, realm 기본 flow 미변경
두 test realm OIDC Brokering	HTML form 진단 통과	최초 local link와 재로그인 link 재사용
service account client credentials	통과	최소 역할 token, API 401/200/403
PostgreSQL backup·격리 restore	통과	source/restore 수와 핵심 realm/client 확인

상세 명령과 환경 기록은 repository의 labs/keycloak/README.md와 verification.md에 있다. 진단은 password, OTP secret/code, authorization code, cookie, client secret과 token 원문을 증거에 남기지 않았다.

아직 검증하지 않은 범위

• 네이티브 Ubuntu 24.04 + rootful Docker Engine의 Samba P03과 빈 상태 P11
• Microsoft AD DS, 실제 회사 upstream IdP, 전체 SAML 로그인
• oauth2-proxy 실행, Kubernetes OIDC/credential plugin/RBAC 실행
• 다중 Keycloak·PostgreSQL HA, failover, rolling upgrade와 site 복구

macOS에서는 login keychain에 web CA를 신뢰시킨 실제 Chrome Admin Console·Account Console과 앱 A Authorization Code + PKCE 로그인까지 확인했다. 이 결과를 Ubuntu·Microsoft AD DS·운영 HA 성공으로 일반화하지 않는다. Kubernetes OIDC와 배포 설계는 후속 실행을 위한 참조이고 현재 실습 성공 항목이 아니다.

다시 찾는 지도

질문	페이지
AD·LDAP·IdP·OIDC·SAML·PKCE는 어떻게 다른가	인증 생태계의 큰 그림
OAuth·OIDC·PKCE는 왜 함께 필요한가	로그인과 접근 위임의 목적
Keycloak은 어디에 있고 무엇을 책임하나	Keycloak의 역할
앱 로그인과 token 검증은 어떻게 이어지나	실습 코드에서 읽을 것, Client 로그인 실습, SSO·API 실습
group이 API 권한이 되는 과정은 무엇인가	Group과 Role, Scope와 Mapper
외부 계정·group을 직접 연결하려면	외부 계정 로그인 실습, 외부 Group 권한 실습
외부 directory 변경은 언제 반영되나	디렉터리 변경과 장애
배포·상태·관찰·복구는 어떻게 나뉘나	배포 설계, 인증 흐름 관찰, 백업과 업그레이드
증상에서 어디부터 볼까	Keycloak 문제 진단
용어를 다시 확인하려면	Keycloak 용어 사전

다음 실행의 시작 조건

Ubuntu 지원 경로는 Ubuntu 24.04 host와 rootful Docker Engine에서 labs/keycloak/samba/verify-p03.sh를 먼저 실행하고, 통과한 같은 환경에서 guarded verify-p11.sh 전체 재현을 수행한다. browser 확인은 사용자가 macOS web CA trust 변경을 승인한 뒤 Chrome의 Admin Console과 앱 A 로그인을 대표 경로로 확인한다. 선택 실습은 별도 범위에서 proxy 또는 cluster topology와 복구 접근을 먼저 확정한다.

요약

• 신원 원본→Keycloak 모델→token claim→API 검증과 권한 결정을 하나의 추적 가능한 흐름으로 본다.
• Compose 핵심 흐름과 OTP·Brokering·서비스 계정·DB 복원은 실제 진단으로 검증했다.
• 대표 macOS Chrome은 통과했고, Ubuntu·실제 AD/IdP·proxy/Kubernetes·HA와 빈 guided 재현은 미실행 상태와 재개 조건을 명시해 남겼다.