401 Unauthorized 원인과 해결

Problem

요청이 401 Unauthorized를 반환합니다. 서버는 요청을 받았지만, 대상 리소스에 대한 유효한 인증이 없어 처리를 거부했습니다.

Symptoms

• HTTP 진단의 최종 상태 코드가 401입니다.
• 브라우저는 로그인 창을 띄우거나, API는 {"error":"invalid_token"} 같은 JSON 본문을 반환합니다.
• 인증이 필요한 경로(API, /admin, 비공개 엔드포인트)에서 터지고 공개 홈페이지는 멀쩡합니다.
• 어제는 되던 요청이 오늘 실패합니다 — 토큰이나 세션 만료의 전형적인 징후입니다.

What 401 Actually Means

RFC 9110(§15.5.2)은 401을 “대상 리소스에 대한 유효한 인증 자격 증명이 없어 요청이 적용되지 않았다”고 정의합니다. 서버는 고장 난 것도, 숨는 것도 아닙니다 — 단지 당신이 누구인지 모르거나, 당신이 보낸 증명이 통과하지 못한 것입니다.

사람들이 건너뛰는 부분: 401 응답은 인증 방법을 설명하는 챌린지를 담은 WWW-Authenticate 헤더를 반드시 하나 이상 포함해야 합니다. 이 헤더가 401의 존재 이유입니다. 서버가 “내가 원하는 방식은 이거야 — Basic이든 Bearer든 — 그걸로 다시 시도해”라고 말하는 것이죠. 401인데 WWW-Authenticate 헤더가 없다면 서버가 규격을 어긴 것이고, 실무에서 이건 거의 항상 토큰 기반 API가 진짜 챌린지를 내보내는 대신 만료·변형된 bearer 토큰을 거부했다는 뜻입니다.

이것이 401을 403과 헷갈리게 만드는 지점이고, 둘을 뒤집으면 몇 시간을 날립니다. 401은 인증입니다: 당신이 누구인가. 403은 인가입니다: 당신이 누군지 알지만, 그래도 안 된다. 401의 해법은 자격 증명을 보내는 것입니다. 403에는 자격 증명이 아무 소용 없습니다 — 이미 신원은 확인됐고, 답은 여전히 ‘안 됨’이니까요.

Top 3 Causes

1. 자격 증명 누락·만료·변형 - Authorization 헤더 자체가 없거나, 만료된 액세스 토큰, 교체된 API 키, 형식이 잘못된 JWT. 실제 401의 압도적 다수가 이 경우이고, 그중에서도 만료가 단연 가장 흔한 방아쇠입니다.
2. Authorization 헤더를 벗겨낸 프록시·게이트웨이 - 리버스 프록시, 로드 밸런서, CDN이 오리진에 닿기 전에 Authorization 헤더를 버리거나 다시 씁니다. 그래서 클라이언트는 유효한 자격 증명을 보냈는데도 앱은 인증되지 않은 요청을 봅니다. 스킴이나 호스트가 바뀌는 리다이렉트도 브라우저가 헤더를 떨구게 만듭니다.
3. 시계 오차로 무효화된 시각 기반 토큰 - JWT와 서명 토큰은 iat/exp 클레임을 담습니다. 클라이언트나 서버 시계가 허용 오차를 넘어 어긋나면, 멀쩡한 토큰이 만료됐거나 아직 유효하지 않은 것으로 읽히고, 모든 요청이 401로 돌아옵니다.

Diagnose with DechoNet

• HTTP 진단으로 최종 코드가 정말 401인지 확인하고 — 결정적으로 — 응답 헤더를 읽으세요. WWW-Authenticate 헤더가 있으면 서버가 기대하는 인증 스킴을 알려주고, 없으면 진짜 챌린지가 아니라 토큰이 거부됐다는 쪽을 가리킵니다.

Resolution Checklist

• 401의 WWW-Authenticate 헤더를 읽으세요. 서버가 기대하는 스킴(Basic, Bearer 등)을 알려줍니다. 헤더가 없으면 대개 토큰이 조용히 거부된 것입니다.
• 실제로 자격 증명을 보내고 있는지 확인하세요 — 브라우저 네트워크 탭이나 curl -v로 나가는 Authorization 헤더를 점검하세요.
• 토큰이라면 디코딩해 exp를 확인하세요. 갱신·재발급 후 재시도 — 만료가 가장 유력한 원인입니다.
• 헤더 탈락을 배제하세요: 오리진 직접 요청과 프록시/CDN 경유 요청을 비교하세요. 오리진은 받는데 프록시는 거부하면, 프록시가 Authorization을 떨구는 것입니다.
• 시각 기반 토큰을 쓴다면 클라이언트·서버 시계를 확인하세요 — 허용 오차를 넘는 skew는 멀쩡한 토큰을 무효화합니다.
• 401인지 403인지 확인하세요. 자격 증명이 유효한데도 거부되면, 인증이 아니라 인가(권한) 문제입니다.

When to Escalate

• 유효한 자격 증명이 오리진에 닿았는데도 401이 나오면, 인증 서비스를 소유한 쪽(토큰 발급자, 세션 저장소, IdP)에 넘기세요 — 설정이 어긋났을 수 있습니다.
• 401이 프록시·CDN 뒤에서만 나타나면, 플랫폼 팀에 헤더 전달 규칙을 확인하도록 넘기세요. Authorization 헤더가 전송 중에 사라지고 있는 것입니다.