시스템

Keycloak 설치 및 구성 매뉴얼 (GCP WIF 테스트)

달빛궁전- 2026. 2. 25. 14:22

 

개요

본 문서는 GCP Workload Identity Federation(WIF)의 외부 신원 공급자(IdP)로 활용될 Keycloak의 설치 및 구성 방법을 다룹니다. Keycloak은 Red Hat에서 주도하는 오픈소스 IAM 솔루션으로, Okta, Auth0, Gluu Server와 같이 엔터프라이즈급 인증 및 인가 기능을 제공합니다.

 

1.1 주요 구성 요소

  • Keycloak: OIDC 프로토콜 기반의 사용자 인증 및 ID 토큰(JWT) 발급 서버
  • ngrok: 로컬 서버를 외부 HTTPS 엔드포인트로 노출하여 GCP WIF의 Discovery를 지원

 

1.2 구축 목적

  • Keyless 인증: 정적 서비스 계정 키 없이 외부 신원을 GCP 권한과 매핑
  • 표준 준수: OIDC 표준을 활용한 확장 가능한 인증 체계 구축

 

2. ngrok: 외부 접속 터널링

GCP WIF가 외부 공급자(Keycloak)를 인식할 수 있도록 퍼블릭 HTTPS 도메인을 생성하는 단계입니다.

 

2.1 ngrok 설치

# 공식 GPG 키 및 저장소 등록
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list

# 패키지 설치
sudo apt update && sudo apt install ngrok -y

 

2.2 인증 토큰 등록 및 실행

  1. 토큰 등록: ngrok가입 후 ngrok Dashboard 에서 복사한 토큰을 입력합니다.
    • ngrok config add-authtoken <YOUR_TOKEN>
  2. 서비스 파일 생성
vi /etc/systemd/system/ngrok.service

 

서비스 파일 내용 작성 (ngrok 설치 경로가 **/usr/local/bin/ngrok** 또는 **/usr/bin/ngrok**인지 **which ngrok**으로 확인)

[Unit]
Description=ngrok tunnel
After=network.target

[Service]
Type=simple
# ngrok 위치와 포트 확인 후 작성
ExecStart=/usr/local/bin/ngrok http 8080 --config=/root/.config/ngrok/ngrok.yml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

 

2.3 ngrok 백그라운드 실행 설정

안정적인 운영을 위해 systemd 서비스 등록을 권장합니다.

 

A. systemd 서비스 등록 (권장)

  • 파일 경로: /etc/systemd/system/ngrok.service
[Unit]
Description=ngrok tunnel
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/ngrok http 8080 --config=/root/.config/ngrok/ngrok.yml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

 

서비스 실행 및 상태 확인

systemctl daemon-reload
systemctl enable ngrok
systemctl start ngrok

# 상태 확인 (초록색 활성화 확인!)
systemctl status ngrok

 

B. nohup을 이용한 빠른 실행

nohup ngrok http 8080 > ngrok.log 2>&1 &

💡 [Tip] 백그라운드 ngrok URL 확인법

터미널을 보지 않고도 현재 열린 주소를 확인하는 API 명령어입니다.

curl -s http://localhost:4040/api/tunnels | jq -r '.tunnels[0].public_url'

 

3. Keycloak: 인증 서버 구축

 

3.1 자바(JDK) 설치

Keycloak 최신 버전(Quarkus 기반)은 JDK 17 또는 21이 필요합니다.

 

sudo apt update
sudo apt install openjdk-17-jdk -y
java -version

 

3.2 Keycloak 다운로드 및 압축 해제

공식 배포판을 받아 적절한 경로(예: /opt)에 설치합니다.

# 다운로드 경로 이동 (권장: /opt)
cd /opt

# 최신 배포판 다운로드 (버전은 26.0.0 기준)
sudo wget https://github.com/keycloak/keycloak/releases/download/26.0.0/keycloak-26.0.0.tar.gz

# 압축 해제 및 소유권 변경
sudo tar -xvzf keycloak-26.0.0.tar.gz
sudo mv keycloak-26.0.0 keycloak

 

3.3 Keycloak 시작 (개발 모드)

관리자 계정을 설정하며 실행합니다.

export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=admin

# 개발 모드로 시작 (HTTP 8080 포트)
bin/kc.sh start-dev --http-port 8080

간단하게는 위와 같이 설정하여도 되나, 두고 계속 실습할 것이라면 아래 백그라운드 가이드를 참조합니다.

 

Keycloak 백그라운드 실행 가이드

Option 1. nohup을 이용한 간이 백그라운드

터미널을 종료해도 프로세스가 유지되도록 하며, 로그를 파일로 기록합니다.

  • 명령어:

Bash

nohup bin/kc.sh start-dev > keycloak.log 2>&1 &
  • 명령어 해설 (매뉴얼 설명용):
    • nohup: 터미널 세션이 끊겨도 프로세스를 중단하지 않음.
    • > keycloak.log: 모든 출력 로그를 keycloak.log 파일에 저장.
    • 2>&1: 에러 메시지까지 로그 파일에 포함.
    • &: 백그라운드에서 실행.
  • 프로세스 확인: ps -ef | grep keycloak

 

Option 2. systemd 서비스 등록

1. 서비스 파일 생성

vi /etc/systemd/system/keycloak.service

 

2. 아래 내용 복사 및 붙여넣기 (경로 /opt/keycloak 기준)

[Unit]
Description=Keycloak Server
After=network.target

[Service]
Type=idle
Environment="KEYCLOAK_ADMIN=admin"
Environment="KEYCLOAK_ADMIN_PASSWORD=password"
WorkingDirectory=/opt/keycloak
ExecStart=/opt/keycloak/bin/kc.sh start-dev --proxy-headers xforwarded --hostname-strict=false
TimeoutStartSec=600
StandardOutput=append:/var/log/keycloak.log
StandardError=append:/var/log/keycloak.log

[Install]
WantedBy=multi-user.target

 

3. 서비스 활성화 및 실행

# 시스템 데몬 재로드
systemctl daemon-reload

# 부팅 시 자동 시작 등록
systemctl enable keycloak

# 서비스 시작
systemctl start keycloak

# 상태 확인
systemctl status keycloak

 

4. Keycloak 웹 콘솔 설정

브라우저에서 ngrok 주소로 접속하여 GCP 연동을 위한 상세 설정을 진행합니다.

4.1 Realm 생성

  • 좌측 상단 [Create Realm] 클릭
  • Realm Name: GCP-WIF-Realm 입력 후 저장

 

4.2 Client 구성

  • Client ID: gcp-wif-client
  • Capability Config: Direct access grants 항목 반드시 체크 (파이썬 스크립트의 인증을 위해 필수)
  • Login Settings:
    • Valid Redirect URIs: * 또는 ngrok 주소 입력
    • Web Origins: * 입력

 

 

4.3 테스트 사용자 생성

  • Users > [Create new user] 클릭 (Username: test-user)
    Email verified : On 으로 설정 (미설정시 GCP에서 인증시 에러발생)
    Save 후 사용자가 생성되면 다시 사용자를 선택
  • Credentials 탭: [ReSet password] 클릭
  • Temporary: Off로 설정 (로그인 시 비밀번호 변경 강제 해제)

 

저작자표시 비영리 변경금지 (새창열림)