Keycloak 학습 지도
앱은 디렉터리 password를 받지 않고, Keycloak이 증명한 신원을 검증해 자기 권한을 결정한다.
이 덱은 디렉터리·IdP 제품·로그인 프로토콜의 종류를 먼저 구분하고 Keycloak의 자리와 OIDC를 이해한 뒤, 로컬 사용자 SSO와 API 인가, Samba AD 호환 디렉터리의 LDAPS Federation, group이 token claim과 API 역할이 되는 두 매핑을 개념으로 정리한다. 마지막에는 brokering·서비스 계정과 배포·관찰·복구 경계를 다룬다. Docker Compose에서 같은 흐름을 직접 재현하는 절차는 Keycloak 실습 덱에 있다.
실습 기준은 Keycloak 26.7.3, PostgreSQL 18.6, Samba 4.19.5와 Node 24다. macOS/Colima 비브라우저 기본 흐름과 macOS의 대표 Chrome 로그인을 검증했지만 네이티브 Ubuntu, Microsoft AD DS, 운영 HA는 미검증이다. 마무리에서 통과·참조·보류 범위를 구분한다.
큰 그림부터 읽기- 큰 그림인증 생태계에서 Keycloak의 자리
디렉터리·IdP · Keycloak 역할 · realm · OAuth·OIDC·PKCE의 목적
비슷한 인증 용어는 어떤 종류이고 어디에서 이어지나
- 로그인과 접근로그인에서 최종 API 권한까지
Code+PKCE · SSO · token 검증 · group/role · MFA · logout
token은 누가 무엇을 검증하고 401·403·200은 어디서 갈리나
- 외부 디렉터리AD 호환 원본에서 API claim까지
Samba · LDAPS Federation · 두 mapper · 변경과 장애
외부 group과 계정 상태는 언제 새 token에 반영되나
- 다른 연동외부 IdP·서비스·비네이티브 앱
OIDC Brokering · SAML · Service Account · proxy · Kubernetes
사용자 redirect와 machine identity, API server 인증은 어떻게 다른가
전체를 관통하는 두 문장
섹션 제목: “전체를 관통하는 두 문장”매핑은 두 번 일어난다. 디렉터리의 group이 Keycloak 모델로 들어오는 LDAP 매핑과 Keycloak의 값이 token claim으로 실리는 protocol 매핑은 별개의 설정이다. “앱에 그룹이 안 보인다”는 문제의 진단은 언제나 이 둘 중 어디서 끊겼는지 가르는 데서 시작한다.
신뢰는 서명으로 흐른다. 앱도, 쿠버네티스 API 서버도 Keycloak에 비밀번호를 물어보지 않는다. Keycloak이 개인키로 서명한 토큰을, 각자가 공개키(JWKS)로 검증할 뿐이다. 그래서 인증은 한 곳에 모이고 검증은 각 소비자에서 일어난다. 최종 인가는 앱이나 Kubernetes RBAC의 몫이다.
문제·작업으로 바로 찾기
섹션 제목: “문제·작업으로 바로 찾기”처음부터 읽지 않고 지금 겪는 증상이나 할 일로 들어가려면 이 표에서 시작한다.
| 찾는 것 | 먼저 볼 장 | 바로 확인할 것 |
|---|---|---|
| 실습을 처음부터 재현 | Keycloak 실습 덱 | runtime·자원·DNS/CA·secret 준비 |
| 로컬 로그인·앱 두 개 SSO | Client 로그인 실습, SSO·API 실습 | client별 redirect/secret과 realm session |
| API token 401·403·200 | Token 검증 | access token의 서명·iss·aud·exp와 role |
| AD 로그인이 안 됨 · LDAPS 오류 | 외부 계정 로그인 실습 | CA, bind, READ_ONLY, import/sync/cache |
| group이 token/API 권한에 없음 | 외부 Group 권한 실습 | LDAP mapper와 protocol mapper를 따로 확인 |
| 변경·disable·장애가 언제 반영됨 | 디렉터리 변경과 장애 | 새 로그인/refresh/기존 JWT/app session |
| 다른 IdP·SAML·서비스 인증 | Identity Brokering, SAML, Service Accounts | redirect trust와 machine identity를 구분 |
| Operator · DB · HA · 관찰 | 배포 설계, 저장소와 가용성, 인증 흐름 관찰 | 실습과 운영 보장을 분리 |
| 백업 · upgrade · key 교체 | 백업과 업그레이드, 관리 권한과 서명 키 | 격리 복원과 키 겹침 기간 |
| 오류 문구로 원인 찾기 | Keycloak 문제 진단 | 마지막 성공 경계부터 확인 |
| 약어·용어만 빠르게 찾기 | Keycloak 용어 사전 | 역할별 뜻과 상세 페이지 링크 |