Keycloak 완벽 가이드: 오픈소스 Identity and Access Management

개요

이 가이드에서는 오픈소스 IAM(Identity and Access Management) 솔루션인 Keycloak의 핵심 개념, 아키텍처, 그리고 실제 구현 방법을 알아봅니다. Keycloak을 사용하면 애플리케이션에 인증과 권한 관리 기능을 최소한의 코드로 추가할 수 있으며, Single Sign-On(SSO), 소셜 로그인, 2단계 인증 등 다양한 보안 기능을 쉽게 구현할 수 있습니다.

이 문서를 읽으면:

• Keycloak이 무엇이고 왜 사용해야 하는지 이해할 수 있습니다
• Realm, Client, User, Role 등 핵심 개념을 파악할 수 있습니다
• Docker를 사용해 Keycloak을 설치하고 설정할 수 있습니다
• Spring Boot와 React 애플리케이션에 Keycloak을 통합할 수 있습니다
• 실제 프로덕션 환경에서 고려해야 할 사항을 이해할 수 있습니다

대상 독자: 인증/권한 관리 시스템 구축이 필요한 백엔드/프론트엔드 개발자

예상 소요 시간: 30-45분

Keycloak이란?

정의

Keycloak은 현대적인 애플리케이션과 서비스를 위한 오픈소스 Identity and Access Management(IAM) 솔루션입니다. 사용자 인증, 권한 관리, Single Sign-On 등의 복잡한 보안 기능을 애플리케이션에 최소한의 코드로 추가할 수 있도록 해줍니다.

역사와 배경

• 최초 릴리스: 2014년 9월 (개발 시작은 2013년)
• 원 개발사: Red Hat (WildFly 커뮤니티 프로젝트)
• 현재 관리: 2023년 4월 CNCF(Cloud Native Computing Foundation)에 기부되어 incubating 프로젝트로 운영 중
• 최신 버전: 26.4.7 (2025년 12월 기준)
• 상용 지원: Red Hat이 “Red Hat build of Keycloak”이라는 이름으로 상용 지원 제공

왜 Keycloak을 사용해야 하는가?

기존 방식의 문제점:

대부분의 애플리케이션은 자체적으로 사용자 인증 시스템을 구현합니다. 이는 다음과 같은 문제를 야기합니다:

// 전통적인 자체 인증 구현 예시
// ❌ 반복적이고 오류가 발생하기 쉬움
app.post('/login', async (req, res) => {
  const user = await User.findOne({ username: req.body.username });
  if (!user) return res.status(401).send('Invalid credentials');
 
  const isValid = await bcrypt.compare(req.body.password, user.passwordHash);
  if (!isValid) return res.status(401).send('Invalid credentials');
 
  const token = jwt.sign({ userId: user.id }, SECRET_KEY);
  res.json({ token });
});

문제점:

• 비밀번호 저장, 해싱, 솔팅 등을 직접 구현해야 함
• 2단계 인증(2FA), 소셜 로그인 등 고급 기능 구현이 복잡함
• 보안 취약점에 대한 지속적인 모니터링과 패치 필요
• 여러 애플리케이션 간 SSO 구현이 어려움
• LDAP, Active Directory 연동이 복잡함

Keycloak을 사용하면:

// ✅ Keycloak 사용 시 - 인증 로직이 대폭 단순화됨
app.get('/protected', keycloak.protect(), (req, res) => {
  // Keycloak이 자동으로 토큰 검증
  res.json({
    message: 'Protected resource',
    user: req.kauth.grant.access_token.content
  });
});

해결되는 문제:

• 표준 프로토콜(OAuth 2.0, OpenID Connect, SAML) 지원
• 즉시 사용 가능한 관리자 콘솔
• 소셜 로그인(Google, GitHub, Facebook 등) 기본 제공
• 사용자 페더레이션(LDAP, Active Directory) 내장
• 2단계 인증, Passkeys 등 최신 보안 기능 지원
• 다중 언어 지원(35개 언어)

지원하는 프로토콜

Keycloak은 업계 표준 프로토콜을 지원합니다:

1. OpenID Connect (OIDC): OAuth 2.0 기반의 인증 레이어
2. OAuth 2.0: 권한 부여 프레임워크
3. SAML 2.0: XML 기반의 인증 및 권한 부여 표준

핵심 개념

Keycloak을 효과적으로 사용하려면 다음 4가지 핵심 개념을 이해해야 합니다.

1. Realm (렘)

정의: Realm은 사용자, 자격 증명, 역할, 그룹을 관리하는 격리된 관리 단위입니다.

비유: Realm은 아파트 단지와 같습니다. 각 단지(Realm)는 독립적으로 운영되며, 자체 주민(사용자), 보안 규칙(정책), 출입 카드(토큰)를 가집니다.

특징:

• 각 Realm은 완전히 격리되어 있어 서로의 사용자를 관리할 수 없음
• 하나의 Keycloak 인스턴스에서 여러 Realm을 관리 가능
• 사용자는 특정 Realm에 속하며, 해당 Realm에만 로그인 가능

일반적인 사용 사례:

회사 구조 예시:
├── master (Keycloak 관리용 - 절대 사용자 관리용으로 사용 금지)
├── company-dev (개발 환경)
├── company-staging (스테이징 환경)
└── company-prod (프로덕션 환경)

2. Client (클라이언트)

정의: Client는 Keycloak에 인증을 요청하는 애플리케이션 또는 서비스입니다.

Client 타입:

3. User (사용자)

정의: User는 Realm에 속한 개인 또는 엔티티로, 인증 정보와 속성을 가집니다.

주요 속성:

• 기본 정보: Username, Email, First Name, Last Name
• 자격 증명: Password, OTP, Passkeys
• 속성: 커스텀 사용자 정보 (부서, 직급, 전화번호 등)
• 그룹 멤버십: 사용자가 속한 그룹
• 역할 매핑: 사용자에게 할당된 역할

4. Role (역할)

정의: Role은 사용자나 그룹에 할당할 수 있는 권한의 타입을 정의합니다.

역할의 두 가지 레벨:

Realm Roles (렘 역할)

Realm 전체에서 사용 가능한 글로벌 역할입니다.

예시:
- admin: 전체 시스템 관리자
- user: 일반 사용자
- manager: 중간 관리자

Client Roles (클라이언트 역할)

특정 Client(애플리케이션)에만 적용되는 역할입니다.

예시: "inventory-app" 클라이언트의 역할
- inventory:view: 재고 조회 권한
- inventory:edit: 재고 수정 권한
- inventory:delete: 재고 삭제 권한

5. Group (그룹)

정의: Group은 공통 속성과 역할 매핑을 가진 사용자의 집합입니다.

그룹 사용 예시:

회사 조직도를 그룹으로 표현:
├── Engineering
│   ├── Backend
│   └── Frontend
├── Sales
│   ├── Korea
│   └── US
└── Marketing

주요 기능

1. Single Sign-On (SSO)

설명: 한 번의 로그인으로 여러 애플리케이션에 접근할 수 있는 기능입니다.

시나리오:

사용자가 App A에 로그인
→ Keycloak 세션 생성
→ App B 접속 시 자동 로그인
→ App C 접속 시 자동 로그인

2. Social Login (소셜 로그인)

Keycloak은 주요 소셜 ID 제공자와의 통합을 기본으로 제공합니다.

지원 제공자:

• Google, GitHub, Facebook, Instagram
• LinkedIn, Microsoft (Azure AD), Twitter
• 기타 OpenID Connect / OAuth 2.0 제공자

3. User Federation (사용자 페더레이션)

기존 사용자 데이터베이스(LDAP, Active Directory)를 Keycloak과 연동할 수 있습니다.

지원 스토리지:

• LDAP, Active Directory, Kerberos
• 커스텀 User Storage SPI

4. 다단계 인증 (Multi-Factor Authentication)

지원 방식:

• OTP (One-Time Password) - Google Authenticator, FreeOTP 등
• SMS 인증, 이메일 인증
• Passkeys (WebAuthn) - 지문, 얼굴 인식, 보안 키

설치 및 설정

Docker로 빠른 시작

가장 빠르고 쉬운 방법은 Docker를 사용하는 것입니다.

Step 1: Docker 이미지 실행

# 개발 모드로 Keycloak 시작
docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.4.7 \
  start-dev

Step 2: Admin Console 접속

1. 브라우저에서 http://localhost:8080 접속
2. “Administration Console” 클릭
3. Username: admin, Password: admin 입력하여 로그인

Docker Compose로 프로덕션 수준 설정

실제 환경에 가까운 설정을 위해 PostgreSQL과 함께 실행하세요.

docker-compose.yml:

version: '3.8'
 
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak_network
 
  keycloak:
    image: quay.io/keycloak/keycloak:26.4.7
    command: start
    environment:
      KC_HOSTNAME: localhost
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: password
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - 8080:8080
    depends_on:
      - postgres
    networks:
      - keycloak_network
 
volumes:
  postgres_data:
 
networks:
  keycloak_network:

프레임워크 통합

React + Keycloak

Step 1: 패키지 설치

npm install keycloak-js

Step 2: Keycloak 초기화

// src/keycloak.js
import Keycloak from 'keycloak-js';
 
const keycloak = new Keycloak({
  url: 'http://localhost:8080',
  realm: 'company-portal',
  clientId: 'portal-frontend'
});
 
export default keycloak;

Step 3: React 앱에 통합

// src/index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import keycloak from './keycloak';
 
const root = ReactDOM.createRoot(document.getElementById('root'));
 
keycloak.init({
  onLoad: 'login-required'
}).then(authenticated => {
  if (authenticated) {
    root.render(
      <React.StrictMode>
        <App keycloak={keycloak} />
      </React.StrictMode>
    );
  }
});

Spring Boot + Keycloak

Step 1: 의존성 추가

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
    </dependency>
</dependencies>

Step 2: application.yml 설정

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8080/realms/company-portal

장점과 한계

✅ 장점

1. 오픈소스 & 무료: 완전한 기능을 무료로 사용 가능
2. 표준 프로토콜 지원: OAuth 2.0, OpenID Connect, SAML 2.0
3. 기능 완성도: SSO, 소셜 로그인, 2FA, Passkeys 등 모든 주요 기능 내장
4. 확장성: 수평 확장 가능 (클러스터링)
5. 개발자 친화적: 훌륭한 Admin Console과 REST API

⚠️ 한계

1. 리소스 요구사항: 메모리 사용량이 큼 (최소 512MB, 권장 1-2GB)
2. 학습 곡선: OAuth 2.0/OIDC 개념 이해 필요
3. UI 커스터마이징 제약: 로그인 페이지 커스터마이징이 제한적
4. 버전 업그레이드: Major 버전 간 Breaking Changes 존재

비교: Keycloak vs 경쟁 제품

다음 단계

Keycloak의 기본 개념과 사용법을 익혔다면, 다음 주제들을 학습해보세요:

고급 주제

1. Custom User Storage SPI: 자체 사용자 데이터베이스와 통합
2. Custom Themes: 로그인 페이지 브랜딩
3. Event Listeners: 사용자 이벤트 모니터링
4. Policy Enforcer: 세밀한 권한 관리 (UMA 2.0)

추천 학습 자료

공식 문서:

• Keycloak Documentation 
• Server Administration Guide 
• Securing Applications Guide 

커뮤니티:

• Keycloak GitHub 
• Keycloak Discourse 

문서 버전: 1.0.0 최종 업데이트: 2025년 1월 6일 대상 Keycloak 버전: 26.x