Realm과 로컬 사용자

다른 이름: Keycloak realm · 로컬 사용자 · required action · master realm내용 검토: 2026. 09. 14.

결론부터

업무 앱과 사용자는 별도 realm에 두고, 계정 활성화·자격 증명·required action을 모두 통과해야 로그인이 완성된다.

Keycloak을 시작하면 관리용 master realm이 먼저 보인다. 이 공간에 업무 사용자를 섞지 않고, 학습에서는 study realm을 별도로 만들어 앱·사용자·정책의 경계를 세운다.

이 장에서 처음 나오는 말3개

master realm: Keycloak 서버 전체 관리자를 두는 특별한 realm. 일반 업무 앱과 사용자를 넣는 공간이 아니다.
required action: 첫 로그인 때 비밀번호 변경·OTP 등록·이메일 확인처럼 사용자가 반드시 끝내야 하는 후속 단계.
credential: 사용자가 신원을 증명할 때 쓰는 비밀번호·OTP 같은 수단. 사용자 레코드와 활성 상태만으로 로그인할 수 있는 것은 아니다.

큰 그림

공간	넣는 것	넣지 않는 것
`master`	서버 전체 bootstrap·관리 계정	업무 앱 client와 일반 사용자
`study`	이 덱의 사용자·client·role·Federation·로그인 정책	다른 환경의 운영 계정

realm을 나누면 사용자 목록만 갈라지는 것이 아니다. 토큰의 issuer와 SSO 세션, client·role·로그인 정책도 분리된다. 같은 이름의 사용자가 두 realm에 있어도 서로 다른 신원이다.

이 장에서 답할 질문

왜 master와 업무 realm을 분리하는가?
사용자를 만들 때 활성 상태·비밀번호·required action은 어떻게 다른가?
첫 로그인이 실패하면 어디부터 확인하는가?

첫 realm과 사용자 만들기

이 실습은 first-start.sh가 study realm과 local-user를 멱등하게 준비한다. 콘솔로 학습할 때도 결과는 같은 세 단계다. Keycloak 관리 가이드는 realm이 사용자·credential·role·group을 관리하는 격리 단위임을 설명한다.

master의 bootstrap 관리자 계정으로 Admin Console에 들어가 study realm을 선택한다.
Users에서 username을 만들고 Enabled 상태를 확인한다.
Credentials에서 비밀번호를 설정한다. 첫 로그인에 바꾸게 하려면 temporary로 두고, 바로 재현할 실습 계정이면 temporary를 끈다.
필요한 경우 Required user actions에 UPDATE_PASSWORD나 CONFIGURE_TOTP를 붙인다.
account 화면이나 등록된 client의 Authorization Code 흐름으로 실제 로그인을 확인한다.

required action은 비밀번호 검증 뒤에도 로그인 흐름을 멈출 수 있다. 로그인 화면이 다시 나타난다고 비밀번호 오류로 단정하지 말고, 사용자가 action 화면에서 끝내지 않은 단계가 있는지 확인한다.

사용자 상태를 나눠 본다

상태	새 로그인	이미 발급된 JWT
사용자는 enabled, credential 정상	정책을 통과하면 성공	`exp`와 소비자 검증 규칙까지 유효
비밀번호 오답	실패	기존 JWT에는 영향 없음
required action 미완료	action 완료 전 client callback에 도달하지 않음	이미 발급된 JWT와 별개
사용자 disabled	새 로그인과 이후 refresh가 거부될 수 있음	로컬 서명 검증만 하는 소비자는 보통 `exp`까지 수용

마지막 행은 이 덱의 장애 실습에서도 확인한다. 계정을 끄는 일과 모든 앱에서 이미 받은 JWT를 즉시 회수하는 일은 같지 않다.

자동화와 콘솔의 관계

콘솔은 개념과 현재 상태를 살피기에 좋지만 재현 가능한 원본은 아니다. 실습의 realm JSON과 seed script는 labs/keycloak/keycloak/ 및 labs/keycloak/scripts/에 둔다. seed는 같은 realm이 있으면 무작정 덮어쓰지 않고, 관리 credential도 앱 container에 전달하지 않는다. 운영에서 같은 역할을 맡는 도구와 선택 기준은 설정을 코드로 관리한다에 있다.

요약

realm과 local-user가 있는 기반 상태에서 첫 client를 직접 붙이려면 Client를 연결하고 로그인 확인하기로 이어 간다.

master는 서버 관리용이고, 앱·사용자·정책은 별도 업무 realm에 둔다.
사용자 레코드, enabled 상태, credential, required action은 로그인 성공의 서로 다른 조건이다.
계정 비활성화는 새 인증을 막지만 이미 발급된 JWT를 자동으로 즉시 지우지는 않는다.
콘솔은 확인 도구이며 재현 원본은 versioned seed와 설정 파일이다.