용어 정리
Realm
Keycloak에서 Realm은 인증, 권한, 사용자 관리 등 보안 정보를 독립적으로 관리하기 위한 논리적 구분 단위이다. 예를 들어, 서로 다른 애플리케이션 환경(개발, 스테이징, 프로덕션)을 완전히 분리해서 관리하고 싶거나, 서로 다른 고객사 혹은 조직에 대해 동일한 Keycloak 인스턴스를 사용하되 보안 도메인은 격리하고 싶을 때 Realm을 활용한다. 각 Realm은 자체 사용자 디렉터리와 설정을 가지므로, 서로 간에 인증·권한 정보가 겹치지 않는다.
Client
Keycloak에서 Client는 보호받아야 하는 애플리케이션 또는 서비스(자원 서버, 웹 애플리케이션, 모바일 앱 등)를 지칭한다. 클라이언트는 사용자의 인증 절차 및 권한 부여 과정을 통해 액세스 토큰(access token)을 발급받아 보안이 필요한 자원에 접근한다. 다음과 같은 예시가 있다.
웹 앱: 서버 사이드 렌더링 웹사이트
SPA(Single Page Application): Vue.js, React 등으로 구성된 프론트엔드 애플리케이션
네이티브 앱: iOS, Android 애플리케이션
API 서버: 자원 서버(Resource Server)로서 액세스 토큰 검증을 수행
User
Keycloak에서 User는 Realm 안에서 인증받을 수 있는 주체를 의미한다. 사용자 정보에는 다음과 같은 항목이 포함될 수 있다.
사용자 이름(user name)
이메일 주소
패스워드(해시 형태로 저장)
2차 인증(MFA) 설정
소셜 계정 또는 외부 IdP(Idenity Provider) 계정 연동
Identity Provider (IdP)
Identity Provider는 사용자 인증을 제공하는 외부 서비스나 시스템을 일컫는다. Keycloak은 자체 데이터베이스에 저장된 사용자를 인증할 수도 있지만, 필요에 따라 외부 IdP를 통해 소셜 로그인이나 조직 내 SSO를 연계할 수 있다. 예:
Google, GitHub 등 소셜 로그인
기업 내부의 LDAP/Active Directory
SAML 기반 기업용 인증 시스템
Identity Broker
Keycloak에서 Identity Broker는 다양한 외부 IdP와 연동하여 인증을 위임하는 모듈이다. 예를 들어, 회사 내부적으로 SAML을 사용하는 ADFS(Active Directory Federation Services)와 연결하거나, OIDC(OpenID Connect)를 사용하는 구글과 연결할 때 Identity Broker가 담당한다.
User Federation
Keycloak에서 User Federation은 LDAP/Active Directory 등 기존의 사용자 디렉터리에서 계정을 가져오거나 동기화할 수 있도록 지원하는 기능이다. 이를 통해 다음을 실현할 수 있다.
기존 사내 디렉터리(예: Active Directory)를 그대로 활용
사용자 계정 관리의 중복이나 이원화 최소화
다양한 도메인 혹은 조직 단위별 사용자 계정 연동
Roles
Role은 접근 권한을 한데 묶는 개념이다. 애플리케이션별 혹은 Realm 차원에서 부여할 수 있는데, 보통 다음과 같은 방식으로 활용한다.
Realm Role: 전체 Realm에서 공통으로 적용될 수 있는 범용 Role
Client Role: 특정 Client에만 유효한 Role 이 Roles를 바탕으로 세분화된 RBAC(Role-Based Access Control) 구조를 구현할 수 있다.
Groups
Group은 여러 사용자를 하나의 그룹으로 묶어 공통 권한을 쉽게 관리하기 위한 개념이다. Role과 마찬가지로, Group에 Role을 매핑함으로써 대량 사용자에 대한 접근 권한을 일괄 부여/철회할 수 있다.
Protocol
Keycloak은 주로 다음 인증 프로토콜을 지원한다.
OpenID Connect (OIDC): OAuth 2.0을 기반으로 한 인증·인가 프로토콜로, 웹·모바일 등 다양한 환경에 적용 가능하다.
SAML (Security Assertion Markup Language): 기업용 SSO를 위해 널리 사용되는 XML 기반 인증·인가 프로토콜이다.
Authentication Flow
Keycloak에서 Authentication Flow는 사용자가 인증을 시도할 때 어떤 단계를 거쳐야 하는지 정의한 절차이다. 예를 들어,
사용자 이름/비밀번호 입력 후 2FA(2단계 인증) 진행
소셜 로그인 선택
시나리오별 조건부 인증 (Conditional Authentication)
를 설정하여 유연한 인증 과정을 구성할 수 있다.
Token
Keycloak은 인증을 완료한 사용자가 자원에 접근할 때, 또는 애플리케이션이 사용자를 대신하여 API를 호출할 때 토큰을 사용한다. 대표적으로 다음이 있다.
Access Token: 사용자가 자원 서버에 요청을 보낼 때 첨부하는 토큰. 유효 기간 내에는 세션 정보를 반복해서 확인할 필요가 없다.
Refresh Token: Access Token이 만료된 경우, 새 토큰 발급을 위해 사용하는 토큰. 유효 기간이 상대적으로 더 길다.
Admin Console
Keycloak의 Admin Console은 웹 기반의 관리 도구로서, 관리자(admin)가 Realm, 사용자, 클라이언트, 정책 등을 설정·관리할 수 있도록 제공된다. 일반적으로 {keycloak_url}/admin 경로로 접속하며, 브라우저 환경에서 모든 설정을 시각적으로 조정할 수 있다.
Service Account
Service Account는 사용자를 대표하지 않고 서비스(혹은 클라이언트) 자신이 시스템 자원에 접근할 때 사용하는 특수 계정이다. 예를 들어, 백엔드 서비스 간 통신에서 각 서비스가 인증을 받을 때 사용한다. 일반 사용자와 달리 인터랙티브한 로그인이 아닌, 클라이언트 크리덴셜(Client Credentials) 흐름을 통해 토큰을 발급받는다.
간단한 구조 예시 (Mermaid)
Keycloak을 활용해 애플리케이션과 IdP가 상호작용하는 흐름을 간단히 나타내면 아래와 같다:
위 다이어그램은 Keycloak이 사용자와 애플리케이션 사이에서 IdP로 인증을 위임하거나 자체 인증을 수행하는 전형적인 구조를 보여준다.
이와 같은 주요 용어를 숙지함으로써 Keycloak의 전반적인 구성 요소와 동작 방식을 이해할 수 있다. 각 용어는 애플리케이션 통합 시 어떻게 응용되는지, 어떤 설정을 통해 구체화되는지를 파악하는 것이 중요하다.
Last updated