WWW-Authenticate

用法

当客户端在没有有效凭据的情况下请求受保护资源时，服务器会以 401 状态码响应并包含 WWW-Authenticate 头部。该头部携带一个或多个认证质询，每个质询指定一种方案以及客户端构造有效凭据所需的任何参数。

收到质询后，客户端会带上包含按所选方案格式化的凭据的 Authorization 头部重新提交请求。服务器验证凭据，成功后返回所请求的资源。

单个响应中的多个质询允许服务器同时提供多种方案。客户端会选择双方都支持的最强方案。质询以单独的头部行或单个逗号分隔的行的形式出现。

用于代理层面认证的等价头部是 Proxy-Authenticate，它触发的是 407 响应而非 401。

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 值。

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="developer@github.com", 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