OAuth 2.0授权框架中文版 [4.1] - 授权码模式

4.获取授权 - Obtaining Authorization

为了获取访问令牌，客户端需要向资源所有者索要授权。授权以授权许可的形式来表示，客户端以此来请求访问令牌。OAuth定义了四中授权类型：授权码、隐式、资源所有者密码凭证以及客户端凭证。同时它也提供一个扩展机制来定义其他的授权类型。

To request an access token, the client obtains authorization from the
resource owner. The authorization is expressed in the form of an
authorization grant, which the client uses to request the access
token. OAuth defines four grant types: authorization code, implicit,
resource owner password credentials, and client credentials. It also
provides an extension mechanism for defining additional grant types.

4.1 授权码模式 - Authorization Code Grant

授权码模式可用于同时获取访问令牌和刷新令牌，对非公开客户端也有所优化。由于该模式依赖重定向，因此客户端必须具备同资源所有者的user-agent(典型的如web浏览器)交互的能力，同时也要具备接收授权服务器请求的能力(通过重定向)。

The authorization code grant type is used to obtain both access
tokens and refresh tokens and is optimized for confidential clients.
Since this is a redirection-based flow, the client must be capable of
interacting with the resource owner’s user-agent (typically a web
browser) and capable of receiving incoming requests (via redirection)
from the authorization server.

图3中的图示包含如下步骤：

(A) 客户端通过将资源所有者的user-agent重定向到授权端点来初始化授权码流程，客户端需要携带客户端标识、请求授权的范围、state以及重定向URI（当授权通过或拒绝时，授权服务器将user-agent重定向回该URI）。

(B) 授权服务器对资源所有者进行认证，并确认资源所有者是授权还是拒绝客户端的访问请求。

(C) 假设资源所有者授权允许客户端的访问，授权服务器会将user-agent重定向到之前提供的重定向URI（授权请求中或者客户端注册时提供的），重定向URI中会包含授权码，以及之前客户端提供的state参数。

(D) 客户端通过上述步骤中获取的授权码，向授权服务器请求访问令牌。当发起该请求时，客户端需要进行身份认证，此外，参数中也需要包含换取授权码时携带的重定向URI，以作为验证。

(E) 授权服务器对客户端进行认证，验证授权码是否正确，并确保重定向URI与步骤C中的完全匹配，如果验证通过，授权服务器将返回访问令牌，也可能包含刷新令牌。

The flow illustrated in Figure 3 includes the following steps:

(A) The client initiates the flow by directing the resource owner’s
user-agent to the authorization endpoint. The client includes
its client identifier, requested scope, local state, and a
redirection URI to which the authorization server will send the
user-agent back once access is granted (or denied).

(B) The authorization server authenticates the resource owner (via
the user-agent) and establishes whether the resource owner
grants or denies the client’s access request.

© Assuming the resource owner grants access, the authorization
server redirects the user-agent back to the client using the
redirection URI provided earlier (in the request or during
client registration). The redirection URI includes an
authorization code and any local state provided by the client
earlier.

(D) The client requests an access token from the authorization
server’s token endpoint by including the authorization code
received in the previous step. When making the request, the
client authenticates with the authorization server. The client
includes the redirection URI used to obtain the authorization
code for verification.

(E) The authorization server authenticates the client, validates the
authorization code, and ensures that the redirection URI
received matches the URI used to redirect the client in
step ©. If valid, the authorization server responds back with
an access token and, optionally, a refresh token.

4.1.1 授权请求 - Authorization Request

客户端使用附录B中说明的"application/x-www-form-urlencoded"格式，去构造授权端点的请求参数：

response_type
    必须。值必须为"code"。

client_id
    必须。章节2.2中描述的客户端标识。

redirect_uri
    可选。章节3.1.2中有描述。

scope
    可选。章节3.3中描述的请求访问的范围。

state
    建议。客户端用来维护请求和回调之间状态的不透明值。授权服务器将user-agent重定向回客户端时会携带该值。该值一般用于防止章节10.12中的跨站请求伪造攻击。

The client constructs the request URI by adding the following
parameters to the query component of the authorization endpoint URI
using the “application/x-www-form-urlencoded” format, per Appendix B:

response_type
REQUIRED. Value MUST be set to “code”.

client_id
REQUIRED. The client identifier as described in Section 2.2.

redirect_uri
OPTIONAL. As described in Section 3.1.2.

scope
OPTIONAL. The scope of the access request as described by
Section 3.3.

state
RECOMMENDED. An opaque value used by the client to maintain
state between the request and callback. The authorization
server includes this value when redirecting the user-agent back
to the client. The parameter SHOULD be used for preventing
cross-site request forgery as described in Section 10.12.

客户端通过HTTP重定向的响应或其它可行的方式，将资源所有者的user-agent引导到构造的URI。

The client directs the resource owner to the constructed URI using an
HTTP redirection response, or by other means available to it via the
user-agent.

比如，客户端引导user-agent通过TLS发起如下请求：

GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

For example, the client directs the user-agent to make the following
HTTP request using TLS (with extra line breaks for display purposes
only):

GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

授权服务器验证授权请求，以确保所有必须的参数都已提供并且经过验证，如果验证通过，授权服务器将验证资源所有者的身份，并获取其是否授权的决定（通过询问资源所有者，或建立其它的同意机制）。

The authorization server validates the request to ensure that all
required parameters are present and valid. If the request is valid,
the authorization server authenticates the resource owner and obtains
an authorization decision (by asking the resource owner or by
establishing approval via other means).

当用户完成其授权决策后，授权服务器将通过HTTP重定向或其它可行的方式，将user-agent引导到重定向URI。

When a decision is established, the authorization server directs the
user-agent to the provided client redirection URI using an HTTP
redirection response, or by other means available to it via the
user-agent.

4.1.2 授权响应 - Authorization Response

如果资源所有者授予了访问权限，授权服务器将签发一个授权码，并且通过附录B中定义的"application/x-www-form-urlencoded"格式将如下参数组织到重定向URI的查询参数中。

code
    必须。授权码由授权服务器生成，且授权码不应该维持太长时间，以减小泄露的风险，一般建议最长维持10分钟。客户端不能多次使用同一个授权码，如果某个授权码出现多次使用的情况，授权服务器应该拒绝当前的请求，并且吊销由该授权码签发的所有令牌。授权码与客户端标识和重定向URI存在绑定关系。

state
    必须。该值为客户端发起授权请求时传递的值（有传则在此时返回）。

If the resource owner grants the access request, the authorization
server issues an authorization code and delivers it to the client by
adding the following parameters to the query component of the
redirection URI using the “application/x-www-form-urlencoded” format,
per Appendix B:

code
REQUIRED. The authorization code generated by the
authorization server. The authorization code MUST expire
shortly after it is issued to mitigate the risk of leaks. A
maximum authorization code lifetime of 10 minutes is
RECOMMENDED. The client MUST NOT use the authorization code
more than once. If an authorization code is used more than
once, the authorization server MUST deny the request and SHOULD
revoke (when possible) all tokens previously issued based on
that authorization code. The authorization code is bound to
the client identifier and redirection URI.

state
REQUIRED if the “state” parameter was present in the client
authorization request. The exact value received from the
client.

例如，授权服务器会通过如下HTTP响应对user-agent进行重定向动作：

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
           &state=xyz

For example, the authorization server redirects the user-agent by
sending the following HTTP response:

 HTTP/1.1 302 Found
 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
           &state=xyz

客户端必须忽略无法识别的响应参数。此规范未定义授权码字符串的长度，因此客户端应避免预设授权码的长度。授权服务器应该记录所有签发的值的长度。

The client MUST ignore unrecognized response parameters. The
authorization code string size is left undefined by this
specification. The client should avoid making assumptions about code
value sizes. The authorization server SHOULD document the size of
any value it issues.

4.1.2.1 错误响应 - Error Response

如果授权请求由于重定向URI或客户端标识参数存在问题（丢失、无效或不匹配）导致请求失败，授权服务器应该告知资源所有者出现异常，而不是自动将user-agent重定向到无效的重定向URI。

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

如果资源所有者拒绝授权，或出现除丢失、无效重定向URI以外的异常，授权服务器应该通过附录B描述的"application/x-www-form-urlencoded"格式，通过以下参数告知客户端异常原因：

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

    invalid_request
        缺少必须的参数，包含无效的参数值，使用同名参数，以及其它问题。

    unauthorized_client
        客户端没有使用该方法获取授权码的权限。

    access_denied
        资源所有者拒绝授权。

    unsupported_response_type
        授权服务器不支持通过该方法获取授权码。

    invalid_scope
        请求的授权范围无效或未定义。

    server_error
        授权服务器发生意外情况，无法完成请求（之所以需要该错误代码，是因为无法通过HTTP重定向将500内部服务器错误状态返回给客户端）。

    temporarily_unavailable
        由于服务器临时过载或维护，授权服务器当前无法处理该请求（之所以需要该错误代码，是因为无法通过HTTP重定向将503服务器不可用状态返回给客户端）。

    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范围内。

state
    如果客户端在授权请求中携带该参数，则必须原样返回。

If the resource owner denies the access request or if the request
fails for reasons other than a missing or invalid redirection URI,
the authorization server informs the client by adding the following
parameters to the query component of the redirection URI using the
“application/x-www-form-urlencoded” format, per Appendix B:

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

     invalid_request
           The request is missing a required parameter, includes an
           invalid parameter value, includes a parameter more than
           once, or is otherwise malformed.

     unauthorized_client
           The client is not authorized to request an authorization
           code using this method.

     access_denied
           The resource owner or authorization server denied the
           request.

     unsupported_response_type
           The authorization server does not support obtaining an
           authorization code using this method.

     invalid_scope
           The requested scope is invalid, unknown, or malformed.

     server_error
           The authorization server encountered an unexpected
           condition that prevented it from fulfilling the request.
           (This error code is needed because a 500 Internal Server
           Error HTTP status code cannot be returned to the client
           via an HTTP redirect.)

     temporarily_unavailable
           The authorization server is currently unable to handle
           the request due to a temporary overloading or maintenance
           of the server.  (This error code is needed because a 503
           Service Unavailable HTTP status code cannot be returned
           to the client via an HTTP redirect.)

     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.

state
REQUIRED if a “state” parameter was present in the client
authorization request. The exact value received from the
client.

比如，授权服务器通过如下HTTP响应对user-agent进行重定向：

HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied&state=xyz

For example, the authorization server redirects the user-agent by
sending the following HTTP response:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied&state=xyz

4.1.3 访问令牌请求 - Access Token Request

客户端按照附录B中的"application/x-www-form-urlencoded"格式组织如下参数，并使用UTF-8编码后放在HTTP请求体中，发送到token端点：

grant_type
    必须。值必须为"authorization_code"。

code
    必须。授权服务器返回的授权码。

redirect_uri
    必须。如果授权请求中有携带redirect_uri参数，那跟此次的值必须完全一致。

client_id
    必须，如果客户端如章节3.2.1所述未进行认证。

The client makes a request to the token endpoint by sending the
following parameters using the “application/x-www-form-urlencoded”
format per Appendix B with a character encoding of UTF-8 in the HTTP
request entity-body:

grant_type
REQUIRED. Value MUST be set to “authorization_code”.

code
REQUIRED. The authorization code received from the
authorization server.

redirect_uri
REQUIRED, if the “redirect_uri” parameter was included in the
authorization request as described in Section 4.1.1, and their
values MUST be identical.

client_id
REQUIRED, if the client is not authenticating with the
authorization server as described in Section 3.2.1.

如果客户端类型是非公开客户端，或者有签发过客户端凭证（或其它认证方式），那客户端必须如章节3.2.1中所述与授权服务器进行认证。

If the client type is confidential or the client was issued client
credentials (or assigned other authentication requirements), the
client MUST authenticate with the authorization server as described
in Section 3.2.1.

比如，客户端通过TLS发送如下请求：

 POST /token HTTP/1.1
 Host: server.example.com
 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
 Content-Type: application/x-www-form-urlencoded

 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

For example, the client makes the following HTTP request using TLS
(with extra line breaks for display purposes only):

 POST /token HTTP/1.1
 Host: server.example.com
 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
 Content-Type: application/x-www-form-urlencoded

 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

授权服务器必须：

• 要求客户端进行认证（非公开客户端、签发过客户端凭证的客户端以及有其它认证要求的客户端）。

• 如果包含客户端认证信息，则进行认证，

• 确保授权码是签发给当前已认证的非公开客户端，如果客户端类型为公开客户端，则确保授权码是签发给请求中的client_id指定的客户端。

• 验证授权码的有效性，并且：

• 如果授权请求中包含redirect_uri参数，则此处也必须包含，且值必须一致。

The authorization server MUST:

o require client authentication for confidential clients or for any
client that was issued client credentials (or with other
authentication requirements),

o authenticate the client if client authentication is included,

o ensure that the authorization code was issued to the authenticated
confidential client, or if the client is public, ensure that the
code was issued to “client_id” in the request,

o verify that the authorization code is valid, and

o ensure that the “redirect_uri” parameter is present if the
“redirect_uri” parameter was included in the initial authorization
request as described in Section 4.1.1, and if included ensure that
their values are identical.

4.1.4 访问令牌响应 - Access Token Reponse

如果访问令牌请求是有效且经过客户端认证的，那授权服务器如章节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 client
authentication failed or is invalid, the authorization server returns
an error response as described in Section 5.2.

如下是成功响应的案例：

 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"
 }

An example successful response:

 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"
 }