Skip to main content

3. The WWW-Authenticate Response Header Field (WWW-Authenticate响应头字段)

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

本规范定义的所有质询 (Challenge) 必须 (MUST) 使用auth-scheme值"Bearer"。此方案必须 (MUST) 后跟一个或多个auth-param值。本规范使用或定义的auth-param属性如下。也可以 (MAY) 使用其他auth-param属性。

可以 (MAY) 包含"realm"属性,以按照HTTP/1.1 [RFC2617] 中描述的方式指示保护范围。"realm"属性禁止 (MUST NOT) 出现多次。

"scope"属性在 [RFC6749] 的第3.3节中定义。"scope"属性是一个空格分隔的、区分大小写的作用域值列表,指示访问所请求资源所需的访问令牌的作用域。"scope"值是实现定义的;没有集中的注册表;允许的值由授权服务器定义。"scope"值的顺序不重要。在某些情况下,"scope"值将在请求具有足够访问作用域的新访问令牌时使用,以利用受保护资源。使用"scope"属性是可选的 (OPTIONAL)。"scope"属性禁止 (MUST NOT) 出现多次。"scope"值用于程序化使用,不应显示给最终用户。

以下是两个示例作用域值;这些分别来自OpenID Connect [OpenID.Messages] 和开放认证技术委员会 (OATC) 在线多媒体授权协议 [OMAP] OAuth 2.0用例:

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

如果受保护资源请求包含访问令牌但认证失败,资源服务器应该 (SHOULD) 包含"error"属性,以向客户端提供访问请求被拒绝的原因。参数值在第3.1节中描述。此外,资源服务器可以 (MAY) 包含"error_description"属性,以向开发人员提供人类可读的解释,该解释不应显示给最终用户。它也可以 (MAY) 包含"error_uri"属性,该属性带有一个绝对URI,标识解释错误的人类可读网页。"error"、"error_description"和"error_uri"属性禁止 (MUST NOT) 出现多次。

"scope"属性的值(在 [RFC6749] 的附录A.4中指定)禁止 (MUST NOT) 包含集合 %x21 / %x23-5B / %x5D-7E 之外的字符(用于表示作用域值)和 %x20(用于作用域值之间的分隔符)。"error"和"error_description"属性的值(在 [RFC6749] 的附录A.7和A.8中指定)禁止 (MUST NOT) 包含集合 %x20-21 / %x23-5B / %x5D-7E 之外的字符。"error_uri"属性的值(在 [RFC6749] 的附录A.9中指定)必须 (MUST) 符合URI-reference语法,因此禁止 (MUST NOT) 包含集合 %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. Error Codes (错误码)​

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

invalid_request (无效请求)​

请求缺少必需参数、包含不支持的参数或参数值、重复相同参数、使用多种方法包含访问令牌,或者格式错误。资源服务器应该 (SHOULD) 使用HTTP 400 (Bad Request) 状态码响应。

invalid_token (无效令牌)​

提供的访问令牌已过期、被撤销、格式错误,或因其他原因无效。资源应该 (SHOULD) 使用HTTP 401 (Unauthorized) 状态码响应。客户端可以 (MAY) 请求新的访问令牌并重试受保护资源请求。

insufficient_scope (作用域不足)​

请求需要的权限高于访问令牌提供的权限。资源服务器应该 (SHOULD) 使用HTTP 403 (Forbidden) 状态码响应,并可以 (MAY) 包含"scope"属性,其中包含访问受保护资源所需的作用域。

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

例如:

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

📋 错误码快速参考​

错误码HTTP状态码含义客户端操作
invalid_request400 Bad Request请求格式错误修复请求格式
invalid_token401 Unauthorized令牌无效/过期获取新令牌后重试
insufficient_scope403 Forbidden权限不足请求更高权限的令牌

WWW-Authenticate响应示例​

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="example",
                  error="insufficient_scope",
                  error_description="The request requires higher privileges",
                  scope="read write"
Last updated on