-
OAuth2.0
- OAuth: OAuth(开放授权)是一个开放标准,允许用户授权第三方网站访问他们存储在另外的服务提供者上的信息,而不需要将用户名和密码提供给第三方网站或分享他们数据的所有内容。
- QQ登录OAuth2.0:对于用户相关的OpenAPI(例如获取用户信息,动态同步,照片,日志,分享等),为了保护用户数据的安全和隐私,第三方网站访问用户数据前都需要显式的向用户征求授权。
QQ登录OAuth2.0总体处理流程:http://wiki.connect.qq.com/oauth2-0%e7%ae%80%e4%bb%8b
- Step1:申请接入,获取appid和appkey;
- Step2:开发应用,并设置协作者帐号进行测试联调;
- Step3:放置QQ登录按钮;
- Step4:通过用户登录验证和授权,获取Access Token;
- Step5:通过Access Token获取用户的OpenID;
- Step6:调用OpenAPI,来请求访问或修改用户授权的资源。
1. 准备工作:
作用:接入QQ登录前,网站需首先进行申请,获得对应的appid与appkey,以保证后续流程中可正确对网站与用户进行验证与授权。
1.1 申请appid和appkey
- 申请appid和appkey的用途
- appid:应用的唯一标识。在OAuth2.0认证过程中,appid的值即为oauth_consumer_key的值。
- appkey:appid对应的密钥,访问用户资源时用来验证应用的合法性。在OAuth2.0认证过程中,appkey的值即为oauth_consumer_secret的值。
- 申请地址
- 申请流程
1.2 保证连接畅通
接入QQ登录时,网站需要不停的和Qzone进行交互,发送请求和接受响应。
(1) 对于PC网站:请在你的服务器上ping graph.qq.com ,保证连接畅通。
(2) 对于WAP网站:请在你的服务器上ping open.z.qq.com和ping graph.z.qq.com,保证连接畅通。
(3)移动应用无需此步骤
2. 放置“QQ登录”按钮
作用:在网站页面上放置“QQ登录”按钮,并为按钮添加前台代码,实现点击按钮即弹出QQ登录对话框。
2.1 下载“QQ登录”按钮图片,并将按钮放置在页面合适的位置
2.2 为“QQ登录”按钮添加前台代码
- 效果演示
- 前台代码
- 代码示例
3. 使用Authorization_Code获取Access_Token(访问令牌)
作用:
- 通过用户验证登录和授权,获取Access Token,为下一步获取用户的OpenID做准备;
- 同时,Access Token是应用在调用OpenAPI访问和修改用户数据时必须传入的参数。
- 移动端应用可以直接获得AccessToken,请参考使用Implicit_Grant方式获取Access_Token
3.1 简介
即server-side模式,是OAuth2.0认证的一种模式,又称Web Server Flow;适用于需要从web server访问的应用,例如Web/wap网站。
其授权验证流程示意图如下(图片来源:OAuth2.0协议草案V21的4.1节 )
对于应用而言,需要进行两步:
1. 获取Authorization Code;
2. 通过Authorization Code获取Access Token
3.2 过程详解
(1)获取Authorization Code
- 请求地址:
PC网站:https://graph.qq.com/oauth2.0/authorize
WAP网站:https://graph.z.qq.com/moc2/authorize (暂停使用,PC接口会自适配WAP网站)
- 请求方法:GET
- 请求参数:请求参数请包含如下内容:
参数 | 是否必须 | 含义 |
---|---|---|
response_type | 必须 | 授权类型,此值固定为“code”。 |
client_id | 必须 | 申请QQ登录成功后,分配给应用的appid。 |
redirect_uri | 必须 | 成功授权后的回调地址,必须是注册appid时填写的主域名下的地址,建议设置为网站首页或网站的用户中心。注意需要将url进行URLEncode。 |
state | 必须 | client端的状态值。用于第三方应用防止CSRF攻击,成功授权后回调时会原样带回。请务必严格按照流程检查用户与state参数状态的绑定。 |
scope | 可选 | 请求用户授权时向用户显示的可进行授权的列表。
可填写的值是API文档中列出的接口,以及一些动作型的授权(目前仅有:do_like),如果要填写多个接口名称,请用逗号隔开。 例如:scope=get_user_info,list_album,upload_pic,do_like 不传则默认请求对接口get_user_info进行授权。 建议控制授权项的数量,只传入必要的接口名称,因为授权项越多,用户越可能拒绝进行任何授权。 |
display | 可选 | 仅PC网站接入时使用。
用于展示的样式。不传则默认展示为PC下的样式。 如果传入“mobile”,则展示为mobile端下的样式。 |
g_ut | 可选 | 仅WAP网站接入时使用。
QQ登录页面版本(1:wml版本; 2:xhtml版本),默认值为1。 |
- 返回说明:
1. 如果用户成功登录并授权,则会跳转到指定的回调地址,并在redirect_uri地址后带上Authorization Code和原始的state值。如:
PC网站:http://graph.qq.com/demo/index.jsp?code=9A5F************************06AF&state=test
WAP网站:http://open.z.qq.com/demo/index.jsp?code=9A5F************************06AF&state=test
注意:此code会在10分钟内过期。
2. 如果用户在登录授权过程中取消登录流程,对于PC网站,登录页面直接关闭;对于WAP网站,同样跳转回指定的回调地址,并在redirect_uri地址后带上usercancel参数和原始的state值,其中usercancel值为非零,如:
http://open.z.qq.com/demo/index.jsp?usercancel=1&state=test
- 错误码说明:
接口调用有错误时,会返回code和msg字段,以url参数对的形式返回,value部分会进行url编码(UTF-8)。
PC网站接入时,错误码详细信息请参见:100000-100031:PC网站接入时的公共返回码。
WAP网站接入时,错误码详细信息请参见:6000-6999:获取Authorization Code时,发生错误。
(2)通过Authorization Code获取Access Token
- 请求地址:
PC网站:https://graph.qq.com/oauth2.0/token
WAP网站:https://graph.z.qq.com/moc2/token
- 请求方法:GET
- 请求参数:请求参数请包含如下内容:
参数 | 是否必须 | 含义 |
---|---|---|
grant_type | 必须 | 授权类型,在本步骤中,此值为“authorization_code”。 |
client_id | 必须 | 申请QQ登录成功后,分配给网站的appid。 |
client_secret | 必须 | 申请QQ登录成功后,分配给网站的appkey。 |
code | 必须 | 上一步返回的authorization code。
如果用户成功登录并授权,则会跳转到指定的回调地址,并在URL中带上Authorization Code。 例如,回调地址为www.qq.com/my.php,则跳转到: http://www.qq.com/my.php?code=520DD95263C1CFEA087****** 注意此code会在10分钟内过期。 |
redirect_uri | 必须 | 与上面一步中传入的redirect_uri保持一致。 |
- 返回说明:如果成功返回,即可在返回包中获取到Access Token。
如:access_token=FE04************************CCE2&expires_in=7776000&refresh_token=88E4************************BE14
参数说明 | 描述 |
---|---|
access_token | 授权令牌,Access_Token。 |
expires_in | 该access token的有效期,单位为秒。 |
refresh_token | 在授权自动续期步骤中,获取新的Access_Token时需要提供的参数。 |
- 错误码说明:
接口调用有错误时,会返回code和msg字段,以url参数对的形式返回,value部分会进行url编码(UTF-8)。
PC网站接入时,错误码详细信息请参见:100000-100031:PC网站接入时的公共返回码。
WAP网站接入时,错误码详细信息请参见:7000-7999:通过Authorization Code获取Access Token时,发生错误。
(3)(可选)权限自动续期,获取Access Token
Access_Token的有效期默认是3个月,过期后需要用户重新授权才能获得新的Access_Token。本步骤可以实现授权自动续期,避免要求用户再次授权的操作,提升用户体验。
- 请求地址:
PC网站:https://graph.qq.com/oauth2.0/token
WAP网站:https://graph.z.qq.com/moc2/token
- 请求方法:GET
- 请求参数:请求参数请包含如下内容:
参数 | 是否必须 | 含义 |
---|---|---|
grant_type | 必须 | 授权类型,在本步骤中,此值为“refresh_token”。 |
client_id | 必须 | 申请QQ登录成功后,分配给网站的appid。 |
client_secret | 必须 | 申请QQ登录成功后,分配给网站的appkey。 |
refresh_token | 必须 | 在Step2中,返回的refres_token。 |
- 返回说明:如果成功返回,即可在返回包中获取到Access Token。
如:access_token=FE04************************CCE2&expires_in=7776000&refresh_token=88E4************************BE14。
参数说明 | 描述 |
---|---|
access_token | 授权令牌,Access_Token。 |
expires_in | 该access token的有效期,单位为秒。 |
refresh_token | 在授权自动续期步骤中,获取新的Access_Token时需要提供的参数。 |
- 错误码说明:
接口调用有错误时,会返回code和msg字段,以url参数对的形式返回,value部分会进行url编码(UTF-8)。
PC网站接入时,错误码详细信息请参见:100000-100031:PC网站接入时的公共返回码。
WAP网站接入时,错误码详细信息请参见:7000-7999:通过Authorization Code获取Access Token时,发生错误。
3.3 快速上手
详见:开发攻略_Server-side。
3.4 其他资源
移动端应用可以直接获得AccessToken,请参考使用Implicit_Grant方式获取Access_Token 。
4. 获取用户OpenID
作用:通过输入在上一步获取的Access Token,得到对应用户身份的OpenID。
OpenID是此网站上或应用中唯一对应用户身份的标识,网站或应用可将此ID进行存储,便于用户下次登录时辨识其身份,或将其与用户在网站上或应用中的原有账号进行绑定。
4.1 请求地址
PC网站:https://graph.qq.com/oauth2.0/me
WAP网站:https://graph.z.qq.com/moc2/me
4.2 请求方法:GET
4.3 请求参数:请求参数请包含如下内容:
参数 | 是否必须 | 含义 |
---|---|---|
access_token | 必须 | 在Step1中获取到的access token。 |
4.4 返回说明:PC网站接入时,获取到用户OpenID,返回包如下:
callback( {"client_id":"YOUR_APPID","openid":"YOUR_OPENID"} );
WAP网站接入时,返回如下字符串:
client_id=100222222&openid=1704************************878C
openid是此网站上唯一对应用户身份的标识,网站可将此ID进行存储便于用户下次登录时辨识其身份,或将其与用户在网站上的原有账号进行绑定。
4.5 错误码说明
接口调用有错误时,会返回code和msg字段,以url参数对的形式返回,value部分会进行url编码(UTF-8)。
PC网站接入时,错误码详细信息请参见:100000-100031:PC网站接入时的公共返回码。
WAP网站接入时,错误码详细信息请参见:9000-9999:根据Access Token获得对应用户身份的openid时,发生错误。
5. OpenAPI调用说明
作用:获取到Access Token和OpenID后,可通过调用OpenAPI来获取或修改用户个人信息。
5.1 前提说明
(1)该appid已经开通了该OpenAPI的使用权限。
从API列表的接口列表中可以看到,有的接口是完全开放的,有的接口则需要提前提交申请,以获取访问权限。
API列表:
分组名称 | 适用平台 | API接口 | 功能说明 | 备注 |
---|---|---|---|---|
访问用户资料 | 网站、移动 | get_user_info | 获取登录用户的昵称、头像、性别 | |
访问用户QQ会员信息 | 网站、移动 | get_vip_info | 获取QQ会员的基本信息 | 需要申请 |
get_vip_rich_info | 获取QQ会员的高级信息 | |||
访问我的空间相册 | 网站、移动 | list_album | 获取用户QQ空间相册列表 | 需要申请 |
upload_pic | 上传一张照片到QQ空间相册 | |||
add_album | 在用户的空间相册里,创建一个新的个人相册 | |||
list_photo | 获取用户QQ空间相册中的照片列表 | |||
访问我的腾讯微博资料 | 网站、移动 | get_info | 获取登录用户在腾讯微博详细资料 | |
分享内容到我的腾讯微博 | 网站、移动 | add_t | 发表一条微博 | |
del_t | 删除一条微博 | |||
add_pic_t | 发表一条带图片的微博 | |||
get_repost_list | 获取单条微博的转发或点评列表 | |||
获得我的微博好友信息 | 网站、移动 | get_other_info | 获取他人微博资料 | |
get_fanslist | 我的微博粉丝列表 | |||
get_idollist | 我的微博偶像列表 | |||
add_idol | 收听某个微博用户 | |||
del_idol | 取消收听某个微博用户 | |||
访问我的财付通信息 | 网站、移动 | get_tenpay_addr | 在这个网站上将展现您财付通登记的收货地址 | 需要申请 |
(2)准备访问的资源是用户授权可访问的。
网站调用该OpenAPI读写某个openid(用户)的信息时,必须是该用户已经对你的appid进行了该OpenAPI的授权(例如用户已经设置了相册不对外公开,则网站是无法读取照片信息的)。用户可以进入QQ空间->设置->授权管理进行访问权限的设置。
(3)已经成功获取到Access Token,并且Access Token在有效期内。
5.2 调用OpenAPI接口
QQ登录提供了用户信息/动态同步/日志/相册/微博等OpenAPI(详见API列表),网站需要将请求发送到某个具体的OpenAPI接口,以访问或修改用户数据。
调用所有OpenAPI时,除了各接口私有的参数外,所有OpenAPI都需要传入基于OAuth2.0协议的通用参数:
参数 | 含义 |
---|---|
access_token | 可通过使用Authorization_Code获取Access_Token 或来获取。
access_token有3个月有效期。 |
oauth_consumer_key | 申请QQ登录成功后,分配给应用的appid |
openid | 用户的ID,与QQ号码一一对应。
可通过调用https://graph.qq.com/oauth2.0/me?access_token=YOUR_ACCESS_TOKEN 来获取。 |
5.3 示例
1. 以get_user_info接口为例: (请将access_token,appid等参数值替换为你自己的)
https://graph.qq.com/user/get_user_info?access_token=YOUR_ACCESS_TOKEN&oauth_consumer_key=YOUR_APP_ID&openid=YOUR_OPENID
2. 成功返回后,即可获取到用户数据:
{ "ret":0, "msg":"", "nickname":"YOUR_NICK_NAME", ... }
获取用户的Access Token和OpenID,之后通过调用OpenAPI进行获取用户信息,并进行分享、发表微博或日志、上传图片等更多操作。
参考:http://wiki.connect.qq.com/%e6%94%be%e7%bd%aeqq%e7%99%bb%e5%bd%95%e6%8c%89%e9%92%ae_oauth2-0