目录

 [隐藏

OAuth2.0概述

目前BIAOTEE开放平台用户身份鉴权只有OAuth2.0这一种方式。


关于OAuth2.0协议授权流程查看以下OAuth2.0授权流程图,其中Client指第三方应用,Resource Owner指用户,Authorization Server是我们的授权服务器,Resource Server是API服务器。


OAuth协议流程


开发者可以先浏览OAuth2.0的接口文档,熟悉OAuth2的接口及参数的含义,然后我们根据应用场景各自说明如何使用OAuth2.0。


注意事项:

    • 1、OAuth2.0授权无需申请,任何应用都可以使用。如果开发者需要更长的授权有效期参考本文档授权有效期部分。
    • 2、如果你是站外网页应用或客户端应用,出于安全性考虑,需要在平台网站填写redirect_url(授权回调页),才能使用OAuth2.0。

接口文档

接口 说明
oauth2/authorize 请求用户授权Token
oauth2/access_token 获取授权过的Access Token
oauth2/get_token_info 授权信息查询接口

授权页

OAuth协议介绍

应用场景

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

    • 1、插件应用授权
    • 2、网站应用授权
    • 3、桌面和无线客户端应用授权

验证授权

基本流程

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

http://open.biaotee.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

http://open.biaotee.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


BIAOTEEOAuth1.0的Access Token不会过期,只有用户手工撤销授权或Biaotee收回您的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:

http://open.biaotee.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 http://open.biaotee.com/statuses/public_timeline.json?access_token=abcd

2. 在header里传递 形式为在header里添加Authorization:OAuth2空格abcd 这里的abcd假定为Access Token的值


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

授权有效期

调用接口时判断接口的返回值,如果用户的access_token失效,需要引导用户重新授权。失效原因有以下几个:

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


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

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

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

授权页功能

scope

scope是OAuth2.0新版授权页提供的一个功能,通过scope,平台将开放更多的BIAOTEE核心功能给开发者,同时也加强用户隐私保护,提升了用户体验,用户在新OAuth2.0授权页中有权利选择赋予应用的功能。

客户端默认回调页

客户端一般没有服务器回调地址,您可以在应用控制台授权回调页处填写回调地址,该回调页面不可见,仅用于获取access token。

取消授权回调页

开发者可以在应用控制台填写取消授权回调页,当用户取消你的应用授权时,开放平台会回调你填写的这个地址。并传递给你以下参数:

client_id:应用appkey

uid :取消授权的用户

auth_end :取消授权的时间

OAuth2.0 错误码

BIAOTEEOAuth2.0实现中,授权服务器在接收到验证授权请求时,会按照OAuth2.0协议对本请求的请求头部、请求参数进行检验,若请求不合法或验证未通过,授权服务器会返回相应的错误信息,包含以下几个参数:

  • error: 错误码
  • error_code: 错误的内部编号
  • error_description: 错误的描述信息
  • error_url: 可读的网页URI,带有关于错误的信息,用于为终端用户提供与错误有关的额外信息。


错误信息的返回方式有两种:

1. 当请求授权:http://open.biaotee.com/oauth2/authorize 时出现错误,将跳转到redirect_uri,并在uri 的query parameter中附带错误的描述信息。

2. 当请求access token时:http://open.biaotee.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 服务暂时无法访问
帐号:
密码:
验证码:
看不清?换一张
 
下次自动登录
 
登录忘记密码,找回?
邮箱:
手机:
 
手机验证码:
用户名:
密码:
确认密码:
验证码:
看不清?换一张
 
同意注册协议
 
注册

您也可以使用合作网站账号登录