1. 接入指南

1.1. 开发者注册

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

1.1.1 个人开发者注册

1.1.2. 企业开发者注册流程

1.2. 应用接入

1.2.1. 创建应用

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

填写开发者的应用信息：

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

1.2.2. 能力配置

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

• Android应用

  Android包签名获取方法：

  1. 下载签名获取工具APP(gensignature.apk)并在Android手机上安装；
  2. 在手机上安装开发者的应用；
  3. 启动签名获取工具APP，然后输入开发者的应用APP包名(如：com.cmic.sso.myapplication)，点击"Get Signature"按钮获取包签名字符串。（注意:包签名区分大小写。）

  

• iOS应用

1.2.3. 获取sourceID

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

什么是业务ID（sourceID）？

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

1.2.4. 配置业务服务端地址

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

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.crt、serverPublicKey.pem拷贝到项目assets目录下。

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

anim文件：

drawable、drawable-xxhdpi文件：

layout文件：

values文件：

2.1.1.3. 配置AndroidManifest

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

1. 配置权限

 
8
1
<uses-permission android:name="android.permission.INTERNET" />
2
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
3
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
4
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
5
<uses-permission android:name="android.permission.SEND_SMS" />
6
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
7
<uses-permission android:name="android.permission.WRITE_SETTINGS"/>
8
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

2. 配置授权登录activity

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

 
20
1
<activity
2
    android:name="com.cmic.sso.sdk.activity.OAuthActivity"
3
    android:configChanges="orientation|keyboardHidden|screenSize"
4
    android:screenOrientation="unspecified"
5
    android:launchMode="singleTop">
6
</activity>
7
<!-- required -->
8
<activity
9
    android:name="com.cmic.sso.sdk.activity.BufferActivity"
10
    android:configChanges="orientation|keyboardHidden|screenSize"
11
    android:screenOrientation="unspecified"
12
    android:launchMode="singleTop">
13
</activity>
14
<!-- required -->
15
<activity
16
    android:name="com.cmic.sso.sdk.activity.LoginAuthActivity"
17
    android:configChanges="orientation|keyboardHidden|screenSize"
18
    android:screenOrientation="unspecified"
19
    android:launchMode="singleTop">
20
</activity>

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

2.1.1.4. SDK使用步骤

1. 创建一个AuthnHelper实例

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

 
6
1
public void onCreate(Bundle savedInstanceState) {
2
    super.onCreate(savedInstanceState);
3
    mContext = this;    
4
    ……
5
    mAuthnHelper = AuthnHelper.getInstance(mContext);
6
    }

2. 实现回调

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

 
12
1
mListener = new TokenListener() {
2
    @Override
3
    public void onGetTokenComplete(JSONObject jObj) {
4
        if (jObj != null) {
5
            mResultString = jObj.toString();
6
            mHandler.sendEmptyMessage(RESULT);
7
            if (jObj.has("token")) {
8
                mtoken = jObj.optString("token");
9
            }
10
        }
11
    }
12
};

3. 接口调用

 
5
1
mAuthnHelper.umcLoginByType(Constant.APP_ID, 
2
        Constant.APP_KEY, 
3
        AuthnHelper.UMC_LOGIN_IMPLICIT,
4
        AuthnHelper.AUTH_TYPE_DYNAMIC_SMS + AuthnHelper.AUTH_TYPE_WAP, 
5
        mListener);

2.1.2. 一键登录

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

1. 方法描述

获取管理类的实例对象

原型

 
1
1
public AuthnHelper (Context context)

2. 参数说明

2.1.2.2. 登录方法

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

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

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

1. 方法描述

业务流程图

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

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

原型

 
5
1
public void umcLoginByType(final String appId, 
2
            final String appKey,
3
            final int loginType, 
4
            final String authType, 
5
            final TokenListener listener)

2. 参数说明

请求参数

响应参数

OnGetTokenComplete的参数JSONObject，含义如下：

3. 示例

请求示例代码

 
5
1
mAuthnHelper.umcLoginByType(Constant.APP_ID, 
2
        Constant.APP_KEY,
3
        AuthnHelper.UMC_LOGIN_DISPLAY, 
4
        AuthnHelper.AUTH_TYPE_DYNAMIC_SMS + AuthnHelper.AUTH_TYPE_WAP, 
5
        mListener);

响应示例代码

 
6
1
{
2
    "authType": "网关鉴权",
3
    "resultCode": "103000",
4
    "openId": "9M7RaoZH1DUrJ15ZjJkctppraYpoNKQW9xKtQrcmCGTFONUKeT3w",
5
    "token": "848401000133020037515451304E7A497A4D7A5A4651554A474E6A41784D304E4640687474703A2F2F3231312E3133362E31302E3133313A383038302F403031030004051C7840040012383030313230313730373230313030303137050010694969C667EA4D248DFA125D7C4BD35BFF00207EF179935851E1578B313B366007126A3FD3667BCD2B812EC2D084B8924E7164"
6
}

2.1.2.3. 预取号方法

1. 方法描述

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

原型

 
3
1
public void umcLoginPre(final String appId, 
2
            final String appKey,
3
            final TokenListener listener)

2. 参数说明

请求参数

响应参数

OnGetTokenComplete的参数JSONObject，含义如下：

3. 示例

 
3
1
mAuthnHelper.umcLoginPre(Constant.APP_ID, 
2
        Constant.APP_KEY,
3
        mListener);

响应示例代码

 
4
1
{
2
    "resultCode": "103000",
3
    "desc": "true",
4
}

2.1.3. 本机号码校验

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

1. 方法描述

获取管理类的实例对象

原型

 
1
1
public AuthnHelper (Context context)

2. 参数说明

2.1.3.2. 获取校验凭证token

1. 方法描述

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

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

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

原型

 
3
1
public void getToken(final String appId, 
2
            final String appKey, 
3
            final TokenListener listener)

2. 参数说明

请求参数

响应参数

OnGetTokenComplete的参数JSONObject，含义如下：

3. 示例

请求示例代码

 
3
1
mAuthnHelper.getToken(Constant.APP_ID, 
2
        Constant.APP_KEY,
3
        mListener);

响应示例代码

 
7
1
{
2
    "resultCode": "103000",
3
    "authType": "2",
4
    "authTypeDes": "网关鉴权",
5
    "openId": "9M7RaoZH1Q95QzY99YFkeFDO4xDfOv5q4BVlwn_0zJNNlNYUkxrw",
6
    "token": "8484010001330200374D455979526A49354E6A59774E444D314E454E47516B4D3140687474703A2F2F3231312E3133362E31302E3133313A383038302F40303103000402D59A6B040012383030313230313730383138313031343437050010D2F28C555CB54316B7D031DE9F6F6B1EFF0020F07B4AAFC3B1499A250AAAB4272BBFB565B440FFA5C8257E90C28595956CC224"
7
}

2.2. iOS开发指南

2.2.1. 开发环境配置

2.2.2.1. 环境配置及发布

1. 导入统一认证framework

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

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

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

2.2.2. Hello 统一认证

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

2.2.2.1. 统一认证登录流程

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

 
2
1
1.  调用登录接口获取token
2
2.  携带token请求登录

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

第一步：

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

 
5
1
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
2
    // Override point for customization after application launch.
3
     [TYRZBaseApi customInit:APPID appKey:APPKEY sourceID:SOURCEID];
4
    return YES;
5
}

第二步：

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

 
20
1
- (void)showImplicitLogin {
2
    self.waitBGV.hidden = NO;
3
    [self.waitAV startAnimating];
4
     __weak typeof(self) weakSelf = self;
5
    [TYRZLogin loginImplicitly:^(id sender) {
6
        dispatch_async(dispatch_get_main_queue(), ^{
7
            weakSelf.waitBGV.hidden = YES;
8
            [weakSelf.waitAV stopAnimating];
9
            NSString *resultCode = sender[@"resultCode"];
10
            self.token = sender[@"token"];
11
            NSMutableDictionary *result = [NSMutableDictionary dictionaryWithDictionary:sender];
12
            if ([resultCode isEqualToString:SUCCESSCODE]) {
13
                result[@"result"] = @"获取token成功";
14
            } else {
15
                result[@"result"] = @"获取token失败";
16
            }
17
            [self showInfo:result];
18
        });
19
    }];
20
}

2.2.3. 一键登录

2.2.3.1. 初始化appid和appkey

1. 方法描述

功能

用于初始化appid、appkey设置。

原型

TYRZBaseApi -> customInit:appKey:sourceID:

 
1
1
+ (void)customInit:(NSString *)appID appKey:(NSString *)appKey sourceID:(NSString *)sourceID;

2. 参数说明

请求参数

响应参数

无

3. 示例

请求示例代码

 
1
1
 [TYRZBaseApi customInit:APPID appKey:APPKEY sourceID:SOURCEID];

响应示例代码

无

2.2.3.2. 短信验证码登录

1. 方法描述

功能

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

原型

TYRZUILogin -> loginSMS:complete:

 
1
1
+ (void)loginSMS:(UIViewController *)vc complete:(void (^)(id sender))complete;

2. 参数说明

请求参数

响应参数

3. 示例

请求示例代码

 
14
1
- (void)showSMSCodeLogin {
2
    [TYRZUILogin loginSMS:self complete:^(id sender) {
3
        NSLog(@"=open=短信验证码登录:%@",sender);
4
        NSString *resultCode = sender[@"resultCode"];
5
        self.token = sender[@"token"];
6
        NSMutableDictionary *result = [NSMutableDictionary dictionaryWithDictionary:sender];
7
        if ([resultCode isEqualToString:SUCCESSCODE]) {
8
            result[@"result"] = @"获取token成功";
9
        } else {
10
            result[@"result"] = @"获取token失败";
11
        }
12
        [self showInfo:result];
13
    }];
14
}

响应示例代码

 
6
1
{
2
    openid = 1918310031;
3
    resultCode = 103000;
4
    token = 84840100013202003A517A424352446B34517A63304D45464751544E464E6A6B3040687474703A2F2F3132302E3139372E3233352E32373A383038302F72732F40303103000403D6A9B1040012383030313230313730383137313031343230FF00209FEDE8882EDD17B521BC36C422F264925383659BE7AFDFB1BB01958AD9AFC080;
5
    userName = "139****0743";
6
}

2.2.3.3. 登录方法

1. 方法描述

功能

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

原型

TYRZUILogin -> loginExplicitly:complete:

 
1
1
+ (void)loginExplicitly:(UIViewController *)vc complete:(void (^)(id sender))complete;

2. 参数说明

请求参数

响应参数

3. 示例

请求示例代码

 
17
1
//显式登录
2
- (void)showExplicitlyLogin {
3
     __weak typeof(self) weakSelf = self;
4
    [TYRZUILogin loginExplicitly:weakSelf complete:^(id sender) {
5
        dispatch_async(dispatch_get_main_queue(), ^{
6
            NSString *resultCode = sender[@"resultCode"];
7
            self.token = sender[@"token"];
8
            NSMutableDictionary *result = [NSMutableDictionary dictionaryWithDictionary:sender];
9
            if ([resultCode isEqualToString:SUCCESSCODE]) {
10
                result[@"result"] = @"获取token成功";
11
            } else {
12
                result[@"result"] = @"获取token失败";
13
            }
14
            [self showInfo:result];
15
        });
16
    }];
17
}

响应示例代码

 
7
1
{
2
    desc = "\U767b\U5f55\U6210\U529f";
3
    openid = 1918310031;
4
    resultCode = 103000;
5
    token = 84840100013202003A4E45564452444D794E7A6C474E45557A4F4441314D304E4340687474703A2F2F3132302E3139372E3233352E32373A383038302F72732F403032030004030DF69E040012383030313230313730383137313031343230FF0020C8C9629B915C41DC3C9528E5D5796BB1551F2A49F8FCF7B5BA23ED0F28A8FAE9;
6
    userName = 13902220743;
7
}

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

1. 方法描述

功能

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

原型

TYRZUILogin -> setCustomSMS

 
1
1
+ (void)setCustomSMS:(BOOL)enable;

2. 参数说明

请求参数

响应参数

无

3. 示例

请求示例代码

 
15
1
  [TYRZUILogin setCustomSMS:YES];
2
     __weak typeof(self) weakSelf = self;
3
    [TYRZUILogin loginExplicitly:weakSelf complete:^(id sender) {
4
        dispatch_async(dispatch_get_main_queue(), ^{
5
            NSString *resultCode = sender[@"resultCode"];
6
            self.token = sender[@"token"];
7
            NSMutableDictionary *result = [NSMutableDictionary dictionaryWithDictionary:sender];
8
            if ([resultCode isEqualToString:SUCCESSCODE]) {
9
                result[@"result"] = @"获取token成功";
10
            } else {
11
                result[@"result"] = @"获取token失败";
12
            }
13
            [self showInfo:result];
14
        });
15
    }];

响应示例代码

设置逻辑不返回

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

1. 方法说明

功能

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

原型 TYRZUILogin -> loginEximplicit

 
1
1
+ (void)setLoginTitle:(NSString *)loginTitle;

2. 参数说明

请求参数

响应参数

无

2.2.3.6. 用户可以自定义Logo

1. 方法说明

功能

用户自定义的登录logo

原型 TYRZUILogin -> loginEximplicit

 
1
1
+ (void)setLogo:(UIImage *)image;

2. 参数说明

请求参数

响应参数

无

3. 平台接口

3.1. 获取用户信息接口（一键登录）

3.1.1. 接口说明

功能

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

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

协议： HTTPS

请求方法： POST+json

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

3.1.2. 参数说明

请求参数

响应参数

3.1.3. 示例

请求示例

 
13
1
{
2
        "header": {
3
            "strictcheck":"0",
4
            "version": "1.0",
5
            "msgid": "40a940a940a940a93b8d3b8d3b8d3b8d",
6
            "systemtime": "20170515090923489",
7
            "appid": "10000001",
8
            "apptype": "5"
9
        },
10
        "body": {
11
            "token": "8484010001320200344E6A5A4551554D784F444E474E446C434E446779517A673340687474703A2F2F3139322E3136382E31322E3233363A393039302F0300040353EA68040006313030303030FF00203A020A143C6703D7D0530953C760744C7D61F5F7B546F12BC17D65254878748C"
12
        }
13
}

响应示例

 
19
1
{
2
         "header": {
3
            "inresponseto": "40a940a940a940a93b8d3b8d3b8d3b8d",
4
            "resultcode": "103000",
5
            "systemtime": "20170522204845598",
6
            "version": "1.0"
7
        },
8
        "body": {
9
            "msisdntype": "0",
10
            "usessionid": "NjZEQUMxODNGNDlCNDgyQzg3@http://192.168.12.236:9090/",
11
            "openid": "000000000",
12
            "loginidtype": "0",
13
            "authtime": "2017-05-22 20:48:45",
14
            "msisdn": "13683329795",
15
            "lastactivetime": "",
16
            "authtype": "WAPGW",
17
            "relateToAndPassport": "1"
18
        }
19
}

3.2. 本机号码校验接口

3.2.1. 业务流程

3.2.2. 接口说明

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

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

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

协议： HTTPS

请求方法： POST+json

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

3.2.3. 参数说明

请求参数

请求示例

 
17
1
{
2
  "body": {
3
    "openType": "1", 
4
    "requesterType": "1", 
5
    "message ": "", 
6
    "expandParams": "",
7
    "phoneNum": "4526285940b6fa7fef49e1dcb04ee944f41a8745444015daf2771bfb7ad7c800", 
8
    "token": "", 
9
    "sign": ""
10
    }, 
11
  "header": {
12
    "msgId ": "61237890345", 
13
    "timestamp ": "20160628180001165", 
14
    "version ": "1.0", 
15
    "appId ": "0008"
16
  }
17
}

响应参数

响应示例

 
12
1
{
2
  "body": {
3
    "resultDesc ": "", 
4
    "message": "", 
5
    "expandParams ": ""
6
    }, 
7
   "header": {
8
    "msgId": "61237890345", 
9
    "timestamp": "20160628180001165", 
10
    "resultCode": "1.0"
11
  }
12
}

4. 返回码说明

4.1. Android返回码

4.2. iOS返回码

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

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