The OAuth 2.0 Authorization Protocol （第四章）

4.1    授权码

授权码授予类型被用来获得访问令牌和刷新令牌，还被用来优化机密性客户端。作为一个基于重定向的流，客户必须具有与资源所有者的用户代理（通常是是web 浏览器）交互的能力和接受来自授权服务器进入请求（通过重定向）的能力。

     +----------+

     | resource |

     |  owner  |

     |         |

     +----------+

          ^

          |

         (B)

     +-------|--------+          Client Identifier   +--------------------+

     |        -+-------(A)-- & Redirection URI ---->|            |

     | User-   |                           | Authorization |

     | Agent  -+-------(B)-- User authenticates---->|     Server  |

     |         |                           |           |

     |        -+--------(C)-- Authorization Code ---<|           |

     +-|--------|-----+                           +------------------+

       |   |                                  ^       v

     (A)  (C)                                   |       |

       |   |                                  |       |

       ^   v                                  |       |

     +----------------+                               |       |

     |        |>---(D)-- Authorization Code ---------'-------       |

     | Client  |          & Redirection URI                |

     |        |                                       |

     |        |<---(E)----- Access Token -------------------'------------- |

     +---------------+  (w/ Optional Refresh Token)

上面的流程图包括了如下3个步骤：

（a）    客户端开始流程，引导资源所有者的用户代理到授权端点。客户端包括其客户端标识符，请求的范围，本地状态和重定向URI，重定向URI是当访问被授权后授权服务器发送回的用户代理的。

（b）    授权服务器认证资源所有者（通过用户代理）然后建立客户端的访问请求，不论资源所有者授权或者拒绝。

（c）     假如资源所有者授权访问，授权服务器使用先前重定向URI（在请求时或者客户注册期间）将用户代理重定向回客户。重定向URI包括一个授权码和任何早起客户端提供的本地状态。

（d）    客户从授权服务器的令牌端点请求一个访问令牌，包括在上一步中收到的授权码。在做出请求时，客户与授权服务器验证。包括重定向URI 的客户用于获得验证授权码。

（e）    授权服务器验证客户端身份，验证授权码，保证接收到的重定向URI与步骤（c）中用于重定向客户端的URI向匹配。如果有效，授权服务器回复一个访问令牌和和可选择的刷新令牌。

4.1.1   授权申请

客户端通过增加下面参数到授权端点URI的查询组件构造请求URI，使用"application/x-www-form-urlencoded"格式来构造。

Response_type

    REQUIRED.    必须被赋值。

Client_id 

    REQUIRED.   客户身份，2.2结介绍

Redirect_uri

    OPTIONAL ,   3.1.2结介绍。

Scope

     OPTIONAL,   访问请求的范围，如3.3结描述。

State

    RECOMMENDED,    一个不透明的值，由客户端用来维持请求和回调状态。当重定向用户代理给客户端时，授权服务器包括此值。参数应当用于防止跨站点请求伪造，如10.12结所述。

 

Client使用一个HTTP重定向回答，或者用其它通过用户代理的方法将资源所有者引导到构造好的URI.

例如，客户端引导用户代理去做如下HTTP请求，使用传输层安全机制：

 

GET/authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz

    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2FcbHTTP/1.1

 Host: server.example.com

 

授权服务器验证请求以确保所有必需的参数存在且有效。如果请求是有效的，授权服务器验证资源的所有者，并获得一个授权决定（通过要求资源所有者或通过其他手段建立审批）。

当一个决定建立时，使用一个HTTP重定向回答，或者用其它通过用户代理的方法将资源所有者引导到构造好的URI.

4.1.2    授权应答

如果资源所有者授权给访问请求，授权服务器发布一个授权码然后传送它给客户端，授权码是增加下面的参数到重定向URI查询组件，使用"application/x-www-form-urlencoded"格式。

Code 

     REQUIRED.   授权服务器产生授权码，授权码必须在分发后不久就到期，以减轻泄露的风险。推荐一个授权码最大的寿命是10分钟。Client必须不能使用授权码超过一次。日过一个授权码被使用超过一次，授权服务器必须拒绝请求，然后尝试撤销前面所有基于那个授权码分发的令牌。授权码是绑定到客户标示符和重定向URI。

State 

     REQUIRED 如果“state“参数存在于客户端授权请求中。从客户端收到确切的值。

 

比如，授权服务器通过发送下面的HTTP应答来重定向用户代理。

   

HTTP/1.1 302 Found

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

 

Client应该忽视不认识应答参数。授权码字符串的大小在本规范是未定义的。Client应该避免对码值的大小做假设。授权服务器应该将任何它发布值的大小归档。

4.1.2.1    错误应答

如果由于丢失，失效，或者重定向URI不匹配而请求失败，或者如果所提供的客户端标示符是无效的，授权服务器应该通知资源服务器错误信息，一定不能自动的重定向用户代理到无效的重定向URI。

如果资源所有者拒绝访问请求，或者如果请求失败是有别于丢失或者无效重定向URI的原因，授权服务器通过增加下面的参数到重定向URI参训组件，来通知client,使用"application/x-www-form-urlencoded"格式：

error 

     REQUIRED    来自以下的简单错误码：

      invalid_request : 请求丢失了必要的参数，包括一个不被支持的参数值，或者格式不正确

     unauthorized_client : client 没有用这种方法被授权去请求授权码。

     access_denied ：资源所有者或者授权服务器拒绝请求。

     Unsupported_response_type ：资源服务器不支持用这种方法获得一个授权码。

     Invalid_scope ：请求范围无效，位置或者不符合格式。

     server_error  : 授权服务器遇到意外情况无法履行请求。

      Temporarily_unavailable: 授权服务器由于暂时过载或者服务器维护现在不能处理请求。

 error_description                 

       OPTIONAL.     一个提供更多信息的人类可读的UTF-8 编码文本，用于帮助客户端开发，使我们了解所发生的错误     

 error_uri 

       OPTIONAL      提供识别有关错误信息，供人参阅的网页URI。提供客户端开发和有关错误的其他信息

state

       REQUIRED      如果一个有效的“state“参数存在于客户授权请求。从客户端接收到一个确切的值

 

例如：授权服务器通过发送下面HTTP应带重定向用户代理：

 

HTTP/1.1 302 Found

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

 

4.1.3    访问令牌请求

Client发出通过在HTTP请求实体文本中增加下面参数来请求令牌端点，使用"application/x-www-form-urlencoded"格式。

 

grand_type

      REQUIRED.   “authorization_code”必须被赋值。

code 

      REQUIRED.    从授权服务器接受的授权码。

redirect_uri

      REQUIRED.    如果“redirect_uri“参数被包含在授权请求中，如4.1.1所述，它的值必须相同。

 

如果client 类型是秘密的或者client 被分发了client 凭证（或者假设另外授

权求）， client 必须和授权服务器验证身份，如 3.2.1.节所述。

 

   例如，client 按照传输层安全性做出如下HTTP 请求：

  

    POST /token HTTP/1.1

     Host: server.example.com

     Authorization: BasicczZCaGRSa3F0MzpnWDFmQmF0M2JW

     Content-Type:application/x-www-form-urlencoded;charset=UTF-8

 

    grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

 

授权服务器必须：

（a）      请求客户验证秘密客户或者每个被分发了凭证（或者其它授权需求）的用户

（b）      如果client 验证被包括就去验证客户端，然后确保授权码被分发给授权client

（c）      确认授权码是有效的

（d）      确保“redirect_uri”参数是存在的，如果“redirect_uri”参数被包括在初始的授权请求（4.1.1所述），如果被包含，确保他们的值是相同的。

 

4.1.4    访问令牌应答

如果访问令牌请求是有效的和授权的，授权服务器分发一个访问令牌和可选的刷新令牌（5.1所述）。如果请求客户端授权失败或者失效，授权服务器返回一个错误应答，如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"

    }

 

4.2    隐式授权

隐式授权类型被用来获得访问令牌（它不支持刷新令牌的发行），隐式授权非常适合懂得操作特定重定向URI的公共客户端。这些客户端通常用一个例如JavaScript的脚本语言在浏览器中实现。

作为一个基于重定向的流，client必须具有与资源所有者的用户代理（通常是一个web浏览器）交互的能力，还要具有从授权服务器接受向内请求（通过重定向）的能力。

不像授权码授权类型，授权码授权类型中，客户端为了授权和访问令牌做出分隔的请求，但在隐式授权中，client接受访问令牌作为授权请求的结果。

隐式授权类型不包括客户身份验证，它依赖于资源所有者和注册过的重定向URI的存在。

因为访问令牌被编码到了重定向URI，它可能被曝光给资源所有者和驻留在磁盘的应用程序。

 

    +-----------------+

    | Resource  |

    |  Owner  |

    |          |

    +-----------------+

         ^

         |

        (B)

    +-------|--------+          ClientIdentifier  +------------------------+

    |         --+----(A)-- &Redirection URI --->|               |

    |  User-    |                        | Authorization   |

    |  Agent  - |----(B)-- User authenticates -->|     Server   |

    |          |                        |               |

    |          |<---(C)---Redirection URI ----<|               |

    |          |          with Access Token +-----------------------+

    |          |            in Fragment

    |          |                        +------------------------+

    |          |----(D)--- RedirectionURI ---->|   Web-Hosted  |

    |          |          without Fragment |     Client   |

    |          |                         |    Resource  |

    |     (F)  |<---(E)------- Script -----------------<|               |

    |          |                         +--------------------------+

    +-|--------+

      |    |

     (A)  (G) Access Token

      |    |

      ^    v

    +---------------+

    |         |

    |  Client  |

    |         |

    +---------------+

上图包括了以下步骤：

（A）     client启动流程是从引导资源所有者的用户代理到授权端点开始的。Client包括他的客户端标示符，请求的范围，本地的状态和一个重定向RUI，一旦访问被授权（或者决绝）授权服务器将把用户代理送回。

（B）     授权服务器认证资源所有者（通过用户代理）。无论资源所有者授权或者拒绝，授权服务器建立客户端的访问请求。

（C）     假设资源所有者授权访问，授权服务器使用早起提供的重定向URI将用户代理重定向回client。重定向URI包含在访问令牌的URI片段里。

（D）     用户代理通过做出对web托管的客户端资源的请求，跟着重定向的指示。客户端保留本地的片段信息。

（E）      Web托管客户端资源返回一个web页面（通常是一个嵌入了脚本的HTML文档），能访问全重定向URI包括保留在用户代理的URI，提取片段中的访问令牌（和其它参数）

（F）      用户代理在本地执行web托管客户端资源的脚本，提取访问指令然后提交给client。

 

4.2.1    授权请求

Client通过增加下面的参数到授权端点URI的查询组件来构造请求URI，并使用"application/x-www-form-urlencoded"格式：

Response_type

     REQUIRED.  “token“必须被赋值。

Client_id

     REQUIRED.   客户端标示符，如2.2所述。

Redirect_uri

     OPTIONAL,    如3.1.2所述。

Scope

     OPTIONAL,    访问请求的范围，3.3节所述。

state

     RECOMMENDED.   客户端的一个不透明的值用来保留请求和回叫的状态。授权服务器包括这个值当重定向用户代理回client时。参数应该被用于防止夸站点访问片段。如10.12所述。

 

Client使用一个HTTP重定向应答来引导资源所有者到构造URI，或者通过其

他方式提供给他的用户代理。

例如,client引导用户代理使用传输层安全性去做出如下HTTP请求：

 

 GET/authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz

   &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1

 Host: server.example.com

 

授权服务器验证请求以确保所有的必须的参数是存在的且有效地。授权服务器必须验证重定向URI，这个URI回重定向访问令牌与一个客户端注册过的重定向URI匹配。

如果请求有效，授权服务器认真资源所有者，获得一个授权决定（通过请求资源所有者或者通过其他方法建立审批）。

当一个决定建立时，授权服务器定向用户代理到提供的客户重定向URI，这是通过一个HTTP重定向应答或者用其他方法提供给他的用户代理。

4.2.2    访问令牌应答

如果资源所有者授权一个访问请求，授权服务器分发一个访问令牌然后传送它给客户端，通过增加以下参数到重定向URI的片段组件。使用"application/x-www-form-urlencoded"格式：

 

access_token

     REQUIRED.    访问令牌被授权服务器分发。

token_type   

     REQUIRED.    发行的令牌类型如7.1所述。其值不区分大小写。

expires_in

     OPTIONAL.    访问令牌的周期以秒为单位。例如，值“3600“表示，访问令牌将在应答产生时起的一个小时内过期。

scope

     OPTIONAL.     访问令牌的范围如3.3节所述。

state

     REQUIRED.     如果“state”参数存在于客户授权请求中。从客户端获得确切的值。

 

授权服务器必须不发行刷新令牌。

例如，授权服务器通过发送下面的HTTP响应重定向用户代理：

 

HTTP/1.1 302 Found

Location:http://example.com/rd#access_token=2YotnFZFEjr1zCsicMWpAA

              &state=xyz&token_type=example&expires_in=3600

 

开发者应该注意一些HTTP客户端的实现不支持将片段部分列入到HTTP“Location”响应的头位置。这样的client 将需要使用其他的方法重定向客户端。比如，返回一个HTML页面包括了一个具有连接到重定向URI动作的“continue”按钮。

Client应该忽视不识别的响应参数。访问令牌字符串大小在本规范中是未定义的。Client应该避免对值的大小做出假设。授权服务器应该将任何分发的值的大小归档。

4.2.2.1    错误响应

如果由于丢失，失效，或者重定向URI不匹配而请求失败，或者如果所提供的客户端标示符是无效的，授权服务器应该通知资源服务器错误信息，一定不能自动的重定向用户代理到无效的重定向URI。

如果资源所有者拒绝访问请求，或者如果请求失败是有别于丢失或者无效重定向URI的原因，授权服务器通过增加下面的参数到重定向URI参训组件，来通知client,使用"application/x-www-form-urlencoded"格式：

error 

     REQUIRED    来自以下的简单错误码：

      invalid_request : 请求丢失了必要的参数，包括一个不被支持的参数值，或者格式不正确

     unauthorized_client : client 没有用这种方法被授权去请求授权码。

     access_denied ：资源所有者或者授权服务器拒绝请求。

     Unsupported_response_type ：资源服务器不支持用这种方法获得一个授权码。

     Invalid_scope ：请求范围无效，位置或者不符合格式。

     server_error  : 授权服务器遇到意外情况无法履行请求。

      Temporarily_unavailable: 授权服务器由于暂时过载或者服务器维护现在不能处理请求。

 error_description                 

       OPTIONAL.     一个提供更多信息的人类可读的UTF-8 编码文本，用于帮助客户端开发，使我们了解所发生的错误     

 error_uri 

       OPTIONAL      提供识别有关错误信息，供人参阅的网页URI。提供客户端开发和有关错误的其他信息

state

       REQUIRED      如果一个有效的“state“参数存在于客户授权请求。从客户端接收到一个确切的值

 

例如：授权服务器通过发送下面HTTP应带重定向用户代理：

 

HTTP/1.1 302 Found

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

 

4.3    资源所有者密码凭据

资源所有者密码凭证授权类型适合这样的案例：资源所有者和客户有一个信任的关系。比如它的设备操作系统或者高优先级应用程序。授权服务器应该特别小心当准许这种授权类型是，当其它流不可用时才准用它。

授权类型适合具有获得资源所有者凭据（username，password，通常使用交互式表单）的客户端。它还被用于迁移现有客户，使用引导授权计划，比如HTTP  Basic 或者 Digest 授权到oAuth,通过直接将存贮的凭证转换为访问令牌。

 

 

    +-------------+

    | Resource |

    | Owner   |

    |         |

    +---------===-+

         v

         |    Resource Owner

        (A)  Password Credentials

         |

         v

    +--------------+                           +-----------------------+

    |         |>--(B)---- ResourceOwner ------->|               |

    |         |         Password Credentials | Authorization   |

    | Client    |                           |     Server   |

    |         |<--(C)---- AccessToken ---------<  |               |

    |         |    (w/Optional Refresh Token) |               |

    +--------------+                          +-----------------------+

上图所示流程包含以下步骤：

（A）   资源所有者提供客户端名字和密码。

（B）   客户端通从授权服务器的令牌端点请求一个访问令牌。当做出请求时，客同授权服务器验证。

（C）   授权服务器认证客户端，验证资源所有者的凭证，如果有效分发一个访问令牌。

 

4.3.1    授权请求和应答

通过客户端获取资源所有者凭证的方法超过了本规范的范围。客户端必须丢弃凭证当一个访问令牌已经被获得时。

4.3.2   访问令牌请求

客户端通过在HTTP请求实体里增加如下参数做出到令牌终端的请求。使用"application/x-www-form-urlencoded"格式：

 

grant_type

      REQUIRED.    “password”必须被赋值。

username

      REQUIRED.     资源所有者的名字，按UTF-8编码

password

      REQUIRED.     资源所有者的密码，按UTF-8编码

scope

      OPTIONAL.      访问申请的范围如3.3节所述。

 

如果客户类型是秘密的或者客户被分发了客户凭证（或者其它授权需求），client必须与授权服务器验证，如3.2.1所述。

比如，client做出如下HTTP请求使用传输层安全性：

 

     POST /token HTTP/1.1

     Host: server.example.com

     Authorization: BasicczZCaGRSa3F0MzpnWDFmQmF0M2JW

     Content-Type:application/x-www-form-urlencoded;charset=UTF-8

 

    grant_type=password&username=johndoe&password=A3ddj3w

 

授权服务器必须：

（A）    要求客户端验证保密客户或者任何被分发客户凭证的客户（或者其它授权需求）

（B）    验证client，如果client授权被包括，验证资源所有者密码凭证。

 

因为方位令牌请求使用资源所有者的密码，授权服务器必须保护端点不给恶意的强行攻击。

4.3.3   访问令牌应答

如果访问令牌请求是有效的和被认证的，授权服务器发行一个访问令牌和可选的刷新令牌，如5.1所述。如果请求失败或者无效，授权服务器返回一个错误应答，如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"

    }

 

4.4    客户端凭证

Client可以只使用它的客户端凭证（或者其它支持认证的方法）请求一个访问令牌，当client正在请求在他控制下的受保护资源，或者那些某个先前安排了授权服务器的资源所有者时。

客户端凭证授权类型必须只用于保密用户。

 

+---------------+                          +-------------------+

     |        |                          |            |

     |        |>--(A)- Client Authentication --->| Authorization |

     | Client   |                           |     Server |

     |        |<--(B)---- Access Token ---------<  |           |

     |        |                           |           |

     +---------------+                           +------------------+

上面的流程图包含了下面的步骤：

（A）     客户跟授权服务器验证，从令牌端点请求一个访问令牌。

（B）     授权服务器验证客户端，如果有效，分发一个访问令牌。

 

4.4.1    授权请求和应答

     由于客户端授权被用来权限授予，不需要额外的权限请求。

4.4.2    访问令牌请求

Client通过给HTTP请求实体增加下面的参数来访问令牌端点，并用"application/x-www-form-urlencoded"格式：

 

grant_type

     REQUIRED.    “client_credentials”必须被赋值。

Scope

    OPTIONAL.    访问请求的范围如3.3节所述。

 

Client必须和授权服务器验证，如3.2.1所述。

例如，client使用传输层安全性作出如下HTTP请求:

 

    POST /token HTTP/1.1

    Host: server.example.com

    Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

    Content-Type: application/x-www-form-urlencoded;charset=UTF-8

     grant_type=client_credentials

 

然后授权服务器必须验证client.

 

4.4.3    访问令牌响应

如果访问令牌请求时有效的或者授权的，授权服务器分发一个访问令牌如5.1所述。一个刷新令牌不应该被包括在内。如果请求客户端验证失败或者无效，授权服务器返回一个所悟响应如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,

      "example_parameter":"example_value"

     }

 

4.5   扩展

Client通过指定授权类型来使用一个扩展授权类型，该指定的授权类型使用绝对URI（被授权服务器定义的）作为令牌节点的“grant_type”参数的值，还能增加任何必须的额外参数。

例如，为了请求一个访问令牌使用一个SAML 2.0授权类型，client用传输层安全机制做出如下HTTP请求：

 

POST /token HTTP/1.1

    Host: server.example.com

    Content-Type: application/x-www-form-urlencoded;charset=UTF-8

 

    grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-

    bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU

 [...omitted forbrevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24-

 

如果访问令牌请求时有效地和被授权的，授权服务器分发一个访问令牌和可选的刷新令牌，如5.1所述。如果请求客户认证失败或者无效，授权服务器返回一个错误响应如5.2所述。