1. 接入指南

1.1. 开发者注册

登录中国移动开发者社区注册成为开发者

insert-01

1.1.1 个人开发者注册

insert-02

1.1.2. 企业开发者注册流程

insert-03

1.2. 应用接入

1.2.1. 创建应用

开发者账号创建后,开发者社区将给您的注册邮箱发一封账号激活邮件,开发者通过邮箱激活账号并登录中国移动开发者社区,如果开发者需要申请使用统一认证能力,从首页点击进去统一认证快捷申请通道:

insert-04

填写开发者的应用信息:

insert-05

应用创建成功后,显示开发者的AppID和APP Key信息

insert-06


1.2.2. 能力配置

开发者在获取APP ID和APP Key后,需要完成能力配置后才可以正式调用统一认证能力 。开发者进入统一认证快捷申请页面,选择需要申请的应用,在操作列点击统一认证配置进入能力配置页面,针对不同的系统平台,能力配置方法如下(其中本机号码校验为可选项):


1.2.3. 获取sourceID

开发者在集成过程中,需要使用sourceID去校验和区分业务,开发者可以在开发者社区管理中心业务维护查看用户创建的(或系统默认的)业务ID(sourceID

什么是业务ID(sourceID)?

业务ID是开发者已申请应用的一个集合,它可以包含开发者已申请的多款相同功能但不同平台的应用。例如,开发者有一款应用叫做和多号,分别在Android、iOS平台发布了两款应用,那么,我们强烈的建议开发者您创建一个业务名为“和多号”的业务,把这两款应用归属到“和多号”业务中。

insert-10


1.2.4. 配置业务服务端地址

统一认证的所有返回结果都会先传给业务侧服务端,再由业务侧服务端通过接口将结果传给客户端,因此,开发者需要在开发者社区中填写业务侧的结果回调IP地址,支持多个IP地址。insert-11

2. 开发指南

2.1. Android开发指南

2.1.1. 开发环境配置

2.1.1.1. 总体使用流程

  1. 调用SDK方法来获得token,步骤如下:

    a. 构造SDK中认证工具类AuthnHelper的对象;
    b. 使用AuthnHelper中的umcLoginByType方法,获得token。

  2. 使用平台获取用户信息接口,取得用户信息


2.1.1.2. 新建工程并导入SDK的jar文件

  1. CMCCSSOSDK_*.jar拷贝到应用工程的libs目录下,如没有该目录,可新建;
  2. 将sdk所需要的证书文件clientCert.crtserverPublicKey.pem拷贝到项目assets目录下。

1

  1. 将sdk所需要的资源文件从res目录下的文件添加到项目工程中,如图:

anim文件:

14

drawabledrawable-xxhdpi文件:

15


16

layout文件:

17

values文件:

18


2.1.1.3. 配置AndroidManifest

注意:为避免出错,请直接从Demo中复制带标签的代码

1. 配置权限

 

2. 配置授权登录activity

开发者根据需要配置横竖屏方向:android:screenOrientation 示列代码为unspecified(默认值由系统选择显示方向)

 

通过以上两个步骤,工程就已经配置完成了。接下来就可以在代码里使用统一认证的SDK进行开发了


2.1.1.4. SDK使用步骤

1. 创建一个AuthnHelper实例

AuthnHelper是SDK的功能入口,所有的接口调用都得通过AuthnHelper进行调用。因此,调用SDK,首先需要创建一个AuthnHelper实例,其代码如下:

 

2. 实现回调

所有的SDK接口调用,都会传入一个回调,用以接收SDK返回的调用结果。结果以JsonObjent的形式传递,TokenListener的实现示例代码如下:

 

3. 接口调用

 

2.1.2. 一键登录

2.1.2.1. 获取管理类的实例对象

1. 方法描述

获取管理类的实例对象


原型

 


2. 参数说明
参数类型说明
contextContext调用者的上下文环境,其中activity中this即可以代表。


2.1.2.2. 登录方法

开发者向统一认证服务器获取用户身份标识openId和临时凭证token

openId:每个APP每个手机号码对应唯一的openId。

临时凭证token:开发者服务端可凭临时凭证token通过3.1获取用户信息接口获取用户手机号码。


1. 方法描述

业务流程图

19

SDK自动调起登录等待界面(图一),同时自动获取本机号码;若获取本机号码成功,自动切换到授权登录页面(图二),用户授权登录后,即可使用本机号码进行登录;若用户获取本机号码失败,自动跳转到短信验证码登录页面(图三),引导用户使用短信验证码登录。

20

用户授权登录后,给开发者返回token用户ID(openID)等信息。


原型

 


2. 参数说明

请求参数

参数类型说明
appIdString应用的AppID
appkeyString应用密钥
loginTypeString登录类型,AuthnHelper.UMC_LOGIN_DISPLAY
authTypeString认证类型,目前支持三种认证类型:
1.短信验证码:AuthnHelper.AUTH_TYPE_DYNAMIC_SMS
2.网关鉴权:AuthnHelper.AUTH_TYPE_WAP
3.短信上行:AuthnHelper.AUTH_TYPE_SMS
(开发者可单独选择其中一种认证类型,也可以用“+”号组合同时使用三种认证类型,SDK登录认证优先级顺序为:网关鉴权 → 短信上行 → 短信验证码)
示例:AuthnHelper.AUTH_TYPE_WAP + AuthnHelper.AUTH_TYPE_DYNAMIC_SMS
listenerTokenListenerTokenListener为回调监听器,是一个java接口,需要调用者自己实现;TokenListener是接口中的认证登录token回调接口,OnGetTokenComplete是该接口中唯一的抽象方法,即void OnGetTokenComplete(JSONObject  jsonobj)


响应参数

OnGetTokenComplete的参数JSONObject,含义如下:

字段类型含义
resultCodeInt接口返回码,“103000”为成功。具体响应码见4.1 SDK返回码
resultDescString失败时返回:返回错误码说明
tokenString成功时返回:身份标识,字符串形式的token,应用将该token经应用侧平台向统一认证平台请求认证
openIdString成功时返回:用户身份唯一标识


3. 示例

请求示例代码

 

响应示例代码

 


2.1.2.3. 预取号方法

1. 方法描述

使用显式登录前,可以通过预取号提前获取用户信息并缓存。用户再次登录时,会自动使用缓存的信息快速登录来获取token用户ID(openID)等信息。提高登录速度,缓存的有效时间是5min并且只有一次使用有效期。


原型

 


2. 参数说明

请求参数

参数类型说明
appIdString应用的AppID
appkeyString应用密钥
listenerTokenListenerTokenListener为回调监听器,是一个java接口,需要调用者自己实现;TokenListener是接口中的认证登录token回调接口,OnGetTokenComplete是该接口中唯一的抽象方法,即void OnGetTokenComplete(JSONObject  jsonobj)


响应参数

OnGetTokenComplete的参数JSONObject,含义如下:

字段类型含义
resultCodeInt接口返回码,“103000”为成功。具体响应码见4.1 SDK返回码
descboolean成功标识,true为成功。


3. 示例
 

响应示例代码

 

2.1.3. 本机号码校验

2.1.3.1. 获取管理类的实例对象

1. 方法描述

获取管理类的实例对象


原型

 


2. 参数说明
参数类型说明
contextContext调用者的上下文环境,其中activity中this即可以代表。


2.1.3.2. 获取校验凭证token

1. 方法描述

开发者向统一认证服务器获取用户身份标识openId和临时凭证token

openId:每个APP每个手机号码对应唯一的openId。

临时凭证token:开发者服务端可凭临时凭证token通过3.1本机号码校验接口对本机号码进行验证。


原型

 


2. 参数说明

请求参数

参数类型说明
appIdString应用的AppID
appkeyString应用密钥
listenerTokenListenerTokenListener为回调监听器,是一个java接口,需要调用者自己实现;TokenListener是接口中的认证登录token回调接口,OnGetTokenComplete是该接口中唯一的抽象方法,即void OnGetTokenComplete(JSONObject  jsonobj)

响应参数

OnGetTokenComplete的参数JSONObject,含义如下:

字段类型含义
resultCodeString接口返回码,“103000”为成功。具体响应码见4.1. 本机号码校验接口返回码
authTypeString登录类型返回码
authTypeDesString登录类型返回码描述
resultDescString失败时返回:返回错误码说明
tokenString成功时返回:身份标识,字符串形式的token,第三方应用将该凭证经应用平台向统一认证平台请求认证
openIdString成功时返回:用户身份唯一标识


3. 示例

请求示例代码

 

响应示例代码

 

2.2. iOS开发指南

2.2.1. 开发环境配置

2.2.2.1. 环境配置及发布

  1. 导入统一认证framework

直接将统一认证TYRZSDK.framework拖到项目中

iOS-1

  1. 在Xcode中找到TARGETS-->Build Setting-->Linking-->Other Linker Flags在这选项中需要添加-ObjC

iOS-4

  1. TARGETS-->Build Setting-->搜索框中搜索"BitCode"选项,并且将该选项的属性设置为NO

iOS-5

2.2.2. Hello 统一认证

本节内容主要面向新接入统一认证的开发者,介绍快速集成统一认证的基本服务的方法。

2.2.2.1. 统一认证登录流程

由流程图可知,业务客户端集成SDK后只需要完成2步集成实现登录

 

2.2.2.2. 统一认证登录集成步骤

第一步:

在appDelegate.m中的didFinish函数中添加初始化代码。初始化代码只需要执行一次就可以。

 

第二步:

在需要用到登录的地方调用登录接口即可,以下是登录示例

 

2.2.3. 一键登录

2.2.3.1. 初始化appid和appkey

1. 方法描述

功能

用于初始化appid、appkey设置。

原型

TYRZBaseApi -> customInit:appKey:sourceID:

 


2. 参数说明

请求参数

参数类型说明是否必填
appIDNSString应用的appid
appKeyNSString应用密钥
sourceIDNSString业务ID

响应参数


3. 示例

请求示例代码

 

响应示例代码


2.2.3.2. 短信验证码登录

1. 方法描述

功能

用于使用短信验证码登录,客户端单独调起SDK的短信验证码登录界面(下图),用户手动输入电话号码,获取短信验证码登录,登录成功后获取token和用户ID等。业务方如果需要获取用户的手机号码,需再次调取3.1接口来换取用户的手机号码等信息。

6

原型

TYRZUILogin -> loginSMS:complete:

 


2. 参数说明

请求参数

参数类型说明是否必填
vcUIViewController调用短信验证码登录所在的vc
completeUAFinishBlock登录回调


响应参数

参数类型说明是否必填
resultCodeNSUinteger返回相应的结果码
tokenNSString登录时需要的token成功时必填
openidNSString和通行证ID成功时必填
authTypeNSString认证类型(详见附录1 认证方法标识)成功时必填
authTypeDesNSString认证类型描述(详见附录1 认证方法标识)成功时必填
descNSString调用描述


3. 示例

请求示例代码

 


响应示例代码

 


2.2.3.3. 登录方法

1. 方法描述

功能

用于显式登录。SDK自动调起登录等待界面(图一),同时自动获取本机号码;若获取本机号码成功,自动切换到授权登录页面(图二),用户授权登录后,即可使用本机号码进行登录;若用户获取本机号码失败,自动跳转到短信验证码登录页面(图三),引导用户使用短信验证码登录;

iOS-2


原型

TYRZUILogin -> loginExplicitly:complete:

 


2. 参数说明

请求参数

参数类型说明是否必填
vcUIViewController调用显式登录所在的vc
completeUAFinishBlock登录回调


响应参数

参数类型说明是否必填
resultCodeNSUinteger返回相应的结果码
tokenNSString登录时需要的token成功时必填
openidNSString和通行证ID成功时必填
authTypeNSString认证类型(详见附录1 认证方法标识)成功时必填
authTypeDesNSString认证类型描述(详见附录1 认证方法标识)成功时必填
descNSString调用描述


3. 示例

请求示例代码

 


响应示例代码

 


2.2.3.4. 显式登录失败后使用短信验证码登录开关

1. 方法描述

功能

显式登录调取失败后,可使用该方法来决定是否使用短信验证码登录


原型

TYRZUILogin -> setCustomSMS

 


2. 参数说明

请求参数

参数类型说明是否必填
enableBOOLYES时显示登录取号失败会跳转至短信验证码界面


响应参数


3. 示例

请求示例代码

 


响应示例代码

设置逻辑不返回

2.2.3.5. 用户可以自定义登录标题

1. 方法说明

功能

用户可以自定义自己的登录标题

原型 TYRZUILogin -> loginEximplicit

 
2. 参数说明

请求参数

参数类型说明是否必填
loginTitleNSString用户自己的自定义的登录标题

响应参数

2.2.3.6. 用户可以自定义Logo

1. 方法说明

功能

用户自定义的登录logo

原型 TYRZUILogin -> loginEximplicit

 
2. 参数说明

请求参数

参数类型说明是否必填
imageUIImage用户自定义的登录logo

响应参数

3. 平台接口

3.1. 获取用户信息接口(一键登录)

3.1.1. 接口说明

功能

业务平台或服务端携带用户授权成功后的token来调用统一认证服务端获取用户信息。

请求地址: https://www.cmpassport.com/unisdk/rsapi/tokenValidate

协议: HTTPS

请求方法: POST+json

回调地址:请参考开发者接入流程文档中配置业务服务端地址相关操作


3.1.2. 参数说明

请求参数

参数层级类型约束说明
header1必选
version2string必选填1.0
msgid2string必选标识请求的随机数即可(1-36位)
systemtime2string必选请求消息发送的系统时间,精确到毫秒,共17位,格式:20121227180001165
strictcheck2string必选验证源ip合法性,填写”1”,统一认证会校验sourceid与出口ip对应关系(ip 地址的配置方法请参考接入流程文档中配置业务服务端地址相关操作)
sourceid2string可选业务集成统一认证的标识,应用接入后可获取
ssotosourceid2string可选单点登录时使用,填写被登录业务的sourceid
appid2string可选业务在统一认证申请的应用id
apptype2string可选1:BOSS
2:web
3:wap
4:pc客户端
5:手机客户端
expandparams2string扩展参数map(key,value)
body1可选
token2string可选需要解析的凭证值。


响应参数

参数层级类型约束说明
header1必选
version2string必选1.0
inresponseto2string必选对应的请求消息中的msgid
systemtime2string必选响应消息发送的系统时间,精确到毫秒,共17位,格式:20121227180001165
resultcode2string必选返回码
body1必选
pcid2string必选伪码id
usessionid2string可选暂忽略
openid2string可选用户统一账号的系统标识
andid2string可选用户的“和ID”
msisdn2string可选表示手机号码
email2string可选表示邮箱地址
loginidtype2string可选登录使用的用户标识:
0:手机号码
1:邮箱
msisdntype2string可选手机号码的归属运营商
0:中国移动
1:中国电信
2:中国联通
99:未知的异网手机号码
province2string可选用户所属省份(暂无)
authtype2string可选认证方式,取值参见附录1 认证方法标识
authtime2string可选统一认证平台认证用户的时间
lastactivetime2string可选暂无
relateToAndPassport2string可选是否已经关联到统一账号,暂无用处
fromsourceid2string可选来源sourceid(即签发token sourceid)
tosourceid2string可选目的sourceid(即被登录业务sourceid)


3.1.3. 示例

请求示例

 

响应示例

 

3.2. 本机号码校验接口

3.2.1. 业务流程

1


3.2.2. 接口说明

校验用户输入的号码是否本机号码。 应用将手机号码传给统一认证SDK,统一认证SDK向统一认证服务端发起本机号码校验请求,统一认证服务端通过网关或者短信上行获取本机手机号码和第三方应用传输的手机号码进行校验,返回校验结果。

调用次数说明:本产品属于收费业务,开发者未签订服务合同前,每天总调用次数有限。

请求地址: https://www.cmpassport.com/openapi/rs/tokenValidate

协议: HTTPS

请求方法: POST+json

回调地址:请参考开发者接入流程文档中配置业务服务端地址相关操作


3.2.3. 参数说明

请求参数

参数类型层级约束说明
header1必选
versionstring2必选版本号,初始版本号1.0,有升级后续调整
msgIdstring2必选使用UUID标识请求的唯一性
timestampstring2必选请求消息发送的系统时间,精确到毫秒,共17位,格式:20121227180001165
appIdstring2必选应用ID
body1必选
openTypeString2否,requestertype字段为0时是运营商类型:
1:移动;
2:联通;
3:电信;
0:未知
requesterTypeString2请求方类型:
0:APP;
1:WAP
messageString2接入方预留参数,该参数会透传给通知接口,此参数需urlencode编码
expandParamsString2扩展参数格式:param1=value1|param2=value2 方式传递,参数以竖线 | 间隔方式传递,此参数需urlencode编码。
phoneNumString2待校验的手机号码的64位sha256值,字母大写。(手机号码+appKey+timestamp)(注:“+”号为合并意思)
tokenString2身份标识,字符串形式的token
signString2签名,HMACSHA256(appId+ msgId+phonNum+timestamp+token+version),输出64位大写字母 (注:“+”号为合并意思,不包含在被加密的字符串中,appkey为秘钥, 参数名做自然排序(Java是用TreeMap进行的自然排序))


请求示例

 

响应参数

参数层级类型约束说明
header1必选
msgId2string必选对应的请求消息中的msgid
timestamp2string必选响应消息发送的系统时间,精确到毫秒,共17位,格式:20121227180001165
appId2string必选应用ID
resultCode2string必选规则参见具体接口返回码说明
body1必选
resultDesc2String必选返回结果描述信息:
000:是本机号码
001:非本机号码
102:参数无效
108:无效的手机号
302:签名校验不通过
606:token校验失败
999:系统异常
102315:使用次数为0
其中,000和001状态纳入计费次数
message2String接入方预留参数,该参数会透传给通知接口,此参数需urlencode编码
expandParams2String扩展参数格式:param1=value1|param2=value2 方式传递,参数以竖线 | 间隔方式传递,此参数需urlencode编码。

响应示例

 

4. 返回码说明

4.1. Android返回码

编码返回码描述
103000成功
102101无网络
102102网络异常
102223数据解析异常
102121用户取消认证
102505业务未注册
102506请求出错
102507请求超时
102201自动登陆失败
102202应用签名失败
102203输入参数错误
102204正在gettoken处理
102210指定号码非本机号码
102211短信验证码验证成功后返回随机码为空
102222http响应头中没有结果码
102299other failed
102302调用service超时
103117mac异常 macError
103200ks无需更新
103203缓存用户不存在
200001imsi为空,跳到短信验证码登录
200002imsi为空,没有短信验证码登录功能
200003复用中间件首次登录
200004复用中间件二次登录
200005用户未授权
200006用户未授权
200007不支持的认证方式 跳到短信验证码登录
200008不支持的认证方式 没有短信验证码登录功能
200009应用合法性校验失败
200010imsi获取失败或者没有sim卡,预取号失败

4.2. iOS返回码

错误编号返回码描述
102000成功
102101无网络
102102网络异常
102103非移动网络
102109网络错误
102201自动登陆失败,用户选择自定义界面时,需要继续处理手动登陆流程,比如弹出登陆界面。
102202APP签名验证不通过
102203接口入参错误
102204正在进行GetToken动作,请稍后
102205当前环境不支持指定的登陆方式
102206选择用户登陆时,本地不存在指定的用户
102207获取的中间件值错误
102208参数错误
102209没有sim卡
102210不支持短信发送
10299其他错误
102301用户取消
102302没有进行初始化参数
102303用户名为空
102304密码为空
102305验证码获得成功
102306验证码获得失败
102307用户名格式错误
102308用户名格式错误
102309验证码格式错误
102310用户名和验证码格式错误
102311密码格式错误
102312用户名和密码格式错误

4.3. 获取用户信息接口返回码

编码返回码描述
103000成功
103101签名错误
103103用户不存在
103104用户不支持该种登录方式
103105密码错误
103106用户名错误
103107已存在相同的随机数
103108短信验证码错误
103109短信验证码超时
103111WAP网关IP不合法
103112请求错误 reqError
103113Token内容错误
103114token验证 KS过期
103115token验证 KS不存在
103116token验证 sqn错误
103117mac异常 macError
103118sourceid不存在
103119appid不存在appidNOExist
103120clientauth不存在
103121openid不存在
103122btid不存在
103123redisinfo不存在
103124ksnaf校验不一致
103125手机格式错误
103126手机号不存在
103127证书验证,版本过期
103128gba webservice接口调用失败
103129获取短信验证码的msgtype异常
103130新密码不能与当前密码相同
103131密码过于简单
103132用户注册失败
103133sourceid不合法
103134wap方式手机号为空
103135昵称非法
103136邮箱非法
103138appid已存在
103139sourceid已存在
103200不需要更新ks
103204缓存随机数不存在
103205服务器内部异常
103207发送短信失败
103212校验密码失败
103213旧密码错误
103214访问缓存或数据库错误
103226sqn过小或过大
103265用户已存在
103901短信验证码下发次数已达上限
103902凭证校验失败
104001APPID和APPKEY已存在
105001联通网关取号失败
105002移动网关取号失败
105003电信网关取号失败
105004短信上行ip检测不合法
105005短信上行发送信息为空
105006手机号码为空
105007手机号码格式错误
105008短信内容为空
105009解析失败

4.4. 本机号码校验接口返回码

错误编号返回码描述
103000成功
102101无网络
102102网络异常
102223数据解析异常
102121用户取消认证
102505业务未注册
102506请求出错
102507请求超时
102201自动登陆失败
102202应用签名失败
102203输入参数错误
102204正在gettoken处理
102210指定号码非本机号码
102211短信验证码验证成功后返回随机码为空
102222http响应头中没有结果码
102299other failed
102302调用service超时
103117mac异常 macError
103200ks无需更新
103203缓存用户不存在
200001imsi为空,跳到短信验证码登录
200002imsi为空,没有短信验证码登录功能
200003复用中间件首次登录
200004复用中间件二次登录
200005用户未授权
200006用户未授权
200007不支持的认证方式 跳到短信验证码登录
200008不支持的认证方式 没有短信验证码登录功能
200009应用合法性校验失败
200010imsi获取失败或者没有sim卡,预取号失败