Keycloak을 Docker에서 실행하는 방법과 HTTP 오류 대처법

Keycloak은 인증 및 권한 관리를 위한 오픈소스 솔루션입니다. 이 글에서는 Keycloak을 Docker 환경에서 손쉽게 실행하는 방법과 실행 중 발생할 수 있는 HTTP 오류 대처 방법에 대해 상세히 설명합니다.

1. Docker로 Keycloak 실행하기

1-1. 기본 실행 방법

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

KEYCLOAK_ADMIN: Keycloak 관리자 계정 ID
KEYCLOAK_ADMIN_PASSWORD: 관리자 비밀번호
start-dev: 개발 모드로 실행 (DB 설정 없이 내부 H2 사용)

1-2. 외부 DB(PostgreSQL) 연동

외부 DB에 연결하면 영속적인 사용자 데이터 저장이 가능합니다.

docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KC_DB=postgres \
  -e KC_DB_URL=jdbc:postgresql://:5432/keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin123 \
  quay.io/keycloak/keycloak:24.0.2 \
  start-dev

※ PostgreSQL 컨테이너와 함께 docker-compose로 실행하는 것이 일반적입니다.

2. Docker Compose로 실행

version: '3.8'
services:
  postgres:
    image: postgres:14
    container_name: keycloak-db
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"

  keycloak:
    image: quay.io/keycloak/keycloak:24.0.2
    container_name: keycloak
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin123
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: password
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    command: start-dev

명령어: docker-compose up -d

3. HTTP 오류 대처 방법

3-1. 401 Unauthorized

Access Token이 누락되었거나 잘못됨
client 설정에서 Access Type이 public/private로 올바르게 설정되었는지 확인
Keycloak에 사용자 인증 정보가 정확히 등록되었는지 확인

3-2. 403 Forbidden

권한 부족 또는 Role 설정 미비
Realm Role, Client Role이 잘 등록되었는지 확인
Scope 설정 또는 token에 role이 포함되었는지 확인

3-3. 404 Not Found

잘못된 API endpoint 또는 client 설정 오류
경로가 정확한지, Keycloak에서 해당 endpoint가 활성화되었는지 확인