一、vivo帐号授权业务介绍
1、简介
支持您的用户使用vivo帐号快速便捷的登录您的应用,在用户授权的情况下可以获取其昵称、头像、性别、所在地、手机号(手机号只能快应用类型获取)等。
2、服务优势
① 一键授权登录
用户不必输入帐号、密码和繁琐验证,就可以通过“vivo帐号”快速登录,即刻使用您的应用,帮助您提升登录转化率。
② 用户信息授权
根据您的不同业务场景需求,可以申请获取用户的基本信息(头像、昵称、性别、所在地)及手机号信息,让您更了解用户。
③ 多设备支持
支持在手机、平板、电脑上接入vivo帐号服务。
二、开发准备
1、应用信息准备
① 接入vivo授权前请先在#vivo开放平台 (opens new window)上进行相关信息的填写与申请
② 如app自助生成软件未申请开发者帐号,请先申请开发者帐号,并创建应用
③ 通过开放平台获取到appid(client_id)、对应的clientsecret等信息,具体参照位置如下:
④ vivo开放平台-【管理中心】-【应用】,点击某个应用进入到应用详情页,【运营维护】-点击【帐号服务】,进入到账号服务页面,点击【vivo应用账号接入流程】了解接入授权流程
新版本授权sdk去除了联系人权限,不需要再去申请联系人权限
添加混淆的应用需要添加以下方法防混淆sdk。
-keep class com.bbk.account.** { *;} -keep public class com.vivo.ic.**{*; } -dontwarn com.vivo.ic.**
注意:非vivo生态应用接入vivo授权sdk需要另外接入一个commonsdk,具体可通过vivo开放平台-管理中心-应用分发-应用列表页-应用详情页-帐号服务进行获取
2、必要说明
① 授权码模式/标准授权模式:功能最完整、流程最严密的授权模式。它的特点是通过客户端的后台服务器,与服务提供商认证的服务器进行互动。cp客户端通过授权sdk获取到code,cp服务器通过code获取accesstoken,cp服务器通过accesstoken获取用户信息。
② v2新增scope用于代表不同类型的权限,每种权限又分完全权限和不完全权限。完全权限:对应信息在授权页面默认勾选、不可取消,用户同意授权后开发者获得授权码可换取对应信息;不完全权限:对应信息在授权页面默认勾选、可取消,如取消勾选但用户同意授权,开发者不能换取对应信息;仅能和具有完全权限的信息一同发起请求。
3、vivo帐号登录图标使用规范
具体使用图片,见附录
三、版本更新说明
1、2.0.1.3
升级内容(相较于上一版本)
新增功能
1.增加isLogin接口判断帐号是否登录
2.去除imei采集
2、v2.0.1.0
重要
1.接入时需要在开平重新申请appid
2.cp服务器必须进行升级以获取增量信息,否则只能获取基础信息
升级内容(相较于上一版本)
新增功能
1.增量授权,cp可通过配置scope获取增量信息
2.小窗授权改版,在不完全权限下用户可勾选需要授权信息
3.H5授权优化
安全优化
1.限制简化授权使用,简化授权不可获取增量信息
3、2.0.0.4
版本功能
新增功能
1.联系人权限去除
2.提供第三方应用登录注册vivo帐号功能
3.提供第三方应用获取vivo帐号信息功能
四、交互流程说明
1、应用间的交互流程图
① APP
② H5/PC
2、术语解释
缩略语/术语 | 全称 | 说明 |
clientid | 第三方服务ID | client_id是vivo标识对第三方的唯一性标识,就是在接入前申请的appid做为clientid |
clientsecret | 第三方服务器密钥 | 第三方访问vivo的密钥,用于签名,不能在公网中传输,在接入前申请的appkey做为clientsecret |
accesstoken | 访问令牌 | 在用户授权许可下,授权服务器下发给客户端的一个授权凭证,可以用access token获取用户授权的信息 |
refreshtoken | 刷新令牌 | 刷新令牌的作用在于更新访问令牌,访问令牌的有效期一般较短,这样在访问令牌失效时,可以利用刷新令牌去授权服务器换取新的访问令牌,是否需要该令牌是由第三方自行选择 |
redirecturi | 回调地址 | 一般回调地址都是根据H5自身的业务配置,如果某个业务仅仅有apk,而没有PC端的授权业务,可以简单配置为该公司的相关主域名|关于回调地址● 填写的地址必须符合 URI 规范,填写后可以修改;● HTTP 和 HTTPS 视为不同域,比如 http://vivo.com.cn 和 https://vivo.com.cn;● 请求传递的参数 redirectUri,其域名部分可以是注册时填写的回调地址的同级或子域名,路径部分可以是同级或子路径,但是 SCHEME 和端口号必须相同;● 授权码模式下,请求code步骤,回调地址是必填项 |
五、授权功能接入
1、APP
① 业务简介
提供安卓应用通过vivo授权sdk接入vivo帐号体系
② 使用入门
授权sdk授权时序图
③ 接口说明
添加混淆的应用需要添加以下方法防混淆sdk。
-keep class com.bbk.account.** { *;} -keep public class com.vivo.ic.**{*; } -dontwarn com.vivo.ic.**
注意:非vivo生态应用接入vivo授权sdk需要另外接入一个commonsdk,具体可通过vivo开放平台-管理中心-应用分发-应用列表页-应用详情页-帐号服务进行获取
必要说明:
a) 授权码模式/标准授权模式:功能最完整、流程最严密的授权模式。它的特点是通过客户端的后台服务器,与服务提供商认证的服务器进行互动。cp客户端通过授权sdk获取到code,cp服务器通过code获取accesstoken,cp服务器通过accesstoken获取用户信息。
b) v2新增scope用于代表不同类型的权限,每种权限又分完全权限和不完全权限。
• 完全权限: 对应信息在授权页面默认勾选、不可取消,用户同意授权后开发者获得授权码可换取对应信息
• 不完全权限: 对应信息在授权页面默认勾选、可取消,如取消勾选但用户同意授权,开发者不能换取对应信息;仅能和具有完全权限的信息一同发起请求
④ 各场景接入帐号细分开发
a) 初始化(app)
首先需要创建一个oauth对象,创建方法如下:
mOauth=newOauth.Builder(MainActivity.this) .setAppID(appid) .setRedirectUrl(reditUrl) .setKeepCookie(keepCookies) .build();
特别注意:
appid需要通过开平申请,reditUrl需要在申请appid的时候进行填写;
v2版本去掉了大小窗的设置,vivo生态应用(快应用、小游戏)默认小窗,非vivo生态应用大窗H5授权;
b) 授权码授权(app)
标准授权方式,授权SDK给应用返回授权Code,应用需要将Code传给应用自己的业务服务器,业务服务器再访问帐号服务器获以获取AccessToken和RefreshToken
c) 应用客户端获取code
调用授权SDK
接口:reqestCode 获取授权码
/** * 新版本授权只提供code模式授权 * @param callback 授权回调 * @param scope 授权信息scope */ public void requestCode(OauthCallback callback, String scope) { ReportParams params = AccountReportManager.getInstance(mContext).getReportParams(); params.requestType = Constant.AUTH_STANDARD; requestCodeOrAccesstoken(callback, Constant.OauthType.TYPE_CODE, scope); }
d) SDK目前提供的scope如下
scope | 说明 |
BASE_USERINFO | 基础用户信息(昵称、头像、openid) |
PHONE_USERINFO | 手机号信息 |
BASE_PHONE_USERINFO | 基础用户信息&手机号信息 |
注意:
i.目前只提供基础信息和手机号信息
ii.如果app申请的是不完全权限,则需要使用BASE_PHONE_USERINFO来申请手机号信息,不可单独入参手机号信息
iii.如果未登录,则会优先拉起vivo帐号登录页面,登录完成后跳转授权页面
iv.如果已登录,则直接拉起授权页面
v.当业务方获取到帐号信息后,下次调用requestCode接口,不再跳转授权页面,静默授权直接获取到code
• 代码示例
i.获取基础用户信息
mOauth.unRegisterOauthCallback(); mOauth.requestCode(mOauthCallback, Constant.Scope.BASE_USERINFO);
ii.获取手机号信息
mOauth.unRegisterOauthCallback(); mOauth.requestCode(mOauthCallback, Constant.Scope.PHONE_USERINFO);
iii.获取基础信息&手机号信息
mOauth.unRegisterOauthCallback(); mOauth.requestCode(mOauthCallback, Constant.Scope.BASE_PHONE_USERINFO);
iv.oauthCallback回调如下
OauthCallback mOauthCallback = new OauthCallback() { @Override public void onStartLoading() { showToast("onStartLoading() enter"); } @Override public void onResult(OauthResult result) { showToast("onResult() enter , result=" + result); } @Override public void onEndLoading() { showToast("onEndLoading() enter"); } };
2、H5
① 业务简介
提供非采用授权sdk的应用方,可通过跳转帐号H5授权页面的方式完成授权获取帐号信息,页面示例如下:
② 使用入门
基本接入流程:
a) 申请APPID和APPKEY。
b) 需要进行vivo账户授权时访问URL: https://passport.vivo.com.cn/oauth/2.0/authorize 跳转授权H5页面。
c) 用户在授权页同意授权,vivo会生成一个授权认证码code参数放在第三方服务申请的重定向URL之后并重定向第三方服务,第三方服务器用授权认证码code获取AccessToken。
d) 第三方服务器根据AccessToken获取用户授权的信息,信息包括头像、昵称、用户的唯一标识openid。
③ 接口说明
1.1 应用服务器根据code获取accessToken和refreshToken【服务器之间对接】
用户在点击确认授权后,授权sdk会返回授权认证码code,应用需要将code传递给应用自己的服务器,由服务器获取accesstoken和refreshToken。
备注:以下接口由应用自己的服务器和vivo帐号服务器进行对接,都是post请求,要设置成表单形式提交,参数放在url后面即可。
接口说明
url:https://passport.vivo.com.cn/oauth/v2/access_token
消息方向:应用服务器-》vivo帐号服务器
请求参数
参数 | 参数名称 | 类型 | 必填 | 参数说明 |
基本参数 | ||||
timestamp | 时间戳 | long | 是 | 请求的当前时间戳,时间戳和服务器时间戳进行校正过,时间戳是自 1970 年 1 月 1 日(00:00:00 GMT)以来的毫秒数 |
nonce | 随机字符串 | String | 是 | 随机字符串 |
sign | 签名 | String | 是 | 签名【附录有关于签名的算法的详细说明】 |
业务参数 | ||||
client_id | 第三方服务唯一标识 | String | 是 | vivo账户系统用来识别第三服务,由vivo分配给第三方服务 |
code | 授权认证码 | String | 是 | 授权认证码 |
grant_type | 授权类型 | String | 是 | 固定值:authorization_code |
示例:
入参
响应示例:
{ "code": 0, "msg": "成功", "data": { "access_token":"d3d8c085-372c-4141-8d0c-7fd5d", "refresh_token":"2edfd55f-2c28-4d09-99a6-c47ee8", "session_key":"96d3e29b-5203-4380-e97be064e0b5", "expire_in": 86400 } }
返回值含义如下
1.2 根据accessToken获取用户授权信息【服务器对接】
根据accessToken获取用户授权信息,帐号服务器会验证accessToken的合法性,当accessToken合法时,vivo服务器会返回对应的scope权限所包含的用户信息。
接口说明
调用方式:post
url:https://passport.vivo.com.cn/oauth/v2/resource
消息方向:应用服务器-》vivo帐号服务器
请求参数
参数 | 参数名称 | 类型 | 必填 | 参数说明 |
基本参数 | ||||
timestamp | 时间戳 | long | 是 | 请求的当前时间戳,时间戳和服务器时间戳进行校正过,时间戳是自 1970 年 1 月 1 日(00:00:00 GMT)以来的毫秒数 |
nonce | 随机字符串 | String | 是 | 随机字符串 |
sign | 签名 | String | 是 | 签名【附录有关于签名的算法的详细说明】 |
业务参数 | ||||
client_id | 第三方服务唯一标识 | String | 是 | vivo账户系统用来识别第三服务,由vivo分配给第三方服务 |
access_token | 授权令牌 | String | 是 | 授权令牌 |
示例:
入参
响应示例:
{ "code": 0, "msg": "成功", "data": { "openid": "vivo用户唯一标识", "nickname": "昵称 ", "avatar": "头像地址", "gender": "性别", "location": "所在地", "watermark": "敏感数据", "iv": "用于解密的iv" } }
敏感信息的解密见附录
1.3 根据refreshToken获取新accessToken【服务器对接】
accessToken有效期是24小时,当accessToken过期后可用refreshToken获取新的accessToken和refreshToken,原来的accessToken和refreshToken失效。
接口说明
url:https://passport.vivo.com.cn/oauth/v2/refresh_token
消息方向:应用服务器-》vivo帐号服务器
请求参数
参数 | 参数名称 | 类型 | 必填 | 参数说明 |
基本参数 | ||||
timestamp | 时间戳 | long | 是 | 请求的当前时间戳,时间戳和服务器时间戳进行校正过,时间戳是自 1970 年 1 月 1 日(00:00:00 GMT)以来的毫秒数 |
nonce | 随机字符串 | String | 是 | 随机字符串 |
sign | 签名 | String | 是 | 签名【附录有关于签名的算法的详细说明】 |
业务参数 | ||||
client_id | 第三方服务唯一标识 | String | 是 | vivo账户系统用来识别第三服务,由vivo分配给第三方服务 |
refresh_token | Refresh授权令牌 | String | 是 | Refresh授权令牌 |
grant_type | 类型 | String | 是 | 固定值:refresh_token |
示例:
响应示例:
{ "code": 0, "msg": "成功", "data": { "access_token":"329ca5a6e7f7f978", "refresh_token":"329ca5a6e7f7f978", "session_key":"329ca5a6e7f7f978", "expire_in": 86400 } }
1.4 取消授权
接入方可以选择给用户提供解除授权的能力
接口说明
url:https://passport.vivo.com.cn/oauth/v2/cancel
消息方向:应用服务器-》vivo帐号服务器
请求参数
参数 | 参数名称 | 类型 | 必填 | 参数说明 |
基本参数 | ||||
timestamp | 时间戳 | long | 是 | 请求的当前时间戳,时间戳和服务器时间戳进行校正过,时间戳是自 1970 年 1 月 1 日(00:00:00 GMT)以来的毫秒数 |
nonce | 随机字符串 | String | 是 | 随机字符串 |
sign | 签名 | String | 是 | 签名【附录有关于签名的算法的详细说明】 |
业务参数 | ||||
client_id | 第三方服务唯一标识 | String | 是 | vivo账户系统用来识别第三服务,由vivo分配给第三方服务 |
vivo_openid | 用户的唯一标识 | String | 是 |
示例:
响应示例:
{ "code": 0, "msg": "成功" }
返回码
2002002 | 超出权限范围 |
2002003 | 请求有风险,暂不提供信息 |
2002004 | 不能同时请求多条敏感权限 |
2002005 | 非法的clientId |
2002007 | 敏感信息的权限等级较低,不允许单独请求 |
2002009 | 非法请求 |
2002010 | timestamp 不能为空 |
2002011 | sign 不能为空 |
2002012 | client_id 不能为空 |
2002013 | sign error |
2002014 | 请求超时 |
2002015 | 无效的code |
2002016 | 无效的access_token |
2002017 | 无效的refresh_token |
④ 开发后自检
a) 回调地址时需要注意以下事项:
• 填写的地址必须符合 URI 规范,填写后可以修改
• HTTP 和 HTTPS 视为不同域,比如 http://vivo.com.cn 和 https://vivo.com.cn
• 请求传递的参数 redirect_uri,其域名部分可以是注册时填写的回调地址的同级或子域名,路径部分可以是同级或子路径,但是 SCHEME 和端口号必须相同
回调地址示例:
假设您申请时填写的回调地址是:https://vivo.com.cn/oauth2,那么 redirect_uri 的参数可以是:
错误示例:
http://vivo.com.cn/oauth?aa=1&bb=2//SCHEME不匹配
六、返回码解释
1、APP
oauthResult返回码说明
statusCode | 说明 |
200 | 授权码获取成功 |
12 | 用户取消授权 |
13 | 授权失败-网络无法链接 |
14 | 授权失败-其他错误 |
15 | aidl service断开 |
16 | 用户退出登录 |
19 | 帐号被冻结 |
20 | 黑名单帐号 |
21 | 外销帐号 |
22 | 超出授权权限 |
23 | 高风险帐号 |
24 | 禁止一次申请多个权限 |
提示
当应用每次调用接口时,接收回调之前都需要先解注册
2、H5/PC
2002002 | 超出权限范围 |
2002003 | 请求有风险,暂不提供信息 |
2002004 | 不能同时请求多条敏感权限 |
2002005 | 非法的clientId |
2002007 | 敏感信息的权限等级较低,不允许单独请求 |
2002009 | 非法请求 |
2002010 | timestamp 不能为空 |
2002011 | sign 不能为空 |
2002012 | client_id 不能为空 |
2002013 | sign error |
2002014 | 请求超时 |
2002015 | 无效的code |
2002016 | 无效的access_token |
2002017 | 无效的refresh_token |
七、附录
1、MD5签名
1.生成待签名的字符串
在请求参数中,除去签名参数(即sign),把其它的参数按照字段的顺序排序,排序完成后再把所有的参数用&符号连接起来,这样就完成了待签名的字符串
2.签名
• 目前暂只支持MD5签名。MD5 是一种摘要生成算法,通过在签名原始串后加上第三方的CientSecret(接入前申请的APPKEY)密钥的内容,进行MD5运算,形成的摘要字符串即为签名结果。
• 可以使用提供的工具类把所有请求所求参数放到Map中生成paraMap,用第三方服务申请的client_id(接入前申请的APPID)对应的client_secret(接入前申请的APPKEY)作为签名密钥,调用PartnerSignUtil的sign方法生成生成签名作为参数放在url后即可
public class PartnerSignUtil { /** * 签名字段名称 */ public final static String SIGNATURE = "sign"; /** * 签名方法字段名称 */ public final static String SIGN_METHOD = "sign_type"; /** * 签名字符串 * @param paraMap 需要签名的参数Map * @return 签名结果 */ public static String sign(Map<String,String> paraMap, String key) { String saltValue = key; return MD5SignUtil.sign(paraMap, saltValue, SIGNATURE, SIGN_METHOD); } /** * 验证签名 * @param paraMap 参数Map * @return 验签结果 */ public static boolean verify(Map<String, String> paraMap, String key) { String saltValue = key; String sign = paraMap.get("sign"); return MD5SignUtil.verify(paraMap, sign, saltValue, SIGNATURE, SIGN_METHOD); } }
注意
如需MD5SignUtil,可在vivo开放平台-管理中心-应用分发-应用列表页-应用详情页-帐号服务获取
2、敏感数据解密
• 用户手机号,邮箱等属于用户敏感数据,接入方拿到数据后需解密后才能拿到明文数据
• 密文数据为获取用户接口返回的watermark字段,采用aes算法进行的加密
• 解密方法调用:OAuthAESUtil.decrypt方法。decrypt(String sSrc, String key, String ivs)。第一个参数为密文字段,第二个参数为获取token时返回的session_key,第三个字段为获取用户信息时返回的字段iv
import javax.crypto.IllegalBlockSizeException; import javax.crypto.NoSuchPaddingException; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; public class OAuthAESUtil { public static String decrypt(String sSrc, String key, String ivs) { try { byte[] raw = key.getBytes("ASCII"); SecretKeySpec skeySpec = new SecretKeySpec(raw, "AES"); Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); IvParameterSpec iv = new IvParameterSpec(ivs.getBytes()); cipher.init(Cipher.DECRYPT_MODE, skeySpec, iv); byte[] encrypted1 = Base64.getDecoder().decode(sSrc);// 先用base64解密 byte[] original = cipher.doFinal(encrypted1); String originalString = new String(original, "utf-8"); return originalString; } catch (Exception ex) { return null; } } }
3、vivo图标合集
PNG、Sketch资源下载
4、SDK接入
授权sdk(oauth文件下载)
帐号工具类sdk(account文件下载)
服务器参数签名包(三个JAVA文件下载)
编辑:yimen,如若转载,请注明出处:https://www.yimenapp.com/kb-yimen/11877/
部分内容来自网络投稿,如有侵权联系立删