llm-wiki/raw/official-docs/traefik-oidc-community-plugin-lukaszraczylo-official.md

---
title: official-doc / traefikoidc — Community Traefik OIDC Middleware Plugin (lukaszraczylo)
source_type: official-doc
url: https://github.com/lukaszraczylo/traefikoidc
archive_url:
related_branches: [feature-keycloak-traefik-forwardauth-alternative]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, auth, traefik, keycloak]
created: 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, `refreshGracePeriodSeconds` row] "Proactively refresh tokens this many seconds before expiry." (default `60`)

> [README.md §Common optional parameters, `maxRefreshTokenAgeSeconds` row, 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." (default `21600`)

> [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 공식 `forwardAuth` middleware (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" 한다고 주장하는 대상).