OAuth 2.0授权框架中文版 [3] - 协议端点

3. 协议端点 - Protocol Endpoints

授权过程中使用了两个授权服务器端点：

• 授权端点： 用于客户端通过用户代理（译者注：一般指浏览器）重定向的方式来向资源所有者索要授权许可。

• 令牌端点： 用于客户端通过授权许可去交换访问令牌，通常会同时进行客户端认证。

The authorization process utilizes two authorization server endpoints
(HTTP resources):

o Authorization endpoint - used by the client to obtain
authorization from the resource owner via user-agent redirection.

o Token endpoint - used by the client to exchange an authorization
grant for an access token, typically with client authentication.

同时也需要使用一个客户端端点：

• 重定向端点： 授权服务器通过资源所有者的用户代理，将授权凭证返回给客户端（译者注：重定向的方式）。

As well as one client endpoint:

o Redirection endpoint - used by the authorization server to return
responses containing authorization credentials to the client via
the resource owner user-agent.

并非每一种授权类型都需要使用这些端点，而扩展授权类型可能根据需要定义其它的端点。

Not every authorization grant type utilizes both endpoints.
Extension grant types MAY define additional endpoints as needed.

3.1 授权端点 - Authorization Endpoint

授权端点用于与资源所有者交互以获取授权许可。授权服务器必须先验证资源所有者的身份，其具体的验证方式（如用户名密码登录、session cookies等）超出了本规范的讨论范围。

The authorization endpoint is used to interact with the resource
owner and obtain an authorization grant. The authorization server
MUST first verify the identity of the resource owner. The way in
which the authorization server authenticates the resource owner
(e.g., username and password login, session cookies) is beyond the
scope of this specification.

客户端通过何种方式来获取授权端点的位置超出了本规范的讨论范围，但一般会在服务目录里提供。

The means through which the client obtains the location of the
authorization endpoint are beyond the scope of this specification,
but the location is typically provided in the service documentation.

授权端点的URI可能包含"application/x-www-form-urlencoded"的查询组件（[RFC3986] 章节3.4）（译者注：query component 是URI以’?‘开始，以’#‘结束的部分），如果有额外的查询参数，则必须包含这部分，相反，授权端点不得包含fragment组件（译者注：以’#'开始直到URI尾部的部分）。

The endpoint URI MAY include an “application/x-www-form-urlencoded”
formatted (per Appendix B) query component ([RFC3986] Section 3.4),
which MUST be retained when adding additional query parameters. The
endpoint URI MUST NOT include a fragment component.

由于发往授权端点的请求涉及用户认证和明文的凭证传输（在HTTP响应中），因此授权服务器必须如章节1.6所述使用TLS。

Since requests to the authorization endpoint result in user
authentication and the transmission of clear-text credentials (in the
HTTP response), the authorization server MUST require the use of TLS
as described in Section 1.6 when sending requests to the
authorization endpoint.

授权服务器提供的授权端点必须支持HTTP "GET"类型的请求 [RFC2616]，同时也可以选择支持"POST"类型的请求。

The authorization server MUST support the use of the HTTP “GET”
method [RFC2616] for the authorization endpoint and MAY support the
use of the “POST” method as well.

必须忽略参数值为空或未定义的参数，请求或响应中的参数名不得重复。

Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server MUST ignore
unrecognized request parameters. Request and response parameters
MUST NOT be included more than once.

3.1.1 响应类型 - Response Type

授权端点用于授权码模式以及隐式授权模式，客户端通过提供如下参数来告知授权服务器其所需的授权模式：

response_type
要求。若为授权码模式，则如章节4.1.1所述，传递“code”值，若为隐式授权模式，则如4.2.1节所述，传递“token”值，或者如8.4章节所述，为扩展类型。

The authorization endpoint is used by the authorization code grant
type and implicit grant type flows. The client informs the
authorization server of the desired grant type using the following
parameter:
response_type
REQUIRED. The value MUST be one of “code” for requesting an
authorization code as described by Section 4.1.1, “token” for
requesting an access token (implicit grant) as described by
Section 4.2.1, or a registered extension value as described by
Section 8.4.

扩展的响应类型可能会包含由空格分隔的值的列表，列表中的值是顺序无关的（如，“a b"等同于"b a”），这些组合形式响应类型的意义在其各自的规范中有定义。

Extension response types MAY contain a space-delimited (%x20) list of
values, where the order of values does not matter (e.g., response
type “a b” is the same as “b a”). The meaning of such composite
response types is defined by their respective specifications.

如果授权请求中未包含"response_type"参数，或者其值是错误的，则授权服务器需如章节4.1.2.1所述，返回相应的错误响应。

If an authorization request is missing the “response_type” parameter,
or if the response type is not understood, the authorization server
MUST return an error response as described in Section 4.1.2.1.

3.1.2 重定向端点 - Redirection Endpoint

当授权服务器完成与资源所有者的交互后，授权服务器会将资源所有者的user-agent重定向回客户端，这个重定向的端点是客户端注册时发布的端点，或是在授权请求时发送的端点。

After completing its interaction with the resource owner, the
authorization server directs the resource owner’s user-agent back to
the client. The authorization server redirects the user-agent to the
client’s redirection endpoint previously established with the
authorization server during the client registration process or when
making the authorization request.

重定向的URI必须是[RFC3986]中定义的绝对URI，如果需要添加额外的参数，则该端点需要包含"application/x-www-form-urlencoded"格式的查询组件([RFC3986]章节3.4)，该端点不可包含fragement组件。

The redirection endpoint URI MUST be an absolute URI as defined by
[RFC3986] Section 4.3. The endpoint URI MAY include an
“application/x-www-form-urlencoded” formatted (per Appendix B) query
component ([RFC3986] Section 3.4), which MUST be retained when adding
additional query parameters. The endpoint URI MUST NOT include a
fragment component.

3.1.2.1 授权请求保密性 - Endpoint Request Confidentiality

当请求的响应类型为"code"或"token"，或者重定向的请求需要在公网传递敏感的凭证数据时，必须要求重定向端点按章节1.6所述使用TLS连接。由于在编写本规范时，对开发者而言部署TLS是相对艰难的任务，因此本规范并未做强制要求。但如果TLS不可用，那授权服务器需要在重定向到该端点前，提示资源所有者该动作并不安全。(如，在授权请求时展示一个警告消息)

The redirection endpoint SHOULD require the use of TLS as described
in Section 1.6 when the requested response type is “code” or “token”,
or when the redirection request will result in the transmission of
sensitive credentials over an open network. This specification does
not mandate the use of TLS because at the time of this writing,
requiring clients to deploy TLS is a significant hurdle for many
client developers. If TLS is not available, the authorization server
SHOULD warn the resource owner about the insecure endpoint prior to
redirection (e.g., display a message during the authorization
request).

传输层的安全缺陷，会严重影响客户端及其授权访问的受保护资源的安全，当客户端将授权过程作为其最终用户认证的一种方式时(如第三方登录服务)，保证传输层安全会尤为重要。

Lack of transport-layer security can have a severe impact on the
security of the client and the protected resources it is authorized
to access. The use of transport-layer security is particularly
critical when the authorization process is used as a form of
delegated end-user authentication by the client (e.g., third-party
sign-in service).

3.1.2.2 注册条件 - Registration Requirements

授权服务器要求如下类型的客户端登记他们的重定向端点：

• 公开客户端

• 使用隐式授权模式的非公开客户端

The authorization server MUST require the following clients to
register their redirection endpoint:

o Public clients.

o Confidential clients utilizing the implicit grant type.

授权服务器要求所有客户端在使用授权端点前，登记他们的重定向端点。

The authorization server SHOULD require all clients to register their
redirection endpoint prior to utilizing the authorization endpoint.

授权服务器应该要求客户端提供完成的重定向URI(客户端可能会使用"state"参数来防范CSRF)。如果要求注册完整的重定向的URI并不现实，那授权服务器必须要求注册URI scheme、authority和path(只允许客户端动态的修改重定向URI的查询组件的参数)。

The authorization server SHOULD require the client to provide the
complete redirection URI (the client MAY use the “state” request
parameter to achieve per-request customization). If requiring the
registration of the complete redirection URI is not possible, the
authorization server SHOULD require the registration of the URI
scheme, authority, and path (allowing the client to dynamically vary
only the query component of the redirection URI when requesting
authorization).

授权服务器允许客户端注册多个重定向端点。

The authorization server MAY allow the client to register multiple
redirection endpoints.

缺乏对重定向URI的注册管理机制，可能导致如10.15章节所描述的攻击者使用授权端点作为公共转向器的问题(译者注：不准确)。

Lack of a redirection URI registration requirement can enable an
attacker to use the authorization endpoint as an open redirector as
described in Section 10.15.

3.1.2.3 动态配置 - Dynamic Configuration

在如下情况下，客户端需要在授权请求时携带"redirect_uri"参数：

• 注册了多个重定向端点
• 注册了重定向端点的某部分(译者注：如上所述，并未注册完整的URI)
• 没有注册重定向端点

If multiple redirection URIs have been registered, if only part of
the redirection URI has been registered, or if no redirection URI has
been registered, the client MUST include a redirection URI with the
authorization request using the “redirect_uri” request parameter.

如果注册过重定向URI，那当授权请求中包含重定向URI(或URI组件)时，授权服务器必须将接收到的值与注册值进行对比(如[RFC3986]第6章节所定义)，如果客户端注册的是完整的重定向URI，那授权服务器应如[RFC3986]第6.2.1章节所述对其进行简单的字符串对比校验。

When a redirection URI is included in an authorization request, the
authorization server MUST compare and match the value received
against at least one of the registered redirection URIs (or URI
components) as defined in [RFC3986] Section 6, if any redirection
URIs were registered. If the client registration included the full
redirection URI, the authorization server MUST compare the two URIs
using simple string comparison as defined in [RFC3986] Section 6.2.1.

3.1.2.4 无效的端点 - Invalid Endpoint

如果授权请求因为丢失或包含无效、不匹配的重定向URI而导致失败，则授权服务器必须提示资源所有者失败原因，而非自动将user-agent重定向到无效的URI。

If an authorization request fails validation due to a missing,
invalid, or mismatching redirection URI, the authorization server
SHOULD inform the resource owner of the error and MUST NOT
automatically redirect the user-agent to the invalid redirection URI.

3.1.2.5 端点内容 - Endpoint Content

客户端的重定向请求的响应通常是HTML的形式，由user-agent处理，如果该HTML响应是直接作为重定向请求的结果，那么该HTML中包含的脚本将有权限访问该重定向URI及其包含的凭证数据。

The redirection request to the client’s endpoint typically results in
an HTML document response, processed by the user-agent. If the HTML
response is served directly as the result of the redirection request,
any script included in the HTML document will execute with full
access to the redirection URI and the credentials it contains.

3.2 Token端点 - Token Endpoint

Token端点用于让客户端获取access token，可以通过出示授权许可和refresh token两种形式。除隐式授权模式外(直接签发access token)，其余授权模式都会使用token端点。

The token endpoint is used by the client to obtain an access token by
presenting its authorization grant or refresh token. The token
endpoint is used with every authorization grant except for the
implicit grant type (since an access token is issued directly).

关于客户端如何获取token端点的地址的问题，超出了该文档的讨论范围，但一般是由服务目录提供。

The means through which the client obtains the location of the token
endpoint are beyond the scope of this specification, but the location
is typically provided in the service documentation.

该端点的URI如需携带参数，则需包含"application/x-www-form-urlencoded"格式的查询组件([RFC3986] 3.4章节)，该端点不允许包含fragment组件。

The endpoint URI MAY include an “application/x-www-form-urlencoded”
formatted (per Appendix B) query component ([RFC3986] Section 3.4),
which MUST be retained when adding additional query parameters. The
endpoint URI MUST NOT include a fragment component.

由于访问token端点的请求或响应都涉及明文凭证的传输，因此必须对token端点使用1.6章节所述的TLS连接。

Since requests to the token endpoint result in the transmission of
clear-text credentials (in the HTTP request and response), the
authorization server MUST require the use of TLS as described in
Section 1.6 when sending requests to the token endpoint.

客户端必须使用"POST"方式来发起获取access token的请求。

The client MUST use the HTTP “POST” method when making access token
requests.

当参数值为空或是未定义的参数时，授权服务器必须忽略该参数，请求或响应中的参数不得重复。

Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server MUST ignore
unrecognized request parameters. Request and response parameters
MUST NOT be included more than once.

3.2.1 客户端认证 - Client Authentication

非公开客户端或其它签发了客户端凭证的客户端，在访问token端点时必须如章节2.3所述由授权服务器进行客户端认证，客户端认证的作用是：

• 确保refresh token和授权码确实是由签发的客户端来使用的。当在不受信的链路传输授权码，或者未注册完整的重定向URI的场景下，客户端验证尤为重要。

• 通过禁用客户端或修改客户端的凭证来恢复被入侵的客户端，从而防止攻击者滥用窃取的refresh token。修改一组客户端凭证显然比撤销整组刷新令牌要快得多。

• 实施认证管理的最佳实践，是定期进行凭证的轮换。整套刷新令牌的轮换可能具有挑战性，而单套客户端凭证的轮换则容易得多。

Confidential clients or other clients issued client credentials MUST
authenticate with the authorization server as described in
Section 2.3 when making requests to the token endpoint. Client
authentication is used for:

o Enforcing the binding of refresh tokens and authorization codes to
the client they were issued to. Client authentication is critical
when an authorization code is transmitted to the redirection
endpoint over an insecure channel or when the redirection URI has
not been registered in full.

o Recovering from a compromised client by disabling the client or
changing its credentials, thus preventing an attacker from abusing
stolen refresh tokens. Changing a single set of client
credentials is significantly faster than revoking an entire set of
refresh tokens.

o Implementing authentication management best practices, which
require periodic credential rotation. Rotation of an entire set
of refresh tokens can be challenging, while rotation of a single
set of client credentials is significantly easier.

当向token端点发送请求时，客户端必须使用"client_id"参数来标识自己，当grant_type为authorization_code时，未认证的客户端必须发送"client_id"参数来防止它接收到其它client的code，这可以保证客户端不会被替换code(没有为受保护的资源提供额外的安全保障)。

A client MAY use the “client_id” request parameter to identify itself
when sending requests to the token endpoint. In the
“authorization_code” “grant_type” request to the token endpoint, an
unauthenticated client MUST send its “client_id” to prevent itself
from inadvertently accepting a code intended for a client with a
different “client_id”. This protects the client from substitution of
the authentication code. (It provides no additional security for the
protected resource.)

3.3 访问令牌的范围 - Access Token Scope

授权和令牌端点允许客户端通过使用"scope"参数来声明其访问范围，相应的，授权服务器也通过"scope"相应参数来指明为客户端签发的access token的授权访问范围。

The authorization and token endpoints allow the client to specify the
scope of the access request using the “scope” request parameter. In
turn, the authorization server uses the “scope” response parameter to
inform the client of the scope of the access token issued.

scope参数的值是空格分割且大小写敏感的字符串，这些字符串的值是有授权服务器定义的，如果scope的值包含多个空格分割的字符串，那这些字符串值是顺序无关的，并且所有的字符串都会为请求的作用域增加额外的访问范围。

The value of the scope parameter is expressed as a list of space-
delimited, case-sensitive strings. The strings are defined by the
authorization server. If the value contains multiple space-delimited
strings, their order does not matter, and each string adds an
additional access range to the requested scope.

scope = scope-token ( SP scope-token )
scope-token = 1( %x21 / %x23-5B / %x5D-7E )

授权服务器可以根据授权服务器策略或资源所有者的指示，完全或部分的忽略客户端请求的作用域，如果发出的访问令牌范围与客户端请求的范围不同，则授权服务器必须包含"scope"响应参数，以告知客户端实际授予的范围。

The authorization server MAY fully or partially ignore the scope
requested by the client, based on the authorization server policy or
the resource owner’s instructions. If the issued access token scope
is different from the one requested by the client, the authorization
server MUST include the “scope” response parameter to inform the
client of the actual scope granted.

如果客户端在授权时忽略了scope参数，则授权服务器必须用预定义的默认值来填充，或直接告知客户端使用了无效的scope。如有定义，授权服务器需要注明其对scope的要求和默认值。

If the client omits the scope parameter when requesting
authorization, the authorization server MUST either process the
request using a pre-defined default value or fail the request
indicating an invalid scope. The authorization server SHOULD
document its scope requirements and default value (if defined).