401 Unauthorized

사용법

401 Unauthorized 오류가 도착하면 클라이언트는 요청한 리소스에 접근하려면 먼저 유효한 로그인 자격 증명이 필요함을 이해합니다. 클라이언트는 먼저 로그인하거나, HTTP 요청의 일부로 자격 증명을 제공해야 합니다. 요청과 함께 보낸 기존 자격 증명이 유효하지 않은 경우에도 마찬가지입니다. 이 상태는 자격 증명과 무관하게 해당 동작이 허용되지 않음을 알리는 403 Forbidden과 구별됩니다.

참고

“Unauthorized”라는 이름은 역사적으로 오해를 부릅니다. 401은 클라이언트가 인증되지 않았다는 뜻으로, 자격 증명이 없거나 유효하지 않은 상태입니다. 인증은 되었지만 요청한 동작을 수행할 권한이 없는 사용자는 대신 403 Forbidden을 받습니다. 이 명명은 최초의 HTTP/1.0 명세에서 그대로 이어져 온 것입니다.

서버가 401 Unauthorized 응답을 보낼 때는 WWW-Authenticate 응답 헤더가 포함됩니다. 이는 허용되는 인가 방식을 클라이언트에 알려 줍니다. IANA는 보안 수준과 보급도가 다양한 표준 인증 스킴 목록을 관리합니다. 흔히 쓰이는 인증 스킴은 다음과 같습니다.

Basic

자격 증명을 ID/비밀번호 쌍으로 전송합니다.

Bearer

토큰 인증이라고도 하며, 로그인에 성공한 뒤 서버가 생성해 클라이언트에 반환한 보안 토큰에 의존합니다. 클라이언트는 보호된 리소스에 접근하기 위해 이후 요청에 이 토큰을 담아 보냅니다. 서버는 필요할 때 오류 정보를 포함합니다. 예: WWW-Authenticate: Bearer error=“invalid_token”, error_description=“Token expired”.

Digest

리소스 요청을 인증하는 데 사용되는 챌린지-응답 프로토콜입니다.

HOBA

HTTP Origin-Bound Authentication의 약자로, 서버가 비밀번호를 저장할 필요가 없는 스킴이며 그 덕분에 피싱 공격에 강합니다.

Mutual

양방향 인증이라고도 하며 basic 및 digest 스킴과 비슷하지만, 서버가 클라이언트의 암호화된 비밀번호를 반드시 알고 있다는 점이 다릅니다. 상호작용을 이어가기 전에 클라이언트와 서버가 서로를 인증합니다.

AWS4-HMAC-SHA256

Amazon Web Services AWS S3 API Reference에 인증 정보를 제공하는 인증 알고리즘입니다.

서버는 여러 줄에 걸쳐 또는 쉼표로 구분된 한 줄에 둘 이상의 인증 방식을 명시합니다. 클라이언트는 필요한 자격 증명을 갖추면 Authorization 요청 헤더를 사용해 전송합니다.

SEO 영향

Google 같은 검색 엔진은 401 Unauthorized 상태를 반환하는 URL을 색인하지 않습니다. 이전에 색인되었다가 이 상태 코드를 반환하는 URL은 검색 결과에서 제거됩니다. 이 코드를 반환하는 페이지는 크롤 예산을 낭비하지 않습니다. Googlebot의 속도를 늦추는 용도로 401을 사용하지 마세요. 크롤링 속도를 줄이는 것은 429뿐입니다.

예시

클라이언트가 리소스를 요청하고, 서버는 해당 리소스가 보호되어 있음을 알리기 위해 401 Unauthorized로 응답합니다. 서버는 Basic과 Mutual 인가를 모두 지원한다고 표시합니다. 클라이언트는 Authorization 헤더에 Basic 인증 프로토콜을 사용해 username:password 쌍을 담아 응답합니다. 그러면 서버가 요청한 리소스를 전송합니다.

최초 요청

GET /documents/tech-news HTTP/1.1
Host: example.com

최초 응답

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Documents"
WWW-Authenticate: Mutual

Authorization을 포함한 다음 요청

GET /documents/tech-news HTTP/1.1
Host: example.com
Authorization: Basic RXhhbXBsZTphaQ==

최종 응답

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 25000

<PDF document included in message body>

해결 방법

401 Unauthorized는 서버가 접근을 허용하기 전에 유효한 자격 증명을 요구한다는 뜻입니다.

응답의 WWW-Authenticate 헤더를 확인하세요. 이 헤더는 기대되는 인증 스킴(Basic, Bearer, Digest 등)을 명시합니다. 클라이언트 요청을 요구되는 스킴에 맞추세요. 브라우저 개발자 도구를 열고 네트워크 탭을 선택한 뒤 Response Headers 아래에서 WWW-Authenticate 항목을 찾아보세요.

자격 증명을 검증하세요. 사용자 이름과 비밀번호, API 키, 또는 bearer 토큰이 올바른지 확인하세요. Authorization 헤더 값에 오타나 공백이 하나만 있어도 거부됩니다. 애플리케이션 수준의 문제를 배제하려면 curl -H “Authorization: Bearer “으로 자격 증명만 따로 테스트해 보세요.

토큰이 만료되지 않았는지 확인하세요. Bearer 토큰과 세션 토큰은 수명이 제한되어 있습니다. JWT는 로컬 디버거에서 디코딩해 exp 클레임을 확인하세요. 인증 공급자를 통해 액세스 토큰을 재발급하거나 갱신하세요.

Authorization 헤더 형식을 스킴에 맞추세요. Basic은 Base64로 인코딩된 username:password 쌍을 기대합니다. Bearer는 원시 토큰 문자열을 기대합니다. 형식이 잘못되면 자격 증명이 유효해도 401이 발생합니다. 흔한 실수는 스킴 접두사를 빠뜨리는 것(Bearer 없이 토큰만 보내는 것)입니다.

필요하면 자격 증명을 재발급하세요. API 키를 교체하거나 인가 서버에서 새 토큰을 요청하세요. 폐기되었거나 무효화된 자격 증명은 항상 이 상태를 만듭니다.

브라우저 캐시와 쿠키를 지우세요. 오래된 세션 쿠키나 캐시된 Authorization 헤더가 갱신된 자격 증명과 충돌합니다. 저장된 데이터를 지우고 다시 인증하세요.

서버 측 인증 설정을 점검하세요. Apache의 .htpasswd 파일, nginx의 auth_basic 지시문, .htaccess의 AuthType 규칙이 접근을 제어합니다. 자격 증명 파일 경로, realm 이름, 사용자 항목이 존재하는지 확인하세요. nginx에서는 다음과 같습니다.

auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;

Apache에서는 다음과 같습니다.

AuthType Basic
AuthName "Restricted"
AuthUserFile /etc/apache2/.htpasswd
Require valid-user

OAuth 스코프와 audience 클레임을 확인하세요. 자격 증명은 맞지만 스코프가 잘못되었거나 aud 클레임이 리소스 서버와 일치하지 않는 액세스 토큰도 401을 유발합니다. 토큰이 대상 API용으로 발급되었는지 확인하세요.

코드 참고

.NET

HttpStatusCode.Unauthorized

Rust

http::StatusCode::UNAUTHORIZED

Rails

:unauthorized

http.StatusUnauthorized

Symfony

Response::HTTP_UNAUTHORIZED

Python3.5+

http.HTTPStatus.UNAUTHORIZED

Java

java.net.HttpURLConnection.HTTP_UNAUTHORIZED

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_UNAUTHORIZED

Angular

@angular/common/http/HttpStatusCode.Unauthorized