跳到主要内容

3. WWW-Authenticate 响应头部字段

如果受保护资源请求不包含认证凭据, 或不包含能够访问该受保护资源的访问令牌, 资源服务器必须包含 HTTP "WWW-Authenticate" 响应头部字段; 在响应其他条件时也可以包含它. "WWW-Authenticate" 头部字段使用 HTTP/1.1 [RFC2617] 定义的框架.

本规范定义的所有 challenge 都必须使用 auth-scheme 值 "Bearer". 该方案后必须跟随一个或多个 auth-param 值. 本规范使用或定义的 auth-param 属性如下. 也可以使用其他 auth-param 属性.

可以包含 "realm" 属性, 以 HTTP/1.1 [RFC2617] 中描述的方式表示保护范围. "realm" 属性禁止出现超过一次.

"scope" 属性定义于 [RFC6749] 第 3.3 节. "scope" 属性是由空格分隔且区分大小写的 scope 值列表, 表示访问所请求资源所需的访问令牌范围. "scope" 值由实现定义; 它们没有集中注册表; 允许值由授权服务器定义. "scope" 值的顺序没有意义. 在某些情况下, 请求具有足够访问范围的新访问令牌时会使用 "scope" 值, 以便使用受保护资源. "scope" 属性的使用是可选的. "scope" 属性禁止出现超过一次. "scope" 值旨在供程序使用, 并不用于显示给最终用户.

下面给出两个 scope 值示例; 它们分别取自 OpenID Connect [OpenID.Messages] 和 Open Authentication Technology Committee (OATC) Online Multimedia Authorization Protocol [OMAP] 的 OAuth 2.0 用例:

scope="openid profile email"
scope="urn:example:channel=HBO&urn:example:rating=G,PG-13"

如果受保护资源请求包含访问令牌但认证失败, 资源服务器应当包含 "error" 属性, 向客户端提供访问请求被拒绝的原因. 参数值见第 3.1 节. 此外, 资源服务器可以包含 "error_description" 属性, 为开发者提供人类可读的说明, 该说明并不用于显示给最终用户. 它还可以包含 "error_uri" 属性, 其值为绝对 URI, 标识解释该错误的人类可读网页. "error", "error_description", 和 "error_uri" 属性禁止出现超过一次.

"scope" 属性值 ([RFC6749] 附录 A.4 指定) 禁止包含集合 %x21 / %x23-5B / %x5D-7E 之外的字符来表示 scope 值, 并使用 %x20 作为 scope 值之间的分隔符. "error" 和 "error_description" 属性值 ([RFC6749] 附录 A.7 和 A.8 指定) 禁止包含集合 %x20-21 / %x23-5B / %x5D-7E 之外的字符. "error_uri" 属性值 ([RFC6749] 附录 A.9 指定) 必须符合 URI-reference 语法, 因而禁止包含集合 %x21 / %x23-5B / %x5D-7E 之外的字符.

例如, 对没有认证信息的受保护资源请求的响应:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"

以及对使用过期访问令牌尝试认证的受保护资源请求的响应:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example",
                  error="invalid_token",
                  error_description="The access token expired"

3.1. 错误码​

请求失败时, 资源服务器使用适当的 HTTP 状态码 (通常为 400, 401, 403 或 405) 响应, 并在响应中包含以下错误码之一:

invalid_request : 请求缺少必需参数, 包含不受支持的参数或参数值, 重复同一参数, 使用多种方法包含访问令牌, 或存在其他格式错误. 资源服务器应当以 HTTP 400 (Bad Request) 状态码响应.

invalid_token : 所提供的访问令牌已过期, 已撤销, 格式错误或因其他原因无效. 资源应当以 HTTP 401 (Unauthorized) 状态码响应. 客户端可以请求新的访问令牌并重试受保护资源请求.

insufficient_scope : 该请求需要的权限高于访问令牌所提供的权限. 资源服务器应当以 HTTP 403 (Forbidden) 状态码响应, 并可以包含 "scope" 属性, 指明访问受保护资源所需的范围.

如果请求缺少任何认证信息 (例如客户端不知道需要认证, 或尝试使用不受支持的认证方法), 资源服务器不应包含错误码或其他错误信息.

例如:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"
最后于 更新