OAuth 2.0授权框架中文版 [5] - 签发访问令牌

5. 签发访问令牌 - Issuing an Access Token

如果访问令牌请求有效且授权通过，则授权服务器按5.1的描述签发访问令牌和可选的刷新令牌。如果无效或授权失败，则按5.2的描述返回适当的错误信息。

If the access token request is valid and authorized, the
authorization server issues an access token and optional refresh
token as described in Section 5.1. If the request failed client
authentication or is invalid, the authorization server returns an
error response as described in Section 5.2.

5.1 成功响应 - Successful Response

授权服务器签发访问令牌和可选的刷新令牌，其响应结构是将如下参数组织到HTTP响应的消息体中，并返回200响应码：

access_token
    必须。授权服务器签发的访问令牌。

token_type
    必须。如章节7.1所述，标识签发的令牌的类型，大小写敏感。

expires_in
    建议。访问令牌的寿命，以秒为单位。比如，值为"3600"，代表访问令牌将在响应后的一小时后过期。如果忽略该值，则授权服务器比如通过其它方式实践过期时间，或者在文档中明确默认的过期时间。

refresh_token
    可选。刷新令牌，使用章节6中描述的授权方式来获取新的访问令牌。

scope
    当与请求中列举的范围相同时，则该返回值可选；否则必须返回，且符合章节3.3中的描述。

The authorization server issues an access token and optional refresh
token, and constructs the response by adding the following parameters
to the entity-body of the HTTP response with a 200 (OK) status code:

access_token
REQUIRED. The access token issued by the authorization server.

token_type
REQUIRED. The type of the token issued as described in
Section 7.1. Value is case insensitive.

expires_in
RECOMMENDED. The lifetime in seconds of the access token. For
example, the value “3600” denotes that the access token will
expire in one hour from the time the response was generated.
If omitted, the authorization server SHOULD provide the
expiration time via other means or document the default value.

refresh_token
OPTIONAL. The refresh token, which can be used to obtain new
access tokens using the same authorization grant as described
in Section 6.

scope
OPTIONAL, if identical to the scope requested by the client;
otherwise, REQUIRED. The scope of the access token as
described by Section 3.3.

参数应如[RFC4627]中所描述的，使用"application/json"媒体类型，并置于HTTP响应的响应体中。这些参数会被序列化为JSON格式，如上的参数都置于JSON的顶级。参数名和参数值都作为JSON字符串，数值类型的参数值作为JSON数字。这些参数排列的顺序无关。

The parameters are included in the entity-body of the HTTP response
using the “application/json” media type as defined by [RFC4627]. The
parameters are serialized into a JavaScript Object Notation (JSON)
structure by adding each parameter at the highest structure level.
Parameter names and string values are included as JSON strings.
Numerical values are included as JSON numbers. The order of
parameters does not matter and can vary.

授权服务器必须包含"Cache-Control"响应头，对所有包含令牌、凭证和其它敏感信息的响应，都需要将其值设置为"no-store"，同样的，“Pragma"响应头也要设置为"no-cache”。

The authorization server MUST include the HTTP “Cache-Control”
response header field [RFC2616] with a value of “no-store” in any
response containing tokens, credentials, or other sensitive
information, as well as the “Pragma” response header field [RFC2616]
with a value of “no-cache”.

举例如下：

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

For example:

 HTTP/1.1 200 OK
 Content-Type: application/json;charset=UTF-8
 Cache-Control: no-store
 Pragma: no-cache

 {
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
   "example_parameter":"example_value"
 }

客户端必须忽略未定义的响应参数。访问令牌和其它值的长度并未在该规范中定义，因此客户端应该避免假设这些字段的长度。授权服务器应明确自己签发的所有值的长度。

The client MUST ignore unrecognized value names in the response. The
sizes of tokens and other values received from the authorization
server are left undefined. The client should avoid making
assumptions about value sizes. The authorization server SHOULD
document the size of any value it issues.

5.2 错误响应 - Error Response

授权服务器返回400（Bad Request）响应码（除非另有声明）以及如下响应参数：

error
    必须。值为如下简单的ASCII错误码：

    invalid_request
        请求丢失必要的参数，或包含不支持的参数（超出授权类型规约的），或使用重复的参数，或包含多种凭证，或使用多种机制进行客户端认证，以及其它的问题。
    
    invalid_client
        客户端认证失败（如，未知的客户端、没有包含客户端认证信息、不支持的认证方式等）。授权服务器可能返回401响应码来指明支持何种类型的HTTP认证方式。如果客户端希望通过Authorization请求头进行认证，那授权服务器必须返回401响应，并包含WWW-Autoenticate响应头来指明客户端使用的认证方式。

    invalid_grant
        采用的授权方式或刷新令牌是无效的、过期的、已吊销的、重定向URI不匹配以及是签发给其它客户端的等等。

    unauthorized_client
        已认证的客户端没有使用此种授权模式的权限。

    unsupported_grant_type
        授权服务器不支持此种授权模式。

    invalid_scope
        请求的授权范围是无效的、未知的，或超出资源所有者的授权范围。

    error参数值包含的字符必须在%x20-21 / %x23-5B / %x5D-7E范围内。

error_description
    可选。可理解的ASCII文本，用于提供额外的信息，帮助客户端开发者理解发生了何种异常。
    error_description参数值包含的字符必须在%x20-21 / %x23-5B / %x5D-7E范围内。

error_uri
    可选。包含错误信息的web界面的URI，用于向客户端开发人员提供额外的错误信息。
    error_uri参数值必须符合URI-reference语法，并且包含的字符必须在%x21 / %x23-5B / %x5D-7E范围内。

The authorization server responds with an HTTP 400 (Bad Request)
status code (unless specified otherwise) and includes the following
parameters with the response:

error
REQUIRED. A single ASCII [USASCII] error code from the
following:

     invalid_request
           The request is missing a required parameter, includes an
           unsupported parameter value (other than grant type),
           repeats a parameter, includes multiple credentials,
           utilizes more than one mechanism for authenticating the
           client, or is otherwise malformed.

     invalid_client
           Client authentication failed (e.g., unknown client, no
           client authentication included, or unsupported
           authentication method).  The authorization server MAY
           return an HTTP 401 (Unauthorized) status code to indicate
           which HTTP authentication schemes are supported.  If the
           client attempted to authenticate via the "Authorization"
           request header field, the authorization server MUST
           respond with an HTTP 401 (Unauthorized) status code and
           include the "WWW-Authenticate" response header field
           matching the authentication scheme used by the client.

     invalid_grant
           The provided authorization grant (e.g., authorization
           code, resource owner credentials) or refresh token is
           invalid, expired, revoked, does not match the redirection
           URI used in the authorization request, or was issued to
           another client.

     unauthorized_client
           The authenticated client is not authorized to use this
           authorization grant type.

     unsupported_grant_type
           The authorization grant type is not supported by the
           authorization server.

     invalid_scope
           The requested scope is invalid, unknown, malformed, or
           exceeds the scope granted by the resource owner.

     Values for the "error" parameter MUST NOT include characters
     outside the set %x20-21 / %x23-5B / %x5D-7E.

error_description
OPTIONAL. Human-readable ASCII [USASCII] text providing
additional information, used to assist the client developer in
understanding the error that occurred.
Values for the “error_description” parameter MUST NOT include
characters outside the set %x20-21 / %x23-5B / %x5D-7E.

error_uri
OPTIONAL. A URI identifying a human-readable web page with
information about the error, used to provide the client
developer with additional information about the error.
Values for the “error_uri” parameter MUST conform to the
URI-reference syntax and thus MUST NOT include characters
outside the set %x21 / %x23-5B / %x5D-7E.

参数应如[RFC4627]中所描述的，使用"application/json"媒体类型，并置于HTTP响应的响应体中。这些参数会被序列化为JSON格式，如上的参数都置于JSON的顶级。参数名和参数值都作为JSON字符串，数值类型的参数值作为JSON数字。这些参数排列的顺序无关。

The parameters are included in the entity-body of the HTTP response
using the “application/json” media type as defined by [RFC4627]. The
parameters are serialized into a JSON structure by adding each
parameter at the highest structure level. Parameter names and string
values are included as JSON strings. Numerical values are included
as JSON numbers. The order of parameters does not matter and can
vary.

举例如下：

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_request"
}

For example:

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;charset=UTF-8
 Cache-Control: no-store
 Pragma: no-cache

 {
   "error":"invalid_request"
 }