登录 | 注册
首页开发文档

OAuth2.0文档

目录

1、OAuth 2.0 简介

OAuth为应用提供了一种访问受保护资源的方法。在应用访问受保护资源之前,它必须先从资源拥有者处获取授权(访问许可),然后用访问许可交换访问令牌(代表许可的作用域、持续时间和其它属性)。应用通过向资源服务器出示访问令牌来访问受保护资源。建议使用oauth2.0。

360开放平台OAuth2.0服务支持以下3种获取Access Token的方式:

A.Authorization Code:Web Server Flow,适用于所有有Server端配合的应用。

B.Implicit Grant:User-Agent Flow,适用于所有无Server端配合的应用。

C.Refresh Token:令牌刷新方式,适用于所有有Server端配合的应用。

下面我们将逐个介绍三种获取Access Token的方法。

2、获取Access Token的流程

2.1、使用Authorization Code获取Access Token

2.1.1、简介

授权码是通过将用户引导到授权服务器而获得的一种访问许可。授权服务器验证用户,获得授权,然后向应用分发一个授权码。因为终端用户只在授权服务器上进行验证,所以终端用户的密码从来不用分享给应用。

当应用通过一个user-agent同用户进行交互的时候,授权码访问许可的方式是很合适的。 t01c30f88cf3bf33a84.png

图1所示的授权码获取流程包含下列步骤:

A.应用调用javascript的window.open()弹出窗口,并在该窗口将用户的user-agent引导到授权服务器的用户授权endpoint来发起这个流程。客户端传入标识符、请求作用域、本地状态,和一个重定向URI(在访问被许可或被拒绝后授权服务器会重新将user-agent引导回这个URI)。

B.授权服务器验证用户的身份(通过user-agent),并且确定用户是许可还是拒绝了应用的访问请求。

C.如果访问被许可,授权服务器会使用重定向URI将user-agent引导回应用。授权服务器传回一个授权码给应用,用于进一步获取访问令牌。如果用户选择拒绝授权,user-agent将关闭此弹出窗口。

2.1.2、获取Authorization Code

请求参数:

参数名 必选 介绍
client_id True 创建应用时获得的App Key
response_type True 此值固定为“code”
redirect_uri False 授权后要回调的URI,即接收Authorization Code的URI, 其值可以是“oob”。 非“oob”值的redirect_uri所在域名必须与开发者注册应用时所提供的回调地址的域名相匹配
scope False 以空格分隔的权限列表,若不传递此参数,代表请求默认的basic权限。(目前只有basic权限)
state False 用于保持请求和回调的状态,授权服务器在回调时(重定向用户浏览器到“redirect_uri”时),会在Query Parameter中原样回传该参数
oauth_version False (可选)版本号,如果填写必须为1.0
display False 登录和授权页面的展现样式,360桌面应用请传递“desktop”,默认为“default”或空。
relogin False 仅在实现"使用360账号登陆"功能时才需要传递。当浏览器有360cookie时,传递relogin可展示“当前账号登陆确认页”;relogin值请传递公司域名,如www.360.cn可传递"relogin=360.cn"

请求示例:

https://openapi.360.cn/oauth2/authorize?client_id=0fb2676d5007f123756d1c1b4b5968bc&response_type=code&redirect_uri=http://www.example.com/oauth_redirect&scope=basic&display=default

授权服务器会根据应用传递参数的不同,为用户展现不同的授权页面。如果用户在此页面同意授权,授权服务则将重定向用户浏览器到指定的“redirect_uri”,并附带上表示授权服务所分配的Authorization Code的code参数,以及state参数(如果请求authorization code时带了这个参数)。

例如:继续上面的例子,假设授权服务在用户同意授权后生成的Authorization Code为“120653f48687763d6ddc486fdce6b51c383c7ee544e6e5eab“,则授权服务将会返回如下响应包以重定向用户浏览器到“http://www.example.com/oauth_redirect”地址上:

返回示例:

HTTP/1.1 200 OK
Location: http://www.example.com/oauth_redirect?
state=&code=120653f48687763d6ddc486fdce6b51c383c7ee544e6e5eab

说明:

A. “code”参数可以在“redirect_uri”对应的应用后端程序中获取。

B. 每一个Authorization Code的有效期为30秒,并且只能使用一次,再次使用将无效。

2.1.3、通过Authorization Code获取Access Token

通过上面第一步获得Authorization Code后,便可以用其换取一个Access Token。

请求参数:

参数名 必选 介绍
grant_type True 此值固定为“authorization_code”
code True 通过上面第一步所获得的Authorization Code
client_id True 应用的App Key
client_secret True 应用的App Secret
redirect_uri True redirect_uri所在域名必须与开发者注册应用时所提供的回调地址的域名相匹配

请求示例:

https://openapi.360.cn/oauth2/access_token?grant_type=authorization_code&code=120653f48687763d6ddc486fdce6b51c383c7ee544e6e5eab&client_id=0fb2676d5007f123756d1c1b4b5968bc&client_secret=8d9e3305c1ab....&redirect_uri=http://www.example.com/oauth_redirect

返回参数:

若参数无误,服务器将返回一段JSON文本,包含以下参数

参数名 必选 介绍
access_token True 获取的Access Token
expires_in True Access Token的有效期,以秒为单位
refresh_token True 用于刷新Access Token 的 Refresh Token
scope True Access Token最终的访问范围,即用户实际授予的权限列表(用户在授权页面时,有可能会取消掉某些请求的权限)

返回示例:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
  "access_token":"120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873",
  "expires_in":"3600",
  "scope":"basic",
  "refresh_token":"12065961868762ec8ab911a3089a7ebdf11f8264d5836fd41"
}

2.2、使用Implicit_Grant获取Access_Token

2.2.1、简介

采用Implicit Grant方式获取Access Token的授权验证流程又被称为User-Agent Flow,适用于所有无Server端配合的应用(由于应用往往位于一个User Agent里,如浏览器里面,因此这类应用在某些平台下又被称为Client-Side Application),如手机/桌面客户端程序、浏览器插件等,以及基于JavaScript等脚本语言实现的应用,他们的一个共同特点是,应用无法妥善保管其应用密钥(App Secret),如果采取Authorization Code模式,则会存在泄漏其应用密钥的可能性。其流程示意图如下:

t010baa26dd4dd48f83.png

2.2.2、获取Access Token

为了获取Access Token,应用需要将用户浏览器(或手机/桌面应用中的浏览器组件)引导到360应用开放平台OAuth2.0授权服务的“https://openapi.360.cn/oauth2/authorize”地址上,并带上以下参数:

参数名 必选 介绍
client_id True 获取的Access Token
response_type True 此值固定为“token”
redirect_uri False 授权后要回调的URI,即接受code的URI, 其值可以是“oob”。 非“oob”值的redirect_uri所在域名必须与开发者注册应用时所提供的回调地址的域名相匹配
scope False 以空格分隔的权限列表,若不传递此参数,代表请求默认的basic权限。(目前只有basic权限)
state False 用于保持请求和回调的状态,授权服务器在回调时(重定向用户浏览器到“redirect_uri”时),会在Query Parameter中原样回传该参数
display False 登录和授权页面的展现样式,PC应用请传递“desktop”,默认为“page”,手机应用请传递mobile.default

例如:“client_id”为“ 0fb2676d5007f123756d1c1b4b5968bc”的应用要请求某个用户的默认权限,并在授权后需跳转到“http://www.example.com/oauth_redirect”,同时希望在弹出窗口中展现用户登录授权界面,则应用需要重定向用户浏览器到如下URL:

https://openapi.360.cn/oauth2/authorize?client_id=0fb2676d5007f123756d1c1b4b5968bc&response_type=token&redirect_uri=http://www.example.com/oauth_redirect&scope=basic&display=default

返回参数:

参数名 必选 介绍
access_token True 要获取的Access Token
expires_in True Access Token的有效期,以秒为单位
state False 如果请求获取Access Token时带有state参数,则将该参数原样返回

返回示例:

HTTP/1.1 200 OK
Location: http://www.example.com/oauth_redirect?state=#
access_token=120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873&
expires_in=3600

2.3、使用Refresh_Token获取Access_Token

2.3.1、简介

360应用开放平台的应用无论通过OAuth2.0哪种方式获取Access Token,都会拿到有效期为14天的Refresh Token,和一个小时有效期的Access Token。对于这些应用,只要用户在14天内登录,应用就可以使用Refresh Token获得新的Access Token。

2.3.2、获取Access Token

要使用Refresh Token获得新的Access Token,需要应用在其服务端发送请求(推荐用POST方法)到360开放平台OAuth2.0授权服务的以下地址: “https://openapi.360.cn/oauth2/access_token”,并带上以下参数:

参数名 必选 介绍
grant_type True 必须为“refresh_token”
refresh_token True 用于刷新Access Token用的Refresh Token
client_id True 应用的App Key
client_secret True 应用的App Secret
scope False 以空格分隔的权限列表,若不传递此参数,代表请求默认的basic权限。注:通过Refresh Token刷新Access Token时所要求的scope权限范围必须小于等于上次获取Access Token时授予的权限范围

请求示例:

https://openapi.360.cn/oauth2/access_token?grant_type=refresh_token&refresh_token=12065961868762ec8ab911a3089a7ebdf11f8264d5836fd41&client_id=0fb2676d5007f123756d1c1b4b5968bc&client_secret=8d9e3305c1ab18384f56.....&scope=basic

若请求成功服务器将返回一段JSON文本,包含以下参数

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
  "access_token":"120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873",
  "expires_in":"3600",
  "scope":"basic",
  "refresh_token":"12065961868762ec8ab911a3089a7ebdf11f8264d5836fd41
"}

3、使用OAuth2.0调用API

获取access_token以后,就可以使用OAuth2.0调用API接口,有以下3种方法。

3.1、使用URL传递验证参数

在调用API的URL中传递需要的参数,如下(参数的详细介绍请参照API文档):

https://openapi.360.cn/user/me.json?access_token=120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873

3.2、在header里传递验证参数

在header里添加Authorization:OAuth2空格Access Token的值。

Authorization: Oauth2 120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873

3.3、在Post中传递验证参数

在post传递的参数中加上Access Token。

access_token=120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873

4、程序示例

4.1、基于360 OAUTH2.0 PHP SDK调用示例

// Create a Oauth2 object
$connection = new QClient(API_KEY, API_SECRET, $access_token);
$apiResult = $connection->userMe();

4.2、返回结果

userMe:object(stdClass)#4 (3) {
  ["id"]=>string(8) "11111111"
  ["name"]=>string(7) "nameExample"
  ["avatar"]=>string(69) "http://avataraddress/face.jpg"
}
关闭

Copyright © 2005-2012 360.CN All Rights Reserved.

360安全中心 版权所有