第86行: | 第86行: | ||
**1、PC端和Web应用,请参考:Web应用的验证授权(Authorization Code) | **1、PC端和Web应用,请参考:Web应用的验证授权(Authorization Code) | ||
− | ** | + | **2、移动端应用可直接使用官方移动SDK,通过呼起微博客户端(未安装微博客户端的会呼起H5授权页)方式授权 |
**3、H5轻应用,请参考 [[轻应用开发指南]] | **3、H5轻应用,请参考 [[轻应用开发指南]] | ||
</div> | </div> | ||
第97行: | 第97行: | ||
+ | <div style="margin:15px 0;"> | ||
1. 引导需要授权的用户到如下地址: | 1. 引导需要授权的用户到如下地址: | ||
+ | </div> | ||
<div class="code_type">URL</div> | <div class="code_type">URL</div> | ||
第104行: | 第106行: | ||
</pre> | </pre> | ||
− | + | <div style="margin:15px 0;"> | |
2. 如果用户同意授权,页面跳转至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE | 2. 如果用户同意授权,页面跳转至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE | ||
+ | </div> | ||
− | + | <div style="margin:15px 0;"> | |
3. 换取Access Token | 3. 换取Access Token | ||
+ | </div> | ||
<div class="code_type">URL</div> | <div class="code_type">URL</div> | ||
第115行: | 第119行: | ||
</pre> | </pre> | ||
− | + | <div style="margin:15px 0;"> | |
− | 其中client_id=YOUR_CLIENT_ID&client_secret= | + | 其中client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET可以使用basic方式加入header中,返回值 |
− | + | </div> | |
− | + | ||
− | + | ||
− | + | ||
<div class="code_type">JSON</div> | <div class="code_type">JSON</div> | ||
第131行: | 第132行: | ||
</pre> | </pre> | ||
− | + | <div style="margin:15px 0;"> | |
4. 使用获得的Access Token调用API | 4. 使用获得的Access Token调用API | ||
+ | </div> | ||
第149行: | 第151行: | ||
<li style="font-size:14px;">[[移动客户端接入#SDK接入流程|SDK接入流程]]</li> | <li style="font-size:14px;">[[移动客户端接入#SDK接入流程|SDK接入流程]]</li> | ||
<li style="font-size:14px;">[https://github.com/sinaweibosdk/weibo_ios_sdk iOS SDK下载]</li> | <li style="font-size:14px;">[https://github.com/sinaweibosdk/weibo_ios_sdk iOS SDK下载]</li> | ||
− | <li style="font-size:14px;">[https:// | + | <li style="font-size:14px;">[https://github.com/sinaweibosdk/weibo_android_sdk Android SDK下载]</li> |
</ul> | </ul> | ||
</div> | </div> | ||
− | |||
+ | ==授权有效期== | ||
− | <div | + | <div class="wiki_txtJ"> |
+ | 微博开放平台的OAuth2.0授权机制下,第三方获取到的access_token是有过期时间的,通常过期时间为7天。 | ||
+ | </div> | ||
− | + | 授权级别和OAuth2.0 access_token有效期对应表: | |
− | + | <table class="wiki_table" border="0" cellspacing="0" cellpadding="0"> | |
− | + | <tr> | |
+ | <th class="wiki_table_thfirst" scope="col">授权级别</th> | ||
+ | <th scope="col">测试</th> | ||
+ | <th scope="col">普通</th> | ||
+ | <th scope="col">中级</th> | ||
+ | <th scope="col">高级</th> | ||
+ | </tr> | ||
+ | <tr> | ||
+ | <td>授权有效期</td> | ||
+ | <td>1天</td> | ||
+ | <td>7天</td> | ||
+ | <td>15天</td> | ||
+ | <td>30天</td> | ||
+ | </tr> | ||
+ | </table> | ||
− | + | 注: | |
+ | *1、只有未过审核的应用才处于测试级别。 | ||
+ | *2、应用所属开发者授权应用时,有效期为5年。 | ||
− | |||
− | |||
− | |||
− | |||
− | + | 你可以在 <span style="color:#FF7D13;">“我的应用>接口管理>授权机制”</span> 上查询当前应用的授权级别。也可以在这里申请提高授权有效期。 | |
− | + | ||
− | + | ||
− | + | ||
− | + | 开发者可以通过两种方式计算access_token的实效时间: | |
+ | *1、用户授权时,oauth2/access_token接口返回的expires_in值就是access_token的生命周期; | ||
+ | *2、从上述对应表中,找到应用所对应的授权有效期,过期时间 = 用户授权时间 + 授权有效期; | ||
− | |||
− | |||
− | + | 第三方开发应用需要具备一定的健壮性,调用接口时判断接口的返回值,如果用户的access_token失效,需要引导用户重新授权。 | |
− | + | ||
− | + | 失效原因有以下几个: | |
− | + | *1、用户取消了对应用的授权; | |
+ | *2、access_token自然过期; | ||
+ | *3、用户修改了密码,冻结了对应用的授权; | ||
+ | *4、微博发现用户帐号被盗,冻结了用户对应用的授权; | ||
− | |||
+ | ==授权有效期的延续== | ||
− | + | <div class="wiki_txtJ"> | |
+ | 如果用户在授权有效期内重新打开授权页授权(如果此时用户有微博登录状态,这个页面将一闪而过),那么微博会为开发者自动延长access_token的生命周期,请开发者维护新授权后得access_token值。 | ||
− | + | 除此之外,我们也提供了通过 Refresh Token 刷新的方式来延续授权有效期,但需要注意的是:只有使用微博官方移动SDK的移动应用,才可以从SDK的方法中获取到 Refresh Token。 | |
− | + | ||
− | |||
− | + | Refresh Token 是 Access Grants 的一种,在获取 Access Token 时,认证服务器将返回相应的 Refresh Token,如果 Access Token 过期,就可以用 Refresh Token 去刷新。 | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | {{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/oAuth2_05.gif}} | |
+ | </div> | ||
− | < | + | <div style="margin:15px 0;"> |
− | + | 1、当你调用API接口返回 Access Token 过期时,你可以调用 oauth2/access_token 并传入 refresh_token: | |
− | + | </div> | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
+ | <div class="code_type">URL</div> | ||
+ | <pre class="brush:html"> | ||
+ | https://api.weibo.com/oauth2/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&refresh_token=… | ||
+ | </pre> | ||
− | |||
+ | 返回值 | ||
− | |||
+ | <div class="code_type">JSON</div> | ||
+ | <pre class="brush:js"> | ||
+ | { | ||
+ | "access_token": "SlAV32hkKG", | ||
+ | "expires_in": 3600 | ||
+ | } | ||
+ | </pre> | ||
− | < | + | <div style="margin:15px 0;"> |
+ | 2.使用获得的OAuth2.0 Access Token调用API | ||
+ | </div> | ||
− | |||
+ | ==使用OAuth2.0调用API== | ||
− | < | + | <div class="wiki_txtJ"> |
+ | 使用OAuth2.0调用API接口有两种方式: | ||
+ | </div> | ||
− | + | <div style="margin:15px 0;"> | |
+ | 1、 直接使用参数,传递参数名为 access_token | ||
+ | </div> | ||
− | + | <div class="code_type">URL</div> | |
− | + | <pre class="brush:html"> | |
+ | https://api.weibo.com/2/statuses/public_timeline.json?access_token=abcd | ||
+ | </pre> | ||
+ | <div style="margin:15px 0;"> | ||
+ | 2、在header里传递,形式为在header里添加 Authorization:OAuth2空格abcd,这里的abcd假定为Access Token的值,其它接口参数正常传递即可。 | ||
− | |||
− | + | 注:所有的微博开放平台接口都部署在weibo.com域下,仅有移动端的授权接口在open.weibo.cn域。 | |
+ | </div> | ||
+ | |||
==授权页功能== | ==授权页功能== | ||
第261行: | 第277行: | ||
===scope=== | ===scope=== | ||
+ | <div class="wiki_txtJ"> | ||
scope是OAuth2.0新版授权页提供的一个功能,通过scope,平台将开放更多的微博核心功能给开发者,同时也加强用户隐私保护,提升了用户体验,用户在新OAuth2.0授权页中有权利选择赋予应用的功能。 | scope是OAuth2.0新版授权页提供的一个功能,通过scope,平台将开放更多的微博核心功能给开发者,同时也加强用户隐私保护,提升了用户体验,用户在新OAuth2.0授权页中有权利选择赋予应用的功能。 | ||
+ | |||
scope开放的接口文档:[[Scope|接口文档]] | scope开放的接口文档:[[Scope|接口文档]] | ||
+ | </div> | ||
+ | |||
===客户端默认回调页=== | ===客户端默认回调页=== | ||
+ | <div class="wiki_txtJ"> | ||
通常Mobile Native App没有服务器回调地址,您可以在应用控制台授权回调页处填写平台提供的默认回调页,该页面用户不可见,仅用于获取access token。 | 通常Mobile Native App没有服务器回调地址,您可以在应用控制台授权回调页处填写平台提供的默认回调页,该页面用户不可见,仅用于获取access token。 | ||
+ | |||
OAuth2.0客户端默认回调页:https://api.weibo.com/oauth2/default.html | OAuth2.0客户端默认回调页:https://api.weibo.com/oauth2/default.html | ||
+ | </div> | ||
+ | |||
===强制登录=== | ===强制登录=== | ||
+ | <div class="wiki_txtJ"> | ||
授权页会默认读取当前用户的微博登录状态,如果你想让用户重新登录,请在调用authorize接口时传入参数:forcelogin=true,默认不填写此参数相当于forcelogin=false。 | 授权页会默认读取当前用户的微博登录状态,如果你想让用户重新登录,请在调用authorize接口时传入参数:forcelogin=true,默认不填写此参数相当于forcelogin=false。 | ||
+ | </div> | ||
+ | |||
===取消授权回调页=== | ===取消授权回调页=== | ||
− | + | <div class="wiki_txtJ"> | |
+ | 开发者可以在应用控制台填写取消授权回调页,当用户取消你的应用授权时,开放平台会回调你填写的这个地址。并传递给你以下参数,source:应用appkey,uid :取消授权的用户,auth_end :取消授权的时间 | ||
+ | </div> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
==OAuth2.0相关资源== | ==OAuth2.0相关资源== | ||
第310行: | 第334行: | ||
</td><td>[http://weibosdk.codeplex.com/ 下载C# SDK]</td></tr> | </td><td>[http://weibosdk.codeplex.com/ 下载C# SDK]</td></tr> | ||
</table> | </table> | ||
+ | |||
===移动开发SDK说明文档=== | ===移动开发SDK说明文档=== | ||
第325行: | 第350行: | ||
</tr> | </tr> | ||
</table> | </table> | ||
+ | |||
===其他参考资料=== | ===其他参考资料=== | ||
+ | |||
OAuth是一种国际通用的授权方式, OAuth2.0的官方技术说明可参看 http://oauth.net/2/ | OAuth是一种国际通用的授权方式, OAuth2.0的官方技术说明可参看 http://oauth.net/2/ | ||
如果你仍在使用[[Oauth|Oauth1.0]],请进入浏览相关文档。 | 如果你仍在使用[[Oauth|Oauth1.0]],请进入浏览相关文档。 | ||
+ | |||
==OAuth2.0 错误码== | ==OAuth2.0 错误码== |
2015年3月26日 (四) 17:42的版本
授权机制
微博开放接口的调用,如发微博、关注等,都是需要获取用户身份认证的。目前微博开放平台用户身份鉴权主要采用的是OAuth2.0。另外,为了方便开发者开发、测试自己的应用,我们还提供了Basic Auth的身份鉴权方式,但Basic Auth仅适用于应用所属的开发者自己调用接口。
OAuth2.0概述
OAuth2.0较1.0相比,整个授权验证流程更简单更安全,也是未来最主要的用户身份验证和授权方式。
关于OAuth2.0协议的授权流程可以参考下面的流程图,其中Client指第三方应用,Resource Owner指用户,Authorization Server是我们的授权服务器,Resource Server是API服务器。
开发者可以先浏览OAuth2.0的接口文档,熟悉OAuth2.0的接口及参数的含义,然后我们根据应用场景各自说明如何使用OAuth2.0。
接口文档
接口 | 说明 |
---|---|
OAuth2/authorize | 请求用户授权Token |
OAuth2/access_token | 获取授权过的Access Token |
OAuth2/get_token_info | 授权信息查询接口 |
OAuth2/revokeoauth2 | 授权回收接口 |
OAuth2/get_oauth2_token | OAuth1.0的Access Token更换至OAuth2.0的Access Token |
注意事项
- 1、OAuth2.0授权无需申请,任何应用都可以使用。如果开发者需要更长的授权有效期参考本文档授权有效期部分。
- 2、如果你是站外网页应用或客户端应用,出于安全性考虑,需要在平台网站填写redirect_url(授权回调页),才能使用OAuth2.0,填写地址:“我的应用>应用信息>高级信息”,对于客户端,我们也提供了默认的回调页地址。详细请查看授权页功能部分。
授权页
新版授权页改变了之前页面信息元素过多,对用户使用带来干扰的问题,登录和授权这两个行为已在新版中分离,用户能够更好地理解帐号登录和授权的过程,也为未来更多的功能带来承载空间。
当前一个最完整的授权分为三个步骤:登录-普通授权-高级授权(SCOPE)。但这三个步骤并不是必然出现,当用户的微博处于登录状态时,页面会自动跳转到普通授权页,“高级授权”同样也不是必须,如果开发者不申请SCOPE权限,系统会自动跳过此步骤,回调应用。我们在灰度测试中统计发现,只要合理的使用高级授权,开发者完全不必担心增加操作所带来的页面流失率问题,相反,一个清晰的授权体验更能获取用户的信任。
与此同时,授权项将会变的更加有条理,之前的普通权限将作为基础服务,用户不再有感知,与用户隐私相关的会归到高级授权,用户在授权时有权利逐条取消,进一步增强了隐私控制。
应用场景
开发者需要根据各自的应用场景,选择适用的OAuth2.0授权流程:
- 1、PC端和Web应用,请参考:Web应用的验证授权(Authorization Code)
- 2、移动端应用可直接使用官方移动SDK,通过呼起微博客户端(未安装微博客户端的会呼起H5授权页)方式授权
- 3、H5轻应用,请参考 轻应用开发指南
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. 使用获得的Access Token调用API
移动应用(主要指Mobile Native App),建议使用官方提供的支持SSO授权的SDK, 可以大大简化授权流程开发,降低开发成本。
需要说明的是,移动应用请使用open.weibo.cn上的授权接口,普通的发博,评论等资源API依旧调用weibo.com接口。
授权有效期
微博开放平台的OAuth2.0授权机制下,第三方获取到的access_token是有过期时间的,通常过期时间为7天。
授权级别和OAuth2.0 access_token有效期对应表:
授权级别 | 测试 | 普通 | 中级 | 高级 |
---|---|---|---|---|
授权有效期 | 1天 | 7天 | 15天 | 30天 |
注:
- 1、只有未过审核的应用才处于测试级别。
- 2、应用所属开发者授权应用时,有效期为5年。
你可以在 “我的应用>接口管理>授权机制” 上查询当前应用的授权级别。也可以在这里申请提高授权有效期。
开发者可以通过两种方式计算access_token的实效时间:
- 1、用户授权时,oauth2/access_token接口返回的expires_in值就是access_token的生命周期;
- 2、从上述对应表中,找到应用所对应的授权有效期,过期时间 = 用户授权时间 + 授权有效期;
第三方开发应用需要具备一定的健壮性,调用接口时判断接口的返回值,如果用户的access_token失效,需要引导用户重新授权。
失效原因有以下几个:
- 1、用户取消了对应用的授权;
- 2、access_token自然过期;
- 3、用户修改了密码,冻结了对应用的授权;
- 4、微博发现用户帐号被盗,冻结了用户对应用的授权;
授权有效期的延续
如果用户在授权有效期内重新打开授权页授权(如果此时用户有微博登录状态,这个页面将一闪而过),那么微博会为开发者自动延长access_token的生命周期,请开发者维护新授权后得access_token值。
除此之外,我们也提供了通过 Refresh Token 刷新的方式来延续授权有效期,但需要注意的是:只有使用微博官方移动SDK的移动应用,才可以从SDK的方法中获取到 Refresh Token。
Refresh Token 是 Access Grants 的一种,在获取 Access Token 时,认证服务器将返回相应的 Refresh Token,如果 Access Token 过期,就可以用 Refresh Token 去刷新。
1、当你调用API接口返回 Access Token 过期时,你可以调用 oauth2/access_token 并传入 refresh_token:
https://api.weibo.com/oauth2/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&refresh_token=…
返回值
{ "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的值,其它接口参数正常传递即可。
注:所有的微博开放平台接口都部署在weibo.com域下,仅有移动端的授权接口在open.weibo.cn域。
授权页功能
scope
scope是OAuth2.0新版授权页提供的一个功能,通过scope,平台将开放更多的微博核心功能给开发者,同时也加强用户隐私保护,提升了用户体验,用户在新OAuth2.0授权页中有权利选择赋予应用的功能。
scope开放的接口文档:接口文档
客户端默认回调页
通常Mobile Native App没有服务器回调地址,您可以在应用控制台授权回调页处填写平台提供的默认回调页,该页面用户不可见,仅用于获取access token。
OAuth2.0客户端默认回调页:https://api.weibo.com/oauth2/default.html
强制登录
授权页会默认读取当前用户的微博登录状态,如果你想让用户重新登录,请在调用authorize接口时传入参数:forcelogin=true,默认不填写此参数相当于forcelogin=false。
取消授权回调页
开发者可以在应用控制台填写取消授权回调页,当用户取消你的应用授权时,开放平台会回调你填写的这个地址。并传递给你以下参数,source:应用appkey,uid :取消授权的用户,auth_end :取消授权的时间
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实现中,授权服务器在接收到验证授权请求时,会按照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 | 服务暂时无法访问 |
appkey permission denied | 21337 | 应用权限不足 |
OAuth2.0相关问题,查看 OAuth2.0相关问题