一、vivo帐号授权业务介绍

1、简介

支持您的用户使用vivo帐号快速便捷的登录您的应用，在用户授权的情况下可以获取其昵称、头像、性别、所在地、手机号（手机号只能快应用类型获取）等。

2、服务优势

① 一键授权登录

用户不必输入帐号、密码和繁琐验证，就可以通过“vivo帐号”快速登录，即刻使用您的应用，帮助您提升登录转化率。

② 用户信息授权

根据您的不同业务场景需求，可以申请获取用户的基本信息（头像、昵称、性别、所在地）及手机号信息，让您更了解用户。

③ 多设备支持

支持在手机、平板、电脑上接入vivo帐号服务。

二、开发准备

1、应用信息准备

① 接入vivo授权前请先在#vivo开放平台 (opens new window)上进行相关信息的填写与申请

② 如未申请开发者帐号，请先申请开发者帐号，并创建应用

③ 通过开放平台获取到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 的参数可以是：

https://vivo.com.cn/oauth2?aa=1&bb=2

https://vivo.com.cn/oauth2/path?aa=1&bb=2

错误示例：

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文件下载）