OAuth2.0开发指南

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": "[email protected]", "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