跳转到: 导航, 搜索

授权机制

微博开放接口的调用,如发微博、关注等,都是需要获取用户身份认证的。目前微博开放平台用户身份鉴权主要采用的是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. 引导需要授权的用户到如下地址:

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接口。



授权有效期

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


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


授权级别 测试 普通
授权有效期 1天 7天


注:

  • 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 的有效期是7天,则新获得的也是7天。


简单来说就是对于使用了微博移动SDK的移动应用,授权(Access Token)7天有效,30天可续,每续一次增加7天有效。



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



文档更新时间: 2015-07-15