OAuth 2.0授权框架中文版 [4.3] - 资源所有者密码凭证模式

4.3 资源所有者密码凭证模式 - Resource Owner Password Credentials Grant

资源所有者密码模式，适用于当资源所有者与客户端具有良好信任关系的场景，比如客户端是设备的操作系统或具备高权限的应用。授权服务器在开放此种授权模式时必须格外小心，并且只有在别的模式不可用时才允许这种模式。

The resource owner password credentials grant type is suitable in
cases where the resource owner has a trust relationship with the
client, such as the device operating system or a highly privileged
application. The authorization server should take special care when
enabling this grant type and only allow it when other flows are not
viable.

该模式适用于客户端有能力获取资源所有者的凭证（用户名密码，典型的通过交互式表单来获取）的场景，同时，也适用于现存的通过HTTP Basic或Digest模式进行认证的客户端，想迁移到OAuth的场景（通过已存储的资源所有者的凭证来换取访问令牌）。

This grant type is suitable for clients capable of obtaining the
resource owner’s credentials (username and password, typically using
an interactive form). It is also used to migrate existing clients
using direct authentication schemes such as HTTP Basic or Digest
authentication to OAuth by converting the stored credentials to an
access token.

图5中包含如下步骤：

(A) 资源所有者向客户端提供自己的用户名和密码。

(B) 客户端通过使用资源所有者的用户名和密码来访问授权服务器的令牌端点，以获取访问令牌。当发起该请求时，授权服务器需要认证客户端的身份。

(C) 授权服务器验证客户端身份，同时也验证资源所有者的凭据，如果都通过，则签发访问令牌。

The flow illustrated in Figure 5 includes the following steps:

(A) The resource owner provides the client with its username and
password.

(B) The client requests an access token from the authorization
server’s token endpoint by including the credentials received
from the resource owner. When making the request, the client
authenticates with the authorization server.

© The authorization server authenticates the client and validates
the resource owner credentials, and if valid, issues an access
token.

4.3.1 授权请求及响应 - Authorization Request and Response

客户端如何获取资源所有者的凭据超出了本规范的讨论范围。当客户端已经获取到访问令牌后，需要丢弃资源所有者的原始凭证。

The method through which the client obtains the resource owner
credentials is beyond the scope of this specification. The client
MUST discard the credentials once an access token has been obtained.

4.3.2 访问令牌请求 - Access Token Request

客户端需要如附录B中的描述，将如下参数按照"application/x-www-form-urlencoded"进行拼装，并以UTF-8进行编码，放置在HTTP的请求体中，来访问令牌端点：

grant_type
    必须。值为"password"。

username
    必须。资源所有者的用户名。

password
    必须。资源所有者的密码。

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

The client makes a request to the token endpoint by adding 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 “password”.

username
REQUIRED. The resource owner username.

password
REQUIRED. The resource owner password.

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

如果客户端类型为非公开客户端，或者签发过客户端凭证（或需要满足其它的认证要求），那授权服务器需要如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发起如下HTTP请求：

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

grant_type=password&username=johndoe&password=A3ddj3w

For example, the client makes the following HTTP request using
transport-layer security (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=password&username=johndoe&password=A3ddj3w

授权服务器必须：

• 要求非公开客户端或签发了客户端凭据的客户端进行认证。

• 对需要认证的客户端进行认证。

• 通过已有的密码处理算法，验证资源所有者的密码凭据。

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, and

o validate the resource owner password credentials using its
existing password validation algorithm.

由于token请求涉及资源所有者的密码，因此授权服务器需要保护其免受暴力破解攻击。

Since this access token request utilizes the resource owner’s
password, the authorization server MUST protect the endpoint against
brute force attacks (e.g., using rate-limitation or generating
alerts).

4.3.3 访问令牌响应 - Access Token Response

如果访问令牌请求有效且授权通过，则授权服务器按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.

成功的响应案例如下：

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