Keycloak
Keycloak 은 웹 애플리케이션과 RESTful 웹 서비스를 위한 오픈소스 SSO(Single Sign-On) 솔루션 입니다. 인증·권한·세션·SNS 연동 등 보안 기능을 표준화된 형태로 제공하며, 조직별 로그인·회원가입·계정 관리 화면을 커스터마이징할 수 있습니다. LDAP / Active Directory 연동도 지원됩니다. Seahorse Cloud 는 사용자·관리자 인증을 Keycloak 에 위임하며, 본 문서는 운영자가 Keycloak Admin Console 을 통해 인증 정책을 관리하는 방법을 안내합니다. 공식 문서: Keycloak Server Admin GuideRealm (렐름)
Keycloak 은 사용자를 독립된 가상 공간인 Realm 단위로 관리합니다. Realm 별로 보안 정책·도메인 주소·로그인 화면이 분리되며, 운영자는 Realm 에서 회원 탈퇴·로그인 화면 세팅 등을 수행합니다.
| Realm | 목적 | 대상 사용자 |
|---|---|---|
| Master Realm | Keycloak 시스템 자체 관리 — 다른 Realm 을 생성·관리하는 최상위 영역 | Keycloak 전체 관리자(admin 계정)만 |
| Seahorse Realm (일반 Realm) | 실제 서비스(Console·Agent 등) 의 인증·인가 처리 | Seahorse 서비스의 실제 사용자 |
사용자에게 비밀번호 재설정·회원가입 승인 이메일 발송 기능을 제공하려면, 네트워크·SMTP 서버·게이트웨이 설정이 필요합니다. 미설정 시 이메일 의존 흐름이 모두 실패합니다.
Keycloak 사용자 관리
Keycloak Realm 페이지에서 사용자 생성·수정·삭제·권한 관리를 수행합니다.사용자 생성 (운영자 콘솔)
전제 조건: Master Realm 이 아닌 Seahorse Realm 에 있어야 합니다.사용자 등록 경로
Keycloak 에서 신규 사용자가 추가되는 경로는 세 가지입니다.| 경로 | 설명 |
|---|---|
| 관리자 수동 추가 | 운영자가 Admin Console 또는 REST API 로 추가 |
| 자가 등록 (Self-Registration) | 로그인 화면의 Register 링크로 사용자가 직접 가입 — Seahorse 는 기본 활성 |
| 신원 중개 (Identity Brokering) | 외부 IdP(Google·GitHub 등) 로그인 시 자동 프로비저닝 |
| LDAP / AD 연동 | 사용자 저장소 활성 시 외부 디렉토리에서 자동 동기화 |
자가 등록 활성화 / 비활성화
사용자는 등록을 완료하기 위해 프로필 정보를 양식에 입력해야 합니다. 양식 필드는 운영자가 추가·제거·커스터마이즈할 수 있습니다.
비밀번호 및 자격 증명 관리
사용자의 자격 증명은 Users → 사용자 상세 → Credentials 탭에서 관리합니다.
| 컬럼 | 설명 |
|---|---|
| Type | 자격 증명 유형 — Password / OTP / WebAuthn 등 |
| User Label | 로그인 시 선택 옵션으로 표시될 라벨 (자유 입력) |
| Data | 자격 증명의 비기밀 메타데이터 (기본 숨김) |
| Actions | 비밀번호 재설정 / 삭제 |
비밀번호 정책 설정
Authentication → Policies → Password Policy 에서 비밀번호 복잡도·재사용 금지·만료 정책을 설정합니다.
사용자 비밀번호 재설정 (관리자)
운영자가 직접 재설정:
사용자에게 이메일로 재설정 요청:
사용자 삭제
더 이상 애플리케이션에 접근할 필요가 없는 사용자를 삭제합니다. 사용자 프로필과 데이터도 함께 삭제됩니다.Keycloak 세션
사용자가 Realm 클라이언트(Seahorse) 에 로그인하면 Keycloak 은 사용자별 세션 을 유지하며 방문 클라이언트를 기록합니다. Realm 관리자는 세션별로 다음 작업을 수행할 수 있습니다.- 활성 사용자와 로그인 위치 확인
- 사용자를 세션에서 강제 로그아웃
- 토큰 취소
- 토큰·세션 타임아웃 설정
Seahorse 의 세션은 두 개의 토큰이 결합된 구조 입니다.
- Keycloak 토큰 — 사용자가 인증된 사용자임을 증명. Keycloak 설정으로 수명 제어 가능.
- Seahorse Cloud 내부 토큰 — Keycloak 인증 이후 Seahorse 가 별도 발급하는 서비스 세션 토큰. 7 일 고정 이며 설정 변경이 불가합니다.
Keycloak 세션 운영
메뉴의 Sessions 에서 활성 클라이언트·세션의 최상위 뷰를 확인합니다.
클라이언트 세션 조회 (Seahorse·Agent 등)
세션 기본값
사용자 세션 조회
활성 세션 일괄 취소
시스템 침해·보안 사고 발생 시 모든 활성 세션을 취소 할 수 있습니다.
이벤트 추적 · 감사 구성
Keycloak 은 로그인·관리 작업 이벤트를 기록할 수 있으며, 이벤트 리스너 SPI 를 통해 외부 로그·이메일 연동도 지원합니다. 기본적으로는 오류 이벤트만 Admin Console 과 서버 로그에 표시되고, 성공 이벤트는 저장되지 않습니다.사용자 이벤트 감사 활성화
Admin 작업 이벤트는 별도의 Admin events settings 에서 동일한 방식으로 활성화합니다. 관리자 활동(사용자 생성·삭제·Realm 변경 등) 추적이 필요하면 반드시 함께 켜세요.
Keycloak 이 수집하는 개인 데이터
Keycloak 은 기본적으로 아래 데이터를 수집합니다.| 분류 | 수집 데이터 |
|---|---|
| 기본 프로필 | 사용자 이메일, 이름, 성 |
| 소셜 로그인 | 소셜 계정 프로필 + 소셜 계정 참조 |
| 감사·보안 | IP 주소, OS 이름, 브라우저 이름 (세션/이벤트 로그) |
| 자격 증명 | 비밀번호 해시, OTP 코드, WebAuthn 공개키 — 암호화 저장, 관리자에게도 비노출 |
| 권한 메타데이터 | 자격 증명 유형, 해시 알고리즘, 해시 반복 횟수 등 비기밀 정보 |
| 선택 수집 | 등록 양식 커스터마이즈 시 생일·성별·국적 등 추가 필드 / LDAP·소셜 IdP 에서 동기화된 데이터 |
| 권한 부여 (UMA) | 권한 부여 서비스 활성 시 사용자 소유 리소스 정보 |
관련 문서
- 관리자 계정 — Master / Seahorse 관리자 구분·발급
- 비밀번호 재설정 운영 가이드
- 회원 탈퇴 운영 가이드