跳转到: 导航, 搜索
(授权页)
(未显示6个用户的38个中间版本)
第1行: 第1行:
==OAuth2.0概述==
+
=授权机制=
  
大部分API的访问如发表微博、获取私信,关注都需要用户身份,目前新浪微博开放平台用户身份鉴权有OAuth2.0和Basic Auth(仅用于应用所属开发者调试接口),新版接口也仅支持这两种方式。
+
<div class="wiki_txtJ">
 +
微博开放接口的调用,如发微博、获取用户基本信息、获取热门微博内容等,都是需要获取用户身份认证的。目前微博开放平台用户身份鉴权主要采用的是OAuth2.0。另外,为了方便开发者开发、测试自己的应用,我们还提供了开发者自身授权的身份鉴权方式,但开发者自身授权仅适用于应用所属的开发者自己调用接口。
 +
</div>
  
  
OAuth2.0较1.0相比整个授权验证流程更简单更安全,也是未来最主要的用户身份验证和授权方式。
+
<div class="wiki_taglist">
 +
快速索引
 +
<ul class="clearfix">
 +
<li style="font-size:14px;">[[#应用场景|如何接入授权]]</li>
 +
<li style="font-size:14px;">[[#授权有效期|授权有效期]]</li>
 +
<li style="font-size:14px;">[[#授权有效期的延续|授权有效期的延续]]</li>
 +
</ul>
 +
</div>
  
  
关于OAuth2.0协议授权流程查看[http://www.sinaimg.cn/blog/developer/wiki/oAuth2_01.gif OAuth2.0授权流程] ,其中Client指第三方应用,Resource Owner指用户,Authorization Server是我们的授权服务器,Resource Server是API服务器。
+
==OAuth2.0概述==
  
 +
<div class="wiki_txtJ">
 +
OAuth2.0较1.0相比,整个授权验证流程更简单更安全,也是未来最主要的用户身份验证和授权方式。
  
开发者可以先浏览OAuth2.0的接口文档,熟悉OAuth2的接口及参数的含义,然后我们根据应用场景各自说明如何使用OAuth2.0。
 
  
 +
关于OAuth2.0协议的授权流程可以参考下面的流程图,其中Client指第三方应用,Resource Owner指用户,Authorization Server是我们的授权服务器,Resource Server是API服务器。
  
'''注意事项:'''
 
  
**1、OAuth2.0授权无需申请,任何应用都可以使用。如果开发者需要更长的授权有效期参考本文档授权有效期部分。
+
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/oAuth2_01.gif}}
**2、如果你是站外网页应用或客户端应用,出于安全性考虑,需要在平台网站填写redirect_url(授权回调页),才能使用OAuth2.0,填写地址:http://open.weibo.com/apps/应用APPKEY/privilege/oauth。对于客户端,我们也提供了默认的回调页地址。详细请查看授权页功能部分。
+
  
==接口文档==
 
  
 +
开发者可以先浏览OAuth2.0的接口文档,熟悉OAuth2.0的接口及参数的含义,然后我们根据应用场景各自说明如何使用OAuth2.0。
 +
</div>
 +
 +
 +
'''接口文档'''
 +
 +
<div style="margin:15px 0;">
 
<table class="wiki_table" border="0" cellspacing="0" cellpadding="0" style="width:100%">
 
<table class="wiki_table" border="0" cellspacing="0" cellpadding="0" style="width:100%">
 
<tr>
 
<tr>
第30行: 第45行:
 
</td></tr>
 
</td></tr>
 
<tr>
 
<tr>
<td class="wiki_table_tdfirst">[[OAuth2/access_token|OAuth2/access_token]]
+
<td class="wiki_table_tdfirst">[[Oauth2/access_token|OAuth2/access_token]]
 
</td><td>获取授权过的Access Token
 
</td><td>获取授权过的Access Token
 
</td></tr>
 
</td></tr>
 
<tr>
 
<tr>
<td class="wiki_table_tdfirst">[[oauth2/get_oauth2_token|OAuth2/get_oauth2_token]] {{Icon_new2}}
+
<td class="wiki_table_tdfirst">[[Oauth2/get_token_info|OAuth2/get_token_info]]{{Icon_new2}}
 +
</td><td>授权信息查询接口
 +
</td></tr>
 +
<tr>
 +
<td class="wiki_table_tdfirst">[[Oauth2/revokeoauth2|OAuth2/revokeoauth2]]{{Icon_new2}}
 +
</td><td>授权回收接口
 +
</td></tr>
 +
<tr>
 +
<td class="wiki_table_tdfirst">[[Oauth2/get_oauth2_token|OAuth2/get_oauth2_token]]
 
</td><td>OAuth1.0的Access Token更换至OAuth2.0的Access Token
 
</td><td>OAuth1.0的Access Token更换至OAuth2.0的Access Token
 
</td></tr>
 
</td></tr>
 
</table>
 
</table>
 +
</div>
  
==授权页==
 
  
新版授权页改变了之前页面信息元素过多,对用户的使用带来干扰的问题,登录和授权这两个行为已在新版中分离,用户能够更好地理解帐号登录和授权的过程,也为未来更多的功能带来承载空间。
+
'''注意事项'''
  
 +
**1、OAuth2.0授权无需申请,任何应用都可以使用。如果开发者需要更长的授权有效期参考本文档授权有效期部分。
 +
**2、如果你是站外网页应用或客户端应用,出于安全性考虑,需要在平台网站填写redirect_url(授权回调页),才能使用OAuth2.0,填写地址:<span style="color:#FF7D13;">“我的应用>应用信息>高级信息”</span>,对于客户端,我们也提供了默认的回调页地址。详细请查看授权页功能部分。
  
当前一个最完整的授权分为三个步骤:登录-普通授权-高级授权(SCOPE)。但这三个步骤并不是必然出现,当用户的新浪微博处于登录状态时,页面会自动跳转到普通授权页,“高级授权”同样也不是必须,如果开发者不申请SCOPE权限,系统会自动跳过此步骤。我们在灰度测试中统计发现,只要合理的使用高级授权,开发者完全不必担心增加操作所带来的页面流失率问题,相反,一个清晰的授权体验更能获取用户的信任。
 
  
 +
==授权界面==
  
与此同时,授权项将会变的更加有条理,之前的普通权限将作为基础服务,用户不再有感知,与用户隐私相关的会归到高级授权,用户在授权时候有权利逐条取消,增强了隐私控制。
+
<div class="wiki_txtJ">
 +
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/OAuth2_intro.png}}
  
  
{{center|http://www.sinaimg.cn/blog/developer/wiki/oauth2v3.png}}
+
新版授权页改变了之前页面信息元素过多,对用户使用带来干扰的问题,登录和授权这两个行为已在新版中分离,用户能够更好地理解帐号登录和授权的过程,也为未来更多的功能带来承载空间。
  
==应用场景==
 
  
 +
当前一个最完整的授权分为三个步骤:登录-普通授权-高级授权(SCOPE)。但这三个步骤并不是必然出现,当用户的微博处于登录状态时,页面会自动跳转到普通授权页,“高级授权”同样也不是必须,如果开发者不申请SCOPE权限,系统会自动跳过此步骤,回调应用。我们在灰度测试中统计发现,只要合理的使用高级授权,开发者完全不必担心增加操作所带来的页面流失率问题,相反,一个清晰的授权体验更能获取用户的信任。
  
开发者需要根据各自的应用场景,选择适用的OAuth2.0授权流程:
 
  
 +
与此同时,授权项将会变的更加有条理,之前的普通权限将作为基础服务,用户不再有感知,与用户隐私相关的会归到高级授权,用户在授权时有权利逐条取消,进一步增强了隐私控制。
  
**1、网站或者站外Web应用,请参考:Web应用的验证授权(Authorization Code)
 
**2、桌面和无线客户端应用,请参考:Web应用的验证授权(Authorization Code),无线客户端可以直接使用官方SDK,通过WebView方式使用授权页。
 
**3、微博站内应用,请参考 [[站内应用开发指南]]。
 
  
 +
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/oauth2v3.png}}
 +
</div>
  
===Web应用的验证授权===
 
[http://www.sinaimg.cn/blog/developer/wiki/oAuth2_02.gif 基本流程]
 
  
 +
==应用场景==
  
1. 引导需要授权的用户到如下地址:
+
<div class="wiki_txtJ">
<pre>
+
开发者需要根据各自的应用场景,选择适用的OAuth2.0授权流程:
https://api.weibo.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
+
</pre>
+
  
  
2. 如果用户同意授权,页面跳转至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE
+
**1、PC端和Web网站,请参考:Web网站的验证授权(Authorization Code)
 +
**2、移动端应用可直接使用微博移动SDK,通过呼起微博客户端(未安装微博的会呼起H5授权页)方式授权
 +
**3、H5轻应用,请参考 [[轻应用开发指南]]
 +
**4、开发者自己在调试阶段,可以使用开发者自身授权
 +
</div>
  
  
3. 换取Access Token
+
<div class="wiki_title_withline">Web网站的授权</div>
<pre>
+
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
+
</pre>
+
(其中client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET可以使用basic方式加入header中)
+
  
  
返回值
+
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/oAuth2_02.gif}}
  
{
 
"access_token":"SlAV32hkKG", "remind_in
 
":3600, "expires_in":3600 
 
}
 
  
 +
<div style="margin:15px 0;">
 +
1. 引导需要授权的用户到如下地址:
 +
</div>
  
4. 使用获得的OAuth2.0 Access Token调用API
+
<div class="code_type">URL</div>
 +
<pre class="brush:html">
 +
https://api.weibo.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
 +
</pre>
  
===移动应用的验证授权===
+
<div style="margin:15px 0;">
移动应用(主要指Mobile Native App),建议使用官方提供的支持SSO授权的SDK, 可以大大简化授权流程开发,降低开发成本。
+
2. 如果用户同意授权,页面跳转至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE
 +
</div>
  
 +
<div style="margin:15px 0;">
 +
3. 换取Access Token
 +
</div>
  
参考:[[移动应用SSO授权]]
+
<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=authorization_code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&code=CODE
 +
</pre>
  
===站内应用的验证授权===
+
<div style="margin:15px 0;">
参考:[[站内应用开发指南]]
+
其中client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET可以使用basic方式加入header中,返回值
 +
</div>
  
<div style="display:none">
+
<div class="code_type">JSON</div>
 +
<pre class="brush:js">
 +
{
 +
    "access_token": "SlAV32hkKG",
 +
    "remind_in": 3600,
 +
    "expires_in": 3600
 +
}
 +
</pre>
  
 +
<div style="margin:15px 0;">
 +
4. 使用获得的Access Token调用API
 +
</div>
  
新浪微博OAuth1.0的Access Token不会过期,只有用户手工撤销授权或新浪收回您的app访问权限时Access Token才会失效。但OAuth2.0的过期时间通常为1天。
 
  
 +
<div class="wiki_title_withline">移动应用的授权</div>
  
Refresh Token 是 Access Grants 的一种,在获取Access Token时,认证服务器将返回相应的Refresh Token,
+
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/sdk72207.png}}
如果Access Token过期,就可以用Refresh Token去刷新。
+
  
 +
<div class="wiki_txtJ">
 +
移动应用(主要指Mobile Native App),建议使用官方提供的支持SSO授权的SDK, 可以大大简化授权流程开发,降低开发成本。
  
[http://www.sinaimg.cn/blog/developer/wiki/oAuth2_05.gif 基本流程]
 
  
 +
需要说明的是,移动应用请使用open.weibo.cn上的授权接口,普通的发博,评论等资源API依旧调用weibo.com接口。
 +
</div>
  
1当你调用API接口返回Access Token过期时,你可以调用oauth2/access_token并传入refresh_token:
 
<pre>
 
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="wiki_taglist">
{
+
<ul class="clearfix">
“access_token”:”SlAV32hkKG”, “expires_in”:3600
+
<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_android_sdk Android SDK下载]</li>
 +
</ul>
 +
</div>
  
  
2.使用获得的OAuth2.0 Access Token调用API
+
<div class="wiki_title_withline">开发者自身的授权</div>
  
 +
<div class="wiki_txtJ">
 +
为了方便开发者编程、调试接口,针对开发者自身,可以使用开发者授权,这样开发者自己就不用通过频繁授权自己的应用,来获取授权token才能调接口。而且开发者的授权token有效期为5年。
  
注:Refresh Token需要单独申请
 
</div>
 
  
==使用OAuth2.0调用API==
+
开发者自身授权有一定的限制要求,即只有应用的所有者账号授权自己名下的应用时,才享有这个特性。
使用OAuth2.0调用API接口有两种方式:
+
  
  
1. 直接使用参数传递参数名为 access_token
+
开发者自身授权可以通过接口测试工具快速获得,前提是需要用开发者的账号登录到微博开放平台,接口测试工具下才会列出这个账号下的应用,进而也只能获取到开发者名下所列出应用的授权token。
https://api.weibo.com/2/statuses/public_timeline.json?access_token=abcd
+
</div>
  
2. 在header里传递 形式为在header里添加Authorization:OAuth2空格abcd  这里的abcd假定为Access Token的值
 
  
 +
<div class="wiki_taglist">
 +
<ul class="clearfix">
 +
<li style="font-size:14px;">[http://open.weibo.com/tools/console 接口测试工具]</li>
 +
</ul>
 +
</div>
  
其它接口参数正常传递即可。
 
  
 
==授权有效期==
 
==授权有效期==
  
程序一定要具备足够的健壮性,调用接口时判断接口的返回值,如果用户的access_token失效,需要引导用户重新授权。失效原因有以下几个:
+
<div class="wiki_txtJ">
*#用户取消了对应用的授权
+
微博开放平台的OAuth2.0授权机制下,第三方获取到的access_token是有过期时间的,通常过期时间为30天。
*#access_token自然过期
+
</div>
*#用户修改了密码,冻结了对应用的授权
+
*#新浪发现用户帐号被盗,冻结了用户对应用的授权
+
  
  
 
授权级别和OAuth2.0 access_token有效期对应表:
 
授权级别和OAuth2.0 access_token有效期对应表:
 +
  
 
<table class="wiki_table" border="0" cellspacing="0" cellpadding="0">
 
<table class="wiki_table" border="0" cellspacing="0" cellpadding="0">
第160行: 第204行:
 
<th scope="col">测试</th>
 
<th scope="col">测试</th>
 
<th scope="col">普通</th>
 
<th scope="col">普通</th>
<th scope="col">中级</th>
 
<th scope="col">高级</th>
 
<th scope="col">合作</th>
 
 
</tr>
 
</tr>
 
<tr>
 
<tr>
 
<td>授权有效期</td>
 
<td>授权有效期</td>
 
<td>1天</td>
 
<td>1天</td>
<td>7天</td>
 
<td>15天</td>
 
 
<td>30天</td>
 
<td>30天</td>
<td>90天</td>
 
 
</tr>
 
</tr>
 
</table>
 
</table>
注:只有未过文案审核的应用才处于测试级别。
 
  
  
<strong>access_token自动延续方案{{Icon_new2}}</strong>
+
注:
 +
*1、只有未过审核的应用才处于测试级别。
 +
*2、应用所属开发者授权应用时,有效期为5年。
  
  
如果用户在授权有效期内重新打开授权页授权(如果此时用户有微博登录状态,这个页面将一闪而过),那么新浪会为开发者自动延长access_token的生命周期,请开发者维护新授权后得access_token值。
+
你可以在 <span style="color:#FF7D13;">“我的应用>接口管理>授权机制”</span> 上查询当前应用的授权级别。也可以在这里申请提高授权有效期。
  
  
<strong>如何查询当前应用的授权级别</strong>
+
开发者可以通过两种方式计算access_token的实效时间:
  
你可以在 http://open.weibo.com/apps/应用APPKEY/privilege/oauth 上查询当前应用的授权级别。
+
*1、用户授权时,<span class="txtS">oauth2/access_token</span>接口返回的<span class="txtS">expires_in</span>值就是access_token的生命周期;
 +
*2、从上述对应表中,找到应用所对应的授权有效期,过期时间 =  用户授权时间 + 授权有效期;
  
  
<strong>如何计算某个用户的access_token过期时间?</strong>
+
第三方开发应用需要具备一定的健壮性,调用接口时判断接口的返回值,如果用户的access_token失效,需要引导用户重新授权。
  
开发者可以通过两种方式计算:
 
  
*#用户授权时,oauth2/access_token接口返回的expires_in值就是access_token的生命周期。
+
失效原因有以下几个:
*#从上述对应表中,找到应用所对应的授权有效期,过期时间 =  用户授权时间 + 授权有效期
+
*1、用户取消了对应用的授权;
 +
*2、access_token自然过期;
 +
*3、用户修改了密码,冻结了对应用的授权;
 +
*4、微博发现用户帐号被盗,冻结了用户对应用的授权;
  
  
<strong>如何申请授权有效期</strong>
+
==授权有效期的延续==
  
可在应用控制台,接口管理标签下的授权机制选项中进行在线申请。
 
  
==授权页功能==
+
===授权有效期内重新授权===
  
===scope===
 
  
scope是OAuth2.0新版授权页提供的一个功能,通过scope,平台将开放更多的微博核心功能给开发者,同时也加强用户隐私保护,提升了用户体验,用户在新OAuth2.0授权页中有权利选择赋予应用的功能。
+
<div class="wiki_txtJ">
 +
如果用户在授权有效期内重新打开授权页授权(如果此时用户有微博登录状态,这个页面将一闪而过),那么微博会为开发者自动延长access_token的生命周期,请开发者维护新授权后得access_token值。
 +
</div>
 +
 
 +
 
 +
===通过Refresh Token刷新授权有效期===
 +
 
 +
 
 +
<div class="wiki_txtJ">
 +
除此之外,我们也提供了通过 Refresh Token 刷新的方式来延续授权有效期,但需要注意的是:<span class="txtS">只有使用微博官方移动SDK的移动应用,才可以从SDK的方法中获取到 Refresh Token。</span>
 +
 
 +
 
 +
Refresh Token 是 Access Grants 的一种,在获取 Access Token 时,认证服务器将返回相应的 Refresh Token,如果 Access Token 过期,就可以用 Refresh Token 去刷新。
 +
 
 +
 
 +
Refresh Token 也是有有效期的,Refresh Token 的有效期目前为30天,在有效期内随时可以刷新。
 +
 
 +
 
 +
通过 Refresh Token 刷新得到的新的 Access Token ,其有效期等同于原来的有效期,即原来 Access Token 的有效期是30天,则新获得的也是30天。
 +
 
 +
 
 +
简单来说就是对于使用了微博移动SDK的移动应用,授权(Access Token)30天有效,30天内可续,从刷新时间点算起重新得到30天有效期。
 +
 
 +
 
 +
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/oAuth2_05.gif}}
 +
</div>
 +
 
 +
 
 +
<div style="margin:15px 0;">
 +
1、当你是使用微博官方移动SDK的移动应用时,授权返回access_token的同时,还会多返回一个refresh_token:
 +
</div>
 +
 
 +
<div class="code_type">JSON</div>
 +
<pre class="brush:js">
 +
{
 +
    "access_token": "SlAV32hkKG",
 +
    "remind_in": 3600,
 +
    "expires_in": 3600
 +
    "refresh_token": "QXBK19xm62"
 +
}
 +
</pre>
 +
 
 +
<div style="margin:15px 0;">
 +
2、当你调用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;">
 +
3、使用新获得的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>
 +
 
 +
 
 +
==授权中的其他功能==
 +
 
 +
===Scope===
 +
 
 +
<div class="wiki_txtJ">
 +
Scope是OAuth2.0新版授权页提供的一个功能,通过scope,平台将开放更多的微博核心功能给开发者,同时也加强用户隐私保护,提升了用户体验,用户在新OAuth2.0授权页中有权利选择赋予应用的功能。
 +
 
 +
 
 +
Scope开放的接口文档:[[Scope|接口文档]]
 +
</div>
  
scope开放的接口文档:[[Scope|接口文档]]
 
  
 
===客户端默认回调页===
 
===客户端默认回调页===
  
 +
<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>
 +
  
 
===强制登录===
 
===强制登录===
  
授权页会默认读取当前用户的新浪微博登录状态,如果你想让用户重新登录,请在调用authorize接口时传入参数:forcelogin=true,默认不填写此参数相当于forcelogin=false。
+
<div class="wiki_txtJ">
 +
授权页会默认读取当前用户的微博登录状态,如果你想让用户重新登录,请在调用authorize接口时传入参数:forcelogin=true,默认不填写此参数相当于forcelogin=false。
 +
</div>
 +
 
  
 
===取消授权回调页===
 
===取消授权回调页===
  
开发者可以在应用控制台填写取消授权回调页,当用户取消你的应用授权时,开放平台会回调你填写的这个地址。并传递给你以下参数:
+
<div class="wiki_txtJ">
 
+
开发者可以在应用控制台填写取消授权回调页,当用户取消你的应用授权时,开放平台会回调你填写的这个地址。并传递给你以下参数,source:应用appkey,uid :取消授权的用户,auth_end :取消授权的时间
source:应用appkey
+
</div>
 
+
uid :取消授权的用户
+
  
auth_end :取消授权的时间
 
  
 
==OAuth2.0相关资源==
 
==OAuth2.0相关资源==
第238行: 第381行:
 
</th></tr>
 
</th></tr>
 
<tr>
 
<tr>
<td class="wiki_table_tdfirst">[https://github.com/mobileresearch/weibo_android_sdk/downloads 下载Android SDK]</td>
+
<td class="wiki_table_tdfirst">[https://github.com/mobileresearch/weibo_android_sdk  下载Android SDK]</td>
<td>[https://github.com/mobileresearch/weibo_ios_sdk_sso-oauth/downloads 下载iOS SDK]</td>
+
<td>[https://github.com/mobileresearch/weibo_ios_sdk_sso-oauth  下载iOS SDK]</td>
 
<td>[http://weibowp7sdk.codeplex.com/  下载WP7 SDK]</td>
 
<td>[http://weibowp7sdk.codeplex.com/  下载WP7 SDK]</td>
 
</tr>
 
</tr>
第252行: 第395行:
 
</td><td>[http://weibosdk.codeplex.com/  下载C# SDK]</td></tr>
 
</td><td>[http://weibosdk.codeplex.com/  下载C# SDK]</td></tr>
 
</table>
 
</table>
 +
  
 
===移动开发SDK说明文档===
 
===移动开发SDK说明文档===
第267行: 第411行:
 
</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 错误码==
  
新浪微博OAuth2.0实现中,授权服务器在接收到验证授权请求时,会按照OAuth2.0协议对本请求的请求头部、请求参数进行检验,若请求不合法或验证未通过,授权服务器会返回相应的错误信息,包含以下几个参数:
+
微博OAuth2.0实现中,授权服务器在接收到验证授权请求时,会按照OAuth2.0协议对本请求的请求头部、请求参数进行检验,若请求不合法或验证未通过,授权服务器会返回相应的错误信息,包含以下几个参数:
 
*error: 错误码
 
*error: 错误码
 
*error_code: 错误的内部编号
 
*error_code: 错误的内部编号
第285行: 第432行:
 
错误信息的返回方式有两种:
 
错误信息的返回方式有两种:
  
1. 当请求授权Endpoint:https://api.weibo.com/2/oauth2/authorize  时出现错误,返回方式是:跳转到redirect_uri,并在uri
+
1. 当请求授权Endpoint:https://api.weibo.com/2/oauth2/authorize  时出现错误,返回方式是:跳转到redirect_uri,并在uri
 
的query parameter中附带错误的描述信息。
 
的query parameter中附带错误的描述信息。
  
2. 当请求access token endpoing:https://api.weibo.com/oauth2/access_token  时出现错误,返回方式:返回JSON文本。
+
2. 当请求access token endpoing:https://api.weibo.com/oauth2/access_token  时出现错误,返回方式:返回JSON文本。例如:
  
例如:
 
  
 +
<div class="code_type">JSON</div>
 +
<pre class="brush:js">
 
{
 
{
*"error":"unsupported_response_type",
+
    "error": "unsupported_response_type",
*"error_code":21329
+
    "error_code": 21329,
* "error_description":"不支持的 ResponseType."
+
    "error_description": "不支持的ResponseType."
 
}
 
}
 +
</pre>
  
  
 
OAuth2.0错误响应中的错误码定义如下表所示:
 
OAuth2.0错误响应中的错误码定义如下表所示:
 +
 +
 
<table class="wiki_table" border="0" cellspacing="0" cellpadding="0">
 
<table class="wiki_table" border="0" cellspacing="0" cellpadding="0">
 
<tr>
 
<tr>
第373行: 第524行:
 
</td><td>21331
 
</td><td>21331
 
</td><td>服务暂时无法访问
 
</td><td>服务暂时无法访问
 +
</td>
 +
</tr>
 +
 +
<tr>
 +
<td class="wiki_table_tdfirst">appkey permission denied
 +
</td><td>21337
 +
</td><td>应用权限不足
 
</td>
 
</td>
 
</tr>
 
</tr>
第378行: 第536行:
 
</table>
 
</table>
  
==OAuth2.0相关问题==
+
 
查看 [http://open.weibo.com/qa/index.php?qa=%E5%BA%94-%E7%94%A8-%E6%8E%88-%E6%9D%83 OAuth2.0相关问题]
+
OAuth2.0相关问题,查看 [http://open.weibo.com/qa/index.php?qa=%E5%BA%94%E7%94%A8%E6%8E%88%E6%9D%83 OAuth2.0相关问题]
 +
 
 +
 
 +
 
 +
{{#a:nobtns|noheading}}
 +
__NOTOC__

2017年9月22日 (五) 10:18的版本

授权机制

微博开放接口的调用,如发微博、获取用户基本信息、获取热门微博内容等,都是需要获取用户身份认证的。目前微博开放平台用户身份鉴权主要采用的是OAuth2.0。另外,为了方便开发者开发、测试自己的应用,我们还提供了开发者自身授权的身份鉴权方式,但开发者自身授权仅适用于应用所属的开发者自己调用接口。



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轻应用,请参考 轻应用开发指南
    • 4、开发者自己在调试阶段,可以使用开发者自身授权


Web网站的授权



1. 引导需要授权的用户到如下地址:

URL
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

URL
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中,返回值

JSON
{
    "access_token": "SlAV32hkKG",
    "remind_in": 3600,
    "expires_in": 3600
}

4. 使用获得的Access Token调用API


移动应用的授权

移动应用(主要指Mobile Native App),建议使用官方提供的支持SSO授权的SDK, 可以大大简化授权流程开发,降低开发成本。


需要说明的是,移动应用请使用open.weibo.cn上的授权接口,普通的发博,评论等资源API依旧调用weibo.com接口。



开发者自身的授权

为了方便开发者编程、调试接口,针对开发者自身,可以使用开发者授权,这样开发者自己就不用通过频繁授权自己的应用,来获取授权token才能调接口。而且开发者的授权token有效期为5年。


开发者自身授权有一定的限制要求,即只有应用的所有者账号授权自己名下的应用时,才享有这个特性。


开发者自身授权可以通过接口测试工具快速获得,前提是需要用开发者的账号登录到微博开放平台,接口测试工具下才会列出这个账号下的应用,进而也只能获取到开发者名下所列出应用的授权token。



授权有效期

微博开放平台的OAuth2.0授权机制下,第三方获取到的access_token是有过期时间的,通常过期时间为30天。


授权级别和OAuth2.0 access_token有效期对应表:


授权级别 测试 普通
授权有效期 1天 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刷新授权有效期

除此之外,我们也提供了通过 Refresh Token 刷新的方式来延续授权有效期,但需要注意的是:只有使用微博官方移动SDK的移动应用,才可以从SDK的方法中获取到 Refresh Token。


Refresh Token 是 Access Grants 的一种,在获取 Access Token 时,认证服务器将返回相应的 Refresh Token,如果 Access Token 过期,就可以用 Refresh Token 去刷新。


Refresh Token 也是有有效期的,Refresh Token 的有效期目前为30天,在有效期内随时可以刷新。


通过 Refresh Token 刷新得到的新的 Access Token ,其有效期等同于原来的有效期,即原来 Access Token 的有效期是30天,则新获得的也是30天。


简单来说就是对于使用了微博移动SDK的移动应用,授权(Access Token)30天有效,30天内可续,从刷新时间点算起重新得到30天有效期。



1、当你是使用微博官方移动SDK的移动应用时,授权返回access_token的同时,还会多返回一个refresh_token:

JSON
{
    "access_token": "SlAV32hkKG",
    "remind_in": 3600,
    "expires_in": 3600
    "refresh_token": "QXBK19xm62"
}

2、当你调用API接口返回 Access Token 过期时,你可以调用 oauth2/access_token 并传入 refresh_token:

URL
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=…


返回值


JSON
{
    "access_token": "SlAV32hkKG",
    "expires_in": 3600
}

3、使用新获得的Access Token调用API


使用OAuth2.0调用API

使用OAuth2.0调用API接口有两种方式:

1、 直接使用参数,传递参数名为 access_token

URL
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文本。例如:


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相关问题