WWW-Authenticate

사용법

클라이언트가 유효한 자격 증명 없이 보호된 리소스를 요청하면, 서버는 401 상태 코드로 응답하며 WWW-Authenticate 헤더를 포함시킵니다. 이 헤더는 하나 이상의 인증 챌린지를 담으며, 각 챌린지는 스킴과 클라이언트가 유효한 자격 증명을 구성하는 데 필요한 매개변수를 지정합니다.

챌린지를 받은 클라이언트는 선택한 스킴의 형식에 맞춘 자격 증명을 담은 Authorization 헤더와 함께 요청을 다시 보냅니다. 서버는 자격 증명을 검증하고 성공하면 요청된 리소스를 반환합니다.

하나의 응답에 여러 챌린지를 담으면 서버가 여러 스킴을 동시에 제시할 수 있습니다. 클라이언트는 양측이 모두 지원하는 가장 강력한 스킴을 선택합니다. 챌린지는 별도의 헤더 줄에 나타나거나 쉼표로 구분된 하나의 줄에 나타납니다.

프록시 수준 인증에 해당하는 헤더는 Proxy-Authenticate이며, 이는 401이 아닌 407 응답을 유발합니다.

scheme

scheme은 인증 방식을 식별합니다. 등록된 스킴은 IANA가 관리합니다. 실무에서 가장 흔한 스킴은 아래에 설명되어 있습니다.

Basic은 Base64로 인코딩된 username:password 쌍을 보냅니다. 이 스킴은 realm 매개변수와 선택적인 charset 매개변수(보통 UTF-8)를 받습니다.

Bearer는 불투명한 액세스 토큰으로 인증하며, 토큰은 대개 OAuth 흐름을 통해 발급됩니다. 이 스킴은 realm, scope, error 매개변수를 지원합니다. scope 매개변수는 토큰이 담아야 할 권한을 나열합니다. error 매개변수는 invalid_token이나 insufficient_scope 같은 구체적인 실패 사유를 전달합니다.

Digest는 서버가 제공한 nonce로 자격 증명을 해싱하여 Basic을 개선한 것으로, 비밀번호가 평문으로 전달되지 않게 합니다. 필수 매개변수로는 realm, nonce, qop(보호 품질)가 있습니다. 선택적 매개변수로는 algorithm, opaque, stale이 있습니다.

Negotiate는 SPNEGO 기반 인증을 시작하며, 기업 환경에서는 보통 Kerberos나 NTLM이 뒷받침합니다. 협상이 진행 중일 때 이 스킴은 Base64로 인코딩된 SPNEGO 토큰을 담습니다.

realm

realm 매개변수는 보호 영역을 정의하는 선택적 문자열입니다. 이 값은 사용자가 어떤 자격 증명이 필요한지 알아보는 데 도움이 됩니다. 서로 다른 영역을 보호하는 서버는 각 영역에 구별되는 realm 값을 부여합니다.

token68

token68 구문은 HTTP 인증 프레임워크가 허용하는 대체 자격 증명 인코딩입니다. 이 값은 제한된 문자 집합(영숫자와 -, ., _, ~, +, /)을 사용하며 끝에 선택적인 = 패딩이 붙습니다.

예시

Basic 인증으로 리소스를 보호하는 서버가 사용자에게 표시될 realm 이름을 담아 챌린지를 반환합니다.

WWW-Authenticate: Basic realm="Staging Environment"

Bearer 토큰 챌린지가 필요한 scope를 알리고 error 매개변수로 토큰 만료를 알립니다.

WWW-Authenticate: Bearer realm="api.example.re", scope="read write", error="invalid_token"

Digest 챌린지는 서버가 생성한 nonce와 보호 품질 설정을 포함합니다.

WWW-Authenticate: Digest realm="admin@example.re", nonce="7ypf/xlj9XXwfDPEoM4URrv/xwf94BcCAzFZH4GiTo0v", qop="auth", algorithm=SHA-256

여러 스킴을 제시하는 서버가 이를 나열하여 클라이언트가 가장 강력한 선택지를 고르게 합니다.

WWW-Authenticate: Negotiate
WWW-Authenticate: Bearer realm="api.example.re"
WWW-Authenticate: Basic realm="api.example.re"

완전한 Basic 인증 핸드셰이크입니다. 클라이언트가 먼저 자격 증명 없이 보호된 리소스를 요청합니다.

GET /admin HTTP/1.1
Host: example.re

서버가 401과 Basic 챌린지로 응답합니다.

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

클라이언트가 Base64로 인코딩된 username:password 쌍을 담은 Authorization 헤더와 함께 다시 시도합니다.

GET /admin HTTP/1.1
Host: example.re
Authorization: Basic dXNlcjpwYXNz

서버가 자격 증명을 검증하고 리소스를 반환합니다.

HTTP/1.1 200 OK
Content-Type: text/html