OAuth 2.0中文译本 (三)

6.2 WWW-Authenticate响应头部字段

 

如果对于受保护资源的请求不包含验证证书，包含一个无效的访问令牌，或格式不正确，那么资源服务器必须包含一个HTTP “WWW-Authenticate”响应头部字段。这个“WWW-Authenticate”头部字段使用[RFC2617]定义的框架，如下所示：

 

challenge = "OAuth2" [ RWS 1#param ]

 

param = scope /

error / error-desc / error-uri /

( token "=" ( token / quoted-string ) )

 

scope = "scope" "=" <"> scope-v *( SP scope-v ) <">

scope-v = 1*quoted-char

 

quoted-char = ALPHA / DIGIT /

"!" / "#" / "$" / "%" / "&" / "'" / "(" / ")" /

"*" / "+" / "-" / "." / "/" / ":" / "<" / "=" /

">" / "?" / "@" / "[" / "]" / "^" / "_" / "`" /

"{" / "|" / "}" / "~" / "\" / "," / ";"

 

error = "error" "=" quoted-string

error-desc = "error_description" "=" quoted-string

error-uri = "error_uri" = <"> URI-reference <">

 

“scope”属性是一个空格隔开的作用域值的列表，表明了为了访问受保护资源所需要访问令牌作用域。“scope”属性一定不能出现多次。

 

如果对于受保护资源的请求包含一个访问令牌并且验证失败了，那么资源服务器应该包含“error”属性来向客户端提供为何访问请求被拒绝的原因。参数值在6.2.1中描述。另外，资源服务器可能包含“error_description”属性来提供一个人类可读的解释，或者包含“error-uri”属性用一个绝对URI来指定一个用于解释错误的人类可读的网页。“error”、“error_description”和“error-uri”属性一定不能出现多次。

 

例如，对于一个缺少验证的受保护资源请求的响应：

 

HTTP/1.1 401 Unauthorized

WWW-Authenticate: OAuth2

 

对于一个使用过期访问令牌尝试验证的受保护资源请求的响应：

 

HTTP/1.1 401 Unauthorized

WWW-Authenticate: OAuth2

error="invalid_token",

error_description="The access token expired"

 

6.2.1 错误码

 

当一个请求失败时，资源服务器使用恰当的HTTP状态码（典型的如400、401或403）进行响应，并且在响应中包含下列错误码之一：

 

invalid_request

请求缺少某个必需参数，包含一个不支持的参数或参数值，参数重复，使用多种方式包含访问令牌，或者请求格式不正确。资源服务器应该使用HTTP 400（Bad Request）状态码进行响应。

 

invalid_token

提供的访问令牌是过期的、已撤销的、格式不正确的，或由于其它原因是无效的。资源服务器应该使用HTTP 401（Unauthorized）状态码进行响应。客户端可能请求一个新的访问令牌并重试受保护资源请求。

 

insufficient_scope

请求需要比访问令牌所提供的权限更高的权限。资源服务器应该使用HTTP 403（Forbidden）状态码进行响应并且包含“scope”属性，带上访问该受保护资源必需的作用域。

 

[[增加扩展错误码的机制]]

 

如果请求中缺少任何验证信息（即客户端没有意识到验证是必需的或尝试使用一个不支持的验证方法），那么资源服务器不应该包含一个错误码和其它错误信息。

 

例如：

 

HTTP/1.1 401 Unauthorized

WWW-Authenticate: OAuth2

 

7. 扩展

 

7.1 定义新的客户端证书类型

 

[[待定]]

 

7.2 定义新的Endpoint参数

 

希望在终端用户授权endpoint和令牌endpoint上定义新的请求和响应参数的应用，应该使用下列两种方式之一：在参数注册表中注册（遵从9.1节描述的流程），或使用“x_”参数名前缀。

 

使用“x_”参数名前缀的参数必须局限于那些不会被广泛应用的针对厂商特性的扩展，并且特定于授权服务器使用场景的实现细节。所有其它参数必须被注册，并且一定不能使用“x_”参数名前缀。

 

参数名必须遵从param-name的ABNF，并且参数值语法必须被规范地定义（例如，使用ABNF，或者引用到现存参数的语法）。

 

param-name = 1*name-char

name-char = "-" / "." / "_" / DIGIT / ALPHA

 

7.3 定义新的头部字段参数

 

希望在OAuth “WWW-Authenticate”头部字段中定义新参数的应用必须在参数注册表中进行注册，遵从9.1节描述的流程。

 

参数名必须遵从param-name的ABNF并且不能以“x_”开头。参数值必须遵从param-value的ABNF并且语法必须被规范地定义（例如，使用ABNF，或者引用到现存参数的语法）。

 

param-value = quoted-value | quoted-string

 

7.4 定义新的访问许可类型

 

断言访问许可类型允许授权服务器接受其它未规定的访问许可。希望定义其它访问许可类型的应用能够通过利用新的或现存的断言类型和格式进行实现。

 

8. 安全考虑

 

[[待定]]

 

9. IANA事项

 

9.1 OAuth参数注册表

 

本文档设立参数注册表。

 

用于终端用户授权endpoint的请求、终端用户授权endpoint的响应、令牌endpoint的请求、令牌endpoint的响应或“WWW-Authenticate”头部字段的多余参数，在一个或多个“指派专家”（由IESG或他们的代理机构指定）的指导下进行注册，遵从所需的规范（使用[RFC5226]的术语）。然而，为了允许在发布之前对值进行分配，“指派专家”们一旦认同这样的一个规范能够发布，可能就立即批准注册。

 

注册请求应该发送给[待定]@ietf.org邮件组进行评审和讨论，使用恰当的标题（如“Request for parameter: example”）。[[RFC-EDITOR注解：邮件组名称应该在与IESG和IANA磋商后确定。建议名称：oauth-ext-review。]]

 

在14天之内，“指派专家”们会批准或拒绝注册请求，并将结果告知邮件组和IANA。拒绝的决定应该包含一个解释，并且，如果可行的话，应该包含如何进行修改的建议。在21天以上未确定的注册请求会交由IESG处理（使用[e-mail]邮件组）。

 

9.1.1 注册模板

 

Parameter name: 请求的名称（例如“example”）。

 

Parameter usage location: 参数能够被使用的位置。可能的位置包括：终端用户授权endpoint的请求、终端用户授权endpoint的响应、令牌endpoint的请求、令牌endpoint的响应或“WWW-Authenticate”头部字段。

 

Change controller: 对于标准轨道的RFC，写明“IETF”。对于其它规范，使用负责机构的名称。其它细节（例如，邮编地址，电子邮件地址，主页URI）也可以包含。

 

Specification document(s): 对规定参数的文档引用，可取的方式是包含一个能够获取到文档拷贝的URI。对于相关章节的标示也可以包含，但不是必需的。

 

Related information: 可选地，对于包含更多相关信息的额外文档的引述。

 

9.1.2 例子

 

下面是对于本规范定义的“scope”参数的参数注册请求：

 

Parameter name: scope

 

Parameter usage location: The end-user authorization endpoint

request, the end-user authorization endpoint response, the token

endpoint request, the token endpoint response, and the

"WWW-Authenticate" header field.

 

Change controller: IETF

 

Specification document(s): [[ this document ]]

 

Related information: None

 

 

附录 翻译略。