511 Network Authentication Required: 캡티브 포털

Problem

여는 사이트마다 같은 “약관 동의” 또는 “로그인” 페이지로 리다이렉트되거나, 브라우저가 아닌 클라이언트 — apt, git, 모바일 앱 — 가 파싱할 수 없는 쓰레기를 받고 멈추거나 실패합니다. 어딘가에서 응답이 511 Network Authentication Required를 실어 나릅니다. 당신이 요청한 사이트는 답한 적이 없습니다. 당신이 앉아 있는 네트워크가 사이트를 대신해 답했습니다.

Symptoms

• 호텔·공항·카페·컨퍼런스 Wi-Fi에 막 접속했고, 어떤 종류든 첫 요청이 포털로 우회됩니다.
• 커맨드라인 도구나 앱이 이상하게 실패합니다 — JSON·이미지·204를 기대한 자리에 HTML 로그인 페이지가 옵니다.
• 브라우저에 “네트워크에 로그인” 시트가 뜨거나, 입력한 페이지가 아닌 페이지가 나옵니다.
• 같은 URL이 셀룰러의 폰에서는, 또는 포털 없는 네트워크에서는 멀쩡히 됩니다.
• 드물게: 당신이 운영하는 API나 오리진이 스스로 511을 내보내고, 클라이언트가 이걸 인증 실패로 취급합니다.

What This Error Actually Means

511 Network Authentication Required(RFC 6585 §6)는 클라이언트가 네트워크 접근을 얻기 위해 인증해야 한다는 뜻입니다 — 리소스가 아니라 네트워크에요. 이 코드는 가로채는 프록시 — 방금 접속한 Wi-Fi의 캡티브 포털 — 가 생성하도록 설계되었고, RFC는 오리진 서버가 이걸 생성하면 안 된다(SHOULD NOT)고 명시합니다. 당신의 요청은 목적지에 닿은 적이 없습니다. 경로 위의 무언가가 그 자리에서 대신 답하며 먼저 로그인하라고 말한 것입니다.

이 코드는 특정한 난장판을 고치려고 생겼습니다. 캡티브 포털은 예전에 당신 요청을 가로채 콘텐츠 자리에 로그인 페이지를 넣고 200 OK를 반환하곤 했습니다. 그건 프로토콜 수준의 거짓말이고, 고약한 결과 두 가지를 낳았습니다. 경로상의 캐시가 그 로그인 페이지를 진짜 리소스의 URL 아래 저장할 수 있어서, 인증한 뒤에도 계속 로그인 페이지가 나왔습니다. 그리고 브라우저를 노려보는 사람이 아닌 클라이언트 — 패키지 매니저, 백그라운드 동기화 앱, 모니터링 점검 — 는 요청한 적 없는 HTML을 받아, 진짜 원인과 한참 동떨어진 방식으로 실패했습니다. 511은 그 거짓말을 정직하고 기계가 읽을 수 있는 신호로 바꿉니다: 당신은 네트워크 관문 뒤에 있으니 먼저 통과하라. 같은 이유로 RFC 6585는 **511 응답을 캐시가 저장하면 안 된다(MUST NOT)**고 요구합니다.

새겨둘 핵심: 511은 주소창의 웹사이트에 관한 것이 거의 아닙니다. 당신과 그 웹사이트 사이의 도로에 관한 것입니다. 그래서 수정은 절대 사이트 쪽이 아니고 당신 애플리케이션 안에도 좀처럼 없습니다 — 네트워크가 통행료를 내라는 것입니다.

Top 3 Causes

1. 캡티브 포털 뒤에 있는데 아직 인증하지 않았다. 약관 동의, 객실 번호 입력, 광고 시청 뒤에야 트래픽을 넘겨주는 호텔·공항·카페·기차·컨퍼런스 Wi-Fi. 실제 511의 압도적 다수가 이것입니다. 포털 로그인을 마치기 전까지는 모든 요청 — OS가 조용히 던지는 captive.apple.com, connectivitycheck.gstatic.com/generate_204 같은 캡티브 포털 프로브 포함 — 이 가로채집니다.
2. 투명 프록시나 회사 프록시가 접근을 막는다. 일부 관리형 네트워크는 프록시가 인라인으로 앉아, 트래픽을 내보내기 전에 네트워크 계층 인증을 요구합니다. 당신이 직접 설정한 프록시(그건 407을 반환)와 달리 이건 당신이 고르지 않았으므로 511을 말합니다. 게스트 VLAN, 교육 네트워크, 잠긴 회사 세그먼트에서 흔합니다.
3. 오리진이 511을 401처럼 오용한다. 드물지만 있습니다: 프레임워크가 개발자에게 아무 상태 코드나 반환하게 해주고, 누군가 “인증 필요”를 찾다 401 대신 511을 집으면, 포털이 전혀 없는 정상 클라이언트가 평범한 앱 엔드포인트로부터 네트워크 관문 신호를 받게 됩니다. RFC가 오리진은 이러면 안 된다(SHOULD NOT)고 하는 이유가 바로 이것입니다 — 하류의 모든 캡티브 포털 탐지를 망가뜨리니까요.

Diagnose with DechoNet

• HTTP 진단은 당신의 캡티브 포털 뒤에 있지 않은 우리 서버에서 URL을 가져옵니다. 우리에게서는 사이트가 정상 200(또는 진짜 상태)을 반환하는데 당신 브라우저는 로그인 페이지로 우회된다면, 관문은 목적지가 아니라 당신의 로컬 네트워크입니다 — 사이트 디버깅을 멈추고 포털 로그인을 찾으세요.
• 같은 진단이 오리진이 실제로 보내는 상태 코드와 헤더를 보여줍니다. 우리 요청도 511로 돌아오면, 그건 오리진 자체가 이 코드를 내보내는 드문 경우 — 포털에 로그인할 게 아니라 서버에서 고칠 진짜 오설정입니다.
• 서로 무관한 호스트명 두어 개로 돌려보세요. 우리 서버에서는 모든 외부 사이트가 정상인데 당신 브라우저에서는 전부 실패한다면, 그 균일함이 사이트별 문제가 아니라 연결 전체를 가로채는 캡티브 포털의 서명입니다.

Resolution Checklist

• 평문 HTTP 사이트를 브라우저로 열어 포털을 유발한다. 많은 포털이 암호화되지 않은 요청에만 로그인을 주입합니다. 알려진 HTTP 엔드포인트로 이동하면(또는 OS의 캡티브 포털 탐지가 돌게 두면) “네트워크에 로그인” 페이지가 나타나 인증할 수 있습니다.
• 네트워크 로그인을 완료한 뒤 재시도한다. 약관 동의, 객실·접속 코드 입력, 또는 결제. 포털이 당신 MAC 주소를 풀어주면 트래픽이 정상으로 흐르고 511이 멈춥니다.
• 사이트가 아니라 네트워크임을 확인한다. 외부 HTTP 진단을 돌리세요. 밖에서는 정상 + 브라우저에서는 실패 = 로컬 캡티브 포털. 밖에서도 같은 511 = 오리진 오설정.
• 당신 오리진이 511을 반환한다면 401로 바꾼다. 자격증명을 원하는 앱 엔드포인트는 511이 아니라 WWW-Authenticate 헤더를 단 401 Unauthorized를 보내야 합니다. 511은 실제 네트워크 관문에만 쓰세요. 오리진에서 내보내면 당신 클라이언트의 캡티브 포털 탐지를 오염시킵니다.
• 포털에 갇힌 비브라우저 클라이언트는 브라우저에서 먼저 인증한다. 패키지 매니저나 앱은 로그인 폼을 채울 수 없습니다. 같은 머신의 브라우저에서 포털을 통과한 뒤 도구를 다시 실행하면, 이제 열린 네트워크 경로를 물려받습니다.
• 511 응답이 캐시되지 않게 한다. 포털을 운영한다면 511이 RFC대로 no-store 의미를 지니게 하세요. 이미 인증한 사용자에게 캐시된 네트워크 관문 페이지를 주는 것은 그 자체로 지원 티켓입니다.

When to Escalate

• 관리형 네트워크에 있는데 포털 로그인에 아예 닿을 수 없다면, Wi-Fi 운영자에게 에스컬레이션하세요 — 포털 자체의 웹 서버가 죽었거나, DNS 가로채기가 로그인 흐름이 의존하는 프로브 URL을 잘못 보내고 있을 수 있습니다.
• 당신이 통제하지 않는 오리진이 포털도 없는데 511을 반환한다면, 운영자에게 상태 코드 버그로 신고하세요: 그건 캡티브 포털 탐지를 망가뜨리고 엔드포인트에 닿는 모든 비브라우저 클라이언트를 혼란시킵니다.