fix(deploy): the production image and compose cannot run OIDC — pyjwt is missing and no OIDC variable is passed

[yeongseon]

Builder(공공데이터를 수집해 데이터셋으로 빌드하는 서버)의 운영 배포용 이미지와 compose 구성으로는 OIDC(Keycloak 같은 인증 서버에 로그인을 맡기는 표준 방식) 인증을 켤 수 없습니다. Studio(Builder 의 웹 화면)는 OIDC 토큰만 보내므로, 이 상태로는 Studio 를 운영 Builder 에 연결할 수 없습니다.

Problem

운영 배포는 API 키 인증만 지원하고 OIDC 를 켤 수 없습니다. Studio 는 Bearer 토큰(Keycloak 이 발급)만 보냅니다. 지금 구성으로는 Studio 가 운영 Builder 에 연결되지 못합니다.

Evidence

• Dockerfile:51 은 ARG EXTRAS=publish 입니다. JWT 검증에 필요한 pyjwt 는 auth extra 에만 있습니다(pyproject.toml:63).
• docker-compose.prod.app.yml:27-38 의 environment 에는 KPUBDATA_BUILDER_API_KEY, HOST, PORT, OUTPUT_DIR, ALLOWED_ORIGINS, CREDENTIAL_MASTER_KEY 여섯 개만 있습니다. OIDC_* 변수는 없습니다.
• .env.app.example 에도 OIDC_* 변수가 없습니다. deploy.yml:45 가 사용하는 파일이 이 compose 입니다.
• OIDC 변수를 넘기는 compose 는 따로 있습니다(infra/oci/docker-compose.yml:46-49). 이 파일은 운영 배포 경로와 맞지 않습니다.
• Studio 쪽에는 X-API-Key 를 보내는 경로가 없습니다(Studio 의 이슈를 참조합니다).

Impact: 실제 Builder 에 연결된 Studio 를 배포할 수 없습니다. "사용자가 자신의 provider 키를 직접 넣고(BYOK) 서버는 그 키를 저장하지 않는다"는 설명은 다중 사용자(OIDC) 모드에서만 성립합니다. 단일 사용자 모드는 CREDENTIAL_MASTER_KEY 로 키를 암호화해 저장합니다.
Blocks: Studio 를 실제 Builder 에 연동한 배포와 V5 검증(제품 전체를 처음부터 끝까지 실행하는 테스트)을 막습니다.
Evidence: 위에 적은 파일들입니다.

먼저 정할 것 (사람)

• 운영 인증 모드를 정합니다. 선택지는 OIDC 다중 사용자와 API 키 단일 사용자입니다. Studio 가 Bearer 토큰만 지원하므로 OIDC 다중 사용자가 권장됩니다.
• 토큰 종류를 정합니다. 선택지는 ID 토큰과 access 토큰입니다. Studio 는 Keycloak 의 access 토큰을 보냅니다.

Scope

• 배포 이미지에 auth extra 를 포함합니다(EXTRAS="publish auth").
• compose, .env.app.example, deploy.yml 에 OIDC_ISSUER, OIDC_AUDIENCE, KPUBDATA_BUILDER_ADMIN_SUBJECTS, KPUBDATA_BUILDER_AUTH_FAILURE_LIMIT 를 추가합니다.
• 다중 사용자 프로필에서 CREDENTIAL_MASTER_KEY 와 provider 키 환경변수를 제거합니다.
• Keycloak 의 realm export(audience mapper 와 email_verified 포함)를 저장소에 추가합니다.

Acceptance Criteria

• 배포 이미지에서 import jwt 가 성공합니다.
• OIDC 변수가 있는 프로필이 CI 에서 기동 스모크 테스트를 통과합니다.
• 실제 Keycloak 토큰으로 GET /providers 를 호출하면 200 이 돌아옵니다.

Required Verification

V3(실제 컴포넌트 사이의 통합 테스트)와 인증에 대한 부정 테스트(거부되어야 할 요청이 실제로 거부되는지 확인하는 테스트)가 필요합니다. 검증 수준은 POLICY.md 의 Verification Level 표를 따릅니다.

Dependencies

Blocked by: #990, #991. 다중 사용자 모드로 열면 이 두 결함이 바로 노출됩니다. #990 은 REQUIRE_OWN_PROVIDER_CREDENTIAL 설정에서도 키 없는 요청이 운영자의 환경 변수 키로 실행되는 문제이고, #991 은 POST /builds 가 다른 호출자의 run_id 를 받으면 그 호출자의 job 을 돌려주는 문제입니다.
Relates: #692 (프로필별 기동 스모크 테스트를 갖춘 Compose 묶음)

Notes

2026-10-04 에 세 저장소의 연동을 검토하면서 나온 항목입니다. main 의 커밋 7a3f78f 에서 다시 확인한 것만 적었습니다.

---

2026-10-07 최소 운영 설계 재검토

HEAD와 릴리스 산출물 구분

2026-10-07 에 커밋 1d93ceb 기준으로 확인한 내용입니다. Dockerfile 의 EXTRAS 는 이미 publish auth 이고, 운영용 compose 에 OIDC 변수가 있습니다. 따라서 위 본문은 과거 시점의 설명이며, 현재 main 의 코드 상태로 인용하지 않습니다. 사용자가 보고한 "v0.4.0 에서 OIDC 를 쓸 수 없다"는 문제는, 이 검토에서 해당 이미지를 받아 실행해 재현하지 않았습니다.

• 다음 실제 릴리스 이미지에서 import jwt, OIDC 토큰 검증, 소유권에 대한 스모크 테스트 결과를 기록합니다(feat: one-click Compose bundle with a per-profile start smoke test #692).
• 남아 있는 API 키 강제는 인증기 자체가 아니라 docker-entrypoint.sh 와 compose 에 있으며, OIDC 만 쓰는 컨테이너를 지원하는 이슈(fix(deploy): support OIDC-only containers without a mandatory administrator API key #1122)에서 추적합니다.
• 스테이징에서 main 또는 특정 커밋(sha)이 성공한 것과 정식 릴리스의 검증을 구분합니다. 긴급 릴리스를 할지는 기존 정책에 따라 프로젝트 메인테이너가 판단합니다.

이 검토에서는 이 이슈를 완료 처리하거나 닫지 않습니다.

[yeongseon]

이 이슈는 Builder(kpubdata 로 수집한 공공데이터를 테이블로 빌드하는 서버)의 프로덕션 이미지와 compose 구성으로는 OIDC 로그인(Keycloak 같은 인증 서버가 발급한 토큰으로 사용자를 확인하는 방식)을 켤 수 없다는 문제를 다룹니다. 2026-10-05 에 진행한 연동 검토 결과를 기준으로, 끝난 범위와 남은 범위를 정리합니다.

• 끝난 작업: 기본 이미지에 auth extra(OIDC 에 필요한 선택 의존성 묶음)를 넣고 compose 파일이 OIDC 환경변수 7개를 전달하게 한 변경(fix(deploy): let the production image and compose run OIDC #1020)과, realm 설정 단계를 적은 문서 변경(docs(auth): state that the bearer token Builder accepts is an access token #1019)이 병합되었습니다.

• 진행 중인 작업: CUBRID 변형 이미지에도 auth extra 를 넣는 변경이 fix(deploy): build the CUBRID-profile image with the auth extra #1033 에서 진행되고 있습니다.

• 남은 작업은 세 가지입니다.

  • deploy.yml 과 rollout 스크립트가 OIDC 변수를 secrets 에서 읽어 주입하게 하는 것.
  • Keycloak realm export 파일을 저장소에 두는 것.
  • "OIDC 설정으로 serve 를 기동하면 /healthz 가 200 을 돌려준다" 를 확인하는 스모크 테스트.

  앞의 두 가지는 배포 대상과 실제 realm 이 정해진 뒤에야 진행할 수 있습니다.

이와 별도로 선행 조건이 하나 있습니다. OIDC 를 켜면 Builder 는 다중 사용자 모드로 동작하고, 이 모드는 kpubdata 의 env_keys 옵션(환경변수에 있는 provider 키를 읽지 않게 하는 Client 인자)이 필요합니다. PyPI 에 올라와 있는 kpubdata 0.8.0 에는 이 옵션이 없어서 serve 가 기동을 거부합니다. 이 거부는 자기 키가 없는 요청이 운영자의 환경변수 키로 실행되던 문제의 수정(#990)이 의도한 동작입니다. 따라서 env_keys 를 담은 kpubdata 릴리스(kpubdata-lab/kpubdata#780)가 먼저 나와야 합니다.

[yeongseon]

Builder 를 처음 실제로 배포할 때의 인증 방식과 배포 방법에 대한 결정을 기록합니다. 근거와 전체 결정 목록은 kpubdata-lab/kpubdata#812(2026-10-06 후속 작업 계획의 결정 기록)에 있습니다.

• 첫 실제 배포의 인증은 OIDC 다중 사용자 방식입니다. OIDC 는 Keycloak 같은 인증 서버가 발급한 토큰으로 사용자를 구분하는 방식입니다.
• 단일 사용자 API 키 프로필은 예약 워크플로와 로컬 실행용으로 남깁니다. 두 프로필의 설정 예시는 문서에서 따로 나누어 적습니다.
• 자동 배포는 두지 않습니다. 배포는 Docker Compose 를 손으로 실행하는 방식입니다.
• 배포 대상(서버, 도메인, Keycloak 운영 주체)은 아직 정해지지 않았습니다.