跳转到: 导航, 搜索

授权机制

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



OAuth2.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权限,系统会自动跳过此步骤,回调回第三方应用。只要合理的使用高级授权(SCOPE),开发者完全不必担心增加操作所带来的页面流失率问题,相反,一个清晰的授权体验更能获取用户的信任。


与此同时,授权项将会变的更加有条理,之前的普通权限将作为基础服务,用户不再有感知,与用户隐私相关的会归到高级授权,用户在授权时有权利逐条取消,进一步增强了隐私控制。



应用场景

开发者需要根据各自的应用场景,选择适用的 OAuth2.0 授权流程:


    • 1、PC端和Web网站,请参考:Web网站的验证授权(Authorization Code)
    • 2、移动端应用可直接使用微博移动SDK,通过呼起微博客户端(未安装微博的会呼起H5授权页)方式授权
    • 3、开发者自己在调试阶段,可以使用开发者自身授权


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),建议使用官方提供的移动SDK。



开发者自身的授权

为了方便开发者编程、调试接口,针对开发者自身,可以使用开发者授权,这样开发者自己就不用通过频繁授权自己的应用,来获取授权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的值,其它接口参数正常传递即可。


授权中的其他功能

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 相关资源

OAuth2.0 的官方技术说明可参看 http://oauth.net/2/


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 应用权限不足





文档更新时间: 2022-10-11