Google oauth 2.0

Oauth 2.0的官方文档的中文译本：http://zhuyonghui116.blog.hexun.com.tw/67962330_d.html

Oauth 2.0的中文讲解参考文档：http://djb4ke.iteye.com/blog/683153

上面的参考文档的笔记如下：

OAuth 2.0的关注点在于简化了oauth1.0的复杂性，从而简化了客户端程序员的工作，因为OAuth1.0实际上只提供了一种交换access token的标准机制，并没有针对不同的客户端提供不同的access token交换方式，这显然并不是在各种客户端都非常适用的，因此在2.0中，将此细化到各种客户端的flow都有相应的标准，比如web程序，桌面程序，手机或一些设备，都可以通过各自的特点来实现OAuth的flow.

OAuth 2.0比Oauth 1.0简化了以下几处地方：
1. no signature method
2. oauth 1.0会先获取unauthorized request token，然后经user授权，使其成为authorized request token，然后再将authorized request token转换为access token，才能access google data。而oauth 2.0则可以直接获取access token (for client-side web app flow)，或者先获取authorization code （不需要获取unauthorized code），然后获取access token
3. 简化了register client ID in google，因为不用verify domain ownership.

OAuth is a security protocol that enables users to grant third-party access to their web resources without sharing their passwords.

OAuth是个安全相关的协议，作用在于，使用户授权第三方的应用程序访问用户的web资源，并且不需要向第三方应用程序透露自己的密码。

OAuth 2.0是个全新的协议，并且不对之前的版本做向后兼容，然而，OAuth 2.0保留了与之前版本OAuth相同的整体架构。

OAuth 2.0的新特性

持信人token

OAuth 2.0 提供一种无需加密的认证方式，此方式是基于现存的cookie验证架构，token本身将自己作为secret，通过HTTPS发送，从而替换了通过HMAC和token secret加密并发送的方式，这将允许使用cURL发起APIcall和其他简单的脚本工具而不需遵循原先的request方式并进行签名。

签名简化：

对于签名的支持，签名机制大大简化，不需要特殊的解析处理，编码，和对参数进行排序。使用一个secret替代原先的两个secret。

短期token和长效的身份凭据

原先的OAuth，会发行一个有效期非常长的token(典型的是一年有效期或者无有效期限制)，在OAuth 2.0中，server将发行一个短有效期的access token和长生命期的refresh token。这将允许客户端无需用户再次操作而获取一个新的access token，并且也限制了access token的有效期。

角色分开

OAuth 2.0将分为两个角色：

Authorization server负责获取用户的授权并且发布token。

Resource负责处理API calls

下面只讲解google oauth 2.0。以下的中文是对2篇英文articles的翻译。

http://code.google.com/apis/accounts/docs/OAuth2.html

http://code.google.com/apis/accounts/docs/OAuth2ForDevices.html

oauth 2.0的core concepts are simple and the same as oauth1.0:

• Your application asks for a particular scope ofaccess
• Google displays an OAuth dialog to users, asking for consent to authorize access to your application
• If the user approves, your application will get a short-lived access token that you can use to validate requests for the user's data

在使用Google OAuth 2.0之前，需要先register your app with google

Step 1. Go to http://code.google.com/apis/console#access

Step 2. Set "Product Name" (it will display to users in the OAuth dialog) if you haven't set it.

Step 3.判断你的app是web app还是an installed application. 如果是web app，需要提供domain or hostname.

注意：the default redirect_uri is your host name followed by oauth2callback. To change that, or to add an authorized JavaScript origin, click the "More options" link. Registering the exact redirect_uri you'll be using helps us be sure that we're actually passing tokens to your application and not an attacker.

Google提供下列4种方式的OAuth 2.0:

• The client-side flow for JavaScript applications running in a browser

该flow适用于那些Javascript-based web app，这种app因为以javascript为主，不需要maintain state over time (例如不需要用session来存储state)。

• The server-side flow for web applications with servers that can securely store persistent information

             This flow is meant for web applications with servers that can keep secrets and maintain state.

• The native application flow for desktop and mobile applications
  

This flow is meant for mobile, and desktop installed applications that wantaccess to user data.

• The OAuth 2.0 for devices flow。

该flow适用于那些想access google data的application which运行在device上，但无法进行用户授权(e.g. game consoles or media hubs), 需要使用另一个PC or device来进行用户授权的动作的case。

英文原文：This flow is suitable for applications executing on devices which wantaccess to user data, but don't have an easy data-entry method (e.g. game consoles or media hubs), and where the end-user has separate access to a user-agent on another computer or device (e.g. home computer, a latop, or asmart phone).

下面会对上面4个flow，逐个逐个讲解如何进行oauth 2.0 without using google client library。我会用紫色标记不同的flow使用不同的oauth 2.0的处理方法的不同之处。

OAuth 2.0 for client-side web applications

Step 1 Send the user to our OAuth dialog at

https://accounts.google.com/o/oauth2/auth

with the following query parameters:

Parameter	Description
client_id	(required) This is how Google identifies your application—Google will give you a client_id when you register your app with Google.
redirect_uri	(required) The URL on your site that will handle OAuth responses after the user takes an action on the dialog. You'll need to register theredirect_uri you'd like to use in advance. See the Registering your app with Google section for details on how to register.
scope	(required) URL identifying the Google service to be accessed. See the documentation for the API you'd like to use for what scope to specify. To specify more than one scope, list each one separated with a space.
response_type	(required) Either code or token. Use code for the server-side flow. For the client-side flow, use token.
state	(optional) A string used to maintain state between the request and redirect. This value will be appended to your redirect_uri after the user takes an action on the OAuth dialog.

例子

https://accounts.google.com/o/oauth2/auth?
  client_id=21302922996.apps.googleusercontent.com&
  redirect_uri=https://www.example.com/back&
  scope=https://www.google.com/m8/feeds/&
  response_type=token

3种flow (client-side flow, server-side flow and native application flow)均会执行this step，唯一不同的是param "response_type"的值不同，client-side flow的"response_type"值为token，server-side flow and native application flow的"response_type"值为code。这表示client-side flow会直接获取access token,而server-side flow and native application flow则是先获取authorize code，然后再转成access token.

OAuth 2.0 for devices flow则不会执行this step，见后面章节。

Step 2 当在browser里send上述http request后，就会出现一个authorization dialog，click "allow access“ button来授权。这时就会redirect to param "redirect_uri"所指定的URL，该redirect url会携带一个short-lived access token。该access token通常寿命只有一个小时多一点。下面是一个redirect url with param的example

https://www.example.com/back#access_token=1/QbIbRMWW&&token_type=Bearer&expires_in=3600

注意：该redirect url的参数并不是跟在"?"后面，而是跟在"#"后面。

这时，在该redirect url web page里的javascript就可以通过window.location.hash来从param中获取access token，然后就可以把它存储在cookie或者post to server。

若user在authorization dialog里click "No, thanks" button，redirect url就会是：

https://www.example.com/back?error=access_denied

获取了access token，就可以access google data了。

若你的access token过期了，当你继续尝试access google data时，就会获取HTTP 401 Unauthorized的response。这时你可以send your user to the same authorization endpoint you used in step 1. 如果user之前已经授权了你的app，就不会再显示OAuth dialog，而是直接redirect to redirect_uri指定的URL with a new access token.

OAuth 2.0 for server-side web applications

Step 1: 和oauth 2.0 for client-side web app的step 1一模一样。唯一不同的是param "response_type"的值为code

例子

https://accounts.google.com/o/oauth2/auth?
  client_id=21302922996.apps.googleusercontent.com&
  redirect_uri=https://www.example.com/back&
  scope=https://www.google.com/m8/feeds/&
  response_type=code

Step 2 当在browser里send上述http request后，就会出现一个authorization dialog，click "allow access“ button来授权。这时就会redirect to param "redirect_uri"所指定的URL，该redirect url会携带一个authorization code。下面是一个redirect url with param的example

https://www.example.com/back ?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp6

若user在authorization dialog里click "No, thanks" button，redirect url就会是：

https://www.example.com/back?error=access_denied

Step 3 当你的web app获取authorization code后，就应该 send a POST request with param authorization code, client_id, client_secret and grant_type=authorization_code to OAuth 2.0 token endpoint:

https://accounts.google.com/o/oauth2/token

例子

POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp6&
client_id=21302922996.apps.googleusercontent.com&
client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&
redirect_uri=https://www.example.com/back&
grant_type=authorization_code

上面的POST request后，如果认证成功，就会在response里（而不是redirect）获取一个a long-lived refresh token and a short-lived access token in a JSON object 类似于

{
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "token_type":"Bearer",
  "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"
}

获取了access token，就可以access google data了。

若你的access token过期了，当你继续尝试access google data时，就会获取HTTP 401 Unauthorized的response。这时你需要重新send a POST request  to OAuth 2.0 token endpoint:

https://accounts.google.com/o/oauth2/token

来获取一个new short-lived access token。注意它所携带的参数和step 3的有所不同，它要携带client id, client secret, refresh token 以及grant_type=refresh_token

例子

POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=21302922996.apps.googleusercontent.com&
client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&
refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ&
grant_type=refresh_token

server-side flow和client-side flow不同的地方是：

1. client-side flow是send a request，经user授权后就可以直接从redirect url的参数里获取access token。而server-side flow分2 part。第一part：send request，经user授权后，在redirect url的参数里获取的authorization code。第二part：your app send a POST request to "https://accounts.google.com/o/oauth2/token"，该request会包含以下params：

* part I 获取的authorization code

* client id

* client secret

* grant_type=authorization_code

之后google会redirect to "redirect_url"指定的url，该URL的参数包含一个short-lived access token和一个long-lived refresh_token。

2. client-side flow获取的是short-lived access token，而server-side flow获取的是一个short-lived access token和一个long-lived refresh_token。

3. client-side flow获取的access token过期后，需要再send GET request to "https://accounts.google.com/o/oauth2/auth"再获取一个new access token。而server-side flow获取的access token过期后，需要再send POST request with "refresh_token" to "https://accounts.google.com/o/oauth2/token"来获取一个new short-lived token。

OAuth 2.0 for native applications

Step 1: 和server-side flow的step 1一模一样的，唯一不同的是param "redirect_uri"的值为urn:ietf:wg:oauth:2.0:oob

例子：

https://accounts.google.com/o/oauth2/auth?
  client_id=21302922996.apps.googleusercontent.com&
  redirect_uri=urn:ietf:wg:oauth:2.0:oob&
  scope=https://www.google.com/m8/feeds/&
  response_type=code

Step 2 当在browser里send上述http request后，就会出现一个authorization dialog，click "allow access“ button来授权。这时web browser就会redirect to https://accounts.google.com/o/oauth2/approval web page，该page会显示一个authorization code（如下图）

On many platforms, your application should be able to monitor the window title of a browser window it creates and close the window when it sees a valid response. If your platform doesn't support that, you can instruct users to copy and paste the code to your application.

剩下的步骤，包括如何通过authorization code获取access token and refresh token，以及access token过期了，如何获取a new access token，都和server side的step 3以及续期处理一摸一样。

OAuth 2.0 for device

该flow适用于那些想access google data的application which运行在device上，但无法进行用户授权(e.g. game consoles or media hubs), 需要使用另一个PC or device来进行用户授权的动作的case。

英文原文：This flow is suitable for applications executing on devices which wantaccess to user data, but don't have an easy data-entry method (e.g. game consoles or media hubs), and where the end-user has separate access to a user-agent on another computer or device (e.g. home computer, a latop, or asmart phone).

Oauth 2.0 for device的基本处理流程是：在该device里先send POST request to google 来获取authorization code and user code，然后user使用该user code在另一个PC or device上send POST request to google来供用户进行授权。在获得授权之前，device app就会不停地利用authorization code来send POST request to https://accounts.google.com/o/oauth2/token来尝试获取access token and refresh token，不过直到end-user完成授权才会成功获取. (注意：在没授权之前，就会不停的send request.)

Step 1: Send a POST HTTP request to the OAuth 2.0 device endpoint at https://accounts.google.com/o/oauth2/device/code with "client_id" and"scope" param。注意：不需要response_type and redirect_ur param

例子

POST /o/oauth2/device/code HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=21302922996.apps.googleusercontent.com&
scope=https://www.google.com/m8/feeds/

该request返回的response是一个json object

{
  "device_code":"4/ULZ-3Vsf-vwu5RMpttob6XBHJlPD",
  "user_code":"dpk5c6ik",
  "verification_url":"http://www.google.com/device",
  "expires_in":1800,
  "interval":5
}

其中的device_code相当于authorization code。"expires_in"表示device code and user code过期的秒数。"interval"表示的client app需要每隔多少秒就应该执行一次step 2的part 1

Step 2:用来获取access token and refresh token.该step分为2 parts，需要注意的是这2 part是同时进行的

Part 1:该part和server-side web app的step 3以及native app的step 3一模一样。有2点不同的地方：

1. To get access token，send request to token endpoint https://accounts.google.com/o/oauth2/token时所带参数"grant_type"的值为"http://oauth.net/grant_type/device/1.0"

例子

POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=21302922996.apps.googleusercontent.com&
client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&
code=4/ULZ-3Vsf-vwu5RMpttob6XBHJlPD&
grant_type=http://oauth.net/grant_type/device/1.0

2. 该part会每隔step 1获取的interval所代表的秒数就会重复执行该part的send post request一次来尝试获取access token and refresh token，不过直到end-user在step 2 part 2里完成授权才会成功获取，返回的response是一个json object (包含access token, refresh token and expire info)。在未获取授权时，response就会返回下列2种可能的error code，这时应该不断重复this part

* authorization_pending: 表示用户还未授权.

* slow_down: client不断send request的间隔太短.

Part 2: 与此同时，user会在另一部PC or Device来进行授权：打开web browser，go to step 1获取的"verification_url"指定的URL，然后在该web page里输入step 1获取的user code, click "Continue“, and then click "Allow access”来完成授权。（如下图）

若access token过期了，重新获取new access token的方法和server-side web app的方法相同