헤드램프 OIDC 청구 변경 사항

증상

Headlamp가 ID 공급자에 성공적으로 도달했지만 다음 방법 중 하나로 여전히 실패하는 경우 이 가이드를 사용하십시오.

• 브라우저 로그인이 로그인 페이지로 다시 돌아갑니다.
• Kubernetes API 호출은 401 Unauthorized를 반환합니다.
• 로그인에 성공했지만 모든 보기가 403 Forbidden를 반환합니다.
• IDP가 invalid_request를 사용한 요청을 거부합니다.
• 헤드램프에 로그인 성공이 표시되지만 Kubernetes 권한이 없음이 표시됩니다.

현재 저장소가 오늘 관리하는 것

검사된 저장소는 현재 활성 Headlamp OIDC 통합을 유지하지 않습니다.

• lumie-infra/applications/kustomization.yaml는 headlamp/argocd.yaml를 주석 처리합니다.
• lumie-infra/applications/headlamp/helm-values.yaml에는 기본 차트 계약만 포함되어 있으며 저장소 관리 OIDC 클라이언트 설정은 포함되어 있지 않습니다.

이는 이 페이지가 여전히 2026년 1월 헤드램프 플러스 K3s OIDC 패턴을 사용하는 클러스터에 대한 과거 트러블슈팅 가이드임을 의미합니다. 해당 사고의 정확한 K3s API 서버 플래그가 검사된 저장소에 없습니다.

사건으로 인한 실패사다리

2026년 1월 13일의 실패 순서에는 5개의 고유한 게이트가 있습니다.

게이트	증상	확인된 원인
클라이언트 인증	로그인 루프	헤드램프와 IDP는 token_endpoint_auth_method에 대해 의견이 일치하지 않습니다
사용자 이름 요청	401 Unauthorized	구성된 사용자 이름 클레임이 ID 토큰에서 누락되었습니다.
사용자 이름 접두어	403 Forbidden	K3s는 확인된 사용자 이름 앞에 발급자 URL을 붙였습니다
범위 요청	invalid_request	헤드램프가 IDP 클라이언트에서 허용하지 않은 범위를 요청했습니다
RBAC	"권한 없음"	확인된 Kubernetes 사용자에게는 ClusterRoleBinding이 없습니다

가장 중요한 트리거는 클레임 ​​변경이었습니다. IDP 업그레이드 후 preferred_username는 K3가 예상했던 위치에 더 이상 존재하지 않아 브라우저 로그인에 성공했지만 인증이 실패했습니다.

진단 경로

1. 클라이언트 인증을 먼저 확인하세요

브라우저가 세션에 정착하지 않으면 Headlamp 클라이언트 구성을 IDP 클라이언트 등록과 비교하십시오. client_secret_basic와 client_secret_post 간의 불일치는 Kubernetes가 포함되기 전에 루프를 생성하기에 충분합니다.

2. userinfo 응답뿐만 아니라 ID 토큰도 디코딩합니다.

K3s는 수신한 ID 토큰의 유효성을 검사합니다. 구성된 사용자 이름 클레임이 없으면 IDP가 userinfo를 통해 클레임을 노출하더라도 요청이 실패합니다.

역사적 실패는 바로 이 클래스였습니다:

• 구성된 클레임: preferred_username
• 업그레이드 후 ID 토큰에서 청구 가능: 아니요
• 결과: Kubernetes API 401

3. 확인된 Kubernetes 사용자 이름을 확인하세요.

클레임이 존재하는 경우에도 K3s는 발급자 URL을 사용자 이름 앞에 추가할 수 있습니다. RBAC가 bluemayne에 대해 작성되었지만 Kubernetes가 사용자를 https://issuer.example#bluemayne로 확인하는 경우 인증이 실패합니다.

4. IDP 클라이언트에 대해 요청된 범위를 확인합니다.

헤드램프는 IDP 클라이언트가 현재 허용하는 것보다 더 많은 범위를 요청할 수 있습니다. 이 사건에서는 RBAC가 평가되기도 전에 지원되지 않는 groups 범위에서 OAuth 오류가 발생했습니다.

5. 마지막으로 RBAC를 확인하세요.

인증이 성공하고 토큰 청구가 올바른 경우 최종 확인된 Kubernetes 사용자 이름에 예상되는 ClusterRoleBinding가 있는지 확인하세요.

패턴 수정

각 레이어를 순서대로 수정하여 문제가 해결되었습니다.

1. 토큰 엔드포인트 인증 방법 정렬
2. Kubernetes 사용자 이름 클레임을 ID 토큰에 존재하는 것으로 보장되는 클레임으로 전환합니다.
3. K3s 사용자 이름 접두사를 제거하거나 고려하십시오.
4. IDP 클라이언트가 실제로 허용하는 범위만 요청합니다.
5. 최종 확인된 사용자 이름을 의도한 Kubernetes 역할에 바인딩합니다.

예방

• 마이너 버전 충돌의 경우에도 OIDC 클레임 동작을 수동 검토로 변경할 수 있는 IDP 업그레이드를 적용하세요.
• 신뢰 당사자가 ID 토큰의 유효성을 검사하는 경우 sub와 같은 지속 가능한 클레임을 선호합니다.
• RBAC가 기대하는 정확한 Kubernetes 사용자 이름 형식을 기록해 두십시오.

확인

cd Lumie
sed -n '1,80p' lumie-infra/applications/headlamp/helm-values.yaml
sed -n '1,40p' lumie-infra/applications/kustomization.yaml

kubectl logs -n headlamp deploy/headlamp --tail=200
kubectl auth can-i --as='<resolved-oidc-username>' get pods -A

성공은 repo 상태가 먼저 이해되고, Headlamp 배포 로그에 더 이상 인증 이탈이 표시되지 않으며, 토큰에서 확인된 정확한 Kubernetes 사용자 이름에 예상한 권한이 있음을 의미합니다.

원본 사고 세부사항

원본 사고는 2026년 1월 13일 Renovate가 Authelia를 4.37.x에서 4.38.0으로 올린 뒤 발생했습니다. Upgrade로 profile claim 노출 방식이 바뀌었습니다. K3s는 ID token만 검증했지만, Headlamp/K3s가 기대한 claim은 userinfo로 이동해 있었습니다.

세부사항	값
영향 경로	Headlamp -> Authelia OIDC -> K3s API
사용자 영향	product user outage는 없었고 cluster UI 운영이 막혔습니다
주요 breaking change	preferred_username이 ID token에 안정적으로 존재하지 않았습니다
추가 실패	token endpoint auth method, username prefix, scope, RBAC drift
지속 교훈	IDP minor upgrade도 relying-party breaking change가 될 수 있습니다

Failure ladder는 다섯 계층이었습니다.

계층	증상	수정 방향
claim 위치	K3s가 ID token에서 username claim을 찾지 못했습니다	K3s가 실제로 검증할 수 있는 claim을 사용합니다
client auth method	Kubernetes auth 전에 token exchange가 실패했습니다	token_endpoint_auth_method를 맞춥니다
username 형식	resolved Kubernetes username이 RBAC와 맞지 않았습니다	정확한 prefix/claim shape를 보존합니다
scope	기대한 claim이 요청되거나 발행되지 않았습니다	relying party 요구와 scope를 맞춥니다
RBAC	authentication은 성공했지만 authorization이 실패했습니다	resolved Kubernetes username 또는 group을 bind합니다

비슷한 문제가 다시 나오면 Headlamp UI 증상부터 보지 않습니다. 먼저 token을 decode하고, ID token claim을 K3s OIDC flag와 비교한 뒤, 정확한 resolved username으로 RBAC를 검증합니다.