Keycloak 설치 및 인증 설정 가이드

Keycloak은 인증 및 권한 부여 플랫폼으로, SSO(Single Sign-On), LDAP, OAuth2, OpenID Connect 등을 지원하는 오픈소스 소프트웨어입니다. Kubernetes, Spring Boot와 같은 다양한 서비스와 애플리케이션에서 사용자 로그인, 토큰 발급, 권한 관리 등을 위해 광범위하게 사용되고 있습니다.

이 글은 Keycloak을 Kubernetes 환경에 설치하고, 사용자 인증과 권한 관리를 포함한 기본 인증 시스템을 구성하는 과정을 다룹니다. 특히 Keycloak 배포, 클라이언트 구성, 사용자와 그룹 매핑, 그리고 토큰 발급까지 이어지는 전체 인증 흐름을 단계적으로 경험하는 것이 핵심 목적입니다.

다음과 같은 순서로 Keycloak을 설치하고, 애플리케이션과 연동하여 인증을 위해 설정해야 하는 기본 과정을 소개드리겠습니다.

  1. 설치 환경
  2. Keycloak 용어 설명
  3. Keycloak 설치
  4. Realm 생성
  5. 사용자 생성
  6. 클라이언트 등록
  7. Client Scope에 그룹 추가
  8. 그룹 생성 및 할당
  9. 인증 흐름 설정
  10. 애플리케이션 연동
  11. 마무리

1. 설치 환경

Keycloak 설치를 위해 사전에 준비되어 있어야 하는 환경 구성 정보입니다.

  • Kubernetes v1.30
  • Kustomize v1.30.0
  • Helm v3.17.1

이 설치 환경 구성에 대한 자세한 방법은 아래 블로그를 참고하세요.

Kubernetes 설치와 GitOps에 대해서는 아래 블로그를 참고하세요.

※ 모든 설치 구성 요소는 arm64(aarch64) Linux 아키텍처를 기준으로 합니다.

2. Keycloak 용어 설명

Keycloak을 설치하기에 앞서, 인증 구성을 이해하기 위해 꼭 알아두어야 할 핵심 용어를 간단히 살펴보겠습니다.

  • Realm: Keycloak에서 인증과 권한을 관리하는 독립된 영역으로, 환경(개발·운영)이나 서비스별로 인증 구성을 분리할 때 필요합니다.
  • Client: Keycloak을 통해 인증을 요청하는 애플리케이션이나 서비스로, 등록을 통해서만 토큰 발급과 로그인 연동이 가능합니다.
  • Client Scope: 발급되는 토큰에 담길 추가 정보(Claims)를 정의하는 설정으로, 애플리케이션이 사용자 속성이나 권한 정보를 토큰에서 활용할 수 있게 합니다.
  • Group: 여러 사용자를 묶어 공통 권한을 부여하는 단위로, 권한 관리와 접근 제어를 단순화하는 데 유용합니다.
  • User: 실제로 로그인하고 서비스를 이용하는 개별 사용자로, Keycloak에서 관리되는 모든 인증의 주체입니다.

3. Keycloak 설치

이 글에서는 Bitnami의 Keycloak Helm Chart를 Kustomize로 배포할 수 있도록 구성된 GitOps 리소스를 사용해 Keycloak을 설치합니다.

  • Helm Chart: Bitnami Keycloak Chart 22.1.3
  • Keycloak 애플리케이션: 25.0.4

Kubernetes 환경에 Keycloak를 배포하기 위해, GitHub의 gitops-demo 저장소를 클론합니다.

git clone https://github.com/cnapcloud/gitops-demo.git

security 네임스페이스 생성하고 Keycloak을 배포합니다.

git clone https://github.com/cnapcloud/gitops-demo.git
cd gitops-demo/keycloak
make namespace
make apply
kubectl -n security get pods

keycloak이 kubernetes에 정상적으로 모두 배포가 완료가 되면, /etc/hosts 파일에 도메인을 등록한다. Kubernetes 서버가 원격에 존재하는 경우는 해당 서버의 IP를 가지고 등록합니다.

127.0.0.1 keycloak-admin.cnap.dev keycloak.cnap.dev

Keycloak 설정을 위해 브라우저에서 https://keycloak-admin.cnap.dev로 Admin console에 접속합니다. Admin console에서 로그인 화면이 나타나면 admin/password로 로그인을 합니다.

이제 왼쪽 상단의 Keycloak 선택 박스에서 2개의 Realm을 볼 수 있습니다. 이 Realm들은 GitOps 방식으로 Keycloak을 설치하는 과정에서 자동으로 추가되었습니다.

이 부분은 Keycloak dev overlay의 helm/values.yaml에 설정이 되어 있습니다. master는 관리자 전용이고 cnap은 application과 연동하여 인증을 구성하기 위해 추가하였습니다. 이 구성에서는 보안 강화를 위해 다음과 같이 front-end url을 관리자 Realm과 분리하여 구성하였습니다.

주의사항

  1. 여기서 배포된 Keycloak 25.0.4는 JDK 21을 사용하며, ARM64 아키텍처 기반이기 때문에 실행 중 오류를 방지하기 위해 _JAVA_OPTIONS='XX:UseSVE=0' 옵션을 설정하였습니다. AMD64 아키텍처에 설치하는 경우는 keycloak/kustomize/overlays/dev/에서 helm/values.yaml의 extraEnvVars과 kustomization.yaml의 patches 항목을 제거해야 합니다.
  2. 이 설치에서는 인그레스에 자체 인증서를 적용하고 있어 반드시 시스템 인증서 저장소에 이 인증서가 등록이 되어 있어야 정상적으로 관리자 콘솔에 접속할 수 있습니다. 시스템 인증서 저장소에 인증서를 등록하는 방법은 Helm과 Kustomize을 이용한 GitOps 배포 전략에 맨 아래을 참조하시기 바랍니다.

4. Realm 생성

Realm은 Keycloak에서 인증을 관리하는 기본 단위로, 애플리케이션마다 별도의 Realm을 만들 수 있습니다. 이를 통해 다중 애플리케이션에 대해 독립적인 인증 관리를 할 수 있습니다.

  • Keycloak 관리자 콘솔에 접속한다.
  • 로그인 후, Realm 메뉴에서 Create Realm 버튼 클릭한다
  • Realm Name을 입력하고 Create 버튼을 클릭하여 새 Realm을 생성합니다.

여기에서 keycloak 설치 시, 초기 구성된 cnap realm을 기준으로 인증 설정하는 방식으로 진행을 하겠습니다.

5. 사용자 생성

인증을 받을 실제 사용자를 Keycloak에 등록하여, 애플리케이션에서 이 사용자가 인증할 수 있도록 합니다. 사용자는 Keycloak을 통해 인증하고 애플리케이션에 접근할 수 있습니다.

  1. cnap realm으로 이동합니다.
  2. Users 메뉴로 이동하여 Add user(or Create new user) 버튼을 클릭합니다.
  3. 사용자 정보를 입력합니다.
    - Email verified: On
    - Username: admin
    - Email: admin@cnap.com
    - First name: admin
    - Last name: cnap
  4. Credentials 탭으로 이동하여 Set Password 버튼을 클릭합니다.
    비밀번호를 password로 입력하고 Temporary를 체크 해제하여 사용자가 로그인할 때 비밀번호를 변경하지 않도록 설정합니다.
  5. 설정이 완료되면 Save 버튼을 클릭하여 사용자를 생성합니다.

참고사항
“Username, Email, First name, Last name"은 필수 필드로 되어 있어, 로그인 시 누락된 정보가 있으면 등록을 요구합니다. 이 필수 항목 설정은 Realm Setting에서 User Profile 탭 메뉴에서 변경할 수 있습니다.

6. 클라이언트 생성

애플리케이션을 Keycloak에 클라이언트로 등록하여 인증을 받을 수 있도록 설정합니다. 클라이언트 등록을 통해 Keycloak이 애플리케이션의 인증 요청을 처리하고, 인증된 사용자에게 권한을 부여할 수 있습니다.

Clients 메뉴로 이동하여 Create Client 버튼을 클릭하고 다음과 같이 설정합니다.

General settings

  1. Client Type: OpenID Connect
  2. Client ID: kong
  3. 설정이 완료되면 Next 버튼을 클릭합니다.

Capability Config

  1. Client authentication: On (Client Secret을 가지고 인증)
  2. Standard Flow: ✔︎ (Standard Authorization Code Flow 사용)
  3. Direct Access Grants: ✔︎ (Resource Owner Password Credentials Flow 활성화)
  4. 설정이 완료되면 Next 버튼을 클릭합니다.

Login Settings

  1. Home URL: https://kong.cnap.dev
  2. Valid Redirect URIs: *
    (로그인 후 돌아올 리디렉션 URI를 설정합니다.)
  3. Valid Post Logout Redirect URIs: +
    (로그아웃 후 리디렉션될 URI를 설정합니다.)
  4. Web Origins: https://kong.cnap.dev
    (애플리케이션의 웹 출처를 설정합니다.)
  5. 설정이 완료되면 Save 버튼을 클릭하여 저장합니다.

7. Client Scopes에 그룹 추가

그룹 기반으로 애플리케이션에서 권한 처리를 위해 Client scopes에 groups을 다음과 같이 설정합니다.

Client scopes 설정

  1. Client Scopes 메뉴로 이동하여 Create client scope 버튼을 클릭합니다. - Name: groups
    - Type: Option 선택
    설정이 완료되면 Save 버튼을 클릭하여 저장합니다.
  2. 생성된 client scope에서 Mappers 탭으로 이동하여 Configure a new mapper를 클릭합니다.
    Configure a new mapper에서 Group Membership을 선택합니다.
    - Name: groups
    - Token Claim Name: groups
    - Full group path: off
    설정이 완료되면 Save 버튼을 클릭하여 저장합니다.

클라이언트에 그룹 추가

  1. Clients 메뉴를 이동하여 앞서 생성한 kong을 선택하고 Client Scopes 탭으로 이동한다.
  2. Add client scope를 선택하고 group을 추가하고 Optional로 Add 버튼을 클릭합니다.

8. 그룹 생성 및 할당

사용자 그룹을 정의하고, 그룹에 할당된 사용자들을 기준으로 애플리케이션에서 그룹 기반 접근 제어를 설정할 수 있습니다.

  1. Groups 메뉴로 이동하여 Create Group 버튼을 클릭합니다.
  2. 그룹 이름을 admin으로 입력합니다.
  3. Create 버튼을 클릭하여 그룹을 생성합니다.
  4. Users 메뉴로 이동하여 그룹에 할당할 특정 사용자를 선택합니다.
  5. Group 탭으로 이동하여 Join Group 버튼을 클릭합니다.
  6. admin 그룹을 선택하고 Join 버튼을 클릭하여 할당합니다.

9. 인증 흐름 설정 (선택 사항)

Keycloak에서 애플리케이션에 맞는 인증 흐름을 설정하여 사용자가 로그인을 진행할 때 어떤 방식으로 인증할지를 정의합니다. 인증 흐름을 통해 사용자가 어떻게 인증을 받는지, 어떤 추가적인 인증 절차가 필요한지를 설정할 수 있습니다.

  1. Authentication 메뉴로 이동하여 Flows 탭을 클릭합니다.
  2. Browser Flow나 Direct Grant Flow 등을 선택합니다.
    - Browser Flow는 웹 브라우저 기반의 인증 흐름을 설정합니다.
    - Direct Grant Flow는 애플리케이션에서 직접 사용자 인증을 받을 때 사용됩니다.
  3. 오른쪽 상단에 Action에서 Duplicate를 선택합니다.
  4. 새로운 Flow Name을 입력하고 Duplicate 버튼을 클릭하여 저장합니다.
  5. 새로 만들어진 Flow를 선택하고, Add Step이나 Add sub-flow 버튼을 클릭하여 Flow를 구성합니다. 예를 들어, Browser Flow에서 로그인 페이지를 커스터마이즈하여 사용자의 UX를 변경하거나, OTP와 같은 2차 인증을 추가할 수 있습니다.
  6. 최종적으로 Flow가 구성이 되면, 왼쪽 상단 Action에서 Bind flow를 선택합니다.

이 가이드에서는 특별한 변경없이 기본 인증 흐름 설정을 그대로 사용합니다.

10. 애플리케이션 연동

다음과 같이 애플리케이션과 Keycloak을 연동하여 OpenID Connect 프로토콜 기반의 인증을 구현할 수 있습니다.

  1. 애플리케이션에서 Keycloak의 OpenID Connect 프로토콜을 사용하여 인증을 처리할 수 있도록 설정합니다. oidc-client 라이브러리나 keycloak-js 라이브러리를 사용하여 애플리케이션에 Keycloak 인증을 통합할 수 있습니다.
  2. Redirect URI를 Keycloak에 등록된 URI와 동일하게 설정해야 합니다.
  3. 애플리케이션에서 로그인 버튼을 클릭하면, 사용자가 Keycloak 로그인 페이지로 리디렉션되어 인증을 진행합니다.
  4. 인증이 완료된 후, Callback URI로 돌아옵니다.
  5. 애플리케이션에서 access token을 받아 인증을 진행합니다.

이 과정은 범위가 넓어 본문에서 모두 다루기 어려우므로, 별도의 글에서 자세히 설명드리겠습니다.

대신, 본 글에서는 Keycloak console과 API를 활용하여 직접 로그인, 토큰 발급, 유효성 검증, 사용자 정보 조회 등 Keycloak의 기본 인증 흐름을 이해하는 데 중점을 두겠습니다.

Keycloak Console 로그인

  1. 브라우저에서 https://keycloak.cnap.dev/realms/cnap/account로 접속합니다.
  2. 신규로 등록한 사용자의 계정정보를 입력하고 로그인 후, 사용자 정보를 확인합니다.

API를 활용한 인증 처리

환경변수 설정
다음과 같이 API 기반으로 인증 테스트하기 위해 먼저 공통으로 사용되는 환경변수를 설정합니다. client_secret은 client 생성한 후에, Credentials 탭에서 확인 가능합니다.

export KEYCLOAK_URL=https://keycloak.cnap.dev
export REALM=cnap
export CLIENT=kong
export CLIENT_SECRET=P2PV5zfx31bJ5s0psxiwlNlNPdUpV25v
export USER=admin
export PASSWORD=password

Access Token 발급
신규로 등록한 사용자의 계정정보와 client_id, client_secret 가지고 access token 발급받는다. 토큰의 기본 유효 시간은 5분으로 설정되어 있으며, 이 시간이 지나면 재발급이 필요합니다. 유효 시간은 Realm 설정 또는 Client 설정을 통해 변경할 수 있습니다.

export ACCESS_TOKEN=$(curl -sk -X POST "${KEYCLOAK_URL}/realms/${REALM}/protocol/openid-connect/token" \
  -d grant_type=password \
  -d client_id=${CLIENT} \
  -d client_secret=${CLIENT_SECRET} \
  -d request_token_type=urn:ietf:params:oauth:token_type:access_token \
  -d username=${USER} \
  -d password=${PASSWORD} \
  -d scope='openid profile groups email' \
| jq -r .access_token)

echo "ACCESS_TOKEN: ${ACCESS_TOKEN}"

토큰 유효성 검사
Access Token의 유효성을 확인하려면 다음 명령어를 사용하여 introspection을 실행합니다.

curl -sk -X POST "${KEYCLOAK_URL}/realms/${REALM}/protocol/openid-connect/token/introspect" \
  -d grant_type=password \
  -d client_id=${CLIENT} \
  -d client_secret=${CLIENT_SECRET} \
  -d "token=${ACCESS_TOKEN}"

사용자 정보 조회
Access Token을 사용하여 사용자 정보를 조회하려면 아래 명령어를 사용합니다:

curl -sk "${KEYCLOAK_URL}/realms/${REALM}/protocol/openid-connect/userinfo" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

11. 마무리

이렇게 Keycloak을 활용하여 애플리케이션의 인증 시스템을 구축하는 방법을 단계별로 살펴보았습니다. Keycloak은 다양한 인증 흐름과 역할 기반 접근 제어(RBAC) 등 강력한 기능을 제공하여, 대규모 시스템에도 적합한 인증 솔루션입니다.

이번 글에서는 Keycloak을 설치하고, 애플리케이션과 연동하기 위한 클라이언트 생성부터 토큰 발급까지의 전체 과정을 다루었습니다. 운영 환경에서 Keycloak을 안정적으로 적용하기 위해서는 다음과 같은 기능 확장과 설정 작업이 요구됩니다.

  • Kong API Gateway와 Keycloak 연동을 통한 API 인증 처리
  • Email OTP 기반의 2차 인증
  • 외부 사용자 관리 시스템과 Keycloak 연계
  • GitHub, Naver 등 소셜 로그인 연동
  • 테마 커스터마이징 및 다국어(i18n) 지원
  • Google reCAPTCHA를 통한 가입 시 보안 강화
  • 비밀번호 정책 및 유효기간 설정
  • 이용약관 및 개인정보 수집 동의 화면 구성

다음 글에서는 Spring Boot 기반 애플리케이션과 Keycloak을 연동하여 인증과 권한을 처리하는 방법에 대해 소개하겠습니다.