OAuth 2.0授权框架中文版 [8] - 扩展点

8. 扩展点 - Extensibility

8.1 定义访问令牌类型 - Defining Access Token Types

访问令牌类型可以以如下两种方式定义：

• 注册到访问令牌类型注册表（按照章节11.1中的流程）；
• 使用代表其名称的绝对路径URI；

Access token types can be defined in one of two ways: registered in
the Access Token Types registry (following the procedures in
Section 11.1), or by using a unique absolute URI as its name.

使用URI名称的令牌类型，应限制为特定的供应商的实现，这些实现通常是不通用的，且仅特定于使用它们的资源服务器。

Types utilizing a URI name SHOULD be limited to vendor-specific
implementations that are not commonly applicable, and are specific to
the implementation details of the resource server where they are
used.

其余的令牌类型都应该注册到注册表。类型名称必须遵循type-name范式，如果该类型定义包含HTTP认证方案，则类型名称必须与HTTP认证方案相同（如[RFC2617]所定义），"example"这种类型作为示例中的保留类型。

type-name  = 1*name-char
name-char  = "-" / "." / "_" / DIGIT / ALPHA

All other types MUST be registered. Type names MUST conform to the
type-name ABNF. If the type definition includes a new HTTP
authentication scheme, the type name SHOULD be identical to the HTTP
authentication scheme name (as defined by [RFC2617]). The token type
“example” is reserved for use in examples.

 type-name  = 1*name-char
 name-char  = "-" / "." / "_" / DIGIT / ALPHA

8.2 定义新的端点的参数 - Defining New Endpoint Parameters

在授权或令牌端点使用新的请求或响应参数，需要遵循章节11.2中的流程，在OAuth Parameters注册表中定义和注册。

New request or response parameters for use with the authorization
endpoint or the token endpoint are defined and registered in the
OAuth Parameters registry following the procedure in Section 11.2.

参数名必须遵循param-name范式，并且参数值的语法也需要被明确定义（比如，使用ABNF，或者指向已存在参数的语法的引用）。

Parameter names MUST conform to the param-name ABNF, and parameter
values syntax MUST be well-defined (e.g., using ABNF, or a reference
to the syntax of an existing parameter).

 param-name  = 1*name-char
 name-char   = "-" / "." / "_" / DIGIT / ALPHA

未注册的、限制于供应商的参数扩展通常不具备适用性，并且受限于使用他们的授权服务器。这些参数通常可以加多一个命名前缀，以避免与其它注册值冲突（比如，使用’companyname_'前缀）。

Unregistered vendor-specific parameter extensions that are not
commonly applicable and that are specific to the implementation
details of the authorization server where they are used SHOULD
utilize a vendor-specific prefix that is not likely to conflict with
other registered values (e.g., begin with ‘companyname_’).

8.3 定义新的授权流程 - Defining New Authorization Grant Types

可以通过为grant_type参数指定唯一的绝对URI路径，来定义新的授权流程。如果这个扩展的授权类型需要在令牌端点使用额外的参数，那必须如章节11.2所述，在OAuth Parameters注册表中进行注册。

New authorization grant types can be defined by assigning them a
unique absolute URI for use with the “grant_type” parameter. If the
extension grant type requires additional token endpoint parameters,
they MUST be registered in the OAuth Parameters registry as described
by Section 11.2.

8.4 定义授权端点的响应类型 - Defining New Authorization Endpoint Response Types

新的响应类型可参考章节11.3中的流程，注册到Authorization Endpoint Response Types注册表中。响应类型名称比如遵循如下范式：

response-type  = response-name *( SP response-name )
response-name  = 1*response-char
response-char  = "_" / DIGIT / ALPHA

New response types for use with the authorization endpoint are
defined and registered in the Authorization Endpoint Response Types
registry following the procedure in Section 11.3. Response type
names MUST conform to the response-type ABNF.

response-type  = response-name *( SP response-name )
response-name  = 1*response-char
response-char  = "_" / DIGIT / ALPHA

如果响应类型中包含一个或多个空格，则将其看待为空格分割的响应类型的列表，且顺序无关。多个响应类型的集合按照一种顺序进行注册即可，其它的组合顺序也可以达到相同的效果。

If a response type contains one or more space characters (%x20), it
is compared as a space-delimited list of values in which the order of
values does not matter. Only one order of values can be registered,
which covers all other arrangements of the same set of values.

比如，响应类型"token code"在本规范中并未定义，因此可以将其定义为扩展的响应类型，一旦注册，那与其顺序不同的"code token"就不能再注册为新的响应类型，但这两个顺序不同的值都可以同时用来表明同一种响应类型。

For example, the response type “token code” is left undefined by this
specification. However, an extension can define and register the
“token code” response type. Once registered, the same combination
cannot be registered as “code token”, but both values can be used to
denote the same response type.

8.5 Defining Additional Error Codes - 定义额外的错误码

当进行协议扩展时（访问令牌类型扩展、参数扩展以及授权类型扩展等），如果需要额外的错误码与授权码流程错误码、隐式授权模式错误码、令牌错误响应以及资源访问错误响应等配合使用，那这些额外的错误码需要进行定义。

In cases where protocol extensions (i.e., access token types,
extension parameters, or extension grant types) require additional
error codes to be used with the authorization code grant error
response (Section 4.1.2.1), the implicit grant error response
(Section 4.2.2.1), the token error response (Section 5.2), or the
resource access error response (Section 7.2), such error codes MAY be
defined.

如果扩展的错误码需要与已注册的令牌类型、已注册的端点参数或者一个扩展的授权类型一起使用，那该错误码必须进行注册（遵循章节11.4）。如果与未注册的扩展点配合使用，则可注册也可不注册。

Extension error codes MUST be registered (following the procedures in
Section 11.4) if the extension they are used in conjunction with is a
registered access token type, a registered endpoint parameter, or an
extension grant type. Error codes used with unregistered extensions
MAY be registered.

错误码必须遵循如下ABNF的范式，如果可能，那在该范式前再增加一个标识前缀。比如，为"example"这个扩展参数增加的标识其无效的扩展错误码，则可以命名为"example_invalid"。

error      = 1*error-char
error-char = %x20-21 / %x23-5B / %x5D-7E

Error codes MUST conform to the error ABNF and SHOULD be prefixed by
an identifying name when possible. For example, an error identifying
an invalid value set to the extension parameter “example” SHOULD be
named “example_invalid”.

 error      = 1*error-char
 error-char = %x20-21 / %x23-5B / %x5D-7E