🧭 Keycloak 기반 엔터프라이즈 인증 구조 & 실전 구성

OAuth2와 OpenID Connect를 실무 수준에서 구현하는 가장 현실적인 접근

---

📘 들어가며 — 왜 OAuth2만으로는 부족한가

JWT를 기반으로 한 Stateless 인증은 강력하지만,

기업 환경(Enterprise)에서는 다음과 같은 현실적인 한계가 있다.

문제	설명
중앙집중형 인증 부재	각 서비스가 직접 로그인·토큰 발급 로직을 구현해야 함
조직 내 다중 애플리케이션 관리 어려움	여러 프로젝트 간 계정, 권한, 역할을 통합 관리하기 어렵다
보안 규정 준수 문제	OAuth2만으로는 SSO, MFA, LDAP, SAML 같은 기업 요구 대응이 제한적
운영 효율성 저하	사용자·권한 변경 시 모든 서비스 배포 필요

➡️ 이 문제를 해결하기 위해 등장한 것이 Keycloak이다.

---

#1. Keycloak 이란 무엇인가?

Keycloak은 Red Hat이 주도하는 오픈소스 인증·인가 서버이다.

OAuth2, OpenID Connect(OIDC), SAML 2.0, LDAP 연동, SSO까지 완비된

Identity and Access Management (IAM) 솔루션이다.

항목	설명
기반 프로토콜	OAuth2, OpenID Connect, SAML
주요 기능	로그인/로그아웃, 사용자 등록, 비밀번호 정책, MFA, 세션 관리
연동 방식	REST API / OIDC Discovery / JWT Token
배포 방법	Docker, Kubernetes, Standalone JAR, Operator
Spring 연동 방식	spring-boot-starter-oauth2-resource-server 또는 spring-boot-starter-oauth2-client

---

#2. Keycloak 구조 한눈에 보기

요약

• Realm: 하나의 인증 영역 (회사 / 서비스 단위)
• Client: OAuth2 클라이언트 (Angular, Spring Boot 등)
• User: Keycloak 내 사용자
• Role: 역할 기반 권한 설정
• Flow: OAuth2 Authorization Code + PKCE

---

#3. Docker로 Keycloak 설치

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

접속

http://localhost:8080

• Username: admin
• Password: admin

---

#4. Realm, Client, User 구성

1️⃣ Realm 생성

• Add Realm → eazybank

2️⃣ Client 등록

• Client ID: eazybank-client
• Protocol: openid-connect
• Access Type: public
• Redirect URI: http://localhost:4200/*
• Valid Redirect URIs → Angular 앱 주소

3️⃣ User 생성

• Username: happy@example.com
• Password: password
• Role Mapping: ROLE_USER

4️⃣ Role 생성

• ROLE_USER, ROLE_ADMIN 등

---

#5. OAuth2 Grant Type 복습

Grant Type	설명	대표 사용처
Authorization Code	브라우저 기반 인증 (PKCE 포함)	웹/모바일 클라이언트
Client Credentials	서버 간 통신	백엔드 마이크로서비스
Password	Deprecated (직접 자격증명 전달)	테스트용만
Refresh Token	Access Token 재발급	장기 세션 관리

---

#6. Authorization Code + PKCE Flow

보안 강화를 위해 클라이언트는 PKCE(Proof Key for Code Exchange) 를 사용한다.

---

#7. Access Token vs ID Token

구분	목적	포함 정보	사용 위치
Access Token	리소스 접근 인증	권한, Scope, 만료시간	Resource Server
ID Token	사용자 식별	사용자 이름, 이메일, 인증 정보	클라이언트 측 (UI)
Refresh Token	토큰 갱신	만료시간, 세션 식별자	Authorization Server

---

#8. Spring Boot Resource Server 설정

application.yml 예시:

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

SecurityConfig.java:

@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/public/**").permitAll()
            .anyRequest().authenticated())
        .oauth2ResourceServer(oauth2 -> oauth2.jwt());
    return http.build();
}

---

#9. Postman으로 검증

1. Authorization 탭 → Type: OAuth2

2. Token URL:

   http://localhost:8080/realms/eazybank/protocol/openid-connect/token
   

3. Client ID: eazybank-client

4. Grant Type: Authorization Code

5. Scope: openid profile email

6. Callback URL: http://localhost:4200/

토큰 발급 성공 시 다음 필드 확인:

{
  "access_token": "...",
  "id_token": "...",
  "refresh_token": "...",
  "expires_in": 300
}

---

#10. Angular 클라이언트 연동 핵심 포인트

• angular-oauth2-oidc 라이브러리 사용
• 설정 파일 예시:

import { AuthConfig } from 'angular-oauth2-oidc';

export const authConfig: AuthConfig = {
  issuer: 'http://localhost:8080/realms/eazybank',
  redirectUri: window.location.origin,
  clientId: 'eazybank-client',
  scope: 'openid profile email',
  responseType: 'code',
  showDebugInformation: true,
  usePkce: true
};

---

#11. Keycloak 연동 후 전체 아키텍처

구성요소	설명
Angular	클라이언트 (Auth Code Flow 수행)
Keycloak	인증·인가 서버 (Token 발급)
Spring Boot	Resource Server (JWT 검증)

---

#12. Keycloak vs 다른 인증 서비스 비교

비교 항목	Keycloak	Okta	AWS Cognito
오픈소스 여부	✅ 완전 오픈소스	❌ 유료 SaaS	✅ 제한적
자체 호스팅	✅ 가능	❌ 불가	✅ 가능
지원 프로토콜	OAuth2, OIDC, SAML	OAuth2, OIDC	OAuth2, OIDC
확장성	높음 (Plugin, SPI)	중간	낮음
통합 관리	Realm 단위 관리	조직 단위 관리	User Pool 단위 관리

---

#13. 보안 운영 팁 (실무 기준)

영역	모범 사례
Secret 관리	.env or Vault, 절대 코드에 포함하지 않기
SSL/TLS	Keycloak 및 API 모두 HTTPS 필수
Token 수명	Access 5~15분 / Refresh 30분 이하
Role/Scope 전략	API별 최소 권한 설계 (RBAC 원칙)
Monitoring	Keycloak Admin Console + Grafana + Loki 연동
Backup	Realm Export JSON 주기적 백업

---

#14. Keycloak의 위치 — OAuth2 진화 구조 요약

Keycloak은 단순한 “보안 서버”가 아니라,

OAuth2와 OIDC를 통합 관리 가능한 플랫폼으로 진화시킨 결과물이다.

---

#15. 결론 — Keycloak이 주는 엔터프라이즈 이점

✅ Single Sign-On (SSO)

✅ Centralized Role Management

✅ OAuth2 / OIDC / SAML 통합 지원

✅ LDAP / AD 연동

✅ API Gateway와 연동 용이 (Kong, Nginx, Istio)

✅ MFA / OTP / Social Login 통합

Keycloak을 통해 우리는 “각 마이크로서비스가 직접 인증을 처리하는 구조”에서 “하나의 중앙 인증 허브를 두는 구조”로 발전할 수 있다.