# Keycloak 이란?

Keycloak은 오픈소스 기반의 **IDaaS(Identity as a Service)** 솔루션이자 **IAM(Identity and Access Management)** 플랫폼으로, 사용자의 인증과 인가, 권한 관리를 중앙화된 방식으로 처리해준다. 일반적으로 기업 환경이나 마이크로서비스 아키텍처에서 **Single Sign-On(SSO)**, **사용자 계정 관리**, **OAuth 2.0** 및 **OpenID Connect(OIDC)** 등 표준 프로토콜 지원을 목적으로 사용된다.

Keycloak은 **Red Hat**이 주도하여 발전시켜 온 프로젝트로, 설치와 설정이 상대적으로 간단하며 유연한 확장성을 제공한다. 또한 자체적으로 **디렉터리(Directory) 서비스** 또는 **외부 사용자 저장소**와 연동할 수 있고, 소셜 로그인(구글, 페이스북, 깃허브 등)도 쉽게 통합할 수 있다.

#### 주요 특징

**통합 인증과 접근 제어**

* Keycloak은 중앙 집중형 인증 서버로 동작하며, RESTful API 혹은 웹 콘솔을 통해 손쉽게 사용자를 등록 및 관리할 수 있다.
* SSO를 제공하여 한 번 로그인하면 여러 애플리케이션에 중복 로그인 없이 접근할 수 있도록 지원한다.

**표준 보안 프로토콜 지원**

* **OAuth 2.0**, **OpenID Connect**, **SAML 2.0** 프로토콜을 지원한다.
* 토큰 기반의 세션 관리를 통해 확장성 있는 인증·인가 메커니즘을 제공한다.
* 암호화 연산(예: HMAC, RSA 서명)으로 토큰 무결성과 신뢰성을 보장한다.

예를 들어, 토큰 서명을 HMAC 알고리즘으로 나타내면 아래와 같이 표현할 수 있다:

$$
\begin{align} \mathrm{Signature} = \mathrm{HMAC}\_{\mathbf{k}}(m) \end{align}
$$

**유연한 사용자 저장소 연동**

* 내부 DB(H2, PostgreSQL, MySQL 등)를 사용자 저장소로 사용할 수 있다.
* LDAP, Active Directory 등 외부 디렉터리 서비스와도 손쉽게 연동이 가능하다.

**확장성과 커스터마이징**

* 스펙 확장, UI 테마 변경, 커스텀 스크립트 등을 통해 다양한 요구 사항을 충족할 수 있다.
* **Identity Broker** 기능을 이용하여 다양한 소셜 로그인이나 파트너 IDP(Identity Provider)와 연동할 수 있다.

#### 구성 요소

* **Realm**: Keycloak에서의 논리적 경계이자, 사용자와 클라이언트가 속하는 영역이다.
* **Client**: 실제 애플리케이션이나 서비스로서, Keycloak으로부터 인증·인가 정보를 받아간다.
* **User**: Keycloak에 등록된 최종 사용자.
* **Identity Provider**: Keycloak에 인증 위임을 받을 수 있는 외부 IdP(예: Google, GitHub 등).
* **Admin Console**: 웹 브라우저에서 Keycloak 서버를 관리할 수 있는 콘솔.

#### 간단한 아키텍처 예시

아래는 간단한 시퀀스 다이어그램으로 나타낸 Keycloak 사용 흐름 예시이다.

{% @mermaid/diagram content="sequenceDiagram
participant User
participant Client
participant Keycloak
User->>Client: 리소스 접근 요청
Client->>Keycloak: 인증/인가 요청
Keycloak-->>Client: 토큰 발급
Client-->>User: 리소스 제공" %}

사용자가 처음으로 애플리케이션(Client)에 접근하면, 애플리케이션은 인증 여부를 확인하기 위해 Keycloak 서버에 요청을 보낸다. Keycloak은 사용자 정보를 확인하여 필요한 경우 로그인 화면을 제공하고, 인증이 정상적으로 완료되면 **액세스 토큰(Access Token)** 등을 돌려준다. 그 후 클라이언트는 토큰을 통해 리소스에 안전하게 접근할 수 있다.

#### 간단한 실행 예시

아래는 도커 컨테이너로 Keycloak을 간단히 실행하는 셸 명령 예시이다.

```shell
docker run --name my-keycloak -p 8080:8080 \
  quay.io/keycloak/keycloak:latest start-dev
```

이제 브라우저에서 [http://localhost:8080으로](https://booiljung.gitbook.io/booil-jung/docs/server_archiecture/keycloak/chapter_01/http:/localhost:8080으로) 접속하면 Keycloak 초기 화면을 볼 수 있다. 초기 관리자 계정(유저명, 비밀번호 등)을 설정한 뒤, Admin Console에 접속하여 Realm, User, Client 등을 관리할 수 있다.

#### 간단한 설정 파일 예시

Keycloak은 JSON 기반의 설정 파일을 사용할 수 있다. 예시:

```
{
  "realm": "myrealm",
  "enabled": true,
  "sslRequired": "none",
  "users": [
    {
      "username": "admin",
      "enabled": true
    }
  ]
}
```

설정 파일을 Admin Console에서 가져오거나, REST API로 업로드하여 손쉽게 Realm 환경을 재현할 수 있다.

위와 같이 Keycloak은 중앙에서 인증을 처리하고, 다양한 프로토콜 지원 및 확장성을 제공하는 강력한 IAM 솔루션이다. 이를 통해 개발자나 운영자는 개별 애플리케이션에 인증 로직을 중복으로 구현할 필요 없이, Keycloak에 인증과 권한 관리를 위임할 수 있다. 이후 챕터에서는 구체적인 설정과 운영 기법을 더 자세히 살펴본다.