llm-wiki/raw/official-docs/traefik-hub-oidc-middleware-official.md

---
title: Traefik — OIDC Authentication Middleware (Traefik Hub, Paid API-Gateway Tier — Official Docs)
source_type: official-doc
url: https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/oidc/
archive_url:
status: raw
confidence: high
tags: [official-doc, keycloak-patterns, auth, traefik, oauth2]
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-traefik-forwardauth-alternative]
created: 2026-07-18
last_reviewed: 2026-07-18
---

# Traefik — OIDC Authentication Middleware (Traefik Hub, Paid API-Gateway Tier — Official Docs)

> Layer: `raw/official-docs/` — Traefik 공식 문서의 `oidc` 미들웨어(플러그인). **이 자료가 다루는 것은 무료 Traefik OSS 가 아니라 유료 Traefik Hub (API Gateway 티어)** 이다. P1A 대안 비교 sub-sub-branch 의 핵심 질문 "OSS Traefik 이 OIDC 를 자체 수행할 수 있는가?"에 공식 vendor 가 **"아니오, Hub 전용"** 이라고 직접 답하는 자료.
> 본 문서는 **동일 제품군의 두 페이지**를 하나의 raw 파일로 묶는다 (`wiki-source-summarizer` 지시에 따름 — 별도 파일 생성 안 함):
> 1. **OSS 사이트 내 reference 페이지** — `https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/oidc/` (Traefik OSS 문서 트리 안에 있지만 "Traefik Hub Feature" 배너로 명시된 페이지 — 설정 옵션 전체 레퍼런스 보유)
> 2. **Traefik Hub 자체 가이드 페이지** — `https://doc.traefik.io/traefik-hub/api-gateway/secure/middleware/oidc` (RFC 6749 정의 문장 + Getting Started 예제 보유)

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-traefik-forwardauth-alternative]] | D10 — "OSS Traefik 이 OIDC 를 자체 수행할 수 있는가"의 공식 vendor 답. Traefik 의 OIDC middleware 가 유료 Traefik Hub 전용임을 확정하고, oauth2-proxy 제거 가능성의 경계를 긋는다 (OSS 만으로는 oauth2-proxy 대체 불가 — Hub 라이선스 없이는 native OIDC 없음). |

## 출처 / Source

- 원본 URL: https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/oidc/
- 교차 참조 URL (동일 제품군, 유료 API-Gateway 티어): https://doc.traefik.io/traefik-hub/api-gateway/secure/middleware/oidc
- 아카이브 URL: (미수집)
- 저자 / 조직: Traefik Labs
- 발행일: rolling docs. Hub 가이드 페이지 하단에 "Last updated on Jul 1, 2026" 명시. OSS reference 페이지는 날짜 미표기 (rolling reference).
- 마지막 확인일: 2026-07-18

## 왜 저장했는지 / Why archived

P1A sub-sub-branch(`feature-keycloak-traefik-forwardauth-alternative`)의 TODO 항목 "Traefik 자체 OIDC plugin 옵션 검토 (community plugin / Traefik Hub 유료)"에 대한 공식 답. Traefik 이 자체 OIDC 미들웨어를 갖고 있다는 사실은 맞지만, **그것이 무료 OSS 가 아니라 Traefik Hub(유료 API Gateway 제품)에 한정**된다는 것을 공식 vendor 문서로 확정해, "oauth2-proxy 를 제거하고 Traefik 단독으로 OIDC 를 처리하자"는 선택지의 실제 비용(라이선스)을 명시한다.

## 핵심 인용 / Key quotes (verbatim, 5문장)

> [OSS Reference — Middlewares → OIDC, "Traefik Hub Feature" 배너] "This middleware is available exclusively in Traefik Hub. Learn more about Traefik Hub's advanced features."

> [Traefik Hub — Secure Access with OpenID Connect, 본문 첫 문장] "OpenID Connect Authentication is built on top of the OAuth2 Authorization Code Flow (defined in OAuth 2.0 RFC 6749, section 4.1)."

> [Traefik Hub — Secure Access with OpenID Connect, 본문 둘째 문장] "It allows an application to be secured by delegating authentication to an external provider (Keycloak, Okta etc.)"

> [OSS Reference — Configuration Options 표, `session.refresh` 행] "Enables the access token refresh when it expires." (Default: `true`)

> [OSS Reference — 페이지 하단 CTA, "Using Traefik OSS in Production?"] "If you are using Traefik at work, consider adding enterprise-grade API gateway capabilities or commercial support for Traefik OSS."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| THUB-C1 | Traefik 공식 문서(OSS 사이트 내 reference 페이지)는 OIDC 인증 미들웨어가 **Traefik Hub 전용**이며 무료 Traefik OSS 에는 포함되지 않는다고 명시한다 | [OSS Reference, "Traefik Hub Feature" 배너] "This middleware is available exclusively in Traefik Hub. Learn more about Traefik Hub's advanced features." | `official-vendor-doc` | OSS Traefik 사용자가 OIDC 를 native middleware 로 자체 수행할 수 있는지 판단 (D10 직접 근거) | 정확한 Traefik Hub 가격/라이선스 조건, 무료 tier 존재 여부, community(비공식) OIDC plugin 이 별도로 존재하는지 여부는 이 인용만으로 증명 안 됨 |
| THUB-C2 | Traefik Hub 의 OpenID Connect Authentication 은 **OAuth 2.0 RFC 6749 §4.1 Authorization Code Flow** 위에 구축되며, Keycloak/Okta 등 외부 provider 에 인증을 위임하는 방식으로 동작한다 | [Traefik Hub — Secure Access with OpenID Connect] "OpenID Connect Authentication is built on top of the OAuth2 Authorization Code Flow (defined in OAuth 2.0 RFC 6749, section 4.1)." / "It allows an application to be secured by delegating authentication to an external provider (Keycloak, Okta etc.)" | `official-vendor-doc` | Traefik Hub OIDC middleware 의 프로토콜 기반 (Authorization Code Flow, RFC 6749 §4.1) 확인 | PKCE 가 기본 활성인지 (설정 옵션 `pkce` 존재는 OSS reference 표에서 확인되나 Default 값은 `false`), 정확한 token 교환 구현 세부, OIDC discovery cache TTL 은 이 인용으로 증명 안 됨 |
| THUB-C3 | `session.refresh` 설정 옵션(Default: `true`)은 access token 이 만료되었을 때 자동 갱신(refresh)을 활성화한다 | [OSS Reference — Configuration Options 표] "session.refresh" / "Enables the access token refresh when it expires." / Default `true` | `official-vendor-doc` | Traefik Hub OIDC middleware 의 access token 자동 갱신 기본 동작(default-on) 확인 | 정확한 refresh 알고리즘(사전 갱신 vs 401 발생 후 지연 갱신), refresh token 자체 만료 시 처리, refresh 실패 시 재로그인 흐름의 세부 동작은 이 인용으로 증명 안 됨 |
| THUB-C4 | Traefik OSS 공식 문서는 OIDC 같은 기능이 필요한 프로덕션 사용자에게 "enterprise-grade API gateway capabilities" 또는 "commercial support" 추가를 권유한다 — OSS 단독으로는 이 기능 계열이 없다는 벤더 자체 포지셔닝 재확인 | [OSS Reference — 페이지 하단 CTA] "If you are using Traefik at work, consider adding enterprise-grade API gateway capabilities or commercial support for Traefik OSS." | `official-vendor-doc` | Traefik 공식 벤더의 OSS vs Hub 제품 포지셔닝 확인 (THUB-C1 의 보강 근거) | 정확한 가격, 라이선스 조건, "enterprise-grade" 기능의 전체 목록은 이 인용으로 증명 안 됨 (마케팅 CTA 문구이며 기술 스펙 문서가 아님) |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `THUB-C1`: OIDC 인증 미들웨어는 Traefik Hub 전용이며 무료 OSS 에 없다 (D10 의 핵심 근거)
  - `THUB-C2`: Traefik Hub OIDC 는 RFC 6749 §4.1 Authorization Code Flow 기반, 외부 provider 위임 방식
  - `THUB-C3`: `session.refresh` (default true) 가 access token 자동 갱신을 활성화
  - `THUB-C4`: Traefik 벤더 스스로 OSS 사용자에게 상업 지원/Hub 업그레이드를 권유하는 포지셔닝
- 이 자료가 증명하지 않는 것:
  - 정확한 Traefik Hub 가격 / 라이선스 조건 (별도 pricing 페이지 필요)
  - discovery cache TTL, 정확한 refresh 알고리즘(사전 갱신 vs lazy), PKCE 기본 활성 여부
  - Traefik OSS 커뮤니티(비공식) plugin catalog 에 별도 무료 OIDC 대체재가 존재하는지 여부 — 미확인
  - oauth2-proxy 를 완전히 제거해도 되는지의 아키텍처 판단 (이는 별도 결정이며 이 자료는 "Hub 없이는 native OIDC 불가"라는 사실만 제공)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - Traefik Hub 무료 tier(있다면) 의 기능 제한과 실제 라이선스 비용
  - P3A(단일 EC2 + docker-compose) 규모에서 Traefik Hub 라이선스가 경제적으로 타당한지 — oauth2-proxy(완전 무료) 유지 대비 비교

## 메모 / Notes

> 검증되지 않은 내 추론은 여기까지만. 결정 해석은 branch-note 쪽에서.

- D10 결론 후보: "Traefik 자체 OIDC plugin 옵션은 1차 채택 안 함"이라는 기존 branch 결정은 이 자료로 **강하게 뒷받침**된다 — community(무료) plugin 이 아니라 Hub(유료) 전용이므로, 무료 스택 유지가 목표라면 oauth2-proxy 조합이 유일한 무료 경로.
- 추가로 봐야 할 동일 출처 페이지: Traefik Hub pricing 페이지(가격 미확인), Traefik OSS plugin catalog(community OIDC plugin 존재 여부 미확인 — 이 두 문서는 아직 raw 에 없음).

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/traefik-forwardauth-middleware-official]] — Traefik **무료 OSS** 의 `forwardAuth` 미들웨어 (oauth2-proxy 와 조합하는 실질적 무료 경로)
  - [[raw/official-docs/oauth2-proxy-overview-config-official]] — oauth2-proxy 자체 OIDC 처리 (무료 대안)
  - [[raw/official-docs/oauth2-proxy-nginx-integration-official]] — nginx 조합 대비 비교 기준
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/...]]` (생성 시)