OAuth2.0开发指南
1.认证与登录
来往开放平台支持3种不同的OAuth 2.0验证与授权流程:
- 服务端流程（协议中Authorization Code Flow): 此流程适用于在Web服务端调用REST API的的应用。例如：网站，站内应用
- 客户端流程（协议中ImplicitFlow）: 此流程适用于在客户端调用REST API的应用。例如：后端无Web Server支持的手机客户端和桌面客户端，运行于浏览器内部的JavaScript、ActionScript应用（浏览器插件、纯Flash应用）
- 用户名密码流程（协议中ResourceOwner Password Credentials Flow）: 此流程适用于无法使用浏览器发起服务端和客户端验流程的应用
来往开放平台支持3种不同的OAuth 2.0验证与授权流程:
- 用户验证：确保用户是谁
- 应用授权：确保用户知道他授予什么样的数据和权限给您的应用
- 应用验证：确保用户授予权限的应用是您的应用，而不是其他应用
当完成这些步骤后，您的应用可以获得一个用户的Access Token。使这个Access Token，您的应用可以获取这个用户的信息，并可以以这个用户的身份做出相应的动作（发POST、回复）
2.服务端流程
登录流程开始于重定向用户浏览器（如果需要的话，可以弹出窗口或打开新页面）到来往OAuth 2.0的Authorize Endpoint，并传递三个必须参数
- client_id：必须参数。在开发者中心注册应用时获得的APPKey
- redirect_uri：流程结束后要跳转回得URL。redirect_uri所在的域名必须在开发者中心注册应用后，填写在编辑属性选项卡中填写到服务器域名中，来往OAuth2.0用以检查跳转的合法性
- response_type：必须参数。服务端流程，此值固定为“code”
- view_mode:选填参数。web表示web端使用授权页面，mobile表示手机端使用授权页面。默认为web
发送以下请求至OAuth服务器
https://api.laiwang.com/oauth/authorize?client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL&response_type=code
如果用户已经登录，来往OAuth2.0会校验存储在用户浏览器中的Cookie。如果用户没有登录，来往OAuth 2.0会为用户展示登录页面，让用户输入用户名和密码
当来往OAuth 2.0成功验证用户之后，会为用户展示授权页面，让用户为应用授权
- scope：非必须参数。以空格分隔的权限列表，若不传递此参数，代表请求用户的默认权限 （权限列表）
发送以下请求至OAuth服务器(带scope)
https://api.laiwang.com/oauth/authorize?client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL&response_type=code&scope=read_user_album+read_user_feed
如果用户不同意授权（点击关闭），应用将不会被授权。来往OAuth2.0会将用户的浏览器重定向（通过HTTP 302）到redirect_uri参数对应的URL上，并在Query中带上相应的错误信息。
http://YOUR_CALBACK_URL?error=nvalid_request&&error_description=The+request+is+missing+a+required+parameter:+client_id.
如果用户同意授权（点击连接），应用将会被授权。来往OAuth2.0会将用户的浏览器重定向（通过HTTP 302）到redirect_uri参数对应的URL上，并在Query中使用'code'参数返回一个AuthorizationCode。
http://YOUR_CALBACK_URL?code=A_CODE_GENERATED_BY_SERVER.
Authorize Code可以在redirect_uri后端程序中获得。获得到Authorization Code后，你可以进行流程的下一步—应用验证，以便获得可以调用REST API的Access Token。应用验证需要使用HTTP POST请求来往OAuth 2.0的Access Token Endpoint，并需要带上一系列需要的参数（来往OAuth2.0支持多种传递“client_id”和“client_secret”的方式，包括：URI Query Parameter、Form-Encoded Body Parameter）
- grant_type：使用Authorization Code 作为Access Grant时，此值为“authorization_code”
- code：上述过程中获得的Authorization Code
- client_id：在开发者中心注册应用时获得的API Key
- client_secret：在开发者中心注册应用时获得的Secret Key
- redirect_uri：必须与获取Authorization Code时传递的“redirect_uri”保持一致
发送以下请求至OAuth服务器
https://api.laiwang.com/oauth/access_token?grant_type=authorization_code&client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL&client_secret=YOUR_SECRET_KEY&code=THE_CODE_FROM_ABOVE
{
"access_token": "68d71cbc2a1c8dcbb770e44ee711676a",
"refresh_token":"7e7f67a83e29126c4f9e51c48f3790“,
"expires_in": 87063
}
- access_token：获取的Access Token
- expires_in：Access Token的有效期，以秒为单位
- refresh_token：用于刷新Access Token 的 Refresh Token，过期时间为1年，过期后需要用户重新登录
如果应用验证过程中出错，来往OAuth 2.0将返回HTTP 401（应用验证失败）或HTTP 400（参数错误），并在HTTP Body中返回错误信息：
{
"error": "invalid_request",
"error_description": "The request is missing a required parameter: client_id",
"error_uri": "http://api.laiwang.com/docs/error_code.html"
}
- error：错误码，有关错误码的详细信息请浏览错误码
- error_description：一段人类可读的文字，用来帮助理解和解决发生的错误
- error_uri：一个人类可读的网页URI，带有关于错误的信息，用来为终端用户提供与错误有关的额外信息
3.客户端流程
客户端流程同样使用来往OAuth 2.0的Authorize Endpoint来实现用户验证和应用验证。唯一不同点是需要指定'response_type'参数为'token':
https://api.laiwang.com/oauth/authorize?client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL&response_type=token
与服务端流程一样，当用户验证和应用授权通过后，来往OAuth2.0会将用户的浏览器重定向（通过HTTP 302）到redirect_uri参数对应的URL上。与服务端流程不同的是，客户端流程不会返回code参数，而是在URI Fragment中返回access_token:（注意：不返回refresh_token）
http://YOUR_CALLBACK_URL#access_token=68d71cbc2a1c8dcbb770e44ee711676a&expires_in=86400
由于返回的Access Token是在URI Fragment中返回，只有客户端代码(例如：例如运行与浏览器中的JavaScript、有浏览器控件支持的客户端代码)才可以获取access_token
4.用户名密码端流程
使用用户名密码端流程的权限需要提前申请,用户名密码流程需要使用HTTP POST请求来往OAuth 2.0的Access Token Endpoint，并需要带上一系列需要的参数
- grant_type：使用Resource Owner Password Credentials作为Access Grant时，此值为“password”
- username：用户的用户名
- password：用户的密码
- site：用户账户的站点，非必须参数，默认为来往账户，TAOBAO为淘宝账户
- client_id：在开发者中心注册应用时获得的App Key
- client_secret：在开发者中心注册应用时获得的Secret Key
- scope：非必须参数。以空格分隔的权限列表，若不传递此参数，代表请求用户的默认权限 （权限列表）
发送以下请求至OAuth服务器
https://api.laiwang.com/oauth/access_token?grant_type=password&username=USERNAME&password=PASSWORD&client_id=YOUR_API_KEY&client_secret=YOUR_SECRET_KEY&scope=...
如果用户验证通过（用户名密码正确），并且应用验证通过，来往OAuth 2.0会返回Access Token相关的信息:
{
"access_token": "68d71cbc2a1c8dcbb770e44ee711676a",
"refresh_token":"7e7f67a83e29126c4f9e51c48f3790“,
"expires_in": 87063
}
- access_token：获取的Access Token
- expires_in：Access Token的有效期，以秒为单位
- refresh_token：用于刷新Access Token 的 Refresh Token，过期时间为1年，过期后需要用户重新登录
如果应用验证过程中出错，来往OAuth 2.0将返回HTTP 401（应用验证失败）或HTTP 400（参数错误），并在HTTP Body中返回错误信息：
{
"error": "invalid_request",
"error_description": "The request is missing a required parameter: client_id",
"error_uri": "http://open.laiwang.com/docs/error_code.html"
}
5.使用Access Token
获得Access Token后，可以Access Token调用来往API，如下所示(获得个人profile):
https://api.laiwang.com/v1/user/profile/get?access_token=68d71cbc2a1c8dcbb770e44ee711676a
返回内容:
{
"name": "苗海",
"id": "25001",
"createdAt": 1312773775000,
"avatar":"http://i01.lw.aliimg.com/4b/as/as4b.50x50.jpg",
"mail": "XXX@alibaba-inc.com",
"mobile": "13777800801",
"gender": "female",
"birthday": "1800-01-20",
"city": "afdafasf",
"avatarBig": "http://i01.lw.aliimg.com/4b/as/as4b.jpg",
"company": "dd",
"brief": "fffff"
}
6.刷新Access Token
Access Token生命周期较短，在某些场景下，应用需求的Access Token的生命期超过一个Access Token的生命期，就可以使用Refresh Token来刷新Access Token，Refresh Token是一个不过期的Token。 刷新Access Token需要使用HTTP POST请求来往OAuth 2.0的Access Token Endpoint，并需要带上一系列需要的参数：
- grant_type：使用Refresh Token刷新Access Token时，此值为“refresh_token”
- refresh_token：获取Access Token时，同时下发的Refresh Token
- client_id：在开发者中心注册应用时获得的App Key
- client_secret：在开发者中心注册应用时获得的Secret Key
发送以下请求至OAuth服务器
https://api.laiwang.com/oauth/access_token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_API_KEY&client_secret=YOUR_SECRET_KEY
如果用户验证通过（用户名密码正确），并且应用验证通过，来往OAuth 2.0会返回Access Token相关的信息:
{
"access_token": "68d71cbc2a1c8dcbb770e44ee711676a",
"refresh_token":"7e7f67a83e29126c4f9e51c48f3790“,
"expires_in": 87063
}
- access_token：获取的Access Token
- expires_in：Access Token的有效期，以秒为单位
- refresh_token：用于刷新Access Token 的 Refresh Token，过期时间为1年，过期后需要用户重新登录
如果应用验证过程中出错，来往OAuth 2.0将返回HTTP 401（应用验证失败）或HTTP 400（参数错误），并在HTTP Body中返回错误信息：
{
"error": "invalid_request",
"error_description": "The request is missing a required parameter: client_id",
"error_uri": "http://api.laiwang.com/docs/error_code.html"
}
7.权限列表
每一个Access Token代表“一个用户”授予“一个应用”的“一系列权限”。这“一系列权限”就是在获取Access Token过程中传递的“scope”参数.在调用API时，API服务会检验请求中的Access Token中是否包含本API需要的权限.
例如：
- 调用/v1/feed/main/list， API会检查请求中的Access Token中包含feed权限
- 调用/v1/user/profile/get， API会检查请求中的Access Token中包含user权限
全部权限
- feed：聚合信息查询
- relationship：好友关系操作
- event：扎堆事件操作
- message：私聊操作
- post：主贴操作
- circle：圈子操作
- notification:通知查询
- remind:提醒服务
- user:个人信息操作
- search:搜索服务
- internal:高阶权限（包括邀请，通讯录上传等.需要特殊申请）
基本权限(Basic)
- feed、relationship、event、message、post、circle、notification、remind、user、search