1️⃣ 개요
Keycloak은 사용자 인증과 권한관리를 위한 Identity And Access management 솔루션이다.
IAM 솔루션으로써 SSO(SingleSignOn), 사용자 Federation 등의 기능을 위해서는 세션 및 토큰 관리를 이해하는것이 매우 중요하다.
이번 포스팅에서는 Keycloak의 세션 및 토큰 관리에 대해 다뤄보려고 한다.
들어가기전에 세션과 토큰에 대한 아주 간단한 개념 정리를 해보자.
| 구분 | 세션 (인증) | 토큰 (인증+인가) |
| 기본 개념 |
|
|
| 저장 위치 | 서버 측에 저장 (메모리/DB) | 클라이언트 측에 저장 (로컬 스토리지, 쿠키 등) |
| 상태 관리 | 서버가 상태를 유지 (Stateful) | 서버는 상태를 유지하지 않음 (Stateless) |
| 확장성 | 서버 확장 시 세션 동기화 문제 발생 가능성 O | 서버가 상태를 유지하지 않기 때문에 서버 확장 영향 X |
| 인증 방식 | 세션 ID로 사용자 식별 | 서명된 토큰의 유효성 검증으로 인증 |
| 보안 | 세션 ID 탈취 위험, 서버 측에서 세션 무효화 가능 | 서명 위조 방지, 일단 발급된 토큰은 만료 전까지 무효화 어려움 |
| Keycloak에서의 역할 | 사용자의 로그인 상태 관리, SSO 구현 | 클라이언트 애플리케이션에 사용자 정보 및 권한 제공 |
| 기타 | UserSession, ClientSession, Single Sign-On Session ... | JWT(JSON Web Token),SAML 토큰.. Access Token, Refresh Token, ID Token... |
이제 Keycloak에서 세션 및 토큰이 어떻게 사용 및 관리되는지 확인해보자.
2️⃣ 세션
세션관리
세션은 서버에 저장되는 사용자 상태 정보이다.
만약 세션이 서버에 저장되어있지 않다면, 사용자는 로그인 후 페이지 이동시마다 다시 로그인 해야할수도 있다.
세션을 어떤 관점에서 관리해야 하는지 살펴보자면 아래와 같다.
- 사용자 관점: 인증여부(로그인여부), 인증 기간(세션만료기간), 재인증 시기 등을 통해 사용자 경험에 영향 미침
- 보안 관점: 사용자 활동을 추적 및 제어 (토큰 검증/ 무효화 등)
- 성능 관점: 활성 세션을 어떻게 관리하느냐에 따라 서버에 부하를 줄 수 있음
세션 종류
공식문서에서 정확히 어떤 세션들을 사용하고있는지 찾아보려고 했지만 정리되어있는건 찾지 못했고,
이전에 [keycloak 맛보기 #7] Production Keycloak을 위한 설정 부분에서 Keycloak 다중 노드 클러스터 아키텍쳐를 공부할때, 아래 세션들이 Embedded ISPN Cache에 저장된다는 것을 언급한적이 있다.
- authenticationSessions: 인증 프로세스 중인 세션 (인증 흐름이 완료되지 않은 상태의 세션, (예: 사용자명/비밀번호 입력, MFA, 소셜 로그인 등)에서 사용되는 임시 세션)
- sessions: 사용자 세션 (인증이 완료된 사용자의 세션, SSO 기능이 이 세션을 기반으로 작동함)
- clientSessions: 클라이언트 세션 (특정 클라이언트와 연결된 세션)
Keycloak admin에서 어떻게 구현되어있는지 확인해보자.
- SSO Session Settings
- SSO Session Idle: 사용자가 활동하지 않을 때 세션이 유지되는 시간 (기본값 30분)
- SSO Session Max: 사용자 세션의 최대 유지 시간 (기본값 10시간)
- 사용자가 로그인 페이지에 Remember Me 옵션이 있는 경우 Idle 시간과 Max 시간도 별도로 설정 가능
- Client Session Settings
- Client Session Idle: 특정 클라이언트에 대한 세션이 비활성 상태로 유지되는 시간
- Client Session Max: 클라이언트 세션의 최대 유지 시간
- Offline Session Settings
- Offline Session Idle: 오프라인 토큰 사용 시 세션이 유지되는 비활성 시간 (기본값 30일)
- Offline Session Max Limited: 오프라인 세션의 최대 유지 시간 제한 (기본적으로 비활성화)
- Login Settings
- Login timeout: 로그인 프로세스가 완료되지 않을 경우 타임아웃 시간 (기본값 30분)
- Login action timeout: 로그인 액션(예: OTP 입력)의 타임아웃 시간 (기본값 5분)
[참고] Offline Session 이란?
오프라인 세션(Offline Session)은 Keycloak에서 제공하는 특별한 유형의 세션으로, 계속 유지되는 세션이라고 이해할 수 있다.
실 상황에서는 모바일 앱 동작에서 사용할 수 있는데, 처음 로그인 후 몇 주 혹은 몇 달 동안 앱에 재 로그인(재인증)하지 않고 앱을 사용할 수 있는 이유가 백그라운드에서 Offline Session을 유지하고 있기 때문이다. (사용예시, IoT장비, 키오스크 및 공용 단말기 등)
OfflineSession을 위해서는 OfflineToken이 사용되며, offline_access 스코프를 요청할 때 발급된다.
세션의 계층관계
전역 세션과 클라이언트별 별도 세션을 나누어서 관리할 수 있다.
SSO Session은 전역 설정으로 SSO Session이 만료되면 모든 Client Session도 자동으로 종료된다.
ClientSession은 종료되더라도 SSO Session과 다른 Client Session은 유지 된다.
- SSO Session (상위 레벨)
- 사용자의 전체 인증 상태를 관리하는 세션
- Keycloak 서버에서 관리되는 중앙 집중식 세션
- 여러 클라이언트에 걸쳐 공유됨
- Client Session (하위 레벨)
- 특정 클라이언트 애플리케이션에 대한 세션
- SSO Session에 종속됨
- 각 클라이언트별로 별도 생성됨
예를들어 Keycloak에 로그인한 후 애플리케이션(A, B, C)에 로그인하면
하나의 SSO Session과 각 애플리케이션에 대한 세 개의 Client Session이 생성된다.
애플리케이션 A에서 로그아웃해도 SSO Session은 유지되며, B와 C에는 여전히 로그인된 상태이다.
SSO Session이 타임아웃되거나 명시적으로 종료되면 모든 애플리케이션(A, B, C)에서 로그아웃되는 것 이다.
세션 확인 및 종료하기
테스트 사용자로 로그인(http://localhost:8082/realms/my-LDAP/account/) 후 확인해보자.
관리자 페이지에서 Session탭을 확인하면 Realm내 세션 정보를 모두 확인할 수 있다.
Actions 에서 Revocation, Sign out all active sessions를 수행할 수 있다.
- Sign out all active sessions (모든 활성 세션 로그아웃):
- 모든 활성 세션을 로그아웃 처리함
- 모든 디바이스와 브라우저에서 로그아웃되며, 사용자는 다시 로그인하면 새 세션을 시작할 수 있음
- Revocation (세션 해지/ 더 강력한 제어):
- 세션뿐만 아니라 관련된 토큰도 해지(무효화)함
- 더 강력한 조치로, 이미 발급된 토큰(리프레시 토큰 포함)을 무효화함
- 오프라인 토큰과 같은 장기 토큰도 해지할 수 있음
- 악의적인 접근이 의심될 때 유용한 보안 조치
Clients > Sessions탭에서 Client별 세션도 별도로 확인할 수 있다.
Clients Session 목록을 확인할 수 있고, Actions에서 Clients Session을 삭제할 수 있다.
Users > Session탭에서 사용자별 세션을 확인할 수 있다.
Actions를 보면 Impersonate, Delete를 수행할 수 있는데 Impersonate이 좀 특이하다.
- Impersonate (가장하기):
- 관리자가 해당 사용자로 가장하여 시스템을 체험할 수 있는 기능
- 사용자가 경험하는 화면이나 권한을 그대로 확인할 수 있어 문제 해결이나 테스트에 유용
- 관리자는 사용자의 동의 없이 해당 계정으로 활동할 수 있으므로 보안상 주의가 필요함
HTTP 쿠키와 세션
HTTP는 기본적으로 무상태(stateless) 프로토콜이기 때문에 각 요청은 독립적이며 이전 요청과의 연관성을 유지하지 않는다.
Stateless 프로토콜의 한계를 극복하여 사용자의 로그인 상태를 유지하고 세션 기반의 인증 시스템을 구현(사용자의 로그인 상태를 유지) 하기 위해 쿠키를 활용한다.
- 세션 (Session): Keycloak에서 세션은 서버 측에 저장되는 사용자의 인증 상태
- AUTH_SESSION_ID: 인증 프로세스 중인 세션을 나타내며, 로그인 진행 중일 때 사용됨
- KEYCLOAK_IDENTITY: 사용자의 신원 정보를 포함하는 세션 데이터
- KEYCLOAK_SESSION: 사용자의 로그인 상태를 유지하는 메인 세션 식별자
- 이러한 세션 정보는 Keycloak 서버의 캐시(일반적으로 Infinispan)에 저장됩니다.
- 쿠키 (Cookies): 쿠키는 클라이언트(브라우저) 측에 저장되는 정보로, 세션과 연결하는 역할을 한다.
- 브라우저는 Keycloak 서버에서 받은 쿠키를 저장합니다.
- 쿠키에는 세션 ID가 포함되어 있어서 서버가 사용자의 세션을 식별할 수 있다.
- 이미지에서 보이는 쿠키들(AUTH_SESSION_ID, KEYCLOAK_IDENTITY, KEYCLOAK_SESSION)은 서버의 해당 세션을 참조한다.
인증 과정에서는 사용자가 로그인을 시도하면 AUTH_SESSION_ID 쿠키가 생성되고, 인증이 완료되면 KEYCLOAK_SESSION과 KEYCLOAK_IDENTITY 쿠키가 설정된다.
세션 유지를 위해서 브라우저는 요청마다 쿠키를 Keycloak 서버에 보내고, 서버는 쿠키의 세션ID를 사용하여 저장된 세션 정보를 조회한다. 이때, 세션이 유효하면 요청을 처리하고, 만료되면 재인증을 요구한다.
여기서 HttpOnly 플래그를 통해 자바스크립트를 통한 접근을 방지하고,
Secure 플래그를 통해 HTTPS 연결에서만 쿠키가 전송되도록 한다.
3️⃣ 토큰
토큰 개요
토큰과 세션의 연관관계를 살펴보자면,
사용자 로그인으로 사용자인증이 완료되면 토큰발급과 동시에 세션이 생성되며, 사용자(=브라우저)에 토큰과 쿠키(=세션)값이 전달된다.
세션이 무효화되면 해당 세션으로 발급된 토큰도 검증 시 무효화될 수 있다.
일반적으로 토큰은 유효시간을 은 짧게 설정하는 것이 보안에 유리하다. AccessToken의 경우 보통 5-15분 정도로 설정한다.
그 이유는 짧은 수명은 토큰이 탈취되더라도 악용 가능한 시간을 제한하며, Refresh Token을 통해 새로운 Access Token을 얻을 수 있으므로 사용자 경험에 큰 영향 없기 때문이다.
토큰 유효시간이 너무 짧으면 서버 성능에 영향을 미칠 수 있고, 너무 길면 탈취 위험이 존재하니 일반적인 권장사항을 기준으로 설정하고,
필요한 경우에만 커스텀 하는것이 좋다.
토큰 종류
Keycloak에서의 토큰은 사용자가 로그인(인증)에 성공한 후 발급받는 인증/인가 티켓이라고 할 수 있다.
예를들어 놀이공원에 언제 입장 가능한지, 어떤 놀이기구를 탈 수 있는지 등이 적인 티켓이라고 생각하면 이해하기 쉽다.
토큰은 OAuth 2.0과 OpenID Connect(OIDC) 프로토콜에서 사용되며, 아래와 같은 특징을 가지고 있다.
| 구분 | ID Token | Access Token | Refresh Token |
| 목적 | 사용자의 신원(identity) 증명 사용자가 누구인지 증명하는 토큰 OpenID Connect 프로토콜의 핵심 요소 |
자원에 대한 접근 권한 증명 특정 리소스나 API에 접근할 수 있는 권한을 나타냄 OAuth 2.0 프로토콜의 핵심 요소 |
새로운 액세스 토큰을 얻기 위한 토큰 액세스 토큰이 만료되었을 때 새 토큰을 발급받는 용도 사용자가 다시 로그인할 필요 없이 인증 상태를 유지 |
| 포함 정보 | 사용자 ID, 이름, 이메일 등 사용자 프로필 정보, 토큰 발급자, 대상 클라이언트, 만료 시간 |
사용자 권한(roles, scopes) 토큰 발급자, 대상 서비스, 만료 시간 |
보통 사용자 식별 정보와 범위(scope) 정보 토큰 발급자, 대상 클라이언트, 만료 시간 |
| 용도 | 클라이언트 애플리케이션이 로그인한 사용자를 식별 주로 인증(Authentication) 단계에서 사용 |
보호된 API나 리소스 서버에 접근할 때 사용 주로 인가(Authorization) 단계에서 사용 API 요청 시 Authorization 헤더에 포함됨 |
액세스 토큰의 수명을 짧게 유지하면서도 사용자 경험 보장 클라이언트는 리프레시 토큰을 서버에 제출하여 새 액세스 토큰을 요청 일반적으로 액세스 토큰보다 긴 수명(hours, days)이나, Refresh Token Rotation 사용 가능 클라이언트에 안전하게 저장되어야 함 서버 측에서 취소 가능 |
토큰은 이전에 정리한 포스팅 [keycloak 맛보기 #2] OpenID Connection 사용자 인증 이해하기 에서 다루고 있으니,
이해 어려운 부분은 보고 이해하고 다시 오자!
토큰 설정 (Lifespan 등)
Keycloak Realm Settings에서 Tokens 설정 수정이 가능하다.
- General (일반 토큰 설정)
- Default Signature Algorithm: 토큰 서명에 사용되는 기본 알고리즘 (RS256 설정)
- OAuth 2.0 Device Code Lifespan: 장치 인증 코드의 유효 기간 (10분)
- OAuth 2.0 Device Polling Interval: 장치 인증 폴링 간격 (5초)
- Short verification_uri in Device Authorization flow: 장치 인증 흐름에서 짧은 확인 URI 사용
- Lifetime of the Request URI for Pushed Authorization Request: 푸시된 인가 요청의 요청 URI 수명 (1분)
- Refresh tokens
- Revoke Refresh Token: 리프레시 토큰 사용 후 해지 여부 (비활성화됨).
(활성화하면 리프레시 토큰은 한 번만 사용 가능하며, 새 액세스 토큰을 얻을 때 새 리프레시 토큰이 발급됨)
- Revoke Refresh Token: 리프레시 토큰 사용 후 해지 여부 (비활성화됨).
- Access tokens
- Access Token Lifespan: 일반 액세스 토큰의 유효 기간 (5분 권장)
- Access Token Lifespan For Implicit Flow: OAuth 2.0 암묵적 흐름에서 사용되는 액세스 토큰의 유효 기간 (15분 설정)
- Client Login Timeout: 클라이언트가 로그인을 완료해야 하는 제한 시간 (1분 설정)
- Action tokens
- User-Initiated Action Lifespan: 사용자가 시작한 작업 토큰의 유효 기간 (5분)
- Default Admin-Initiated Action Lifespan: 관리자가 시작한 작업 토큰의 기본 유효 기간 (12시간)
- Email Verification: 이메일 확인 링크의 유효 기간
- IdP account email verification: 외부 ID 제공자 계정 이메일 확인의 유효 기간
- Forgot password: 비밀번호 재설정 링크의 유효 기간
- Execute actions: 필수 작업 실행 링크의 유효 기간
혹은 Client별로 Access Token의 유효시간을 커스텀 할 수 있다.
4️⃣ 세션, 쿠키, 토큰 Keycloak SSO 환경에서의 상호작용
- 초기 접근 및 인증:
- 사용자가 A 애플리케이션에 접근하면 Keycloak으로 리다이렉트
- 사용자 인증 후 Keycloak 서버에 세션이 생성되고 토큰 발급
- 쿠키 설정 및 리다이렉트:
- Keycloak은 브라우저에 세션 쿠키를 설정하고 애플리케이션으로 리다이렉트
- 토큰(ID Token, Access Token, Refresh Token)이 애플리케이션에 전달
- 애플리케이션 접근:
- A 애플리케이션은 토큰을 검증하고 사용자에게 리소스를 제공
- 다른 앱 SSO 접근:
- 사용자가 B 애플리케이션에 접근하면 Keycloak은 쿠키를 통해 기존 세션 확인
- 재인증 없이 B 애플리케이션용 토큰이 발급되어 SSO 구현
- 토큰 갱신:
- Access Token이 만료되면 애플리케이션은 Refresh Token을 사용해 새 토큰을 요청
- 세션 종료:
- 로그아웃 시 Keycloak은 세션을 종료하고 모든 SSO 애플리케이션에 알림