授权机制说明
目录 |
OAuth2.0概述
大部分API的访问如发表微博、获取私信,关注都需要用户身份。
目前新浪微博开放平台用户身份鉴权有OAuth2.0和Basic Auth(仅用于应用所属开发者调试接口)两种方式。
OAuth2.0较1.0相比整个授权验证流程更简单更安全,也是未来最主要的用户身份验证和授权方式。
注:OAuth2.0授权无需申请,任何应用都可以使用。
开发者需要根据各自的应用场景,选择适用的OAuth2.0授权流程:
- 1、网站或者站外Web应用,请参考:Web应用的验证授权(Authorization Code)
- 2、桌面和无线客户端应用,请参考:Web应用的验证授权(Authorization Code),无线客户端可以直接使用官方SDK,通过WebView方式使用授权页。
- 3、微博站内应用,请参考 站内应用开发指南。
基本流程
![oAuth2_01.gif](http://www.sinaimg.cn/blog/developer/wiki/oAuth2_01.gif)
(注:Client指第三方应用,Resource Owner指用户,Authorization Server是我们的授权服务器,Resource Server是API服务器)
开发者可以先浏览OAuth2.0的接口文档,熟悉OAuth2的接口及参数的含义,然后我们根据应用场景各自说明如何使用OAuth2.0。
接口文档
接口 | 说明 |
---|---|
OAuth2/authorize | 请求用户授权Token |
OAuth2/access_token | 获取授权过的Access Token |
OAuth2/get_oauth2_token | OAuth1.0的Access Token更换至OAuth2.0的Access Token |
应用场景
Web应用的验证授权(Authorization Code)
1. 引导需要授权的用户到如下地址:
https://api.weibo.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
2. 如果用户同意授权,页面跳转至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE
3. 换取Access Token
https://api.weibo.com/oauth2/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&code=CODE
(其中client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET可以使用basic方式加入header中)
返回值
{ "access_token":"SlAV32hkKG", "remind_in ":3600, "expires_in":3600 }
4. 使用获得的OAuth2.0 Access Token调用API
客户端的验证授权(Resource Owner Password Credentials)
1.调用
https://api.weibo.com/oauth2/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=password&username=USER_NAME&password=PASSWORD
返回值 { "access_token":"SlAV32hkKG", "expires_in":3600 }
2. 使用获得的OAuth2.0 Access Token调用API
注:客户端的验证授权需要申请
站内应用的验证授权
参考:站内应用开发指南
使用OAuth2.0调用API
使用OAuth2.0调用API接口有两种方式:
1. 直接使用参数传递参数名为 access_token
https://api.weibo.com/2/statuses/public_timeline.json?access_token=abcd
2. 在header里传递 形式为在header里添加Authorization:OAuth2空格abcd 这里的abcd假定为Access Token的值
其它接口参数正常传递即可。
OAuth2.0 错误码
新浪微博OAuth2.0实现中,授权服务器在接收到验证授权请求时,会按照OAuth2.0协议对本请求的请求头部、请求参数进行检验,若请求不合法或验证未通过,授权服务器会返回相应的错误信息,包含以下几个参数:
- error: 错误码
- error_code: 错误的内部编号
- error_description: 错误的描述信息
- error_url: 可读的网页URI,带有关于错误的信息,用于为终端用户提供与错误有关的额外信息。
错误信息的返回方式有两种:
1. 当请求授权Endpoint:https://api.weibo.com/2/oauth2/authorize 时出现错误,返回方式是:跳转到redirect_uri,并在uri 的query parameter中附带错误的描述信息。
2. 当请求access token endpoing:https://api.weibo.com/oauth2/access_token 时出现错误,返回方式:返回JSON文本。
例如:
{
- "error":"unsupported_response_type",
- "error_code":21329
- "error_description":"不支持的 ResponseType."
}
OAuth2.0错误响应中的错误码定义如下表所示:
错误码(error) | 错误编号(error_code) | 错误描述(error_description) |
---|---|---|
redirect_uri_mismatch | 21322 | 重定向地址不匹配 |
invalid_request | 21323 | 请求不合法 |
invalid_client | 21324 | client_id或client_secret参数无效 |
invalid_grant | 21325 | 提供的Access Grant是无效的、过期的或已撤销的 |
unauthorized_client | 21326 | 客户端没有权限 |
expired_token | 21327 | token过期 |
unsupported_grant_type | 21328 | 不支持的 GrantType |
unsupported_response_type | 21329 | 不支持的 ResponseType |
access_denied | 21330 | 用户或授权服务器拒绝授予数据访问权限 |
temporarily_unavailable | 21331 | 服务暂时无法访问 |
特殊权限申请
因为OAuth2.0的客户端验证授权会获得用户明文密码,所以实行有限开放。
申请条件:
- 应用分类属于桌面客户端、手机客户端。
- 应用本身已经通过开放平台文案、广场审核,并在广场上展示超过15天。
- 应用使用人数在30000以上。
- 应用本身功能与新浪微博关联紧密。
如果您的应用符合以上申请条件,可在应用控制台,接口管理标签下的授权机制选项中进行在线申请。
![sqyxq01.jpg](http://www.sinaimg.cn/blog/developer/wiki/sqyxq01.jpg)
申请时请详细填写应用的产品介绍、推广策略和改进目标。
![sqyxq02_2.jpg](http://www.sinaimg.cn/blog/developer/wiki/sqyxq02_2.jpg)
申请成功后请等待审核,三个工作日之内反馈结果。
![sqyxq03.jpg](http://www.sinaimg.cn/blog/developer/wiki/sqyxq03.jpg)
授权失效
程序一定要具备足够的健壮性,如果用户的access_token失效,需要引导用户重新授权。失效原因有以下几个:
- 用户取消了对应用的授权
- access_token自然过期
- 用户修改了密码,冻结了对应用的授权
- 新浪发现用户帐号被盗,冻结了用户对应用的授权
授权级别和OAuth2.0 access_token有效期对应表:
授权级别 | 测试 | 普通 | 中级 | 高级 | 合作 |
---|---|---|---|---|---|
授权有效期 | 1天 | 7天 | 15天 | 30天 | 90天 |
注:只有未过文案审核的应用才处于测试级别。
access_token自动延续方案 (仅支持code方式)
如果用户在授权有效期内重新打开授权页授权(如果此时用户有微博登录状态,这个页面将一闪而过),那么新浪会为开发者自动延长access_token的生命周期,请开发者维护新授权后得access_token值。
如何计算某个用户的access_token过期时间?
开发者可以通过两种方式计算:
- 用户授权时,oauth2/access_token接口返回的expires_in值就是access_token的生命周期。
- 从上述对应表中,找到应用所对应的授权有效期,过期时间 = 用户授权时间 + 授权有效期
如何查询当前应用得授权级别
你可以在http://open.weibo.com/apps/你的APPKEY/privilege/limit 上查询当前应用的授权级别。
如何申请授权有效期
可在应用控制台,接口管理标签下的授权机制选项中进行在线申请。
其他授权页功能
客户端授权页默认回调页
通常Mobile Native App没有服务器回调地址,您可以在应用控制台授权回调页处填写平台提供的默认回调页,该页面用户不可见,仅用于获取access token。
OAuth2.0客户端默认回调页:https://api.weibo.com/oauth2/default.html
强制登录
授权页会默认读取当前用户的新浪微博登录状态,如果你想让用户重新登录,请在调用authorize接口时传入参数:forcelogin=true,默认不填写此参数相当于forcelogin=false。
取消授权回调页
开发者可以在应用控制台填写取消授权回调页,当用户取消你的应用授权时,开放平台会回调你填写的这个地址。并传递给你以下参数:
source:应用appkey
uid :取消授权的用户
auth_end :取消授权的时间
注意事项
- 如果你的应用是站外网页应用,你需要在平台网站填写redirect_url(授权回调页),才能使用OAuth2.0。
- 新浪微博会暂时保留原有的OAuth1.0授权方式,但为了给用户更好的体验,新版V2接口仅支持OAuth2.0。
OAuth2.0相关资源
以下SDK包含了OAuth2.0及新版API接口
下载Android SDK | 下载iOS SDK | 下载WP7 SDK |
下载PHP SDK(由SAE维护) | 下载Java SDK | 下载Python SDK |
下载Flash SDK | 下载Javascript SDK | 下载C# SDK |
移动开发SDK说明文档
Android SDK 说明文档 | iOS SDK 说明文档 | WP7 SDK 说明文档 |
其他参考资料
OAuth是一种国际通用的授权方式, OAuth2.0的官方技术说明可参看 http://oauth.net/2/
如果你仍在使用Oauth1.0,请进入浏览相关文档。
OAuth2.0相关问题
查看 OAuth2.0相关问题