i-mini

[Kafka #2] 카프카 프로듀서

mini_world — Tue, 16 Sep 2025 23:46:43 +0900

프로듀서란?

프로듀서는 어플리케이션에서 Kafka로 메세지를 발행(produce)하는 역할을 수행한다.
프로듀서는 특정 토픽에 전송하고, 카프카 브로커가 이를 파티션단위로 저장한다.
이벤트 스트리밍(사용자행동기록)/ 성능 매트릭 기록/ 로그수집/ 실시간 데이터 파이프라인에 사용된다.

https://www.confluent.io/blog/kafka-producer-internals-preparing-event-data/

프로듀서에서 생성하는 메세지는 키-밸류 형식이다.
어플리케이션 코드에서 이벤트/데이터를 메세지 객체로 생성하고, 메세지가 전송될 토픽을 지정한다.
이때, 메세지의 키는 어떤 파티션으로 전송될지 지정된다. (키가 없으면 라운드로빈)

메세지를 브로커에 전송할때는 크게 동기/비동기 방식이 있지만, 보통 비동기 전송 방식을 사용한다.

Fire and forget: 메세지 전송만하고 확인 안함
Synchronous send: 메세지 동기전송 ( send() 호출 후 Future객체 대기)
Asynchronous send : 메세지 비동기전송 ( send() 호출 후 콜백)

프로듀서는 세가지 필수 속성값을 갖는다.

bootstrap.servers: 프로듀서가 사용할 호스트 목록 지정
key.serializer: 키값으로 쓰일 객체를 직렬화 하기 위한 시리얼라이저 클래스 이름
value.serializer: 밸류값으로 쓰일 객체를 직렬화 하기 위한 시리얼라이저 클래스 이름

프로듀서 주요 파라메터

https://docs.confluent.io/platform/current/clients/producer.html

Kafka Producer for Confluent Platform | Confluent Documentation

The full list of configuration settings are available in Kafka Producer Configurations. The key configuration settings and how they affect the producer’s behavior are highlighted below. Core Configuration These settings are the same for Java, C/C++, Pyth

docs.confluent.io

프로듀서의 주요 파라메터는 위 링크에서 확인 할 수 있다.
전체가 아닌 중요한 부분만 짧게 확인해보자.

메시지 지속성	acks	이 설정을 통해 Kafka에 작성된 메시지의 내구성을 제어할 수 있다. - 기본값 all: 파티션 리더가 쓰기를 수락할 뿐만 아니라 모든 동기화된 복제본에 성공적으로 복제됨을 보장 (신뢰성 높지만 레코드 전송 느림) - 1: 1파티션 리더로부터 쓰기가 성공했다는 명시적인 확인이 필요함 - 0: 처리량을 극대화하지만 브로커가 응답을 보내지 않으므로 메시지가 브로커 로그에 성공적으로 기록되었다는 보장은 없음 (신뢰성 낮지만 레코드 전송 빠름) 다만, 컨슈머가 값을 읽을 수 있는 시간까지의 의미의 종단간 지연의 경우 세값이 모두 같다. 카프카는 일관성을 위해 모든 인-싱크 레플리카에 복제가 완료된 후에 컨슈머가 레코드를 읽을 수 있기 때문이다.
메시지 순서	retries	일반적으로 메시지는 프로듀서 클라이언트가 수신한 순서대로 브로커에 기록되지만,이 설정에 따라 순서가 변경될 수 있다. - 기본값 0, 메시지 재시도를 활성화 수
메시지 순서	max.in.flight.requests.per.connection	순서를 변경하지 않고 재시도를 활성화하려면 이 속성을 1로 설정한다. 프로듀서가 서버로부터응답을 받지 못한 상태에서 전송할 수 있는 최대 메세지의 수를 결정하는 옵션이다.

시리얼라이저

시리얼라이저란, 데이터를 한 형태에서 다른 형태로 변환하는 도구를 말한다.

브로커는 바이트 단위로 처리한다.

카프카 프로듀서가 메세지를 브로커에 보내려면 메세지의 키와 값을 바이트 배열로 변환하야 하며,
이 작업을 하는것이 시리얼라이저 이다. (객체 -> 바이트 변환)

카프카에서 기본으로 제공하는 시리얼라이저가 존재하지만, 스키마 기반의 시리얼라이저(Apache Avro, Protobuf, Thrift)를 사용하는것이 좋다.

https://medium.com/@affanhasan88/how-to-publish-and-consume-avro-encoded-apache-kafka-messages-using-java-44ed42890637

Json/String 직렬화는 쉽지만 명확한 데이터 구조(스키마)가 없기때문에 필드를 변경하려고 할때 문제가 발생한다.
이때, 스키마 기반의 시리얼라이저를 사용하면 데이터 구조가 바뀌어도 호환성을 유지할 수있다.

별도의 스키마 레지스트리가 존재하며, 메세지를 직렬화 할때 데이터와 스키마 정보를 함께 관리한다.

파티션

토픽은 여러개의 파티션으로 나뉘어 저장되며, 각 파티션은 순서가 보장된 로그 구조이다.

프로듀서에서 메세지를 보낼 때 토픽/키/값/파티션 정보를 ProducerRecord에 담는다.
(메세지 작성 과정에서 파티션 지정 가능한 구조)

# https://docs.confluent.io/platform/current/clients/confluent-kafka-python/html/index.html?_gl=1*1jdp8yp*_gcl_aw*R0NMLjE3NTgwMzE5MTkuRUFJYUlRb2JDaE1JMklmRW5MdmRqd01WNkRKN0J4M250Q24zRUFBWUFTQUFFZ0tBaFBEX0J3RQ..*_gcl_au*MjA3MjYxMjE4OC4xNzU4MDMxMTI4*_ga*ODYxODc0NTAwLjE3NTgwMzExMjg.*_ga_D2D3EGKSGD*czE3NTgwMzExMjgkbzEkZzEkdDE3NTgwMzMzNDAkajYwJGwwJGgw&_ga=2.269062833.1731004784.1758031128-861874500.1758031128#confluent_kafka.Producer.produce
produce(topic[, value][, key][, partition][, on_delivery][, timestamp][, headers])

프로듀서에서 파티션 번호를 지정한 경우에는 지정한 파티션으로 바로 전송된다. (직접 제어)
키가 있는경우에는 키를 해시하여 파티션을 정한다.
키가 없는경우 라운드로빈 또는 스티키 파티셔너 방식으로 파티션을 고른다.

운영시 주의할점

핫파티션: 특정 파티션만 과부하 (병목)
파티션 수 변경 문제: hash(key) / numPartitions 이기때문에, 파티션 개수가 달라지면 기존 키의 파티션 위치가 달라져 순서가 깨짐

헤더

카프카 메세지는 키/ 값/ 토픽/ 파티션/ 오프셋으로 구성되지만 헤더를 추가할 수 있다.
메세지의 값과는 별도로 추가적인 메타데이터를 헤더로 담을 수 있다.

헤더는 메세지 본문을 건드리지 않고 부가 정보를 전달할때 유용하게 쓰일 수 있다.
예를들어 트레이싱/로깅/라우팅정보전달/ 메세지 포멧 버전/ 우선순위/ 보안&인증 등에 쓰일 수 있다.

주의할점은 헤더는 메세지 본문과 독립적으로 구성되어 별도 처리가 가능하고,
브로커는 헤더에 관심이 없다.

인터셉터

인터셉터(Interceptor)는 프로듀서와 컨슈머 양쪽에 다 있는 개념이며,
메세지를 브로커에 보내거나 읽기 전에 가로채서 추가 동작을 할 수 있게 해주는 훅(hook) 이다.

프로듀서 인터셉터로 프로듀서가 메세지를 브로커에 전송하기 직전 또는 전송 결과를 받은 직후에 동작하는 콜백 로직을 추가할 수 있다.

일반적으로 운영 편의성과 모니터링 목적으로 쓰이며, 코드를 변경하지 않고 작동을 변경해야 하는 경우일때 유용하게 쓰일 수있다.

[Kafka #1] 카프카 개요

mini_world — Sun, 17 Aug 2025 22:16:57 +0900

개요

Kafka는 설계할 때 Commit Log 개념을 시스템 전체 아키텍처에 적용함

토픽의 파티션 = 일종의 Commit Log : 메시지가 오면 뒤에 차곡차곡 추가(Append)만 하고, 절대 지우거나 덮어쓰지 않음
오프셋(Offset) = 커서(cursor): 메시지를 읽는 소비자(Consumer)는 “내가 어디까지 읽었는지”를 오프셋으로 기억함
(데이터는 그대로 두고, 읽는 쪽 위치만 바꾸는 구조)
재처리(Replay): 소비자가 오프셋을 옛날로 되돌리면, 같은 로그를 다시 읽으면서 과거 이벤트를 재현할 수 있음
(데이터 파이프라인이나 장애 복구에 매우 유용)
내구성과 복제
Commit Log는 보통 분산 시스템에서 “진실의 원본(Source of Truth)” 역할을 함
Kafka도 여러 브로커에 파티션을 복제(Replication)해서, 장애가 나도 Commit Log처럼 메세지를 안전하게 보존함

다만, Kafka의 시작은 Commit Log 개념을 시스템 전체 아키텍처에 적용함으로서 시작했지만,
대규모 분산 환경에 맞게 확장한 형태임

파티션을 여러 개 두어 병렬성과 확장성 제공
데이터 보존 기간(retention)을 설정해서 오래된 메시지는 삭제 가능
단순한 로그 저장을 넘어서 “실시간 스트리밍 플랫폼” 역할 수행

카프카 주요 개념

메시지	Kafka에서 주고받는 데이터의 기본 단위. (e.g. 편지) 각 메시지는 키(key), 값(value), 타임스탬프로 구성되어있음
배치	네트워크 효율성을 위해 메시지를 묶어서 한 번에 처리하는 것 메세지를 배치단위로 모아서 쓰는것으로, 네트워크 오버헤드를 줄일 수 있음 단, 지연(latency)와 처리량(throughput)t사이의 트레이드 오프 있음
스키마	메시지의 구조를 정의하는 규칙 Kafka에서는 주로 Avro, Protobuf, JSON Schema 같은 포맷을 사용하며, Schema Registry를 이용해 관리함
토픽	메시지가 저장되는 카테고리나 폴더 같은 개념 (e.g. 데이터베이스의 테이블/ 파일시스템의 폴더) "주문", "결제", "사용자 로그" 같은 주제별로 분류할 수 있음
파티션	나의 토픽을 여러 개의 작은 통으로 나누는 것 큰 창고를 여러 구역으로 나누어서 물건을 분산 저장하는 것과 같고, 여러 서버에서 동시에 처리할 수 있어서 성능이 좋아짐 파티션 내에서는 메시지 순서가 보장됨
프로듀서	메시지를 생산하여 Kafka에 보내는 애플리케이션 (Publisher/Writer)
컨슈머	Kafka에서 메시지를 읽어가는 애플리케이션 (Subscriber/Reader)
컨슈머 그룹	여러 컨슈머가 하나의 팀처럼 협력해서, 토픽의 메시지를 나눠 처리하도록 하는 장치 메세지 순서는 파티션이 보장함, 각 파티션이 어떤 컨슈머가 처리할 수 있도록 매핑(ownership)해주는 역할을 컨슈머 그룹이 담당함 여러 컨슈머가 일을 분담해서 처리 속도가 빨라지며, 컨슈머를 수평 확장할 수 있기때문에 부하분산, 장애 대응이 자동으로 이루어짐 추가로, 파티션 개수 이상으로 컨슈머를 늘려도 성능 향상없음 (컨슈머 놀게됨)
브로커	Kafka 서버 하나를 의미함 브로커는 프로듀서로부터 메세지를 받아 오프셋을 할당한 뒤 디스크 저장소에 쓰고, 컨슈머의 읽기(fetch) 요청을 처리하고 발행된 메세지를 보냄
클러스터	브로커 여러 대를 묶어 놓은 집합 토픽의 파티션들이 여러 브로커에 분산 저장될 수 있도록 하며, 분산저장으로 안정성과 성능을 높임 파티션 리더 (Leader) • 메시지를 실제로 처리하는 주인 역할 • 프로듀서(Producer)가 메시지를 보낼 때 → 항상 리더 파티션에 기록 • 컨슈머(Consumer)가 메시지를 읽을 때 → 항상 리더 파티션에서 읽음 팔로워 (Follower) • 리더가 받은 메시지를 그대로 복제(Replication)해서 보관 • 평소에는 요청을 직접 처리하지 않고, 리더를 따라가기만 함 • 리더에 장애가 생기면, 팔로워 중 하나가 자동으로 승격되어 새로운 리더가 됨 → 고가용성(HA) 보장 컨트롤러(Controller) • 클러스터의 메타데이터를 관리하고 리더 선출 등을 담당 • 컨트롤러의 역할: - 어떤 브로커가 살아있는지 감시 (헬스 체크) - 리더 브로커가 죽으면 → 팔로워 중 하나를 새로운 리더로 지정 - 파티션과 리더의 할당(assignment)을 관리

Broker 주요 파라메터들

* 참고링크: https://docs.confluent.io/platform/current/installation/configuration/index.html

broker.id	클러스터 내에서 브로커를 구분하는 ID(정수)임 KRaft 모드 도입 이후에는 점차 node.id로 대체되는 중 • node.id KRaft 모드(Zookeeper 없는 Kafka 모드)에서 추가된 개념 • node.id = universal identifier (브로커 + 컨트롤러) • broker.id = 브로커 프로세스 전용 identifier (과거 호환성 때문에 남아있음)
listener	listeners → 브로커가 실제로 바인드(bind) 해서 네트워크를 수신하는 주소 (내부 바인드 인터페이스). advertised.listeners → 브로커가 클러스터 메타데이터에 알리고, 클라이언트가 접속할 때 쓰라고 알려주는 주소. # 브로커가 내부적으로 바인드할 주소 listeners=PLAINTEXT://0.0.0.0:9092 # 클러스터 메타데이터에 알릴 주소 (외부에서 접속 가능한 주소) advertised.listeners=PLAINTEXT://broker1.mycompany.com:9092
log.dir	Kafka는 토픽 파티션의 실제 데이터(로그 세그먼트)를 이 디렉터리들 안에 저장한다. 브로커는 새 파티션을 생성할 때 , 디렉토리 별 저장된 파티션 수를 비교해서 가장 적은 파티션을 가진 디렉토리에 새 파티션을 저장한다. (디스크 용량을 기준으로 하지 않고, 파티션 개수 기준으로 균등 분산) • log.dir → 단일 디렉터리 경로만 지정할 때 사용 (예전 설정 방식) • log.dirs → 여러 디렉터리를 지정할 때 사용 (콤마로 구분) 하나의 파티션은 여러 개의 로그 세그먼트 파일(.log, .index, .timeindex 등)로 쪼개져서 저장됨. 같은 파티션의 세그먼트들은 반드시 같은 디렉토리에 모여 저장됨. 파티션은 리더/팔로워 동기화 단위라서, 데이터가 한 디렉토리에 모여 있어야 함.
num.recovery. threads.per. data.dir	Kafka 브로커 재시작/종료 시 로그 복구 작업에 쓰는 스레드 개수. (디렉터리당 병렬 스레드 개수) log.dirs 에 지정한 디렉터리 1개당 몇 개의 스레드를 쓸지 결정. • 총 스레드 수 = log.dirs 개수 × num.recovery.threads.per.data.dir • 스레드가 많으면 복구 속도↑ (재기동 빠름)/ 과하면 CPU·디스크 경합↑ (오히려 느려짐). Kafka 브로커가 재시작할 때는 각 log.dirs 안의 모든 파티션 로그 세그먼트를 검증하고 인덱스를 재생성하기때문에 설정에 따라 몇시간 차이날수도있음
auto.create. topics.enable	브로커가 자동으로 토픽을 생성할 수 있는지 여부를 설정. • true (기본값): 클라이언트(Producer, Consumer, get metadata 등)가 없는 토픽에 대해 요청을 보내면 Kafka 브로커가 자동으로 새 토픽을 생성 • false: 없는 토픽에 대해 요청하면 에러 반환하고, 토픽을 만들땐 명시적으로 만들어주어야 함
auto.leader. rebalance.enable	리더 파티션 자동 재분배 여부 설정 Kafka에서 각 파티션은 여러 개의 복제본(replica)을 가지며, 그 중 하나가 리더(leader) 역할을 하며, 리더 파티션이 특정 브로커에 몰리면 트래픽 불균형이 생기기 때문에 자동으로 리더를 다른 브로커로 옮기는 설정 • 리더 파티션 → 클라이언트(Producer/Consumer)의 모든 read/write 트래픽 처리 • 팔로워(follower) 파티션 → 리더를 복제만 수행 • leader.imbalance.check.interval.seconds (기본 300초 = 5분) 마다 체크
num.partitions	Kafka에서 새 토픽을 자동 생성할 때 기본으로 몇 개의 파티션을 만들지 정하는 브로커 단위 설정임 (default:1) 토픽을 생성할 때 파티션 개수를 명시하지 않으면 이 값이 기본으로 사용됨 • 파티션 수는 Kafka의 병렬 처리 단위 • 파티션이 많을수록 Consumer Group이 더 많은 Consumer 인스턴스를 병렬로 돌릴 수 있음 → 처리량↑ • 하지만 파티션이 많을수록 메타데이터 관리, 파일 핸들, 리더 선출 → 오버헤드↑ • num.partitions는 운영 환경에서의 디폴트 안전값일 뿐, 실제 토픽은 필요에 맞게 직접 파티션 수를 정해야 함 • 이미 생성된 토픽의 파티션 수는 늘릴수만있고 줄일수없음. (데이터 재배치 문제 때문) • 파티션을 늘릴때 기존 메시지는 그대로 있고, 새 메시지만 새로운 파티션에 배치되기때문에 컨슈머 처리 순서에 영향을 준다 (메세지 리벨런싱 이런거 없음), 운영에 영향을 줄수있기때문에 신중!주의!해야한다. • 카프카는 “키 → 파티션”으로 보냄, ( partition = hash(key) % (파티션 개수) ) 같은 키의 메시지는 항상 같은 파티션으로 가므로, 그 파티션 안에서는 순서가 보장되는것. • 그런데 파티션 개수가 늘리면 예전 파티션이 아닌 다른 파티션으로 가게 됨 특정 키의 메시지가 두 파티션에 흩어져 도착하고, 컨슈머 그룹은 파티션 단위로 읽으니 키 단위 순서가 깨짐
default. replication.factor	파티션의 복제본 수를 말한다. 복제본수와 최소 동기 replica수(min.insync.replicas)를 함께 고려해야하며, replication.factor 값은 min.insync.replicas보다 항상 1이상 크게 설정해야한다. Replication Factor (RF) default.replication.factor, min.insync.replicas 는 데이터 내구성(durability)과 가용성(availability) 에 직결되는 핵심 설정임 • default.replication.factor → 토픽 생성 시 기본 복제본 개수 (내구성 수준) • min.insync.replicas → acks=all 시 “성공”으로 인정할 최소 동기 replica 수 (데이터 안전성)
log.retention.ms	메세지 보존 주기 설정 (default: 168) log.retention.ms, log.retention.minutes, log.retention.hours 옵션값이 제공되나 항상 가장 작은 단위의 설정값이 우선권을 갖기때문에 log.retention.ms을 설정하는것이 좋다. • 시간기준 보존은 디스크에 저장된 각 로그 세그먼트 파일의 마지막 수정시간(mtime)을 기준으로 작동한다.
log.retention.bytes	메세지 보존 용량 설정 (default: -1) 파티션 단위로 적용된다. (예, 8개의 파티션을 가진 토픽에 값이 1GB라면, 토픽의 최대 저장용량은 8GB임 • 만약 log.retention.ms/log.retention.bytes두개 다 설정했다면 두 조건 중 하나만 성립해도 메세지 삭제됨
log.segment.bytes	단일 로그 파일의 최대 크기 (default: 1073741824 (1 gibibyte)) 주의할점은 위에서 말한 로그 보존설정은 로그 세그먼트(파일)에 적용되는것이지 각 로그 메세지에 적용되는것이 아니다. 즉, log.segment.bytes에 지정된 크기에 다 다르지 않는다면 계속해서 로그 세그먼트를 닫지않고 사용한다. log.segment.bytes값이 너무 작으면, 파일을 너무 자주 닫고 새로 생성해야한다 (디스크 쓰기 효율성 감소) log.segment.bytes값이 너무 크면, log.retention 설정에 영향을 미친다. (예, 하루에 100M 메세지가 쓰이는 경우 1G까지 10일이 소요됨, retiontion이 1주일로 잡혀져있다면 17일분의 메세지가 저장되어있는것) 로그 세그먼트의크기는 타임스탬프 기준으로 요프셋을 찾는 기능에도 영향을 미친다. 클라이언트가 특정 타임스탬프를 기준으로 파티션의 오프셋을 요청하면 카프카는 해당 시각에쓰여진 로그 세그먼트를 찾고, 로그 세그먼트 맨 앞에 있는 오프셋이 응답으로 리턴된다. • 세그먼트가 너무 크면 → 하나의 세그먼트가 긴 시간(며칠, 몇 주) 동안 데이터를 담음. 그러면 “특정 시각”을 찾을 때 granularity(정밀도)가 떨어짐 예: 1GB 세그먼트에 10일치 메시지가 들어 있다면, “8월 5일”을 요청해도 Kafka는 세그먼트 맨 앞 오프셋(예: 8월 1일)을 반환할 수 있음. • 세그먼트가 작으면 → 파일은 자주 생기지만, 타임스탬프 기반 오프셋 조회가 더 정밀해짐.
log.roll.ms log.roll.hours	새로운 로그 세그먼트가 롤아웃되기까지의 최대 시간 (default: null) 세그먼트 용량(log.segment.bytes)에 도달하지 않아도, 지정 시간이 지나면 세그먼트를 닫고 새 세그먼트를 만듦 log.roll.ms(밀리초 단위)가 우선 적용됨 retention 정책 적용을 보장하기 위해 설정하는 것이며, 값이 너무 짧으면 세그먼트가 과도하게 쪼개져 성능 저하 발생 가능. 브로커가 해당 세그먼트를 연 시각부터 타이머가 시작되며, 대부분 브로커 시작(재기동) 시점에 여러 파티션이 동시에 새 세그먼트를 열기 때문에 동시롤링 (파일 flush + 인덱스 파일 sync + 새 파일 오픈)에 부하가 있을 수 있음 짧은 시간 안에 엄청난 I/O burst 발생 → 디스크 성능 스파이크
min.insync.replicas	쓰기가 성공적으로 완료되기 위해 최소한 몇 개의 복제본이 쓰기를 확인해야 하는지 지정하는 옵션 메시지는 모든 동기화된 복제본에 복제되고 min.insync.replicas 조건이 충족될 때까지 소비자에게 표시되지 않음 min.insync.replicas와 acks를 함께 사용하면 더 강력한 내구성 보장을 강제할 수 있음 • acks=all 과 min.insync.replicas=2 (RF=3일 때) → 메시지가 최소 2개 replica에 성공적으로 쓰여야 성공 응답 → 브로커 1대 죽어도 데이터는 안전 다만, 이 값을 늘림으로써 추가적인 오버헤드가 발생하면서 성능이 떨어질 수 있고, 데이터 일부 유실은 가능하지만 높은 처리량이 필요하다면 기본값인 1에서 변경하지 않는 구성도 가능함 *acks 는 프로듀서(producer)가 메시지를 보낸 후 “성공”으로 간주할 때 브로커 쪽에서 몇 개의 replica가 응답해야 하는지를 정하는 옵션
message.max.bytes	Kafka에서 허용되는 최대 레코드 배치 크기(압축이 활성화된 경우 압축 후 크기) (default: 1048588 (1M) 메세지 크기가 커지면 네트워크 연결과 요청을 처리하는 브로커 스레드의 요청당 작업 시간 및 I/O처리량이 증가하기 때문에 성능에 큰 영향을 미친다. message.max.bytes 값은 fetch.message.max.bytes(컨슈머), replica.fetch.max.byte(브로커) 값과 설정이 맞아야 한다.

하드웨어 선택 기준

1. 디스크

처리량

브로커 디스크의 처리량은 프로듀서 클라이언트 성능에 가장 큰 영향을 미친다. (브로커 로컬 저장소에 커밋되기때문)
즉, 디스크 쓰기속도가 빨라지면 쓰기 지연이 줄어든다.

용량

필요한 디스크 용량은 특정 시점에 얼마나 많은 메세지가 보존되어야 하는지에 따라 결정된다.
예를들어 하루 1TB의 트래픽을 받고, 1주일 보존해야 한다면, 브로커는 최소 7TB가 필요하다.
이때, 트래픽 변동 및 저장해야할 다른 파일들을 고려하여 최소 10%의 오버헤드를 고려해야한다.
또한 복제방식에 따라서도 달라진다.

2. 메모리

Kafka 힙 메모리 (JVM Heap)
- Kafka 자체는 힙 메모리를 많이 쓰지 않음
- 초당 150,000 메시지, 200MB/s 처리량을 다루는 브로커도 5GB 힙 정도면 충분
- 따라서 브로커 JVM 옵션은 보통 4~8GB 사이에서 안정적으로 설정
페이지 캐시 (OS Page Cache)
- 핵심 성능 포인트는 JVM 힙이 아니라 운영체제 페이지 캐시
- 컨슈머는 보통 “프로듀서가 막 쓴 메시지를 바로 읽는” 패턴 → OS 페이지 캐시에 남아 있는 로그 세그먼트를 바로 읽음
- 디스크에서 읽는 게 아니라 메모리 캐시에서 읽기 때문에 성능이 크게 향상됨
- 즉, Kafka 성능 = 가용한 페이지 캐시 메모리 크기에 크게 좌우됨
총 시스템 메모리 배분
- VM 힙: 4~8GB (너무 크게 잡을 필요 없음)
- 나머지 대부분: OS 페이지 캐시 용도로 확보
- 프로덕션 최소 체감선: RAM 16GB(아주 낮은 트래픽), 권장 32GB+
운영 고려사항
- Kafka 브로커와 다른 애플리케이션을 같은 서버에서 돌리지 않는 것이 권장
- 이유: OS 페이지 캐시 메모리를 서로 뺏어 쓰게 되면 Kafka가 캐시 효율을 잃음 → 컨슈머 성능 저하
- 따라서 전용 서버(전용 VM/노드) 위에 Kafka를 올려야 안정적인 처리량을 확보할 수 있음

3. 네트워크

네트워크 대역폭은 Kafka가 처리할 수 있는 트래픽 최대치를 결정하는 핵심 자원
디스크 용량과 함께 클러스터 크기 산정의 가장 중요한 요소
주요 고려사항
- 프로듀서 → 브로커 유입 트래픽보다, 다수 컨슈머가 동시에 가져가는 아웃바운드 트래픽이 훨씬 클 수 있음
- 클러스터 내부의 복제/미러링도 모두 네트워크를 소모 → 네트워크 사용량은 예측보다 커질 수 있음
- 네트워크가 포화 상태가 되면 → 복제 지연 → ISR(In-Sync Replicas) 축소 → 리더 선출 지연 → 장애 위험으로 이어짐
- 예 RF=3, min.insync.replicas=2 환경
  - 원래 ISR={Leader, F1, F2} → 정상 (ISR, Leader와 동기화된 replica 집합)
  - F1이 지연되면 ISR={Leader, F2} → ISR 축소 발생
  - 만약 Leader까지 장애 나면 → F1은 뒤처져 있어서 데이터 유실 위험
  - 더 심각하게는 ISR이 min.insync.replicas보다 작아지면 acks=all 쓰기가 실패해서, Producer가 계속 에러를 보게 됨.

4. CPU

CPU는 다른 자원보다는 성능에 영향을 덜 미친다.
하지만, 메세지 체크섬 확인, 오프셋 부여 등을 위해 메세지의 압축의 해제하며, 이때 CPU가 쓰인다.

운영체제 튜닝

가상 메모리(Virtual Memory) 튜닝

1. 페이지 캐시(Page Cache) 활용

정의: 리눅스 커널이 디스크 I/O를 빠르게 하기 위해 파일 데이터를 메모리에 캐싱하는 영역
운영 권장: Kafka 브로커 JVM 힙은 4~8GB로 작게 두고, 나머지 물리 메모리를 페이지 캐시로 최대 확보

2. Dirty Page 관리

Dirty Page: 페이지 캐시에 있지만 아직 디스크에 flush되지 않은 데이터
관련 커널 파라미터:
- vm.dirty_background_ratio
  - 백그라운드 flush를 시작하는 비율
  - 10 미만 권장
  - 단, 0으로 두면 디스크에 계속 즉시 쓰려 하기 때문에 성능 스파이크 발생 가능 → ❌
- vm.dirty_ratio
  - 시스템 메모리 대비 허용할 최대 dirty page 비율
  - 보통 60~80 권장 (너무 낮으면 flush 잦아지고, 너무 높으면 flush 몰림으로 I/O burst 발생)

3. Swap 설정

권장: Kafka 브로커 서버는 swap off
이유: 스왑 발생 시 I/O 지연이 급격히 증가하여 Kafka 지연·ISR 축소 발생

4. 파일 디스크립터(File Descriptor)

Kafka는 파티션·세그먼트·네트워크 연결 수만큼 FD를 소모
필요량 = 파티션 수 × (파티션당 세그먼트 개수) + 브로커 네트워크 연결 수
따라서 ulimit -n (open files) 값을 충분히 크게 설정해야 함 (수십만 단위 권장)

5. 기타 VM 관련 커널 파라미터

vm.max_map_count
- mmap 가능한 영역 개수 제한
- Kafka는 세그먼트를 파일 단위로 mmap 하므로 매우 큰 값 권장 (예: 1,000,000 이상)
vm.overcommit_memory
- 메모리 오버커밋 정책
- 0(기본): Heuristic 모드, 일반적으로 안전 → Kafka 운영 시 권장

############################################
# /etc/sysctl.conf 예시
############################################
# Dirty Page 관리
vm.dirty_background_ratio = 5      # 백그라운드 flush 시작 비율 (10 미만 권장)
vm.dirty_ratio = 70                # 최대 dirty page 비율 (60~80 권장)
# mmap 가능한 영역 수 (Kafka 세그먼트 파일이 많아질 때 필요)
vm.max_map_count = 1048576         # 1,000,000 이상 권장
# 메모리 오버커밋 정책
vm.overcommit_memory = 0           # 기본 heuristic 모드 (Kafka 운영에 안전)
# Swap 관련 (swapoff -a 로 꺼두는 것이 일반적)
vm.swappiness = 1                  # 혹시 swap을 켠 상태라면 최소화

############################################
# /etc/security/limits.conf 예시
############################################
# Kafka 브로커 유저 (예: kafka) 기준
kafka soft nofile 500000
kafka hard nofile 500000

디스크 튜닝

파일시스템은 XFS 사용
noatime 옵션 지정
largeio 옵션 지정

# /etc/fstab 예시
/dev/nvme1n1  /data/kafka  xfs  noatime,nodiratime,largeio,inode64  0 0

네트워크 튜닝

* 소켓 버퍼 (Socket Buffer) 설정

net.core.wmem_default = 131072     # 송신 버퍼 기본값 (128KB)
net.core.rmem_default = 131072     # 수신 버퍼 기본값 (128KB)
net.core.wmem_max = 2097152        # 송신 버퍼 최대값 (2MB)
net.core.rmem_max = 2097152        # 수신 버퍼 최대값 (2MB)

* TCP 소켓 설정

# 송수신 버퍼 자동 조정 범위
net.ipv4.tcp_wmem = 4096 65536 2097152   # [최소, 기본, 최대]
net.ipv4.tcp_rmem = 4096 87380 2097152   # [최소, 기본, 최대]

# TCP 윈도우 스케일 (65KB 이상의 윈도우 크기를 지원 (고대역폭 환경 필수))
net.ipv4.tcp_window_scaling = 1

# TCP SYN 백로그
# 동시에 처리 가능한 미완성 연결(half-open) 큐 크기
# Kafka 브로커에 다수 클라이언트 연결 시 1024 이상 권장
net.ipv4.tcp_max_syn_backlog = 4096

# NIC 수신 대기열 (Network Device Backlog)
# NIC 드라이버가 커널 네트워크 스택으로 패킷을 전달하기 전의 큐 크기
# Kafka는 burst 트래픽이 많으므로 기본값(1000)을 10배 이상 늘려주면 안전
net.core.netdev_max_backlog = 10000

macOS에서Docker Colima 사용

mini_world — Mon, 16 Jun 2025 00:27:42 +0900

Docker Desktop, orbstack은 기업환경에서 사용할 수 없어서 완전무료인 Colima를 사용하여 Docker 개발환경을 구성한다.

macOS에서는 Docker Engine이 macOS에서 직접 동작하지 않음
• Docker의 핵심인 Docker Engine (dockerd)는 리눅스 커널 기능에 의존함 (예: cgroups, namespaces 등)
• macOS는 리눅스 커널이 아니기 때문에 Docker Engine을 직접 실행할 수 없음
• 그래서 Linux 가상 머신(VM) 위에서 Docker Engine을 실행해야 함. 이때 Colima 사용.

패키지설명

docker	Docker CLI 도구 (도커 명령어 사용)
colima	Docker Engine을 실행할 macOS용 경량 VM

설치

brew install docker
brew install docker-compose
brew install docker-buildx
brew install colima

실행

# 실행
colima start

# Docker가 Colima를 바라보는지 확인
docker context ls

NAME       DESCRIPTION                               DOCKER ENDPOINT                                       ERROR
colima *   colima                                    unix:///Users/{dir}/.colima/default/docker.sock
default    Current DOCKER_HOST based configuration   unix:///var/run/docker.sock

# 작동 테스트
docker run hello-world

동작확인

# Colima 상태 확인
colima status

INFO[0000] colima is running using macOS Virtualization.Framework
INFO[0000] arch: aarch64
INFO[0000] runtime: docker
INFO[0000] mountType: sshfs
INFO[0000] socket: unix:///Users/{dir}/.colima/default/docker.sock

# Colima 목록 확인
colima list

PROFILE    STATUS     ARCH       CPUS    MEMORY    DISK      RUNTIME    ADDRESS
default    Running    aarch64    2       2GiB      100GiB    docker

# Colima 리소스 변경
colima stop
colima start --cpu 4 --memory 8 --disk 60

# Colima VM 접속
colima ssh

[keycloak 실습 #2] GoogleWorkSpace + Keycloak+ AWS IdentityCenter(SSO) 연동까지

mini_world — Sun, 20 Apr 2025 20:08:56 +0900

개요

⚠️ 주의: 이번 실습은 비용이 들어갑니다. (AWS/GoogleWorkSpace/Domain..)

Google Workspace를 그룹웨어로 사용하는 환경에서는 Google 계정을 중심으로 다양한 서비스에 접근할 수 있도록 구성할 수 있다.
이때, Google Workspace를 직접 사용하는 것도 가능하지만, 중앙 인증 및 인가 솔루션인 Keycloak을 중간에 두고 구성하면 다음과 같은 장점이 있다.

통합 사용자 및 그룹 관리
• Google Workspace의 사용자 정보를 Role 또는 Group 단위로 다양한 서비스에 대한 접근 제어를 통합 관리할 수 있음
중앙 권한 제어 및 유연한 확장성
• “dev팀”, “infra팀”과 같이 그룹을 구성하고, 그룹별로 접근 가능한 AWS 계정이나 ArgoCD 프로젝트를 분리하여 제어 할 수 있음
• 추후 SAML 또는 OIDC 기반의 외부 서비스가 추가되더라도, Keycloak을 중심으로 쉽게 통합할 수 있음
유연한 Attribute 및 Claim 매핑
• Google Workspace에서 전달되는 claim 값을 Keycloak에서 필터링하거나 변환하여 전달할 수 있음
(예: 이메일 → preferred_username)
• AWS Identity Center 등에서 Role Mapping 시 필요한 claim 값 (groups, roles 등)도 유연하게 조정 가능함
일관된 사용자 경험 제공
• 사용자는 Google Workspace 계정으로 로그인만 하면 되고, Keycloak이 중계자 역할을 하여 다양한 서비스까지 자연스럽게 SSO가 연계됨

즉, 정리하면 Google WorkSpace에 비로 연동되지 않는 경우에도 Keycloak에 연동(SAML/OIDC/Federate)할 수 있고, Group, Role-mapping, Attribute/Claim-mapping으로 일관된 정책으로 솔루션을 관리할 수 있다.

GoogleWorkSpace <-> Keycloak 연동

1. Keycloak 구성

이번 실습에서는 공인 도메인을 가지고 있는 Keycloak이 필요하다.
Keycloak 구성에 대한 내용은 이전 실습에서도 많이 다루고 있으니 패스 하도록 한다.
실습을 위한 Realm을 새로 생성한다.

2. Google WorkSpace 생성 및 구성

Google WorkSpace는 14일동안 비용없이 사용해볼 수 있다.
이 링크에서 Business Starter (사용자당 $7.56) 로 테스트 해보자.

계정을 생성했다면 Google Cloud 에서 새로운 프로젝트를 생성해야 한다.

새로운 프로젝트를 생성했다면 Google 인증 플랫폼(https://console.cloud.google.com/auth/overview)을 구성 해야한다.

이제 OAuth Client를 생성한다.

승인된 리디렉션 URL에 https://${Keycloak도메인}/realms/${Realm이름}/broker/google/endpoint 을 작성한다.

구성이 완료 후 Client ID & Secret 을 복사한다.

3. Keycloak + Google Identity Provider 연동

이제 Keycloak으로 이동해서 IdentityProvider에 Google을 등록한다.

2 단계에서 생성한 Client의 ID/Secret을 입력한다.

4. Keycloak 에 Google User로 로그인 해보기

이제 연동이 되었으니, Google 사용자로 로그인 해보자.

https://${${Keycloak도메인}}/realms/${Realm이름}/account

사용자 로그인이 성공했다면 Keycloak Realm으로 가서 사용자 목록을 확인해보자.

방금 로그인 한 사용자가 생성되어있다. (사용자는 첫 로그인 후 생성된다.)

Keycloak <-> AWS IdentityCenter(AWS SSO) SAML 연동

위 단계에서 Google WorkSpace와 Keycloak을 연동했고,
Keycloak에 google Workspace 계정으로 로그인까지 진행했다.

이번 단계에서는 AWS IdentitiyCenter와 Keycloak연동을 통해
결과적으로는 Google WorkSpace계정으로 AWS 까지 사용할 수 있도록 해보자.

1. AWS 계정 구성 (ControlTower+IdentityCenter)

⚠️ 주의
로그인 후 https://us-east-1.console.aws.amazon.com/iam/ 에서 루트사용자 MFA를 등록하기를 강력 권장함

테스트를 위한 AWS계정을 생성한다.
이때, Organization, ControlTower, IdentityCenter를 모두 활성화한 구성으로 테스트를 진행한다. (AWS 계정생성 링크)

이제 control tower 서비스에서 랜딩존을 활성화 한다.
(랜딩존은 편한방식으로 생성하면 된다. 이 실습에서는 IdentityCenter의 기능만 사용한다.)

Control Tower가 활성화 되었다면, IdentityCenter 서비스로 이동하고,
설정 > 작업증명 소스 탭에서 자격증명 소스 변경을 클릭한다.

이때, 외부자격증명 공급자를 선택한다.

메타데이터 파일을 다운로드 한다.

2. KeyCloak AWS Client 생성

이제 다시 KeyCloak으로 가서 AWS Client를 생성하자.

import하면 기본적인 부분은 자동으로 설정되며, Name작성 및 Always display in UI 부분만 On으로 변경하고 Save한다.

추가로 Home URL에 /realms/${Realm이름}/protocol/saml/clients/${Client이름} 만 추가한다.

3. KeyCloak SAML파일 다운로드 및 AWS IdentityCenter 설정 완료하기

이제 Realms Settings로 가서 SAML 2.0 Identity Provider Metadata를 다운받는다.

다시 1번에서 설정중이었던 AWS콘솔로 들어가서 방금 다운받은 SAML 2.0 Identity Provider Metadata 파일을 업로드 한다.

이제 자격증명 소스가 외부Idp(Keycloak)으로 설정되었다.
사용자 및 그룹 설정을 Keycloak과 연동하기 위해서는 SCIM설정이 필요하다.
따라서 아래 자동프로비저닝 부분에서 활성화를 클릭한다.

자동프로비저닝을 활성화 하면 아래처럼 SCIM 엔드포인트와 토큰이 나오는데,
혹시모르니 따로 저장해둔다.

이제 AWS IdentityCenter 로그인 페이지에 접속해보면, google 로그인이 보일것이다.

그런데 문제는 Google계정으로 로그인 후 IdentityCenter에 접근하지 못한다.

이 이유는 AWS IdentityCenter에 사용자가 생성되지않았기 때문인데, 아래 [알고갈것]SCIM이 뭔지? 에서 내용을 다룬다.

일단 이 동기화 문제를 해결하기 위해 아래 SCIM 설정을 진행해보자.

Keycloak <-> AWS IdentityCenter(AWS SSO) SCIM 설정

이렇게 Keycloak과 AWS IdentityCenter사이에 SAML설정 후에도 사용자/그룹이 동기화 되지 않는 이슈가 있다.
일단 이번에는 스크립트를 통해 일단 원리를 이해하고,
나중에는 cron등 등록해서 자동으로 프로비저닝 하게 해주어야 한다.

1. 임시로 사용할 AWS AccessKey 생성 및 IdentityCenter ID 확인

스크립트만 사용하고 제거할 IAM 사용자를 만든다. (링크)

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowIdentityStore",
            "Effect": "Allow",
            "Action": [
                "identitystore:*"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

권한 설정 후 AccessKey를 생성하고 AccessKey,SecretKey를 복사해둔다.

IdentityCenterID도 스크립트에서 쓰이니 복사해두자.

2. Keycloak admin-cli 설정

SCIM 스크립트는 Keycloak API 접근용 클라이언트가 필요하다.
AWS Identity Center 연결을 위한 SAML 클라이언트와는 별도로 관리 API 접근용 클라이언트(일반적으로 admin-cli)를 사용한다.

Client목록에서 admin-cli를 클릭하고, 아래와 같이 설정을 수정한다.

이후 해당 Client에서 유저와 그룹을 쿼리할 수 있도록 권한을 추가한다.

마지막으로 이 클라이언트의 Credentials을 복사한다. 스크립트에 사용할 예정이다.

3. SCIM 스크립트 실행

스크립트가 너무 길어서 아래 접근글로 넣어놨다.
로컬에서 python scim.py 실행하면 된다.

수정할 부분은 변수 부분이다.

# Keycloak Settings
KEYCLOAK_URL = "your-keycloak-url"
KEYCLOAK_REALM = "your-realm"
KEYCLOAK_CLIENT_ID = "admin-cli"
KEYCLOAK_CLIENT_SECRET_KEY = "your-secret-key"

# AWS Settings
AWS_IDENTITY_STORE_ID = "your-identity-store-id"
AWS_ACCESS_KEY = "your-access-key"
AWS_SECRET_KEY = "your-secret-key"
AWS_REGION = "your-region"

아래 열어서 스크립트 확인

SCIM 스크립트

from keycloak import KeycloakAdmin, KeycloakOpenIDConnection
import boto3
import logging
import traceback
from datetime import datetime

# Keycloak Settings
KEYCLOAK_URL = "your-keycloak-url"
KEYCLOAK_REALM = "your-realm"
KEYCLOAK_CLIENT_ID = "admin-cli"
KEYCLOAK_CLIENT_SECRET_KEY = "your-secret-key"

# AWS Settings
AWS_IDENTITY_STORE_ID = "your-identity-store-id"
AWS_ACCESS_KEY = "your-access-key"
AWS_SECRET_KEY = "your-secret-key"
AWS_REGION = "your-region"

class Keycloak:
    def __init__(self):
        connection = KeycloakOpenIDConnection(
            server_url=KEYCLOAK_URL,
            realm_name=KEYCLOAK_REALM,
            client_id=KEYCLOAK_CLIENT_ID,
            client_secret_key=KEYCLOAK_CLIENT_SECRET_KEY,
            verify=True
        )
        self.admin_client = KeycloakAdmin(
            server_url=KEYCLOAK_URL,
            realm_name=KEYCLOAK_REALM,
            client_id=KEYCLOAK_CLIENT_ID,
            client_secret_key=KEYCLOAK_CLIENT_SECRET_KEY,
            connection=connection
        )
        self.logger = logging.getLogger(__name__)

    def list_users(self):
        try:
            return self.admin_client.get_users({})
        except Exception as e:
            self.logger.error(f"Keycloak list_users error: {e}")
            return []

    def list_groups(self):
        try:
            return self.admin_client.get_groups({})
        except Exception as e:
            self.logger.error(f"Keycloak list_groups error: {e}")
            return []

    def get_group_members(self, group_id):
        try:
            return self.admin_client.get_group_members(group_id)
        except Exception as e:
            self.logger.error(f"Keycloak get_group_members error: {e}")
            return []

class KeycloakAWSSync:
    def __init__(self, dry_run=False):
        self.setup_logging()
        self.logger.info("Initializing sync components")

        self.dry_run = dry_run
        self.keycloak = Keycloak()
        self.aws_client = boto3.client(
            'identitystore',
            aws_access_key_id=AWS_ACCESS_KEY,
            aws_secret_access_key=AWS_SECRET_KEY,
            region_name=AWS_REGION
        )
        self.identity_store_id = AWS_IDENTITY_STORE_ID

    def setup_logging(self):
        logging.basicConfig(
            level=logging.INFO,
            format='%(asctime)s - %(levelname)s - %(message)s',
            handlers=[logging.StreamHandler(), logging.FileHandler("sync.log")]
        )
        self.logger = logging.getLogger(__name__)

    def sync_users(self):
        users = self.keycloak.list_users()
        existing_users = self.aws_client.list_users(IdentityStoreId=self.identity_store_id)["Users"]

        aws_usernames = {u["UserName"]: u for u in existing_users if u.get("UserType") == "keycloak"}
        keycloak_usernames = {u["username"]: u for u in users}

        for username, user in keycloak_usernames.items():
            first = user.get("firstName", "")
            last = user.get("lastName", "")
            display = f"{first} {last}"
            if username in aws_usernames:
                self.logger.info(f"Updating user: {username}")
                if not self.dry_run:
                    self.aws_client.update_user(
                        IdentityStoreId=self.identity_store_id,
                        UserId=aws_usernames[username]["UserId"],
                        Operations=[
                            {"AttributePath": "userName", "AttributeValue": username},
                            {"AttributePath": "name.givenName", "AttributeValue": first},
                            {"AttributePath": "name.familyName", "AttributeValue": last},
                            {"AttributePath": "displayName", "AttributeValue": display}
                        ]
                    )
                else:
                    self.logger.info(f"[DRY-RUN] Would update user: {username}")
            else:
                self.logger.info(f"Creating user: {username}")
                if not self.dry_run:
                    self.aws_client.create_user(
                        IdentityStoreId=self.identity_store_id,
                        UserName=username,
                        Name={"GivenName": first, "FamilyName": last},
                        DisplayName=display,
                        UserType="keycloak"
                    )
                else:
                    self.logger.info(f"[DRY-RUN] Would create user: {username}")

        for username, user in aws_usernames.items():
            if username not in keycloak_usernames:
                self.logger.info(f"Deleting user: {username}")
                if not self.dry_run:
                    self.aws_client.delete_user(
                        IdentityStoreId=self.identity_store_id,
                        UserId=user["UserId"]
                    )
                else:
                    self.logger.info(f"[DRY-RUN] Would delete user: {username}")

    def sync_groups(self):
        groups = self.keycloak.list_groups()
        existing_groups = self.aws_client.list_groups(IdentityStoreId=self.identity_store_id)["Groups"]

        aws_groups = {g["DisplayName"].strip().lower(): g for g in existing_groups if g["DisplayName"].startswith("keycloak-")}
        keycloak_groupnames = {f"keycloak-{g['name']}": g for g in groups}
        keycloak_keys = set(k.strip().lower() for k in keycloak_groupnames.keys())

        for display, group in keycloak_groupnames.items():
            norm_display = display.strip().lower()
            if norm_display in aws_groups:
                self.logger.info(f"Updating group: {display}")
                if not self.dry_run:
                    self.aws_client.update_group(
                        IdentityStoreId=self.identity_store_id,
                        GroupId=aws_groups[norm_display]["GroupId"],
                        Operations=[
                            {"AttributePath": "displayName", "AttributeValue": display},
                            {"AttributePath": "description", "AttributeValue": f"Updated at {datetime.now().isoformat()}"}
                        ]
                    )
                else:
                    self.logger.info(f"[DRY-RUN] Would update group: {display}")
            else:
                self.logger.info(f"Creating group: {display}")
                if not self.dry_run:
                    self.aws_client.create_group(
                        IdentityStoreId=self.identity_store_id,
                        DisplayName=display,
                        Description=f"Keycloak synced group. Created at {datetime.now().isoformat()}"
                    )
                else:
                    self.logger.info(f"[DRY-RUN] Would create group: {display}")

        for display, group in aws_groups.items():
            if display not in keycloak_keys:
                self.logger.info(f"Deleting group not found in Keycloak: {display}")
                if not self.dry_run:
                    self.aws_client.delete_group(
                        IdentityStoreId=self.identity_store_id,
                        GroupId=group["GroupId"]
                    )
                else:
                    self.logger.info(f"[DRY-RUN] Would delete group: {display}")

    def sync_group_memberships(self):
        groups = self.keycloak.list_groups()
        for group in groups:
            group_name = group["name"]
            group_id = group["id"]
            prefixed_name = f"keycloak-{group_name}"
            try:
                group_resp = self.aws_client.get_group_id(
                    IdentityStoreId=self.identity_store_id,
                    AlternateIdentifier={
                        'UniqueAttribute': {
                            'AttributePath': 'displayName',
                            'AttributeValue': prefixed_name
                        }
                    }
                )
                aws_group_id = group_resp["GroupId"]
            except Exception:
                self.logger.warning(f"Group {prefixed_name} not found in AWS")
                continue

            # Keycloak members
            kc_members = self.keycloak.get_group_members(group_id)
            kc_usernames = {m["username"] for m in kc_members}

            # AWS members
            aws_members = self.aws_client.list_group_memberships(
                IdentityStoreId=self.identity_store_id,
                GroupId=aws_group_id
            ).get("GroupMemberships", [])

            aws_user_map = {}
            for mem in aws_members:
                mem_id = mem["MemberId"].get("UserId")
                if mem_id:
                    user_detail = self.aws_client.describe_user(
                        IdentityStoreId=self.identity_store_id,
                        UserId=mem_id
                    )
                    aws_user_map[user_detail["UserName"]] = mem["MembershipId"]

            # Add missing users
            for username in kc_usernames:
                if username not in aws_user_map:
                    self.logger.info(f"Adding user {username} to group {prefixed_name}")
                    if not self.dry_run:
                        try:
                            user_resp = self.aws_client.get_user_id(
                                IdentityStoreId=self.identity_store_id,
                                AlternateIdentifier={
                                    'UniqueAttribute': {
                                        'AttributePath': 'userName',
                                        'AttributeValue': username
                                    }
                                }
                            )
                            aws_user_id = user_resp["UserId"]
                            self.aws_client.create_group_membership(
                                IdentityStoreId=self.identity_store_id,
                                GroupId=aws_group_id,
                                MemberId={'UserId': aws_user_id}
                            )
                        except Exception as e:
                            self.logger.warning(f"Failed to add {username} to group {prefixed_name}: {e}")
                    else:
                        self.logger.info(f"[DRY-RUN] Would add user {username} to group {prefixed_name}")

            # Remove stale users
            for username, membership_id in aws_user_map.items():
                if username not in kc_usernames:
                    self.logger.info(f"Removing user {username} from group {prefixed_name}")
                    if not self.dry_run:
                        self.aws_client.delete_group_membership(
                            IdentityStoreId=self.identity_store_id,
                            MembershipId=membership_id
                        )
                    else:
                        self.logger.info(f"[DRY-RUN] Would remove user {username} from group {prefixed_name}")

    def run_sync(self):
        self.sync_users()
        self.sync_groups()
        self.sync_group_memberships()

if __name__ == "__main__":
    syncer = KeycloakAWSSync(dry_run=False)  # Set to False for actual sync
    syncer.run_sync()

이제 Keyclock에서 사용자나 그룹을 생성하고 스크립트를 돌리면 아래처럼 싱크가 맞춰진다.

Keycloak콘솔과 AWS IdentityCenter 콘솔에서 sync가 잘 되었는지 확인한다.

4. Google Workspace 계정으로 AWS IdentityCenter로그인

이제 다시 Google Workspace계정으로 AWS IdentityCenter에 로그인 해보자.
그 전에 사용자에 매핑된 계정/권한이 잘 반영되는지 확인하기 위해 설정을 추가한다.

먼저 아무 계정이나 선택하고, 그룹과 권한세트를 할당하자.

이후 Keycloak 콘솔에서 해당 그룹에 google workspace 사용자를 추가한다.
추가한 후 SCIM 싱크 실행해줘야한다.

이제 다시한번 로그인해보자.

이제 오류없이 제대로 접근이 된것을 확인할 수 있다.

[알고갈것] SCIM이 뭔지?

SAML
- SAML(Security Assertion Markup Language)은 인증(Authentication) 정보를 교환하는 프로토콜임
- 목적: 사용자가 한 번 로그인하면 여러 서비스에 접근할 수 있게 하는 SSO(Single Sign-On) 구현
- 작동 방식:
  - Keycloak(IdP)이 사용자를 인증하고 SAML 어설션(assertion)을 AWS Identity Center(SP)에 전달
  - AWS는 이 어설션을 신뢰하고 사용자에게 접근 권한 부여
- 한계: 사용자 계정의 프로비저닝(생성/수정/삭제)은 처리하지 않음
SCIM
- SCIM(System for Cross-domain Identity Management)은 사용자 프로비저닝(User Provisioning) 을 자동화하는 프로토콜이다.
- 목적: IdP와 SP 간 사용자 정보 자동 동기화
- 작동 방식:
  - Keycloak의 사용자/그룹 정보를 AWS Identity Center로 자동 동기화
  - 사용자 생성, 수정, 삭제, 그룹 멤버십 변경 등을 자동으로 반영
- 이점:
  - 수동으로 사용자를 관리할 필요 없음
  - 사용자 정보 불일치 방지
  - 사용자 온보딩/오프보딩 자동화

즉, SCIM 스크립트는 Keycloak과 AWS Identity Center 사이에서 아래 작업을 수행한다.

Keycloak에서 사용자/그룹 정보 추출
AWS Identity Center의 SCIM 엔드포인트로 이 정보 전송
양쪽 시스템의 사용자/그룹 상태를 지속적으로 동기화

일반적으로 SCIM 스크립트는 아래처럼 구성된다.

주기적으로 실행되도록 스케줄링(예: cron 작업)
AWS Lambda 함수로 구현
컨테이너화된 애플리케이션으로 실행
CI/CD 파이프라인의 일부로 실행 등

요약

SAML: 로그인(인증) 정보를 교환하여 SSO 구현
SCIM: 사용자 계정 정보를 자동으로 동기화하여 계정 관리 자동화

이 두 프로토콜을 함께 사용하면 사용자는 Google Workspace로 로그인하고, 이 인증 정보가 Keycloak을 통해 AWS Identity Center로 전달되며(SAML), 동시에 사용자 계정 정보도 자동으로 동기화(SCIM)되어 완전한 IAM 솔루션을 구현할 수 있다.

참고링크

* 참고 블로그: https://blog.beachgeek.co.uk/keycloak-on-aws-part-two/

[keycloak 실습 #1] LDAP + Keycloak+ Grafana 연동까지

mini_world — Sun, 20 Apr 2025 15:04:45 +0900

개요

LDAP이란?

* 참고자료: https://www.okta.com/identity-101/what-is-ldap/

LDAP(Lightweight Directory Access Protocol)이란, 디렉터리 서비스를 위한 프로토콜이다.
일반적으로 회사에서 부서 및 사용자를 관리하기 위해 사용하며, 사용자/그룹/권한 등의 정보를 저장 및 조회 할 수 있다.

dc=example,dc=org (회사)
    ├── ou=Development (개발부서)
    │   ├── cn=developer1
    │   └── cn=developer2
    ├── ou=Sales (영업부서)
    │   ├── cn=sales1
    │   └── cn=sales2
    └── ou=HR (인사부서)
        ├── cn=hr1
        └── cn=hr2

dc, ou, cn 등 각 객체들에 대해 간단히 설명하자면 아래와 같다.

dc (Domain Component): 도메인 구성요소
ou (Organizational Unit): 조직 단위/부서
cn (Common Name): 일반적인 이름
uid (User ID): 사용자 식별자
gid (Group ID): 그룹 식별자

설치 후 사용자를 생성할때 각 객체를 만나게 될 예정이니 약간은 익숙해지도록 하자!

LDAP과 Keycloak의 Federate (연동)

LDAP은 그룹 및 사용자 정보를 저장하고 관리하는 시스템이다.
LDAP의 사용자/그룹을 ketcloak하고 연동(federate)해서 여러 어플리케이션에 SSO(single-sing-on)할 수 있도록 구성할 수 있다.

LDAP: 사용자 및 그룹의 중앙 저장소 역할
Keycloak: 인증/인가 처리 및 SSO 제공 역할

바로 테스트 해보자

테스트 환경 구성

1. minikube 실행

helm으로 쉽게 설치할 수 있기때문에, 로컬에 minikube를 설치한다.
minikube는 각 환경마다 설치 매뉴얼을 아주 자세히 쉽고 간단하게 설명해 놓았으니 링크를 따라서 설치하면 된다.

minikube start

kubectl 명령어가 없다면 여기 링크를 따라서 설치한다.

2. Keycloak 실행

가장 많이 사용하는 bitnami keycloak helm chart를 이용한다.
아래 명령어로 설치한다.

helm install keycloak oci://registry-1.docker.io/bitnamicharts/keycloak \
  --set auth.adminUser=admin \
  --set auth.adminPassword=admin \
  --set postgresql.auth.username=bn_keycloak \
  --set postgresql.auth.password=password \
  --set postgresql.auth.database=keycloak \
  --set postgresql.auth.postgresPassword=password

설치가 완료 되었다면 포트 포워딩을 통해 로컬 브라우저에서 접근 가능하도록 설정한다.

# Keycloak 서비스로 포트포워딩
kubectl port-forward svc/keycloak 8082:80 &

브라우저로 localhost:8082 접속해서 로그인 한다.

3. OpenLDAP 실행

* 참고링크: https://artifacthub.io/packages/helm/helm-openldap/openldap

LDAP을 제공하는 여러 솔루션이 있는데, 그 중 대표적인게 Windows Active Directory이고,
오픈소스로는 OpenLDAP이 있다. 아래 명렁어 대로 간단하게 OpenLDAP을 설치해보자.

git clone https://github.com/jp-gouin/helm-openldap.git
cd helm-openldap
helm install openldap .

설치가 완료 되었다면 포트 포워딩을 통해 로컬 브라우저에서 접근 가능하도록 설정한다.
openLDAP webadmin에 접속하려면 비밀번호를 알아야 하기떄문에 비밀번호 확인 명령어로 비밀번호를 확인한다.

# openldap admin으로 포트 포워딩
kubectl port-forward svc/openldap-phpldapadmin 8083:80 &

# 비밀번호 확인 명령어
kubectl get secret --namespace default openldap -o jsonpath="{.data.LDAP_ADMIN_PASSWORD}" | base64 --decode; echo
kubectl get secret --namespace default openldap -o jsonpath="{.data.LDAP_CONFIG_ADMIN_PASSWORD}" | base64 --decode; echo

브라우저로 localhost:8083 접속해서 로그인 한다.

LDAP 간단하게 설정하기

위 개요에서 언급한것과 같이 LDAP은 조직 (사용자/그룹) 중앙 저장소 역할이다.
OpenLDAP에 접속하여 기본적인 객체들을 생성해보자.

1. Group 생성

그룹(Groups)은 사용자를 묶는 사용자를 묶는 단위이며, 권한과 정책을 관리하는데 사용한다.
admin, read-only처럼 권한을 분리하고 정책을 적용하는 단위가 된다.

ou=groups에 공통으로 사용할 그룹을 3개 생성한다.

administrator
editor
readonlyuser

2. OU 생성 (Sales/Marketing 조직)

ou는 트리 형태로 만들 수 있다. 일반적으로는 조직의 부서/팀 형태로 많이 구성한다.

# OU구성 예시
dc=example,dc=org
├── ou=headquarters
│   ├── ou=development
│   │   ├── ou=web-team
│   │   └── ou=mobile-team
│   ├── ou=marketing
│   │   ├── ou=digital
│   │   └── ou=branding
│   └── ou=sales
│   │   ├── ou=domestic
│   │   └── ou=international
├── ou=branch-busan-office
│   └── ou=sales
│   │   ├── ou=retail
│   │   └── ou=wholesale
└── ou=groups
    ├── ou=admin-groups
    └── ou=user-groups

우리는 테스트이므로 간단하게 2개의 ou를 생성한다.

sales
marketing

3. User 생성

이제 조직에 속할 사용자를 만들어보자. sales, marketing ou에 사용자를 만들고, 위에서 생성한 Group에 한명씩 매핑한다.

각 OU에 3명씩 총 6명의 사용자가 생성 완료 되었다면, 다음단계로 넘어가보자!

Keycloak LDAP Federate

Realm 단위로 LDAP 연동이 가능하다.
먼저, my-LDAP이라는 Realm을 생성하자.

1. LDAP Realm 생성

2. Keycloak LDAP 연동

생성한 my-LDAP realm에서 LDAP연동을 진행한다.
왼쪽 하단 [User Federation] -> [Add Ldap providers]를 클릭한다.

이제 각 항목을 살펴보면서 설정해보자. 설정해야할 부분은 빨간 네모로 표시해두었고,
설명은 각 캡쳐 하위에 달아놓았다.

Vendor: Other (openldap 이므로 other 선택)
Connection URL: ldap://openldap.default:389 (LDAP 서버 주소)
Bind DN(Distinguished Name): cn=admin,dc=example,dc=org (관리자 계정)
Bind Credential: (관리자 비밀번호)

여기서 말하는 DN은 아래와 같은 형태로 사용된다.

cn=lee.leader,ou=marketing,ou=headquarters,dc=example,dc=org
└─────────┴──────────────┴───────────────┴─────────┴────────
     │           │              │             │         │
     │           │              │             │         └─ 최상위 도메인
     │           │              │             └─ 도메인
     │           │              └─ 본사
     │           └─ 마케팅 부서
     └─ 사용자 이름

Edit mode (WRITABLE): LDAP 서버에 대한 접근 모드 설정 (WRITABLE/READ_ONLY/UNSYNCED)
Users DN: 사용자들이 저장된 기본 DN 위치
Username LDAP attribute: 사용자 이름으로 사용될 LDAP 속성 (cn (Common Name)이 일반적으로 사용됨)
RDN LDAP attribute: 엔트리의 고유 식별자로 사용할 속성
UUID LDAP attribute: 사용자의 고유 식별자로 사용되는 속성 (objectGUID는 전역적으로 고유한 식별자)
User object classes: LDAP 사용자 객체의 클래스 정의 (person, organizationalPerson, user는 표준 사용자 객체 클래스
User LDAP filter: 사용자 검색 시 적용할 필터 (특정 조건으로 사용자를 필터링할 때 사용)
Search scope (Subtree): LDAP 검색 범위 설정 (Subtree: 하위 모든 레벨 검색/OneLevel: 직계 하위 레벨만 검색)
Read timeout: LDAP 검색 작업의 제한 시간 설정
Pagination: 대량의 검색 결과를 페이지 단위로 가져올지 설정 (메모리 사용 효율화를 위해 ON 권장)
Referral: LDAP 리퍼럴(다른 LDAP 서버로의 참조) 처리 방식 설정

Synchronization settings (동기화 설정)
- Import users: LDAP의 사용자를 Keycloak으로 가져올지 여부를 설정 (ON/OFF)
- Sync Registrations: Keycloak에서 생성된 사용자를 LDAP에 동기화할지 여부를 설정 (ON/OFF)
- Batch size: 한 번에 동기화할 사용자의 수를 지정 (성능과 메모리 사용량 조절)
- Periodic full sync: 전체 사용자 데이터를 주기적으로 동기화할지 설정 (ON/OFF)
- Periodic changed users sync: 변경된 사용자만 주기적으로 동기화할지 설정 (ON/OFF)
Kerberos integration (Kerberos 통합)
- Allow Kerberos authentication: Kerberos 인증 허용 여부 설정 (ON/OFF)
- Use Kerberos for password authentication: 비밀번호 인증에 Kerberos 사용할지 여부 설정 (ON/OFF)

* 참고: Kerberos는 네트워크 인증 프로토콜로, 싱글 사인온(SSO)을 구현하는 데 사용되는 보안 시스템이다.

Cache settings (캐시 설정)
- Cache policy: LDAP 조회 결과를 캐시하는 정책 설정 (DEFAULT/EVICT_DAILY/EVICT_WEEKLY/MAX_LIFESPAN/NO_CACHE)
Advanced settings (고급 설정)
- Enable the LDAPv3 password modify extended operation:
  LDAPv3의 확장된 비밀번호 수정 작업 활성화 여부 (ON/OFF)
- Validate password policy: LDAP 서버의 비밀번호 정책 검증 활성화 여부 (ON/OFF)
- Trust Email: LDAP에서 가져온 이메일 주소를 신뢰할지 여부 설정 (ON이면 이메일 검증 절차 생략) (ON/OFF)
- Connection trace: LDAP 연결 디버깅을 위한 상세 로그 활성화 여부 (ON/OFF)
- Query Supported Extensions: LDAP 서버가 지원하는 확장 기능 조회 버튼

이제 LDAP 연동이 완료 되었다.

Users 탭으로 이동해서 사용자가 보이는지 점검해보자.

사용자가 잘 보인다.
여기까지만 하면 실제 환경에서 어떻게 쓰이는지 이해하기 쉽지 않으니, 샘플 어플리케이션으로 테스트를 해보자.

어플리케이션 추가 (Ldap 사용자로 Keycloak SSO로 Grafana 로그인하기)

1. Grafana 설치

* 설치링크: https://grafana.com/docs/grafana/latest/setup-grafana/installation/helm/

널리 사용하는 Grafana를 설치하고, 사용자 로그인까지 테스트 해보자.

# helm 저장소 등록 및 업데이트
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

# helm 다운받고 압축풀기
helm fetch grafana/grafana
tar -zxvf grafana-8.10.1.tgz

# 설치하기
cd grafana
helm install grafana .

설치했다면 역시 포트 포워딩을 통해 로컬 브라우저에서 접속 가능하도록 하자.

# Grafana 서비스로 포트포워딩
kubectl port-forward svc/grafana 8084:80 &

# Grafana admin 비밀번호 확인
kubectl get secret --namespace default grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo

브라우저로 localhost:8084 접속해서 로그인 한다.

2. Keycloak LDAP Mapper 설정

위 Keycloak 단계에서 사용자 정보를 가져오는것은 확인했지만, 잘 보면 사용자에 그룹정보가 빠져있다.
LDAP의 Group정보를 가져오기위해서는 추가적인 Mapper를 설정해주어야 한다.

- 그룹 정보 동기화 (group-ldap-mapper)

먼저 LDAP의 그룹을 가져와 보자.
LDAP연동한 곳에서 새로운 매퍼를 추가한다.

이 매퍼는 그룹을 동기화 시키기 위해 설정한다.
LDAP 기본설정이아닌 openLDAP 그룹(posixGroup)설정에 맞춰져 있으니 AD등 다른 LDAP서버를 사용한다면,
설정되어있는 LDAP 정보를 잘 보고 사용해야 한다.

Name: group-ldap-mapper
Mapper type: group-ldap-mapper
Group Name LDAP Attribute: cn
Group Object Class: posixGroup
Preserve Group Ingeritance: off
Ignore Missing Group: off
Membership LDAP Attribute: gidNumber
Membership Attribute Type: UID
Membership User LDAP Attribute
LDAP FIlter: (빈값)
Mode: READ_ONLY
User Groups Retrieve Strategy: LODA_GROUPS_BY_MEMBER_ATTRIBUTE

이렇게 설정하고나서 동기화를 해준다.

OpenLDAP에서 설정했던것과 같이 3개의 그룹이 보인다.

다만, 안에 들어가면 유저가 하나도 없는데 그 이유는 아직 사용자의 gidNumber를 가져오지 않았기 때문이다.

- 사용자의 그룹 정보 동기화 (user-attribute-ldap-mapper)

이제 사용자의 gidNumber를 가져오기 위해 매퍼를 하나 더 생성한다.

LDAP에서 사용자와 그룹 정보는 gidMember 값으로 매핑되기때문에,
keycloak에서도 이 정보를 가지고 있어야 사용자를 그룹에 올바르게 매핑할 수 있다.

이제 Sync all users를 클릭하면 사용자 정보를 업데이트 하는것을 확인할 수 있다.

이제 그룹에 사용자가 할당되어있다!

3. Keycloak Client 생성

Keycloak으로 Grafana 인증/인가를 처리할 예정이니, Client를 생성한다.
물론 위에서 만든 my-LDAP Realm에서 만들어야 한다.

Client type: OpenID Connect
ClientID: grafana
Name: grafana
Client authentication: on
Root URL: http://127.0.0.1:8084
Home URL: http://127.0.0.1:8084
Valid redirect URIs: http://127.0.0.1:8084/login/generic_oauth
Web origins: http://127.0.0.1:8084

4. LDAP Group Keycloak Role 매핑

이제 앞에서 설정한 LDAP Group과 Client의 Role을 연결해주어야 한다.
우선 Client Role탭에서 Role을 생성한다.

GrafanaAdmin
GrafanaEditor
GrafanaViewer

이제 Group으로 가서 각 그룹과 매칭되는 Client Role을 매핑한다.

administrartor(LDAP Group) --[mapping]-- GrafanaAdmin(ClientRole)
editor(LDAP Group) --[mapping]-- GrafanaEditor(ClientRole)
readonlyuser(LDAP Group) --[mapping]-- GrafanaViewer(ClientRole)

이렇게 하면 LDAP Group설정과 Client Role설정이 매핑된다.
매핑이 잘 되었는지 확인하려면 [사용자 -> Role mapping탭]에서 Hide inherited roles를 해제하고 보면 된다.

4. Client Role을 Protocal Mapper를 통해 Claim에 추가

이제 Role이 사용자 정보에 포함되어있다.
이제 Protocal Mapper를 통해 Claim에 추가해주어야 한다. ("어떤 정보를" "어떤 형식으로" 토큰에 넣을지 지정)

이제 정말 끝났다!!
마지막으로 client secret을 저장한다.

5. Grafana oauth 설정 (grafana.ini)

* Grafana Keycloak SSO 문서: https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/keycloak/

이제 위에서 받아놓은 grafana helm charts를 수정해주어야 한다.
grafana 디렉토리 내 values.yaml을 찾아 아래 내용을 추가한다. 주의해야할점은 기존 정보를 건드리지 않는것이다!

  server:
    # Grafana의 외부 접근 URL 설정
    root_url: http://127.0.0.1:8084

  auth.generic_oauth:
    # OAuth 인증 활성화 여부
    enabled: true
    # OAuth 제공자 이름 설정
    name: Keycloak-OAuth
    # 새로운 사용자의 자동 회원가입 허용
    allow_sign_up: true
    # OAuth 클라이언트 ID
    client_id: grafana
    # OAuth 클라이언트 시크릿 키
    client_secret: "Qi3lPg5eU9HA8Hc3LHyseWuhAH936qYU"
    # 요청할 OAuth 스코프 (권한 범위)
    scopes: "openid email profile offline_access roles"
    # 로그인에 사용할 사용자 속성 경로
    login_attribute_path: "username"
    # 사용자 이름으로 사용할 속성 경로
    name_attribute_path: "name"
    # 이메일로 사용할 속성 경로
    email_attribute_path: "email"
    # OAuth 인증 엔드포인트 URL (사용자인증 경로)
    auth_url: "http://127.0.0.1:8082/realms/my-LDAP/protocol/openid-connect/auth"
    # OAuth 토큰 발급 엔드포인트 URL
    token_url: http://keycloak.default.svc.cluster.local/realms/my-LDAP/protocol/openid-connect/token
    # 사용자 정보를 가져올 API URL
    api_url: http://keycloak.default.svc.cluster.local/realms/my-LDAP/protocol/openid-connect/userinfo
    # 사용자 역할 매핑 규칙 (GrafanaAdmin -> Admin, GrafanaViewer -> Editor, 기타 -> Viewer)
    role_attribute_path: "contains(roles[*], 'GrafanaAdmin') && 'Admin' || contains(roles[*], 'GrafanaEditor') && 'Editor' || contains(roles[*], 'GrafanaViewer') && 'Viewer'"
    # Grafana 관리자 권한 할당 허용
    allow_assign_grafana_admin: true
    # Grafana 조직 역할 동기화 건너뛰기 비활성화
    skip_org_role_sync: false
    # 엄격한 역할 속성 매칭 사용
    role_attribute_strict: true

이렇게 수정했다면 이제 helm을 업데이트 한다.

helm upgrade grafana . -f values.yaml --set assertNoLeakedSecrets=false

헬름 업데이트 후 터널링이 끊겨있을텐데 한번 더 연결해주자!

kubectl port-forward svc/grafana 8084:80

6. Grafana 에 LDAP 계정으로 로그인하기

이제 드디어 접속해보자

LDAP 계정에 이메일 설정이 안되어있기 때문에, 이메일 정보를 추가하고 Submit하면 Grafana에 로그인 되며,
사용자 Profile을 확인하면 admin에 매핑되어있는걸 확인할 수 있다.

7. 추가) 트러블슈팅 "IdP did not return a role attribute, please contact your administrator"

# Grafana logs
logger=context userId=0 orgId=0 uname= t=2025-02-22T20:43:15.60593592Z level=info msg="Request Completed" method=GET path=/login/generic_oauth status=302 remote_addr=127.0.0.1 time_ms=0 duration=683.167µs size=309 referer=http://127.0.0.1:8084/login handler=/login/:name status_source=server
logger=oauth.generic_oauth t=2025-02-22T20:43:15.709432879Z level=warn msg="Failed to extract role" err="[oauth.role_attribute_strict_violation] idP did not return a role attribute, but role_attribute_strict is set"
logger=authn.service t=2025-02-22T20:43:15.709525962Z level=error msg="Failed to authenticate request" client=auth.client.generic_oauth error="[auth.oauth.userinfo.error] failed to get user info: [oauth.role_attribute_strict_violation] could not evaluate any valid roles using IdP provided data"
logger=context userId=0 orgId=0 uname= t=2025-02-22T20:43:15.712088504Z level=info msg="Request Completed" method=GET path=/login/generic_oauth status=302 remote_addr=127.0.0.1 time_ms=28 duration=28.130417ms size=29 referer= handler=/login/:name status_source=server

만약 IdP did not return a role attribute, please contact your administrator 오류를 만났다면,
아래 명령어를 통해 Claim으로 roles 추가가 잘 된건지 한번 더 점검해보자.

curl -X POST "http://localhost:8082/realms/my-LDAP/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=grafana" \
-d "client_secret=Qi3lPg5eU9HA8Hc3LHyseWuhAH936qYU" \
-d "username=sadministrator" \
-d "password=1234" \
-d "grant_type=password" | jq -r '.access_token' | jwt decode -

만약 이부분이 정상이라면 helm charts values의 role_attribute_path가 잘못되었을 가능성이 크다.
Roles와 매핑이 잘 되는지 한번 더 점검해보자.

[keycloak 맛보기#9] 세션 및 토큰 관리

mini_world — Wed, 12 Mar 2025 02:15:41 +0900

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: 리프레시 토큰 사용 후 해지 여부 (비활성화됨).
  (활성화하면 리프레시 토큰은 한 번만 사용 가능하며, 새 액세스 토큰을 얻을 때 새 리프레시 토큰이 발급됨)
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 애플리케이션에 알림

[keycloak 맛보기#8] 사용자 인증(Authentication)

mini_world — Sun, 9 Mar 2025 00:50:28 +0900

개요

공식문서 링크

인증은 Client(사람/기기/애플리케이션 등)의 신원을 검증하는것을 말한다.
Keycloak은 OAuth2.0 기반의 인증/인가 프로세스를 가지고 있고, Keycloak에서의 인증은 어떻게 사용할 수 있는지 어떤 기능이 있는지 살펴보고자 한다.

인증 흐름 (Authentication flows)

공식문서 링크

인증 흐름이란?

인증 흐름이란 클라이언트가 시스템에 접근할 때 거치는 인증 단계의 순서와 방법을 정의한 것을 말한다.
Keycloak에서는 인증 흐름을 재사용 할 수 있도록 Template 형태로 정의할 수 있다.

Keycloak에서 인증을 어떻게 수행할지 그 방법과 순서를 Authentication Flow로 정의하고,
정의된 Authentication Flow를 특정 인증 상황에 연결(Bind)해서 사용할 수 있도록 한다.

Keycloak에서 사용할 수 있는 인증 흐름은 아래와 같다. 인증 Flow 탬플릿을 정의해서 Bind하여 사용할 수 있다.

Browser Flow: 웹 브라우저 기반 로그인을 처리하는 기본 흐름 (사용자명/비밀번호, OTP, WebAuthn 등)
Client Authentication: 클라이언트(애플리케이션) 인증 방식을 정의하는 흐름
Direct Grant Flow: 사용자 자격 증명을 직접 API로 전송하는 방식(REST API 인증용)
Docker Authentication: Docker 레지스트리 인증을 위한 특수 흐름
First Broker Login: 소셜 로그인이나 외부 IDP 최초 사용 시 계정 연결 방식 정의
Registration Flow: 새 사용자 등록 과정에서 사용되는 단계와 검증을 정의
Reset Credentials Flow: 비밀번호 재설정 프로세스를 관리하는 흐름

"재사용한다"는 의미를 정확히 이해할 수 있게 실습을 해보자.

[참고] OAuth2.0의 권한부여 유형(Grant Types)과 어떤 관계가 있는지?

이전 OAuth2.0 정리하는 포스팅에서 주요 권한 부여 유형에 대해 살펴 봤었는데, 이것과 어떤 관계인건지 확인하보자.

Keycloak은 OAuth 2.0/OIDC 프로토콜을 구현하는 제품이며, Grant Types를 구현하기 위해 Authentication Flow를 사용한다.
예를들면 아래와 같다.

Authorization Code Grant: Browser Flow를 통해 구현 (사용자 로그인, 권한 동의 등의 단계 포함)
Client Credentials Grant: Client Authentication Flow를 통해 구현 (클라이언트 ID/시크릿 검증)
Resource Owner Password Grant: Direct Grant Flow를 통해 구현 (사용자 ID/비밀번호 직접 검증)
Device Authorization Grant: HTTP Challenge Flow를 통해 구현 (기기 인증 코드 검증)

즉, Grant Type은 OAuth2.0수준에서 정의된 프로토콜 수준의 명세이고, Keycloak의 Authentication Flow는 구현체인것이다.

인증 흐름 (Authentication flows) 실습해보기

이제 Keycloak을 실행해보자.
이전 포스팅에서 Docker로 실행하는것과 K8s(minikube) helm으로 실행하는것 모두 실습해보았는데, 실행 방법 편한 방법으로 하자.

# Docker로 실행하기
docker run -p 8080:8080 \
          -e KEYCLOAK_ADMIN=admin \
          -e KEYCLOAK_ADMIN_PASSWORD=admin \
          quay.io/keycloak/keycloak:24.0.4 \
          start-dev

# k8s(minikube) helm으로 실행하기
minikube start
helm install keycloak oci://registry-1.docker.io/bitnamicharts/keycloak \
  --set auth.adminUser=admin \
  --set auth.adminPassword=admin \
  --set postgresql.auth.username=bn_keycloak \
  --set postgresql.auth.password=password \
  --set postgresql.auth.database=keycloak \
  --set postgresql.auth.postgresPassword=password
kubectl port-forward svc/keycloak 8082:80 &

새로운 Realm을 만든다. (my-Authentication)
개념만 이해할 예정이니 기존에 테스트 하던 Realm을 사용해도 상관없다.

이제 테스트를 위해 사용자를 만들어보자.
나는 user01 사용자를 생성했다. 유저를 생성한 후에는 반드시 Credentials에서 비밀번호를 추가해주어야 한다.

사용자 로그인 테스트를 해보자.
왼쪽 네비게이션바 Clients에서 account home URL을 클릭하면 사용자 로그인 페이지로 들어갈 수 있다.

사용자 로그인 페이지에서 계정과 비밀번호를 입력하게 되어있고, 계정 정보를 입력하면 바로 로그인 할 수 있다.

이제 기본값으로 로그인을 했으니, 인증 방식을 변경해보자.

왼쪽 네비게이션바에서 `Authentication`을 클릭하자.
사용가능한 인증 Flow가 정의되어있다.

재사용 가능하다는것이 어떤 의미인지 테스트 해보자. 먼저 Browser Flow를 복제한다.

이제 이 폼을 좀 바꿔보자.
AS-IS, TO-BE를 확인하고 그대로 수정해도 좋고, 원하는 방식으로 수정해도 된다.
아래의 경우에는 UsernameForm 단계를 추가하고, OTP를 Required로 추가했다.

그리고 방금 수정한 Form을 Browser flow로 바인드 한다.

그럼 이제 다시한번 사용자 로그인을 통해 인증 방식이 어떻게 변경 되었는지 확인할 수 있다.
이전에는 계정 ID와 비밀번호를 한번에 입력한 후 바로 로그인 되었는데,
my-test-browser 탬플릿으로 변경한 후 ID입력창, PW입력창, OTP설정이 강제된것을 확인할 수 있다.

인증 정책 (Authentication Policies)

인증 정책은 인증 방식에 대한 정의이다.
위에서 설명했던 인증흐름이 "어떤 순서로 인증할것인가"에 대한 정의였다면,
인증 정책은 "어떻게 동작해야 하는가"를 정의하는 것 이다.

인증 정책(Policies) 종류

Keycloak의 Authentication을 살펴보면 정말 다양한 인증 옵션을 제공하는것을 확인할 수 있다.

Password policy: 비밀번호 길이, 복잡성, 특수문자 요구사항 등 비밀번호 강도를 제어하는 설정
OTP Policy: 일회용 비밀번호 인증의 알고리즘, 자릿수, 유효기간 등을 설정
Webauthn Policy: 생체인증 등 FIDO2/WebAuthn 기반 2차 인증(MFA)을 위한 설정
Webauthn Passwordless Policy: 비밀번호 없이 WebAuthn만으로 인증할 수 있는 정책 설정
CIBA Policy: 클라이언트 주도 백채널 인증의 시간제한, 인증방식 등을 설정

특히 비밀번호 정책은 KISA홈페이지에만 가도 사용 가이드가 있으니, 자세한 내용은 패스한다.

[참고] WebAuthn(Web Authentication)이란?

webauthn.guide

WebAuthn(Web Authentication)은 웹 상에서 비밀번호대신 공개키 방식의 로그인을 지원하는 인증 기술이며,
2019년 3월에 W3C(World Wide Web Consortium)와 FIDO 얼라이언스가 공동으로 개발하여 공식 웹 표준으로 승인되었다고 한다.

작동 방식:
- 사이트에 등록할 때:
  1. 사용자가 등록을 시작하면 웹사이트(Keycloak)가 브라우저를 통해 인증 요청을 전송한다.
  2. 인증기(Authenticator- iCloud 키체인, 휴대전화/태블릿의 보안 모듈, USB 보안키 등)가 고유한 암호화 키 쌍을 생성한다.
  2. 개인 키는 인증기(Authenticator) 내부에 안전하게 저장되고, 공개 키는 브라우저를 통해 웹사이트에 전송되어 사용자 계정과 연결된다.
- 로그인할 때:
  1. 웹사이트는 브라우저를 통해 인증 요청(challenge)을 전송한다.
  2. 브라우저는 이 요청을 인증기(Authenticator)로 전달한다.
  3. 사용자가 지문, 얼굴 인식, PIN 코드 또는 버튼 터치 등으로 자신을 인증하면, 인증기는 저장된 개인 키를 사용하여 challenge에 서명하고 이 서명된 응답을 브라우저를 통해 웹사이트로 전송한다.
  4. 웹사이트는 등록된 공개 키로 서명을 검증하여 사용자를 인증한다.
장점:
- 피싱 방지: 가짜 웹사이트는 실제 웹사이트의 키를 복제할 수 없음
- 비밀번호 없음: 기억할 비밀번호가 필요 없음
- 편리함: 지문 하나로 빠르게 로그인
- 강력한 보안: 비밀번호보다 훨씬 해킹하기 어려움

[keycloak 맛보기 #7] Production Keycloak을 위한 설정

mini_world — Sun, 16 Feb 2025 16:58:29 +0900

들어가기전에,

*https://www.keycloak.org/server/configuration-production

Keycloak은 수백~수천명의 사용자에게 안전한 인증 및 권한부여를 제공할 수 있도록 설계되어있다.
안전하고 안정적인 Keycloak을 프로덕션 환경에 배포하기 위해 설정해야 할 부분들을 확인 해 보자.

1. Keycloak의 Hostname 설정

* 공식문서: https://www.keycloak.org/server/hostname

✓ Hostname을 설정해야하는 이유

keycloak은 보안상의 이유로 hostname 설정을 필수로한다.

▪︎ 설명

Keycloak은 OIDC Discovery 엔드포인트, 사용자 비밀번호 변경 엔드포인트 등의 URL이 외부로 공개된다.
이때, hostname이 설정되어있지 않다면 가짜 도메인으로 redirect하여 사용자 정보(token, password)를 탈취 당할수도 있다.
따라서 Hostname을 명시적으로 설정하여 다른 도메인으로 토큰이 발급되는것을 방지할 수 있다.

keycloak의 보안 강화를 위해 아래 3가지를 기본적으로 설정하는것이 바람직하다.

항상 https 사용
관리자 콘솔 분리
프록시 설정 시 신뢰할수있는 프록시 주소 설정

▪︎ 탈취 시나리오

공격자가 조작된 Host헤더를 사용하여 Keycloak Redirect URL을 생성할때 악의적인 도메인을 설정할 수 있다.

사용자가 my.keycloak.com에서 로그인을 시도
↓
공격자가 Host 헤더를 fake-site.com으로 변조
↓
리다이렉트 URL이 fake-site.com으로 생성됨
↓
사용자가 피싱 사이트로 리다이렉트됨

혹은 리버스 프록시 설정도 오용 될 수 있다.
리버스 프록시 설정은 뒤에서 조금 더 다뤄보도록 한다.

Client -> Reverse Proxy -> Keycloak
                      ↑
                      | 
                      공격자가 X-Forwarded-Host 
                      헤더를 조작

✓ 세가지 주요 엔드포인트 그룹

Keycloak은 각각 다른 목적을 가진 3가지 주요 엔드포인트가 있다.
일반적인 환경에서 어떻게 쓰이는지 좀 더 확인해보자.

▪︎ frontend

사용자 및 애플리케이션이 직접 접근하는 공개 엔드포인트다.
로그인/로그아웃/비밀번호 재설정 URL 또는 세션 관리와 관련된 엔드포인트 등이있다.

bin/kc.[sh|bat] start --hostname https://auth.my.com

▪︎ Backend

클라이언트 애플리케이션과 Keycloak간의 내부통신을 위한 엔드포인트다.
인증 엔드포인트, 토큰 및 토큰 인트로스펙션 엔드포인트, userinfo 엔드포인트, JWKS URI 엔드포인트 등이 있다.
기본적으로는 hostname-backchannel-dynamic 옵션이 false로 설정되어있다.

여기서 조금 헷갈릴 수 있는 부분은 hostname-backchannel-dynamic 옵션 설정을 true로 변경한다면
내부 통신을 위한 내부 endpoint가 활성화 된다는 뜻이라는 거다.
서브도메인을 별도로 설정할 수 있는것이 아니다.

hostname-backchannel-dynamic=False	hostname-backchannel-dynamic=True
- 백채널 통신도 --hostname 값 사용 - 내부 서비스간 통신도 외부 URL을 통해 이루어짐	- 백채널 통신은 실제 요청이 들어온 호스트/IP 사용 - 내부 통신 최적화 가능

백엔드 엔드포인트는 아래 설정으로 활성화 할 수있다.

bin/kc.[sh|bat] start --hostname https://auth.my.com --hostname-backchannel-dynamic true

▪︎ Administrator

관리용 콘솔 엔드포인트다.
별도의 호스트 네임을 설정할 수 있다.

bin/kc.[sh|bat] start --hostname https://auth.my.com --hostname-admin https://admin.auth.my.com:8443

2. Keycloak TLS 활성화

* 공식문서: https://www.keycloak.org/server/enabletls, https://www.keycloak.org/server/keycloak-truststore

너무나 당연하게도, 외부 인터넷으로 노출된 Keycloak엔드포인트는 반드시 https/TLS를 사용해야 한다.
다만, AWS를 사용하는 경우 ALB에서 SSL을 해제하여 외부 노출된 엔드포인트는 TLS설정을, 내부 네트워크에서는 평문통신을 사용하기도 한다.

Keycloak은 PEM 형식의 파일이나 Java Keystore에서 필요한 인증서 인프라를 로드하도록 구성할 수 있으며,
두 가지 모두 설정된 경우 PEM 파일이 Java Keystore보다 우선한다.

▪︎ AWS ALB(+ACM)에서 TLS/SSL 오프로드

[클라이언트] → HTTPS → [ALB(+ACM)] → HTTP → [Keycloak]

bin/kc.[sh|bat] start \
 --hostname auth.my.com \
 --proxy edge \
 --http-enabled=true \
 --http-port=8080

인증서 관리가 AWS AWS Certificate Manager(ACM)로 간편화
ACM에서 인증서 자동갱신
ALB에서의 TLS/SSL 오프로딩으로 Keycloak 서버 부하 감소

▪︎ End to End TLS/SSL 사용

[클라이언트] → HTTPS → [ALB] → HTTPS → [Keycloak]

# PEM 파일 사용방식
bin/kc.[sh|bat] start \
 --hostname auth.my.com \
 --proxy passthrough \
 --https-certificate-file=/path/to/cert.pem \
 --https-certificate-key-file=/path/to/key.pem \
 --http-enabled=false

# Java Keystore (JKS) 방식
###1. Keystore 생성
keytool -genkeypair \
  -alias keycloak \
  -keyalg RSA \
  -keysize 2048 \
  -validity 365 \
  -keystore keycloak.jks \
  -dname "CN=auth.my.com" \
  -storepass store123 \
  -keypass key123
### 2. Keycloak 시작 명령어
bin/kc.[sh|bat] start \
  --hostname auth.my.com \
  --proxy passthrough \
  --https-key-store-file=/path/to/keycloak.jks \
  --https-key-store-password=store123 \
  --https-key-store-type=JKS \
  --http-enabled=false

전 구간 암호화로 더 높은 보안성

3. Keycloak Database 설정

* 공식문서: https://www.keycloak.org/server/db

Keycloak 서버를 구성할때 사용할 수 있는 database engine은 여러가지가 있다.
(mariadb, mssql, mysql, oracle, postgres..)

처음에 테스트로 설치할때는 dev-file 데이터베이스를 사용하기때문에, 프로덕션에 구성할땐 반드시 설정을 변경하여 사용해야 한다.

▪︎ Postgres Database를 이용한 설정 예시

conf/keycloak.conf 파일에서 Database 를 위한 설정을 할 수 있다.

# conf/keycloak.conf
db=postgres # 데이터베이스 유형(mariadb, mysql, postgres..등이 있음)
db-username=keycloak # 데이터베이스 사용자 이름
db-password=password # 사용자 패스워드
db-url-host=keycloak-postgres # DB 엔드포인트

설정파일을 수정했다면 아래 명령어로 실행할 수 있다.

bin/kc.[sh|bat] build
bin/kc.[sh|bat] start --optimized

설정파일로 추가하는것이 아니라 그냥 커멘드로도 설정할 수 있다.

bin/kc.[sh|bat] start --db postgres --db-url-host keycloak-postgres --db-username keycloak --db-password password

▪︎ 설정 옵션들과 주의사항

설정 가능한 옵션들은 여기 링크에서 확인할 수 있다.
oracle을 제외한 대부분의 데이터베이스 엔진 드라이버가 설치되어있고, 사용시 기본 드라이버를 사용하지만, 별도로 드라이버를 설정 할 수 있다.

추가적으로 주의해야할 부분은 connection pool 부분일 것이다.
프로덕션인 경우, max,min connection pool을 잘 설정해주어야 한다.

각 데이터베이스 엔진에 따라 설정 방법이 공식문서에 잘 설명되어있으니, 공식문서를 통해 구성하는것이 좋다.

4. Keycloak 다중 노드 클러스터 설정 - Cache

* 공식문서: https://www.keycloak.org/server/caching

▪︎ 아키텍쳐

Keycloak은 고가용성(HA) 및 다중 노트 클러스터링 설정을 할 수 있도록 설계되어있다.
여러대의 Keycloak노드를 사용하므로써, 특정 노드가 중단되도 장애를 방지할 수 있고, 부하에 따라 노드를 확장/축소 함으로써 가용성을 확보할 수 있다.

Keycloak 클러스터링의 핵심은 Reverse Proxy(LoadBalanceing) 및 캐시 구성이라고 할 수 있다.
Keycloak은 Infinispan을 기반으로 (key-value In-memory) 클러스터 캐시를 구성할 수 있도록 제공한다.
캐시 구성이 클러스터 설정에 어떤역할을 하는지 확인해본다.

▪︎ Cache 옵션

Keycloak의 캐시는 --cache 옵션으로 설정할 수 있고, 옵션은 local/ ispn이 있다.

--cache=local 인 경우 모든 캐시가 로컬에서만 동작(클러스터링❌불가능):
- sessions, clientSessions도 로컬에만 저장
- realms, users 등도 로컬에만 저장
- 노드간 데이터 공유 없음
--cache=ispn* 인 경우 클러스터 내 공유되어야하는 데이터가 노드 외부에 캐시로 저장 (클러스터링 가능):
- Session 등 클러스터 전체에 공유되어야 하는 데이터가 외부 캐시에 저장됨 (아래 표 참고)

구분	Local Cache	Distribute Cache
목적	데이터베이스의 부하를 줄이기 위한 로컬 캐시	클러스터 전체에 공유되어야 하는 데이터 캐시
종류	- realms: Realm 데이터 - users: 사용자 데이터 - authorization: 권한 데이터 - keys: 공개키 데이터	- authenticationSessions: 인증 프로세스 중인 세션 - sessions: 사용자 세션 - clientSessions: 클라이언트 세션 - loginFailures: 로그인 실패 기록 - actionTokens: 일회용 액션 토큰 등..
특징	- 노드별로 독립적으로 동작 - 클라이언트 세션 캐시 기본 10,000개 엔트리 저장 - 다른 노드의 변경사항은 work 캐시*를 통해 무효화	- 세션 데이터가 특정 노드들에 분산 저장 - owners 설정에 따라 복제본 수 결정 - 노드 장애시 자동 복구

* ispn은 Infinispan(ispn/링크)을 말하며, Redis나 Memcache와 같은 캐시 시스템이다.
keycloak은 공식적으로 ispn만 지원한다.
* work cache는 캐시 무효화를 위한 방법이다. (링크) 간단하게 설명하자면 A,B,C 3개의 노드 를 운영할때 A노드에서 User데이터가 변경되었다고 하면, A노드는 User의 데이터가 변경되었다고 Work Cache에 무효화 메시지 전송하고, Work Cache가 모든 노드에 브로드캐스트하며 각 노드는 해당 데이터를 삭제한다. 이렇게 설정해야 데이터의 수정이 발생하더라도 모든 노드가 같은 데이터를 가지고 있을 수 있다.

▪︎ Cache 설정 방법

일반 명령어로는 아래 설정으로 클러스터를 위한 캐시를 구성할 수 있다.

bin/kc.sh start \
  --cache=ispn \
  --cache-stack=kubernetes \
  --cache-owners=2 \
  --features-disabled=persistent-user-session \
  --spi-sticky-session-encoder-infinispan-should-attach-route=true \ 
  --metrics-enabled=true \
  --cache-metrics-histograms-enabled=true

--cache=ispn: 클러스터링 활성화
--cache-stack=kubernetes: Discovery 방법 선택 (jdbc-ping, kubernetes)
--cache-owners*=2: 각 캐시 엔트리 복제본 수
--features-disabled=persistent-user-session: 세션 DB저장 비활성화
--spi-sticky-session-encoder-infinispan-should-attach-route=true : 스티키 세션 활성화, 세션 소유 노드로 요청 라우팅, 캐시 접근 최적화
--metrics-enabled=true: 모니터링 활성화
--cache-metrics-histograms-enabled=true: 캐시 메트릭 히스토그램 활성화

* --cache-owners 설정은 엔트리(데이터)의 복제본을 몇개 사용할건지 설정한다.
이 설정은 너무 큰 값으로 설정하면 네트워크,CPU등에 부하를 줄 수 있으므로 , 일반적으로 2~3개의 복제본을 권장한다. owners=2는 한 노드 장애를, owners=3은 두 노드 장애를 허용할 수 있다.

bitnami에서 제공하는 keycloak helm chart 설정으로는 아래와 같이 설정된다. (특별히 커스텀할게 없다)

# https://artifacthub.io/packages/helm/bitnami/keycloak?modal=values
## Keycloak cache configuration
## ref: https://www.keycloak.org/server/caching
## @param cache.enabled Switch to enable or disable the keycloak distributed cache for kubernetes.
## NOTE: Set to false to use 'local' cache (only supported when replicaCount=1).
## @param cache.stackName Set infinispan cache stack to use
## @param cache.stackFile Set infinispan cache stack filename to use
## @param cache.useHeadlessServiceWithAppVersion Set to true to create the headless service used for ispn containing the app version
##
cache:
  enabled: true
  stackName: kubernetes
  stackFile: ""
  useHeadlessServiceWithAppVersion: false

5. Keycloak 다중 노드 클러스터 설정 - Reverse Proxy

* 공식문서: https://www.keycloak.org/server/reverseproxy

▪︎ 아키텍쳐

위에서 설명한데로, Keycloak은 고가용성(HA) 및 다중 노트 클러스터링 설정을 할 수 있도록 설계되어있으며,
Keycloak 클러스터링의 핵심은 Reverse Proxy(LoadBalanceing) 및 캐시 구성이다.
이번 단계에서는 Reverse Proxy(=API Gateway, LoadBalancer) 부분을 확인해보자.

▪︎ Reverse Proxy의 역할

리버스 프록시가 해주어야 하는 역할은 아래와 같다.

구분	설명
노드 부하 분산	- 트래픽을 여러 Keycloak 노드에 균등하게 분배한다. - 부하 분산 알고리즘을 적절하게 선택하여 사용한다. - Round Robin: 순차적 분배 - Least Connection: 연결 수가 적은 노드 우선 - Response Time: 응답 시간 기준 예시 설정 (nginx): upstream keycloak { server keycloak1:8080; server keycloak2:8080; server keycloak3:8080; }
세션 어피니티 (Sticky Session) 공식문서 링크	- 캐시 히트율 향상/ 세션 데이터 접근 최적화/ 불필요한 노드간 통신 감소를 위해 동일 사용자의 요청을 같은 노드로 라우팅 - 필수 설정은 아니지만 설정하면 부하 감소 및 처리 속도에 이점이 있음 예시 설정 (nginx): upstream keycloak { ip_hash; # 또는 sticky cookie server keycloak1:8080; server keycloak2:8080; }
헤더 전송 공식문서 링크	- 클라이언트 정보를 Keycloak에 전달 - 주요 헤더: - X-Forwarded-For: 실제 클라이언트 IP - X-Forwarded-Proto: 원본 프로토콜 - X-Forwarded-Host: 원본 호스트 - X-Real-IP: 실제 클라이언트 IP - --proxy-headers 옵션을 설정하지 않으면, Origin 체크 실패하고 403(Forbidden)을 반환함 예시 설정 (nginx): proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;
SSL/TLS 처리 최적화	- SSL/TLS 오프로드를 Reverse Proxy에서 처리할 수 있음 - "2. Keycloak TLS 활성화" 참고
노드 상태 모니터링	- 타겟 노드의 상태를 모니터링하고, 비정상적인 노드에 트래픽 차단 예시 설정 (nginx): health_check uri=/health interval=5s;

▪︎ 노출할 엔드포인트 지정

Reverse Proxy를 사용할때 모든 엔드포인트를 다 노출하는것이 아니라, 필요한 몇개의 엔드포인트만 노출하도록 설정한다.
(공식문서링크)

Keycloak Path	Reverse Proxy Path	Exposed	설명
/		❌	불필요한 관리자 경로 노출될 우려가 있음
/admin/		❌	불필요한 관리자 경로 노출될 우려가 있음
/realms/	/realms/	✅	- OIDC 엔드포인트 필요 - 인증/인가 프로세스 필수 - 클라이언트 연동 필요
/resources/	/resources/	✅	- UI 자원 제공 - 정적 파일 서비스 - CDN 사용 가능
/metrics		❌	시스템 정보/성능데이터/내부 모니터링 노출 불필요
/health		❌	시스템 상태 정보 노출 불필요 내부 로드밸런서용으로 사용하며, 불필요한 공격 정보가 제공됨

▪︎ 기타 알면 좋은것..

공식문서에는 reverse proxy로 사용할 수 있는 프록시로 nginx, haproxy, nginx를 말하지만,
AWS환경에서는 간단하게 AWS ALB를 사용하면 된다.

AWS ALB는 다른 프록시들과 비교해보자면, 기본적인 기능 (SSL/TLS 오프로드, 세션 어피니티, 헬스체크, 라우팅 알고리즘 선택 등의 기능 제공)은 똑같은데 관리할 필요가 거의 없다는 장점이 있다.

[keycloak 맛보기 #6] Keycloak의 인가 전략

mini_world — Sun, 9 Feb 2025 14:47:13 +0900

개요, 인가란 무엇인가?

들어가기 전에 인가(Authorization)이 무엇인지 한번 더 개념을 정리해보자.
인가는 "이 사용자가 특정 리소스나 기능에 접근할 권한이 있는지 확인하는 과정"이다.

예를들자면 어떤 사용자가 ID/PW를 입력하고 사진첩 어플리케이션에 로그인했다면,
사용자 본인의 사진첩에만 접근 가능해야하며 다른 사용자의 사진첩에는 접근해서는 안된다.

구분	개념	예시
인증 Authentication	누구인지 확인하는 과정	로그인
인가 Authorization	무엇을 할 수 있는지 확인하는 과정	내 사진첩에만 접근

즉, 인가란 사용자가 허용된 리소스에만 접근하도록 하는것이 인가의 개념이다.

인가를 위해 고려해야하는 요소는 정말 많다.

사용자 컨텍스트 (Who): 사용자 신원, 역할, 그룹, 속성, 조직 구조 내 위치
리소스 컨텍스트 (What): 리소스 유형, 소유권, 민감도 수준, 계층 구조, 메타데이터
접근 조건 (When/How): 시간/위치 기반 제약, 디바이스/네트워크 조건, 다중 인증, 접근 빈도
운영 관점 (Operation): 권한 위임/상속, 긴급 접근, 임시 권한, 권한 취소
감사 및 모니터링 (Audit): 접근 로그, 권한 변경 이력, 비정상 탐지, 컴플라이언스, 사용 패턴
정책 관리 (Policy): 버전 관리, 충돌 해결, 테스트, 배포 전략, 예외 처리
보안 고려사항: 최소 권한 원칙, 직무 분리, 권한 에스컬레이션 방지, 세션/토큰 관리
확장성 및 성능: 캐싱, 분산 시스템, 정책 처리, 응답 시간, 장애 복구
통합 고려사항: 레거시 통합, SSO, 외부 시스템 연동, API 보안, 프로토콜
규정 준수: 산업 표준, 데이터 보호, 감사 요구사항, 법규, 개인정보 보호

그렇다면, Keycloak에서는 인가를 어떻게 처리할것인가?
공식문서 Authorization Services Guide 에서는 주요 접근제어모델과 정책 집행 포인트에 대해 제공하고있고,
이전 실습에서도 아주 잠깐 다룬적이 있다. ( 실습)

접근제어모델	설명
Attribute-based access control (ABAC)	사용자, 리소스, 환경의 속성을 기반으로 접근을 제어 예: 사용자의 부서, 직급, 위치 등의 속성을 기반으로 접근 권한 허용
Role-based access control (RBAC)	사용자에게 할당된 역할을 기반으로 접근을 제어 예: Realm Role에 매핑된 사용자만 접근 권한 허용
User-based access control (UBAC)	특정 사용자를 기반으로 접근을 제어 (개별 사용자 단위의 세밀한 권한 제어 가능) 예, user01에게만 접근 권한 허용
Context-based access control (CBAC)	요청의 컨텍스트(시간, 위치, 디바이스 등)를 기반으로 접근을 제어 예: 특정 IP 범위에서만 접근 허용
Rule-based access control:	JavaScript를 사용한 커스텀 규칙 정의 (복잡한 비즈니스 로직을 구현할 수 있음)
Time-based access control:	시간 기반의 접근 제어 (특정 시간대나 기간 동안만 접근 허용)
Custom ACMs through SPI:	Service Provider Interface를 통한 커스텀 접근 제어 메커니즘 구현 가능 (필요한 경우 자체 정책 타입을 개발하여 확장 가능)

정책 집행 포인트	설명
Policy Information Point (PIP/정책 정보)	정책 평가에 필요한 정보 제공 사용자 속성, 환경 정보 등 수집
Policy Administration Point (PAP/정책 관리)	정책을 생성, 관리, 저장하는 곳 Keycloak 관리 콘솔에서 정책 설정
Policy Decision Point (PDP/정책 결정)	접근 허용/거부 결정 정책과 속성 정보를 기반으로 판단
Policy Enforcement Point (PEP/정책 집행)	실제 접근 제어 실행 PDP의 결정을 강제

1. PAP (정책 관리) 엔드포인트
# 기본 URL
${keycloak_url}/admin/realms/${realm_name}/clients/${client_id}/authz/resource-server
# 정책 관리
GET    /policies                  # 정책 목록 조회
POST   /policies                  # 정책 생성
GET    /policies/{id}            # 특정 정책 조회
PUT    /policies/{id}            # 정책 업데이트
DELETE /policies/{id}            # 정책 삭제

2. PIP (정보 수집) 엔드포인트
# 사용자 정보
GET /admin/realms/${realm_name}/users/{id}
GET /admin/realms/${realm_name}/users/{id}/groups
GET /admin/realms/${realm_name}/users/{id}/role-mappings
# 리소스 정보
GET /authz/protection/resource_set
GET /authz/protection/resource_set/{id}

3. PDP (결정) 엔드포인트
# 권한 평가
POST /realms/${realm_name}/protocol/openid-connect/token
{
    "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
    "audience": "${client_id}",
    "permission": "${resource}#${scope}"
}
# 정책 평가
POST /realms/${realm_name}/clients/${client_id}/authz/resource-server/policy/evaluate

4. PEP (실행) 엔드포인트
# 토큰 검증
GET /realms/${realm_name}/protocol/openid-connect/userinfo
GET /realms/${realm_name}/protocol/openid-connect/token/introspect
# 권한 확인
POST /realms/${realm_name}/clients/${client_id}/authz/resource-server/permission/ticket

오늘은 KeyCloak에서의 접근제어 메커니즘 중 RBAC, ABAC에 대해 확인해보자.

RBAC (Role-Based Access Control)

개념 이해하기

Keycloak에서는 Role은 사용자 혹은 그룹에 매핑되어 사용된다. (공식문서 링크)
Role이란, 일반적으로 조직 또는 애플리케이션 컨텍스트에서 사용자가 가지는 역할을 말한다.
(e.g. administrator, system-manager, people-manager, audit-user, readonly-user ..)

Keycloak의 RBAC을 이해하기 위해서는 user, group의 개념도 함께 이해해야 한다.

User

Keycloak에서 인증과 인가의 주체이다.
직접적으로 Role을 할당받을 수 있으며(UBAC), Group의 멤버가 될 수 있다.
e.g. 사용자1(user01@test.com), 사용자2(user02@test.com)

Group

여러 User를 묶어서 관리하는 단위이며, Role을 할당받을 수 있다. (GBAC)
계층적 구조가 가능(하위 그룹 생성 가능)하여 여러 User를 한번에 관리 가능하다.
Role 관리 효율성 증가된다.

Role

keycloak에는 세 종류의 역할이 있다.

구분	설명
Realm Role [링크]	- 전역적(Global) 범위의 역할 - Realm 내의 모든 클라이언트 애플리케이션에서 공통으로 사용 - 일반적으로 조직 전체에 적용되는 광범위한 권한을 정의 ⚠️주의⚠️ 전역적으로 사용 가능하지만, 자동으로 모든 사용자에게 할당되지는 않음
Client Role [링크]	- 특정 클라이언트 애플리케이션에 한정된 역할 - 해당 애플리케이션에 특화된 세부적인 권한을 정의 - 다른 클라이언트와 독립적으로 관리
Default Role [링크]	- 새로운 사용자가 생성될 때 자동으로 할당되는 역할 - `default-roles-{realm-name}` Composite Role을 통해 관리 - Realm Role이나 Client Role을 Default Role로 설정 가능

Role들은 상호 베타적인 것이 아니며, 조합하여 계층적이고 세밀한 접근 제어가 가능해진다.
아래 시나리오에서 각 Role들을 함께 사용하는 예시를 확인해보자.

[Realm Role & Client Role 혼용 시나리오]

Realm Role (USER)
- 시스템 전반의 기본 접근 권한
- 모든 클라이언트 앱에서 유효
- "이 사용자가 앨범 서비스를 사용할 자격이 있는가?"

Client Role ({사용자ID}:all_access)
- 사용자 본인의 앨범에 대한 모든 권한
- 조회/수정/삭제 등 모든 기능 사용 가능
- "이 사용자가 본인의 앨범에 대한 모든 권한을 가지는가?"

이런식으로 사용자가 사진앱을 사용할수는 있지만, 모든 사진첩이 아닌 본인의 사진첩만 접근하여 수정할 수 있도록
두 권한을 조합하여 계층적으로 사용할 수 있다.

정리

Role은 단독으로 사용할 수 없고, 반드시 User혹은 Group에 매핑되어야 한다.
Keycloak에서는 RBAC, UBAC, GBAC 별개의 다른 개념이 아니라 같은 접근제어 메커니즘을 가지고 있다고 할 수 있다.
모든 종류의 Role은 Group이나 User에게 직접 할당 가능하다.
Group에 할당된 Role은 해당 Group의 모든 멤버가 상속받는다.
한 사용자는 여러 경로(Default, Group, 직접 할당)로 Role을 가질 수 있다.

실습) Role 사용 실습하기

RealmRole, User에 할당

Realm Role은 아래와 같이 설정하면 되며,
Client Role은 [Clients > 생성한 Client > Roles 탭 > Create role] 에서 생성할 수 있다.
이 실습에서는 Realm Role만 간략히 설명한다.

1. Realm Role을 생성한다.

2. 사용자에게 Realm Role을 할당한다.

3. 사용자에 연결된 Realm Role 확인

먼저 Users에 Realm Role이 잘 연결되었는지 점검한다.

터미널에서 호출할 예정이므로, Direct access grants를 허용해준다.

이후 아래 환경변수 부분을 내 환경에 맞춰 변경하고, 터미널에서 실행해보자.

# 1. keycloak 테스트서버 실행
docker run -p 8080:8080 \
          -e KEYCLOAK_ADMIN=admin \
          -e KEYCLOAK_ADMIN_PASSWORD=admin \
          quay.io/keycloak/keycloak \
          start-dev
          
# 2. 환경변수 설정
export ADMIN_USERNAME="admin"
export ADMIN_PASSWORD="admin"
export CLIENT_ID="admin-cli"
export REALM_NAME="my-realm"
export KEYCLOAK_URL="http://localhost:8080"
export KEYCLOAK_USERNAME=user01

# 3. 관리자 토큰 획득
export ADMIN_TOKEN=$(curl -X POST "${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=${CLIENT_ID}" \
-d "username=${ADMIN_USERNAME}" \
-d "password=${ADMIN_PASSWORD}" \
-d "grant_type=password" | jq -r '.access_token')

# 4. 사용자 ID 조회
export USER_ID=$(curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/users?username=${KEYCLOAK_USERNAME}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq -r '.[0].id')

# 5. Role 매핑 확인 (관리자 토큰 사용)
curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/users/${USER_ID}/role-mappings/realm" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq '.' --color-output

결과로 아래와 같이 새로 생성한 my-realm-role이 매핑된것을 확인할 수 있다.

ClientRole, Group에 할당

1. Client Role 생성
[client > 'my-client' > Roles > create role] 으로 새로운 Role (my-client-role)을 생성한다.

2. 그룹에 ClientRole을 매핑한다.

3. 그룹에 ClientRole 매핑된것 확인

# 1. 환경변수 설정
export ADMIN_USERNAME="admin"
export ADMIN_PASSWORD="admin"
export CLIENT_ID="my-client"
export REALM_NAME="my-realm"
export KEYCLOAK_URL="http://localhost:8080"
export KEYCLOAK_USERNAME="user01"
export KEYCLOAK_GROUPNAME="my-group"

# 2. 관리자 토큰 획득
export ADMIN_TOKEN=$(curl -X POST "${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=admin-cli" \
-d "username=${ADMIN_USERNAME}" \
-d "password=${ADMIN_PASSWORD}" \
-d "grant_type=password" | jq -r '.access_token')

# 3. 사용자 ID 조회
export USER_ID=$(curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/users?username=${KEYCLOAK_USERNAME}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq -r '.[0].id')

# 4. Client ID(UUID) 조회
export MY_CLIENT_ID=$(curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/clients?clientId=${CLIENT_ID}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq -r '.[0].id')

# 5. 사용자의 Client Role 매핑 확인 (직접 할당된 role)
echo "Direct Client Roles:"
curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/users/${USER_ID}/role-mappings/clients/${MY_CLIENT_ID}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq '.' --color-output

# 6. 사용자의 Effective Client Role 매핑 확인 (그룹에서 상속받은 role 포함)
echo -e "\nEffective Client Roles (including inherited from groups):"
curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/users/${USER_ID}/role-mappings/clients/${MY_CLIENT_ID}/composite" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq '.' --color-output

# 7. 그룹 ID 조회 및 Client Role 매핑 확인
export MY_GROUP_ID=$(curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/groups?search=${KEYCLOAK_GROUPNAME}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq -r '.[0].id')

echo -e "\nGroup Client Roles:"
curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/groups/${MY_GROUP_ID}/role-mappings/clients/${MY_CLIENT_ID}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq '.' --color-output

그룹에 연결된 ClientRole, 그리고 사용자에게 상속된 ClientRole도 위 명령어를 통해 확인할 수 있다.

ABAC (Attribute-Based Access Control)

개념 이해하기

Keycloak에서 ABAC(Attribute-Based Access Control)은 사용자, 리소스, 환경의 속성(Attribute)을 기반으로 접근을 제어하는 방식이며, Role기반의 접근제어보다 더 유연하고 세밀한 접근제어가 가능하다.

Attribute도 마찬가지로 기본적으로는 User와 Group에 할당하여 사용하며,
그 외에도 Organization, Client, Identity Provider 등 다양한 Keycloak 컴포넌트에 Attribute를 추가할 수 있다.
(core concepts and terms)

ABAC을 확인하기 전에 먼저 주요 개념부터 확인해보자.

Attribute

Keycloak에서 엔티티(User, Group 등)의 추가 정보를 저장하는 Key-Value 형태의 데이터를 말한다.
동적으로 추가/수정이 가능하며, 하나의 Key에 여러 Value를 가질 수 있으며,
ABAC(Attribute Based Access Control)에서 접근 제어 결정에 사용된다.
Group에서 User로 상속 가능 하다. (Group → User)
e.g. department: "HR", location: ["Seoul", "Busan"]

Protocol Mapper

Attribute를 Token Claim으로 변환하는 설정이다.
Keycloak의 JavaDoc 인터페이스 구현체 링크
Mapper 종류:
- User Property Mapper: 기본 사용자 속성 매핑
- User Attribute Mapper: 커스텀 사용자 속성 매핑
- Group Membership Mapper: 그룹 정보 매핑
- Role Mapper: 역할 정보 매핑

{
    "name": "department",     // Mapper의 이름 (관리자가 구분하기 위한 용도)
    "protocol": "openid-connect",     // 사용할 프로토콜 (보통 OpenID Connect 사용)
    "protocolMapper": "oidc-usermodel-attribute-mapper",// Mapper의 타입 (User Attribute를 매핑)
    "config": {                            // 실제 매핑 설정
        "user.attribute": "department",         // Keycloak에 저장된 속성 이름
        "claim.name": "department",        // 토큰에 포함될 때 사용할 이름
        "token.claim": "true"        // 토큰에 포함할지 여부
    }
}

Token Claim

토큰에 포함되는 정보의 한 조각으로, 사용자나 토큰 자체에 대한 statement를 말한다.
Protocol Mapper를 통해 Attribute를 Claim으로 변환하여 토큰에 포함시킬 수 있다.
클라이언트 애플리케이션에서 사용자 정보나 권한 확인에 사용한다.

{
    // 기본 Claims
    "sub": "user123",
    "iss": "http://keycloak.example.com",
    "exp": 1516239022,
    
    // User Attributes -> Claims
    "user_attributes": {
        "department": "HR",
        "location": ["Seoul"]
    },
    
    // Group Attributes -> Claims
    "group_attributes": {
        "costCenter": "HR001"
    }
}

Attribute와 Token Claim 관계

사용자나 그룹의 속성(attributes)은 protocol mapper설정을 통해 Token에 Claims 형태로 담겨 전달된다.
즉,Attribute는 Keycloak 내부 데이터이고, Claim은 이 데이터를 토큰을 통해 외부로 전달하는 방식이다.

실습) Attribute 사용방법

User Attribute 사용하기

먼저 사용자 속성(Attributes)를 설정해보자.

1. [realm settings > User profile > create attribute]를 클릭하고 department 속성을 만든다.

2. User Details에 새로 생긴 Department에 값을 입력한다.

3. 사용자에 Attribute가 제대로 설정 되었는지 확인한다.

# 1. 환경변수 설정
export ADMIN_USERNAME="admin"
export ADMIN_PASSWORD="admin"
export CLIENT_ID="my-client"
export REALM_NAME="my-realm"
export KEYCLOAK_URL="http://localhost:8080"
export USER_NAME="user01"

# 2. 관리자 토큰 획득
export ADMIN_TOKEN=$(curl -X POST "${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=admin-cli" \
-d "username=${ADMIN_USERNAME}" \
-d "password=${ADMIN_PASSWORD}" \
-d "grant_type=password" | jq -r '.access_token')

# 3. 사용자 ID 조회
export USER_ID=$(curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/users?username=${USER_NAME}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq -r '.[0].id')
echo $USER_ID

# 4. Client ID(UUID) 조회
export CLIENT_UUID=$(curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/clients?clientId=${CLIENT_ID}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" | jq -r '.[0].id')
echo $CLIENT_UUID

# 5. 현재 사용자 정보 조회
export USER_INFO=$(curl -X GET "${KEYCLOAK_URL}/admin/realms/${REALM_NAME}/users/${USER_ID}" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json")
echo $USER_INFO | jq

# 6. User Attribute 조회
echo "Current User Attributes:"
echo ${USER_INFO} | jq '.attributes' --color-output

user attribute에 department가 추가된것을 볼 수 있다.

4. Protocol Mapper를 설정한다.

5. 이제 AccessToken을 발급받고 Attribute가 포함되었는지 확인한다.

# 1. 환경변수 설정
export USER_NAME="user01"
export USER_PASSWORD="user01"
export CLIENT_ID="my-client"
export REALM_NAME="my-realm"
export KEYCLOAK_URL="http://localhost:8080"


# 1. 사용자 토큰 발급
export USER_TOKEN=$(curl -X POST "${KEYCLOAK_URL}/realms/${REALM_NAME}/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=${CLIENT_ID}" \
-d "username=${USER_NAME}" \
-d "password=${USER_PASSWORD}" \
-d "grant_type=password")

# 2. Access Token 추출
export ACCESS_TOKEN=$(echo $USER_TOKEN | jq -r '.access_token')

# 3. Access Token 디코딩 (JWT)
echo $ACCESS_TOKEN | cut -d"." -f2 | tr -d '-' | tr '_' '/' | sed -e 's/$/\=/' | base64 -d | jq '.' --color-output

protocol mapper까지 설정하고 나면 AccessToken에 Department가 추가되어 전달된다.

RBAC vs ABAC

실제로는 하나만 사용하는것이 아니라
기본적인 권한은 RBAC으로 관리하고, 특수한 상황은 ABAC으로 보완하는 형태로 두 방식을 혼합하여 사용하는 경우가 많다.

구분	RBAC	ABAC
설명	Role기반의 접근제어 { "user": "user01", "roles": ["admin"], "groups": ["/hr/manager"], "permissions": ["read", "write"] }	속성 기반의 접근제어 { "user": { "department": "HR", "level": "senior", "location": "Seoul", "clearance": "top-secret" }, "resource": { "type": "document", "classification": "confidential", "department": "HR" }, "action": "read", "environment": { "time": "09:00-18:00", "ip_range": "10.0.0.0/24" } }
특징	미리 정의된 역할/그룹에 기반 관리가 단순 변경이 적은 환경에 적합 확장성 제한적	다양한 속성 기반 결정 유연한 정책 설정 가능 상황에 따른 동적 접근 제어 복잡한 규칙 지원
예시	@RolesAllowed("admin") public void adminMethod() { // 관리자만 접근 가능 }	@Attribute("department == 'HR' && time.between('09:00', '18:00')") public void hrDocumentAccess() { // HR부서 직원이 업무시간 내 접근 }
시나리오	조직 구조가 명확한 기업 시스템 권한 체계가 단순한 웹 애플리케이션 사용자 그룹이 명확한 시스템	복잡한 보안 요구사항이 있는 시스템 시간/위치 기반 접근 제어 필요 다양한 조건에 따른 동적 권한 필요

주의사항

Role Explosion (역할 폭발) 문제를 주의해야한다. 역할은 세분화된 인가를 위한 역할 사용하는것을 지양하고, 조직 구조/직무를 반영하도록 하는것이 좋다. (ADMIN, READ_USER 등)

역할(Role)은 큰 범주로 정의한다. (admin, superuser, readonlyuser 혹은 department 등)
세부 접근제어는 속성(attributes)를 사용한다.

{
    "accessPolicy": {
        "role": "MANAGER",
        "requiredAttributes": {
            "department": ["HR", "IT"],
            "location": "Seoul",
            "timeWindow": "businessHours"
        }
    }
}

Role Explosion (역할 폭발) 문제란,
세부적인 부분까지 전부 Role로 정의하여 Role이 엄청 많아지는것

[keycloak 맛보기 #5] Keycloak의 애플리케이션 통합

mini_world — Tue, 17 Dec 2024 22:29:16 +0900

참고자료

책: https://www.yes24.com/Product/Goods/122459785
테스트 소스코드: https://github.com/PacktPublishing/Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition

통합 방식 설명

Keycloak과 애플리케이션을 통합할 때, Embedded와 Proxied 방식이 있다.
각 방법은 애플리케이션의 구조와 보안 요구 사항에 따라 선택할 수 있다.

구분	Embedded	Proxied
설명	애플리케이션 코드 내에서 Keycloak 어댑터를 직접 사용하여 인증 및 권한 부여를 처리한다.	역방향 프록시를 사용하여 Keycloak과의 통신을 처리하는 역방향 프록시를 설정하여 애플리케이션 앞단에서 인증을 처리한다. 애플리케이션 코드와 독립적으로 Keycloak과의 통합을 관리한다.
장점	애플리케이션 코드에서 인증 흐름을 직접 제어할 수 있다. 다양한 인증 및 권한 부여 시나리오를 구현할 수 있다.	애플리케이션 코드에서 인증 로직을 제거하여 코드가 단순해진다. 인증 및 권한 부여 로직이 프록시에서 처리되므로 보안이 강화된다.
단점	복잡성 증가: 애플리케이션 코드에 인증 로직이 포함되어 복잡성이 증가할 수 있다. 보안 위험: 클라이언트 측에서 직접 토큰을 관리할 경우 보안 위험이 증가할 수 있다.	프록시 설정이 복잡할 수 있으며, 추가적인 인프라가 필요할 수 있다. 프록시에서 제공하는 기능에 의존하게 되어, 특정 인증 시나리오를 구현하는 데 제한이 있을 수 있다.

두 방식 모두 상황에 따라 선택할 수 있고, 때로는 함께 사용할 수 있다.

Certified OpenID Connect Implementations 에서 인증된 라이브러리를 사용하는것이 좋다.

Javascript 애플리케이션 통합

실습 진행

실습을 위해 Keycloak을 준비한다.

docker run -p 8080:8080 \
          -e KEYCLOAK_ADMIN=admin \
          -e KEYCLOAK_ADMIN_PASSWORD=admin \
          quay.io/keycloak/keycloak \
          start-dev

http://localhost:8080/으로 접속하여 새로운 realm을 생성했다. (옵션/생략가능)

새로운 client를 생성한다.

client id: javascript
root URL: http://localhost:8000
valid redirect URIs: http://localhost:8000/*

새로운 사용자도 생성한다.

이제 테스트 코드를 준비한다.

# 테스트 코드 다운로드
git clone https://github.com/PacktPublishing/Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition.git
cd ch7/keycloak-js-adapter

realm과 client를 생성했으니, 코드도 수정해주자.

# ch7/keycloak-js-adapter/public/keycloak.json
{
  "realm": "myservice",
  "auth-server-url": "http://localhost:8080",
  "ssl-required": "external",
  "resource": "javascript",
  "public-client": true
}

# ch7/keycloak-js-adapter/app.js
import express from 'express';
import stringReplace from 'string-replace-middleware';

const app = express();
const port = 8000;

app.use(stringReplace({
  KC_URL: process.env.KC_URL || "http://localhost:8080"
}));

app.use('/', express.static('public'));

app.listen(port, () => {
  console.log(`Listening on port ${port}.`);
});

keycloak은 로컬의 8080포트에서 운영되며, 어플리케이션은 8000포트로 올라오게 된다.
이제 실행해보자.

# 경로 잘 들어와있는지 한번 더 확인
cd Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition/ch7/keycloak-js-adapter
# 시작
npm install
npm start

브라우저에서 http://localhost:8000 접속해보자.

접속하면 바로 keycloak으로 연결되며, 로그인 하면 페이지에 접근할 수 있게 된다.

설명

코드를 확인해보자.

javascript를 8000번 포트로 띄우기 위해 실행하는 이 app.js코드에서는
string-replace-middleware를 사용하여 애플리케이션의 정적 파일을 제공할 때, 파일 내의 KC_URL 변수에 Keycloak 주소를 담는다.

// ch7/keycloak-js-adapter/app.js
import express from 'express';
import stringReplace from 'string-replace-middleware';

const app = express();
const port = 8000;

// 환경 변수 KC_URL을 사용하여 Keycloak 서버의 URL을 설정한다.
app.use(stringReplace({
  KC_URL: process.env.KC_URL || "http://localhost:8080"
}));

app.use('/', express.static('public'));

app.listen(port, () => {
  console.log(`Listening on port ${port}.`);
});

keycloak.json Keycloak 클라이언트 설정을 포함하고 있으며, Keycloak 라이브러리가 초기화될 때 해당 설정을 사용한다.
(Keycloak JavaScript 어댑터 라이브러리가 자동으로 로드함)

작동 방식은 아래와 같다.

Keycloak 초기화: index.html에서 Keycloak() 객체를 생성하고 init 메서드를 호출할 때, 라이브러리는 기본적으로 keycloak.json 파일을 찾는다.
설정 로드: keycloak.json 파일이 public 디렉토리에 위치해 있으면, Keycloak 라이브러리가 이 파일을 자동으로 로드하여 필요한 설정을 적용한다.

# ch7/keycloak-js-adapter/public/keycloak.json
{
  "realm": "myservice",
  "auth-server-url": "http://localhost:8080",
  "ssl-required": "external",
  "resource": "javascript",
  "public-client": true
}

index.html은 Keycloak을 사용하여 사용자 인증을 처리하는 웹 페이지다. 코드는 길어서 설명만 추가했다.

<script src="KC_URL/js/keycloak.js"></script>

이 부분에서 KC_URL은 app.js에서 설정된 Keycloak 서버의 URL로 대체된다.
이 과정은 Keycloak 초기화의 일부로, Keycloak() 객체를 생성하고 init 메서드를 호출하여 Keycloak을 초기화한다.
이때 keycloak.json 파일이 자동으로 로드되며, Keycloak JavaScript 어댑터 라이브러리가 로드되어 클라이언트 측에서 Keycloak과의 통신을 처리할 수 있게 된다.

<!-- 생략 -->
      document.getElementById("logout").addEventListener("click", () => {
        keycloak.logout();
      });

      document.getElementById("showIdToken").addEventListener("click", () => {
        output(keycloak.idTokenParsed);
      });

      document
        .getElementById("showAccessToken")
        .addEventListener("click", () => {
          output(keycloak.tokenParsed);
        });

      document
        .getElementById("refreshToken")
        .addEventListener("click", async () => {
          await keycloak.updateToken(-1);
          output(keycloak.idTokenParsed);
          showProfile();
        });

      document
        .getElementById("showMyAccount")
        .addEventListener("click", async () => {
          await keycloak.accountManagement()
        });
<!-- 생략 -->

또한 코드내 버튼을 통해 클릭 이벤트 리스너를 추가하여 Keycloak의 기능을 수행할 수 있도록 했다.

로그아웃: keycloak.logout()을 호출하여 사용자를 로그아웃한다.
토큰 표시: keycloak.idTokenParsed)을 통해 토큰과 액세스 토큰을 JSON 형식으로 출력한다.
토큰 갱신: keycloak.updateToken()을 호출하여 토큰을 갱신한다.
계정 관리: keycloak.accountManagement()를 호출하여 사용자의 계정 관리 페이지로 이동한다.

Nodejs 애플리케이션 통합 (frontend)

실습 진행

실습을 진행해보자.
위 단계에서 keycloak을 도커로 띄우고 realm을 생성했으니 해당 단계는 건너뛰고 바로 client부터 생성한다.

client id: nodejs
root URL: http://localhost:8000
client authentication: on

보안 client이므로, Credentials 탭에서 Secret을 복사해둔다.

이제 코드를 준비한다.

# 테스트 코드 다운로드
git clone https://github.com/PacktPublishing/Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition.git
cd ch7/nodejs/frontend

keycloak 설정에 맞게 코드를 수정한다.
위에서 복제한 client secret으로 값을 변경하고, 8000포트에서 애플리케이션이 시작될 수 있도록 코드를 수정한다.

// ch7/nodejs/frontend/app.js
var express = require('express');
var session = require('express-session');
var Keycloak = require('keycloak-connect');
var cors = require('cors');

var app = express();

app.use(cors());

var memoryStore = new session.MemoryStore();

app.use(session({
    secret: 'io9bBSukiwEyUekE62g88aeI4CKYUBTi', // 위에서 복사한 client secret 입력
    resave: false,
    saveUninitialized: true,
    store: memoryStore
}));

var keycloak = new Keycloak({ store: memoryStore });

app.use(keycloak.middleware());

app.get('/', keycloak.protect(), function (req, res) {
    res.setHeader('content-type', 'text/plain');
    res.send('Welcome!');
});

app.listen(8000, function () {         // 애플리케이션 포트 8000으로 수정
    console.log('Started at port 8000'); 
});

# ch7/nodejs/frontend/keycloak.json
{
  "realm": "myservice", 
  "auth-server-url": "${env.KC_URL:http://localhost:8080}",
  "resource": "nodejs",
  "credentials" : {
    "secret" : "io9bBSukiwEyUekE62g88aeI4CKYUBTi"
  }
}

이제 실행해보자

# 경로 잘 들어와있는지 한번 더 확인
cd Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition/ch7/nodejs/frontend
# 시작
npm install
npm start

로컬 브라우저에서 http://localhost:8000을 접속하면 아래와 같은 결과가 나온다.

설명

먼저 keycloak.json 은 Keycloak 클라이언트 설정을 포함한다.

위 javascript 실습에서도 keycloak.json파일이 사용되었는데 이는 javascript환경에서 주로 사용되는 표준으로,
다른 언어에서는 XML등의 형식으로 사용할 수 도있다. (어뎁터에 따라 다름)

app.js 파일 내 모듈이 초기화될 때(var keycloak = new Keycloak({ store: memoryStore });)
해당 설정을 사용하여 Keycloak 서버와의 통신을 설정한다.

# ch7/nodejs/frontend/keycloak.json
{
  "realm": "myservice",
  "auth-server-url": "${env.KC_URL:http://localhost:8080}",
  "resource": "nodejs",
  "credentials" : {
    "secret" : "io9bBSukiwEyUekE62g88aeI4CKYUBTi"
  }
}

app.js에서는 keycloak모듈을 불러오고 초기화 한다.

keycloak.json 그리고 app.js 두 곳에서 client secret이 모두 사용되었는데, 목적이 다르다.

[app.js] Express 세션의 secret:
- Express의 세션 미들웨어는 사용자 세션을 관리하기 위해 사용된다.
- app.js에 사용된 secret은 세션 ID 쿠키를 서명하는 데 사용되어, 클라이언트와 서버 간의 세션 데이터가 변조되지 않도록 보호한다.
[keycloak.json] Keycloak의 secret:
- Keycloak의 secret은 클라이언트 인증을 위해 사용된다.
- Keycloak 서버와 애플리케이션 간의 안전한 통신을 보장하기 위해 사용되며, keycloak.json 파일에 저장된다.
- Keycloak이 클라이언트를 식별하고 인증하는 데 필요하다.

var memoryStore = new session.MemoryStore(); 부분은 세션데이터를 로컬 메모리에 저장하겠다는 설정이며,
메모리 스토어는 일반적으로 개발환경에서만 사용된다. (서버가 재시작되면 세션데이터 모두 지워짐)
따라서 보통은 별도의 데이터베이스(Mongodb, rdb, redis) 등을 활용하여 세션을 관리한다.

var express = require('express');
var session = require('express-session');
// Keycloak 모듈 불러오기
// 이 모듈은 Node.js 애플리케이션에서 Keycloak과의 통합을 지원함
var Keycloak = require('keycloak-connect');
var cors = require('cors');

var app = express();

app.use(cors());

// 메모리스토어 설정
// 세션 데이터를 저장하기 위해 메모리 스토어를 생성
var memoryStore = new session.MemoryStore();

app.use(session({
    secret: 'io9bBSukiwEyUekE62g88aeI4CKYUBTi',
    resave: false,
    saveUninitialized: true,
    store: memoryStore
}));

// Keycloak 인스턴스 생성
// Keycloak 인스턴스를 생성하고, 세션 스토어를 전달한다. 
// 이 인스턴스는 Keycloak과의 상호작용을 관리한다.
var keycloak = new Keycloak({ store: memoryStore });

// Keycloak 미들웨어 사용
// Keycloak 미들웨어를 Express 애플리케이션에 추가한다.
// 이 미들웨어는 요청을 가로채고, 인증 및 권한 부여를 처리한다.
app.use(keycloak.middleware());

// Keycloak으로 보호할 경로 설정
// keycloak.protect()를 사용하여 특정 경로를 보호한다. 
// 이 경로에 접근하려면 사용자가 인증되어야 합니다.
app.get('/', keycloak.protect(), function (req, res) {
    res.setHeader('content-type', 'text/plain');
    res.send('Welcome!');
});

app.listen(8000, function () {
    console.log('Started at port 8000');
});

Nodejs 애플리케이션 통합 ( backend)

실습 진행

실습을 진행해보자. 위에서 생성한 client를 재활용한다.

client id: nodejs
root URL: http://localhost:8000
client authentication: on

코드를 준비한다.

# 테스트 코드 다운로드
git clone https://github.com/PacktPublishing/Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition.git
cd ch7/nodejs/backend

keycloak 설정에 맞게 코드를 수정한다.
위에서 복제한 client secret으로 값을 변경하고, 8001포트에서 애플리케이션이 시작될 수 있도록 코드를 수정한다.

// ch7/nodejs/backend/app.js
var express = require('express');
var Keycloak = require('keycloak-connect');

var app = express();

var keycloak = new Keycloak({});

app.use(keycloak.middleware());

app.get('/hello', keycloak.protect(), function (req, res) {
  res.setHeader('content-type', 'text/plain');
  res.send('Access granted to protected resource');
});

app.listen(8001, function () {
  console.log('Started at port 8001');
});

# ch7/nodejs/backend/keycloak.json
{
  "realm": "myservice",
  "bearer-only": true,
  "auth-server-url": "${env.KC_URL:http://localhost:8080}",
  "resource": "nodejs"
}

이제 실행해보자.

# 경로 잘 들어와있는지 한번 더 확인
cd Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition/ch7/nodejs/backend
# 시작
npm install
npm start

로컬 브라우저에서 http://localhost:8001에 접속하면 아래처럼 Cannot GET / 오류가 발생한다.

그 이유는 AccessToken이 없기때문이다.
CLI로 AccessToken을 가져와보자.

# curl -X POST http://localhost:8080/realms/myservice/protocol/openid-connect/token \
#	 -u "nodejs:io9bBSukiwEyUekE62g88aeI4CKYUBTi" \
#	 -H "Content-Type: application/x-www-form-urlencoded" \
#	 -d "username=test01" -d "password=1234"  \
#	 -d "grant_type=password" | jq -r '.access_token'

curl -X POST http://localhost:8080/realms/${realm}/protocol/openid-connect/token \
    -u "${client_id}:${client_secret}" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "username=${user_name}" -d "password=${user_password}" \
    -d "grant_type=password" | jq -r '.access_token'

결과로 Access Token을 얻었다. (참고: 브라우저를 통하지 않고 사용자ID/PW를 이용하여 접근토큰을 받으려면 Direct access grants이 허용되어있어야 하며, keycloak은 기본값이 허용이다.)

이제 이 Access Token을 가지고 Backend 서버에 접근해보자.

# 예시, 각 변수 올바르게 설정 필요
# export access_token=$(curl -X POST http://localhost:8080/realms/myservice/protocol/openid-connect/token \
# -u "nodejs:io9bBSukiwEyUekE62g88aeI4CKYUBTi" \
# -H "Content-Type: application/x-www-form-urlencoded" \
# -d "username=test01" -d "password=1234"  \
# -d "grant_type=password" | jq -r '.access_token')

export access_token=$(curl -X POST http://localhost:8080/realms/${realm}/protocol/openid-connect/token \
-u "${client_id}:${client_secret}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=${user_name}" -d "password=${user_password}" \
-d "grant_type=password" | jq -r '.access_token')

echo $access_token

curl -v GET http://localhost:8001/hello \
-H "Authorization: Bearer "$access_token

그럼 아래와 같은 결과가 나온다.

만약 AccessToken 없이 요청한다면 실패하게 된다.

설명

여기에서 실습한 nodejs/backend 는 Keycloak을 사용해서 사용자를 인증하는것이 아닌,
AccessToken을 활용하여 인증된 요청을 처리하는 리소스 서버로서의 역할을 한다.

// ch7/nodejs/backend/app.js
var express = require('express');
var Keycloak = require('keycloak-connect');

var app = express();

var keycloak = new Keycloak({});

// keycloak 미들웨어 사용
app.use(keycloak.middleware());

// 보호된 리소스에 요청이오면 Keycloak 서버에 해당 토큰의 유효성을 검증
app.get('/hello', keycloak.protect(), function (req, res) {
  res.setHeader('content-type', 'text/plain');
  res.send('Access granted to protected resource');
});

app.listen(8001, function () {
  console.log('Started at port 8001');
});

keycloak.protect()를 사용하여 특정 경로에 대한 접근을 보호하며, 작동방식은 아래와 같다.

AccessToken 수신: 클라이언트가 요청을 보낼 때, Authorization 헤더에 AccessToken을 포함한다.
토큰 검증: keycloak.protect() 미들웨어가 요청을 가로채고, Keycloak 서버에 해당 토큰의 유효성을 검증한다.
인증 처리: 토큰이 유효하면 요청을 처리하고, 그렇지 않으면 접근이 거부된다.