테스트에서 Dex로 OAuth 서비스 모킹하기

테스트에서 Dex로 OAuth 서비스 모킹하기 (Mocking OAuth services in testing with Dex)

Dex는 오픈소스 OpenID Connect(OIDC) 및 OAuth 2.0 ID 제공자(identity provider)로, LDAP, SAML, OAuth 같은 다양한 백엔드 ID 제공자를 대상으로 인증하도록 구성할 수 있어요. Dex를 Docker 컨테이너에서 실행하면 개발·테스트 목적으로 OAuth 2.0 서버를 시뮬레이션할 수 있어요. 이 가이드에서는 Docker 컨테이너로 Dex를 OAuth 목(mock) 서버로 구성하는 과정을 함께 살펴볼게요.

출처: 문서

본문

요즘 웹 서비스에서 인증할 때는 OAuth가 선호되는 선택이에요. 대부분의 웹 서비스는 GitHub, Google, Apple 같은 인기 있는 OAuth 서비스로 접근할 수 있는 기능을 제공하죠. OAuth를 사용하면 각 서비스마다 새 프로필을 만들 필요가 없어서 보안 수준이 높아지고 단순화된다는 장점이 있어요. 즉, 서비스가 비밀번호를 공유하지 않고도 사용자를 대신해 리소스에 접근할 수 있게 해줘서, OAuth는 자격 증명 노출 위험을 최소화해요.

이 가이드에서 배울 내용은 다음과 같아요:

Docker로 Dex 컨테이너를 띄우는 방법
외부 OAuth 제공자에 의존하지 않고 GitHub Action(GHA)에서 목 OAuth를 사용하는 방법

Docker로 Dex 사용하기 (Using Dex with Docker)

Dex의 공식 Docker 이미지는 Dex 인스턴스를 쉽게 배포·관리하는 방법을 제공해요. Dex는 amd64, armv7, arm64를 포함한 다양한 CPU 아키텍처에서 사용할 수 있어서 여러 기기·플랫폼과 호환돼요. Dex 단독 사용에 대해 더 알고 싶다면 Dex 문서 사이트를 참고하세요.

사전 요구사항 (Prerequisites)

Docker Compose: 여러 컨테이너 Docker 애플리케이션을 관리할 때 권장돼요.

Docker로 Dex 설정하기 (Setting up Dex with Docker)

Dex 프로젝트용 디렉터리를 먼저 만들어요:

mkdir dex-mock-server
cd dex-mock-server

프로젝트를 다음 구조로 구성하세요:

dex-mock-server/
├── config.yaml
└── compose.yaml

Dex 구성 파일 만들기

config.yaml 파일은 connectors, clients, storage를 포함한 Dex의 설정을 정의해요. 목 서버 구성에서는 다음의 최소 구성(minimal configuration)을 사용할 수 있어요:

# config.yaml
issuer: http://localhost:5556/dex
storage:
  type: memory
web:
  http: 0.0.0.0:5556
staticClients:
  - id: example-app
    redirectURIs:
      - 'http://localhost:5555/callback'
    name: 'Example App'
    secret: ZXhhbXBsZS1hcHAtc2VjcmV0
enablePasswordDB: true
staticPasswords:
  - email: "[email protected]"
    hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
    username: "admin"
    userID: "1234"

설명:

issuer: Dex의 공개 URL이에요.
storage: 단순함을 위해 인메모리 스토리지를 사용해요.
web: Dex가 5556 포트에서 수신 대기해요.
staticClients: 리다이렉트 URI와 시크릿을 가진 클라이언트 애플리케이션(example-app)을 정의해요.
enablePasswordDB: 정적 비밀번호 인증을 활성화해요.
staticPasswords: 인증용 정적 사용자를 정의해요. hash는 비밀번호의 bcrypt 해시예요.

참고: hash가 원하는 비밀번호의 유효한 bcrypt 해시인지 확인하세요. bcrypt-generator.com 같은 도구로 생성할 수 있어요. 또는 다음과 같이 htpasswd 같은 CLI 도구를 사용할 수도 있어요: echo password | htpasswd -BinC 10 admin | cut -d: -f2

Docker Compose를 구성했으면 Dex를 시작하세요:

# compose.yaml
services:
  dex:
    image: dexidp/dex:latest
    container_name: dex
    ports:
      - "5556:5556"
    volumes:
      - ./config.yaml:/etc/dex/config.yaml
    command: ["dex", "serve", "/etc/dex/config.yaml"]

이제 docker compose 명령으로 컨테이너를 실행할 수 있어요.

docker compose up -d

이 명령은 Dex Docker 이미지를 (아직 없다면) 내려받고 컨테이너를 분리(detached) 모드로 시작해요.

Dex가 실행 중인지 확인하려면 로그를 확인해 Dex가 성공적으로 시작됐는지 보세요:

docker compose logs -f dex

Dex가 지정된 포트에서 수신 대기 중임을 알려주는 출력이 보일 거예요.

GHA에서 Dex OAuth 테스트 사용하기 (Using Dex OAuth testing in GHA)

OAuth 흐름을 테스트하려면 Dex에 대해 인증하도록 구성된 클라이언트 애플리케이션이 필요해요. 가장 대표적인 사용 사례 중 하나는 GitHub Actions 안에서 사용하는 거예요. Dex가 목(mock) 인증을 지원하므로, 문서에서 제안하는 것처럼 테스트 사용자를 미리 정의할 수 있어요. config.yaml 파일은 다음과 같이 생겨야 해요:

issuer: http://127.0.0.1:5556/dex
storage:
  type: memory
web:
  http: 0.0.0.0:5556
oauth2:
  skipApprovalScreen: true
staticClients:
  - name: TestClient
    id: client_test_id
    secret: client_test_secret
    redirectURIs:
      - http://{ip-your-app}/path/to/callback/ # example: http://localhost:5555/callback
connectors:
  # mockCallback connector always returns the user '[email protected]'.
  - type: mockCallback
    id: mock
    name: Mock

이제 ~/.github/workflows/ci.yaml 파일 안에 Dex 서비스를 넣을 수 있어요:

[...]
jobs:
  test-oauth:
    runs-on: ubuntu-latest
    steps:
      - name: Install Dex
        run: |
          curl -L https://github.com/dexidp/dex/releases/download/v2.37.0/dex_linux_amd64 -o dex
          chmod +x dex
      - name: Start Dex Server
        run: |
          nohup ./dex serve config.yaml > dex.log 2>&1 &
          sleep 5  # Give Dex time to start
[...]

결론 (Conclusion)

이 가이드를 따라 하면서 Docker로 Dex를 OAuth 목 서버로 구성해봤어요. 이 구성은 외부 ID 제공자에 의존하지 않고 OAuth 흐름을 시뮬레이션할 수 있게 해줘서 테스트·개발에 매우 유용해요. 더 고급 구성과 통합은 Dex 문서를 참고하세요.