跳转到: 导航, 搜索
第1行: 第1行:
==OAuth2.0概述==
+
=授权机制=
  
大部分API的访问如发表微博、获取私信,关注都需要用户身份,目前微博开放平台用户身份鉴权有OAuth2.0和Basic Auth(仅用于应用所属开发者调试接口),新版接口也仅支持这两种方式。
+
<div class="wiki_txtJ">
 +
微博开放接口的调用,如发微博、关注等,都是需要获取用户身份认证的。目前微博开放平台用户身份鉴权主要采用的是OAuth2.0。另外,为了方便开发者开发、测试自己的应用,我们还提供了Basic Auth的身份鉴权方式,但Basic Auth仅适用于应用所属的开发者自己调用接口。
 +
</div>
  
  
OAuth2.0较1.0相比整个授权验证流程更简单更安全,也是未来最主要的用户身份验证和授权方式。
+
==OAuth2.0概述==
  
 +
<div class="wiki_txtJ">
 +
OAuth2.0较1.0相比,整个授权验证流程更简单更安全,也是未来最主要的用户身份验证和授权方式。
  
关于OAuth2.0协议授权流程查看[http://www.sinaimg.cn/blog/developer/wiki/oAuth2_01.gif OAuth2.0授权流程] ,其中Client指第三方应用,Resource Owner指用户,Authorization Server是我们的授权服务器,Resource Server是API服务器。
 
  
 +
关于OAuth2.0协议的授权流程可以参考下面的流程图,其中Client指第三方应用,Resource Owner指用户,Authorization Server是我们的授权服务器,Resource Server是API服务器。
  
开发者可以先浏览OAuth2.0的接口文档,熟悉OAuth2的接口及参数的含义,然后我们根据应用场景各自说明如何使用OAuth2.0。
 
  
 +
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/oAuth2_01.gif}}
  
'''注意事项:'''
 
  
**1、OAuth2.0授权无需申请,任何应用都可以使用。如果开发者需要更长的授权有效期参考本文档授权有效期部分。
+
开发者可以先浏览OAuth2.0的接口文档,熟悉OAuth2.0的接口及参数的含义,然后我们根据应用场景各自说明如何使用OAuth2.0。
**2、如果你是站外网页应用或客户端应用,出于安全性考虑,需要在平台网站填写redirect_url(授权回调页),才能使用OAuth2.0,填写地址:http://open.weibo.com/apps/应用APPKEY/privilege/oauth  对于客户端,我们也提供了默认的回调页地址。详细请查看授权页功能部分。
+
</div>
 +
 
  
==接口文档==
+
'''接口文档'''
  
 
<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%">
第46行: 第50行:
 
</td></tr>
 
</td></tr>
 
</table>
 
</table>
 +
 +
 +
'''注意事项'''
 +
 +
**1、OAuth2.0授权无需申请,任何应用都可以使用。如果开发者需要更长的授权有效期参考本文档授权有效期部分。
 +
**2、如果你是站外网页应用或客户端应用,出于安全性考虑,需要在平台网站填写redirect_url(授权回调页),才能使用OAuth2.0,填写地址:<span style="color:#FF7D13;">“我的应用>应用信息>高级信息”</span>,对于客户端,我们也提供了默认的回调页地址。详细请查看授权页功能部分。
 +
  
 
==授权页==
 
==授权页==
  
{{center|http://www.sinaimg.cn/blog/developer/wiki/OAuth2_intro.png}}
+
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/OAuth2_intro.png}}
 +
 
  
 
新版授权页改变了之前页面信息元素过多,对用户使用带来干扰的问题,登录和授权这两个行为已在新版中分离,用户能够更好地理解帐号登录和授权的过程,也为未来更多的功能带来承载空间。
 
新版授权页改变了之前页面信息元素过多,对用户使用带来干扰的问题,登录和授权这两个行为已在新版中分离,用户能够更好地理解帐号登录和授权的过程,也为未来更多的功能带来承载空间。
第60行: 第72行:
  
  
{{center|http://www.sinaimg.cn/blog/developer/wiki/oauth2v3.png}}
+
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/oauth2v3.png}}
 +
 
  
 
==应用场景==
 
==应用场景==
  
 
+
<div style="margin:15px 0;">
 
开发者需要根据各自的应用场景,选择适用的OAuth2.0授权流程:
 
开发者需要根据各自的应用场景,选择适用的OAuth2.0授权流程:
  
  
**1、网站或者站外Web应用,请参考:Web应用的验证授权(Authorization Code)
+
**1、PC端和Web应用,请参考:Web应用的验证授权(Authorization Code)
**2、桌面和无线客户端应用,请参考:Web应用的验证授权(Authorization Code),无线客户端可以直接使用官方SDK,通过WebView方式使用授权页。
+
**2、移动端应用,可以直接使用官方移动SDK,通过呼起微博客户端(未安装微博客户端的会呼起H5授权页)方式使用授权
**3、微博站内应用,请参考 [[站内应用开发指南]]
+
**3、H5轻应用,请参考 [[轻应用开发指南]]
 +
</div>
 +
 
 +
 
 +
<div class="wiki_title_withline">Web应用的验证授权</div>
  
  
===Web应用的验证授权===
+
{{Img_polaroid|src=http://www.sinaimg.cn/blog/developer/wiki/oAuth2_02.gif}}
[http://www.sinaimg.cn/blog/developer/wiki/oAuth2_02.gif 基本流程]
+
  
  
第404行: 第420行:
 
==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相关问题]
 
查看 [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__

2015年3月26日 (四) 16:20的版本

授权机制

微博开放接口的调用,如发微博、关注等,都是需要获取用户身份认证的。目前微博开放平台用户身份鉴权主要采用的是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轻应用,请参考 轻应用开发指南


Web应用的验证授权



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

移动应用的验证授权

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


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


参考:移动客户端接入

站内应用的验证授权

参考: 站内应用开发指南


微博OAuth1.0的Access Token不会过期,只有用户手工撤销授权或新浪收回您的app访问权限时Access Token才会失效。但OAuth2.0的过期时间通常为1天。


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


注:Refresh Token需要单独申请

使用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的值


其它接口参数正常传递即可。


注:所有的资源API都部署在weibo.com域下,仅有移动端的授权接口在open.weibo.cn域。 所以任何一种应用类型,调用的都是weibo.com上的资源API。

授权有效期

程序一定要具备足够的健壮性,调用接口时判断接口的返回值,如果用户的access_token失效,需要引导用户重新授权。失效原因有以下几个:

    1. 用户取消了对应用的授权
    2. access_token自然过期
    3. 用户修改了密码,冻结了对应用的授权
    4. 新浪发现用户帐号被盗,冻结了用户对应用的授权


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

授权级别 测试 普通 中级 高级
授权有效期 1天 7天 30天 90天

注:

  1. 只有未过文案审核的应用才处于测试级别。
  2. 应用所属开发者授权应用时,有效期为5年。


access_token自动延续方案


如果用户在授权有效期内重新打开授权页授权(如果此时用户有微博登录状态,这个页面将一闪而过),那么新浪会为开发者自动延长access_token的生命周期,请开发者维护新授权后得access_token值。


如何查询当前应用的授权级别

你可以在 http://open.weibo.com/apps/应用APPKEY/privilege/oauth 上查询当前应用的授权级别。


如何计算某个用户的access_token过期时间?

开发者可以通过两种方式计算:

    1. 用户授权时,oauth2/access_token接口返回的expires_in值就是access_token的生命周期。
    2. 从上述对应表中,找到应用所对应的授权有效期,过期时间 = 用户授权时间 + 授权有效期


如何申请授权有效期

可在应用控制台,接口管理标签下的授权机制选项中进行在线申请。

授权页功能

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