13 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, created
| title | source_type | url | archive_url | related_branches | related_projects | tags | created | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| official-doc / traefikoidc — Community Traefik OIDC Middleware Plugin (lukaszraczylo) | official-doc | https://github.com/lukaszraczylo/traefikoidc |
|
|
|
2026-07-18 |
official-doc / traefikoidc — Community Traefik OIDC Middleware Plugin (lukaszraczylo)
Layer:
raw/— 외부 자료(공식 문서 / 대기업 기술 블로그)의 원문 발췌·출처 기록. Trust caveat (필수 선언): 이 자료는source_type: official-doc이지만, 이는 플러그인 프로젝트 자체의 authoritative 문서라는 뜻이지 Traefik Labs 의 공식 승인/검증을 의미하지 않는다.github.com/lukaszraczylo/traefikoidc는 단일 메인테이너(개인, org 아님) 커뮤니티 Yaegi 플러그인이며, Traefik Plugin Catalog 상에서 Traefik Labs 의 verification badge 를 확인하지 못했다 (아래 §메모 참조). 이 문서의 Claim 들 중 플러그인 자기 서술은 모두official-vendor-doc (self-published, community, NOT endorsed by Traefik Labs)로 표기한다.
Parent / 활용 branch
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-keycloak-traefik-forwardauth-alternative | D10 — Traefik 자체 OIDC 의 in-process(community plugin) 대안 대표 사례. oauth2-proxy 를 제거하고 Traefik 프로세스 내부에서 OIDC 를 수행하는 경로가 존재함을 보이되, 그 유지보수 리스크(single-maintainer, Traefik Labs 무보증, production 사례 0건)를 named failure mode 로 근거화. |
출처 / Source
- 원본 URL: https://github.com/lukaszraczylo/traefikoidc
- 교차 참조 (동일 source family, 별도 파일 생성 안 함):
- https://traefikoidc.raczylo.com/ — 전용 docs 사이트. "drop-in replacement" / "bounded caches" 정확 문구 출처.
- https://plugins.traefik.io/plugins/6613338ea28c508f411a44d5/traefik-oidc — Traefik Plugin Catalog 등재 페이지.
type: "middleware"(Yaegi 계열 catalog 항목), Traefik Labs verification badge 텍스트 미확인. - https://doc.traefik.io/traefik/extend/extend-traefik/ — Traefik Labs 공식 plugin 확장 문서. 플러그인 일반에 대한 공식 caution 인용 (SECONDARY quote, 이 파일에만 인용 — 별도 파일 생성 안 함).
- 아카이브 URL: (미제공)
- 저자 / 조직: Lukasz Raczylo (GitHub:
lukaszraczylo, 개인 — org 아님) - 발행일: 지속 갱신 리포지토리. 관측된 최신 릴리스
v1.0.27(2026-06-26T10:52:34Z, GitHub Releases API) - 마지막 확인일: 2026-07-18
왜 저장했는지 / Why archived
Traefik 자체 in-process OIDC 대안(oauth2-proxy 제거) 이 실존함을 근거화하되, 이 대안이 Traefik Labs 비보증 커뮤니티 단일 메인테이너 플러그인이라는 유지보수 리스크를 D10 결정의 named failure mode 로 문서화하기 위함.
핵심 인용 / Key quotes (verbatim)
[docs site, traefikoidc.raczylo.com] "Drop-in replacement for oauth2-proxy and forward-auth with support for 9+ identity providers."
[docs site, traefikoidc.raczylo.com] "Bounded caches with LRU eviction, automatic cleanup, and zero goroutine leaks"
[README.md §Common optional parameters,
refreshGracePeriodSecondsrow] "Proactively refresh tokens this many seconds before expiry." (default60)
[README.md §Common optional parameters,
maxRefreshTokenAgeSecondsrow, elided — 232자] "Heuristic max stored refresh-token lifetime (6h). Past this, the plugin treats the RT as expired without contacting the IdP — returns 401 to AJAX, full re-auth on navigations." [...] "Tune to match your IdP's RT TTL." (default21600)
[README.md §Install] "This middleware tracks the current Traefik helm chart release. If it fails to load, update Traefik first."
[README.md §Provider support table] "Keycloak | Full | Yes | host containing
keycloak, or/realms/in path (covers KC <17/auth/realms/and 17+/realms/)"
[LICENSE file, raw.githubusercontent.com/lukaszraczylo/traefikoidc/main/LICENSE] "MIT License" (Copyright (c) 2025 Lukasz Raczylo)
[GitHub Releases API, v1.0.27 release body] "...security: remediate audit findings (ranks 1–16 + 22 Lows) + yaegi load validation (#144)" — 릴리스 changelog 자체가 "yaegi" 를 언급, Yaegi 인터프리터 기반 플러그인임을 뒷받침.
[SECONDARY — 공식 Traefik Labs 출처, doc.traefik.io/traefik/extend/extend-traefik/] "Plugins can change the behavior of Traefik in unforeseen ways. Exercise caution when adding new plugins to production Traefik instances."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| TOIDC-C1 | 플러그인은 스스로를 "oauth2-proxy 와 forward-auth 의 drop-in replacement"로 서술하며, Keycloak 을 "Full OIDC + refresh" 지원 provider 로 명시 (호스트명에 keycloak 포함 또는 경로에 /realms/ 포함 시 auto-detect) |
"Drop-in replacement for oauth2-proxy and forward-auth with support for 9+ identity providers." / "Keycloak | Full | Yes | host containing keycloak, or /realms/ in path..." |
official-vendor-doc (self-published, community, NOT endorsed by Traefik Labs) |
oauth2-proxy 제거 후 Traefik in-process OIDC 로 대체 가능한 아키텍처 옵션이 실존함을 보이는 근거, Keycloak 대상 포함 | production-readiness 를 증명하지 않음. Keycloak 연동이 실제 운영 환경에서 정확히 동작함을 증명하지 않음. Traefik Labs 또는 Keycloak 프로젝트의 공식 승인/보증을 의미하지 않음 |
| TOIDC-C2 | refreshGracePeriodSeconds (기본 60초) 는 만료 전 사전 refresh 시점을 설정. maxRefreshTokenAgeSeconds (기본 21600초=6h) 는 저장된 refresh token 의 heuristic 최대 수명 — 이 기간이 지나면 IdP 에 문의 없이 만료로 간주 |
"Proactively refresh tokens this many seconds before expiry." / "Heuristic max stored refresh-token lifetime (6h). Past this, the plugin treats the RT as expired without contacting the IdP..." | official-vendor-doc (self-published, community, NOT endorsed by Traefik Labs) |
토큰 refresh 설정 노브의 존재와 기본값 확인 | 고부하/동시성 상황에서의 정확한 동작을 증명하지 않음. heuristic 값이 실제 IdP(Keycloak 등)의 RT TTL 과 항상 일치함을 보장하지 않음 — 문서 자체가 "Tune to match your IdP's RT TTL" 로 사용자 수동 조정을 요구 |
| TOIDC-C3 | 캐시는 "LRU eviction, automatic cleanup, zero goroutine leaks" 를 갖춘 "bounded caches" 로 서술됨 | "Bounded caches with LRU eviction, automatic cleanup, and zero goroutine leaks" | official-vendor-doc (self-published, community, NOT endorsed by Traefik Labs) |
discovery/session 캐시가 무한 증가하지 않도록 설계 의도가 있음을 보이는 근거 | 구체적 TTL 값 / 캐시 크기 상한 / 실제 goroutine leak 부재를 독립적으로 검증하는 벤치마크·프로파일링 결과를 제공하지 않음 (자기 서술, 수치 미공개) |
| TOIDC-C4 | 미들웨어는 "현재 Traefik helm chart release 를 추적"하며, 로드 실패 시 Traefik 버전을 먼저 업데이트하라고 안내 | "This middleware tracks the current Traefik helm chart release. If it fails to load, update Traefik first." | official-vendor-doc (self-published, community, NOT endorsed by Traefik Labs) |
Traefik 버전과의 결합도(coupling)가 formal compatibility matrix 가 아니라 informal tracking 임을 보이는 유지보수 리스크 근거 | 지원되는 구체적 Traefik 버전 범위나 하위 호환성 보장을 제공하지 않음. 문제 발생 시 수동 버전 업그레이드가 1차 대응이라는 뜻이며 자동 호환성 테스트 존재를 증명하지 않음 |
| TOIDC-C5 | License = MIT (Copyright 2025 Lukasz Raczylo). 관측된 최신 릴리스 = v1.0.27 (2026-06-26T10:52:34Z, GitHub Releases API). 해당 릴리스 changelog 본문에 "yaegi load validation" 문구가 있어 Yaegi 인터프리터 기반 플러그인임을 뒷받침 |
"MIT License" / "tag_name":"v1.0.27","published_at":"2026-06-26T10:52:34Z" / "...yaegi load validation (#144)" |
official-vendor-doc (self-published, community, NOT endorsed by Traefik Labs) |
라이선스 호환성 확인, 관측 시점 기준 최신성(recency) snapshot, Yaegi(비-WASM) 플러그인 유형 확인 | 지속적 유지보수 커밋먼트나 bus-factor 완화를 증명하지 않음 — GitHub author 가 조직이 아닌 개인(lukaszraczylo) 이므로 single-maintainer 리스크 존재. "최신 릴리스 recency" 는 한 시점의 snapshot 일 뿐 향후 유지보수 추세를 보장하지 않음 |
| TOIDC-C6 (SECONDARY, 공식 Traefik Labs) | Traefik Labs 는 프로덕션에 신규 플러그인을 추가할 때 주의를 명시적으로 경고 | "Plugins can change the behavior of Traefik in unforeseen ways. Exercise caution when adding new plugins to production Traefik instances." | official-vendor-doc (Traefik Labs — 공식, 플러그인 작성자와 무관한 별도 출처) |
커뮤니티 Traefik 플러그인 일반(본 플러그인 포함)의 production 도입 리스크를 뒷받침하는 vendor-neutral 근거 | 이 플러그인이 특정하게 위험하다는 뜻은 아님 — Traefik 의 모든 plugin (Yaegi/WASM 무관) 에 적용되는 일반 경고 |
Strength 허용값 (본 문서에서 사용한 것)
official-vendor-doc— 단, 본 문서는 자기서술(self-published community project) 임을 매 row 마다 명시적으로 부기함. 공식 best practice 로 취급 금지.
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
TOIDC-C1: 플러그인이 스스로를 oauth2-proxy/forward-auth 대체재로 서술하고 Keycloak 을 지원 provider 로 명시하는 사실 자체 (자기 서술 존재).TOIDC-C2~TOIDC-C4: 설정 노브의 존재, 기본값, 그리고 Traefik 버전 결합에 대한 vendor 서술 존재.TOIDC-C5: 라이선스(MIT), 관측 시점 최신 릴리스, Yaegi 플러그인 유형.TOIDC-C6: Traefik Labs 자체의 plugin 일반 caution — 이것만 유일하게 plugin 작성자가 아닌 독립 공식 출처.
- 이 자료가 증명하지 않는 것:
- production-readiness (실제 프로덕션 사례 0건 관측 — 본 raw 자료 조사 범위에서 사례를 찾지 못함).
- discovery/session 캐시의 구체적 TTL 값 (문서에 수치 미기재).
- 고부하 상황에서의 정확한 token refresh 동작 (자기서술만 존재, 독립 벤치마크 없음).
- 지속적 유지보수 (single-maintainer bus-factor — 조직이 아닌 개인 저장소. 최신 릴리스 recency 는 트렌드가 아니라 한 시점 snapshot).
- Traefik Labs 또는 Keycloak 프로젝트의 공식 승인/검증 (Plugin Catalog 페이지에서 verification badge 텍스트 미확인).
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 실제 Keycloak realm 대상 hands-on 시연 (discovery, token refresh, logout 흐름 실측).
refreshGracePeriodSeconds/maxRefreshTokenAgeSeconds값이 실제 Keycloak 세션/RT 정책과 정합하는지 실측.- 단일 메인테이너 리스크에 대한 조직 차원의 수용 가능 여부 판단 (fork 유지 계획 포함).
메모 / Notes
나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것.
- Traefik Plugin Catalog 페이지(
plugins.traefik.io/.../traefik-oidc)를 curl 로 직접 받은 HTML/__NEXT_DATA__JSON 전체를 grep 했으나 "verified"/"official"/"traefik labs 검증" 류 배지 텍스트를 찾지 못했다 (footer 의 "Traefik Labs" 링크는 catalog 사이트 저작권 표시일 뿐, 개별 플러그인 보증 표시가 아님). 부재의 증거는 증거의 부재이므로 이것 자체를 Claim 으로 올리지 않고 메모로만 남김 — Traefik Labs 가 별도 페이지/UI 요소에서 배지를 표시할 가능성을 완전히 배제하지 못함. - WebFetch 1차 시도 결과 3건(GitHub repo, docs site, plugin catalog)이 모두 요약/재구성된 산문으로 반환되어 verbatim self-grep 이 불가능했음 (예: WebFetch 는 "Released under Apache 2.0 License." 라고 잘못 보고했으나 curl 로 받은 실제 LICENSE 파일은 MIT였음 — WebFetch 요약 오류의 실제 사례). 이에 따라 본 문서의 모든 인용은
curl로 재수집한 raw HTML/텍스트에 대해 self-grep 검증했다. - 추가로 봐야 할 동일 출처 페이지:
docs/REDIS.md,docs/BEARER_AUTH.md(multi-replica 배포 시 Redis 필수 여부 상세, 본 문서 범위 밖).
Related / 관련
- raw/official-docs/traefik-forwardauth-middleware-official — Traefik 공식
forwardAuthmiddleware (OSS, sidecar 방식). 본 문서(in-process community OIDC plugin)와의 대안 비교 baseline. - raw/official-docs/traefik-hub-oidc-middleware-official — Traefik Hub(유료) 전용 native OIDC 미들웨어. 본 문서(무료 community 대안)와의 비교 대상.
- raw/official-docs/oauth2-proxy-overview-config-official — oauth2-proxy 자체 공식 문서 (본 플러그인이 "replace" 한다고 주장하는 대상).