WEB登录框开发指南
交互流程图
一张图看懂WEB对接：通过拼装参数后的URL显示天翼账号登录WEB页面，用户认证成功后开发者获取code，通过服务器使用code换取accessToken，再通过“获取用户信息”API接口拿accessToken换取手机号码等信息。
注意：
“蓝色流程”由合作方实现对接，流程序号与本文标题序号章节相对应。
“绿色流程”由天翼账号实现，合作方可进行了解。
1.接入准备
接入方在天翼账号开放平台申请企业开发者、应用APPID、及免密登录权限，详见 《接入流程》 。
2.1 登录模式
主要应用于合作方WEB页面接入天翼账号登录认证的场景，如天翼云WEB版和189邮箱WEB版。由天翼账号提供登录框给予合作方，在合作方页面通过iframe的方式嵌入天翼账号的登录框，其中登录框为天翼账号提供的统一登录框，页面其他样式为合作方自身的页面。
种对接方式不影响合作方本身页面的特色和布局。目前已有对接应用示例，可以前往体验：
天翼账号： http://e.189.cn/
189邮箱： http://mail.189.cn/
天翼云盘： http://cloud.189.cn/
2.2 登录框样式
天翼账号WEB登录框，为合作方的WEB应用提供便捷的账号注册、认证、找回密码和登录认证服务。
WEB登录流程：由天翼账号提供登录框给予合作方，在合作方页面通过iframe的方式嵌入天翼账号的登录框。登录方式包括扫码登录、账号密码登录和短信验证码登录， 合作方可以根据自身需要选择优先的登录方式。
方式1：扫码登录
方式2：账号密码登录
方式3：短信验证码登录
接入优势：天翼账号WEB登录框支持扫码登录，可以用合作方的app或微信等任意扫码工具进行扫码，扫码后的登录页面支持免密登录，无需用户输入账号密码等，提升用户体验。
3.能力对接
3.1 对接指引(获取code)
3.1.1 接口说明
应用账号登录模块，通常包括账号登录及注销功能，因此，天翼账号在WEB应用对接上，分别提供WEB登录框接口和注销登录账号接口，协助合作方应用分别实现登录及注销功能，以提供完整的账号使用流程。
3.1.2 实现WEB应用登录
合作方WEB页面通过iframe嵌入天翼账号提供的WEB登录框接口地址，实现WEB应用登录，用户登录天翼账号后重定向返回给合作方认证处理结果。
接口定义
| 接口名称 | unifyAccountLogin.do |
| 接口描述 | WEB登录框接口，应用于加载登录框界面 |
| 承载协议 | HTTPS |
| 承载网络 | 公网 |
| 请求方式 | GET |
| 数据格式 | redirect |
| WEB接口URL | https://open.e.189.cn/api/logbox/oauth2/web/unifyAccountLogin.do |
请求参数：包含公共请求参数和非公共请求参数
1）公共请求参数:天翼账号支持以GET方式提交数据，如下表所述：
| 字段标识 | 说明 |
|---|---|
| appId | 开发者在天翼账号开放平台申请获取的应用ID |
| clientType | 统一为：10010 |
| format | 统一为：redirect（用于重定向接口的显示说明） |
| version | 调用的接口版本号：v1.5 |
| paras | 使用appSecret对所有传入参数采用XXTea加密，并且按照接口详细规范中定义的参数(除appId、clientType、format、version、sign)拼接，不要求参数顺序。
例如：paras = XXTea((a=value1&b=value2&…),appSecret) 备注：appSecret转16进制后进行加密，加密算法后的值只有数字和全大写字母 |
| sign | 签名算法：
sign=HMAC-SHA1(appId+clientType+format+version+paras,appSecret).toUpperCase()
备注：注意保持签名的各字段顺序正确，签名算法后的值只有数字和全大写字母 |
2）非公共请求参数（paras中需要加密的参数）：
| 字段标识 | 说明 | 数据类型 | 长度(字节) | 可空 |
|---|---|---|---|---|
| timeStamp | 时间戳，毫秒 | Long | 18 | N |
| returnURL |
重定向返回URL（returnURL如带参数，整个returnURL需进行URL编码） |
String | 124 | N |
| pageKey | 值为normal或popping（normal为正常嵌入页面，popping为弹出式页面,默认normal） | String | 8 | Y |
| regReturnUrl | 注册成功后返回的URL（登录框右下角注册链接）。默认注册后返回天翼账号，如需注册后返回接入方，可传入该参数。（regReturnUrl如带参数，整个regReturnUrl需进行URL编码） | String | 255 | Y |
|
state |
用于保持请求和回调的状态，登录请求后原样带回给第三方。该参数可用于防止csrf攻击（跨站请求伪造攻击），建议第三方带上该参数，可设置为简单的随机数加session进行校验 |
String | 32
|
Y
|
| defaultSaveName | 默认优先展示登录天数；1- 7天自动登录，2- 15天自动登录;3- 30天自动登录 | String | 8 | Y |
| defaultSaveNameCheck | 是否默认勾选自动登录；check - 默认勾选; uncheck - 默认不勾选 | String | 10 | Y |
响应参数：
| 字段名称 | 描述 |
|---|---|
| appId | 开发者在天翼账号开放平台申请获取的应用ID |
| paras | 使用appSecret对所有传入参数采用XXTea加密，并且按具体接口详细规范中定义的参数拼接，不要求参数顺序
例如：paras=XXTea((a=value1&b=value2&…)，appSecret)。 |
| sign | 签名算法公式：HMAC-SHA1(appId+paras，appSecret) |
paras解密得到如下数据：
| 字段标识 | 说明 | 数据类型 | 长度 | 可空 |
|---|---|---|---|---|
| result |
0：成功 1：失败 |
Integer | 10 | N |
| timeStamp |
时间戳yyyy-MM-dd HH:mm:ss，其中HH 取值为00-23，时区为东八区(接入方必须判断时间戳的有效性，以防重放攻击) |
String |
19 |
N |
|
code |
2分钟内一次有效（服务端调用） |
String | 32
|
N
|
|
state |
用于保持请求和回调的状态，登录请求后原样带回给第三方。 |
String | 32
|
Y
|
返回结果
重定向到指定的URL，如http://returnURL?appId=123¶s=123&sign=123。returnURL按照本接口规范定义的参数处理方式接收和处理。
3.1.3 实现注销登录接口
用户在合作方WEB网站应用登录后需要退出登录时，合作方调用此接口，请求天翼账号注销用户登录，天翼账号清除用户登录信息后，根据传入的returnUrl返回合作方。
请求参数：包含公共请求参数和非公共请求参数
接口定义
| 接口名称 | unifyAccountLogout.do |
| 接口描述 | 注销登录接口，为合作方注销登录令牌，清除登录用户信息(该接口需在前端/浏览器调用) |
| 承载协议 | HTTPS |
| 承载网络 | 公网 |
| 请求方式 | GET
|
| 数据格式 | redirect |
| 约束 | 用户已登录 |
| WEB接口URL | https://open.e.189.cn/api/account/unifyAccountLogout.do |
请求参数：包含公共请求参数和非公共请求参数
1）公共请求参数：
| 字段标识 | 说明 |
|---|---|
| appId | 开发者在天翼账号开放平台申请获取的应用ID |
| clientType | 客户端类型:10010 |
| format | 目前仅支持json格式，统一为：redirect（用于重定向接口的显示说明） |
| version | 调用的接口版本号:v1.5 |
| paras | 使用appSecret对所有传入参数采用XXTea加密，并且按照接口详细规范中定义的参数(除appId、clientType、format、version、sign)拼接，不要求参数顺序。
例如：paras = XXTea((a=value1&b=value2&…),appSecret) |
| sign | 签名算法：
sign=HMAC-SHA1(appId+clientType+format+version+paras,appSecret).toUpperCase()
备注：注意保持签名的各字段顺序正确，签名算法后的值转换为全大写 |
2）非公共请求参数（paras中需要加密的参数）：
| 字段标识 | 说明 | 数据类型 | 长度 | 可空 |
|---|---|---|---|---|
| timeStamp | 时间戳，毫秒 | Long | 18 | N |
| returnURL | 重定向返回URL（returnURL如带参数，整个returnURL需进行URL编码） | String | 1024 | N |
响应参数：
| 字段名称 | 描述 |
|---|---|
| appId | 开发者在天翼账号开放平台申请获取的应用ID |
| paras | 使用appSecret对所有传入参数采用XXTea加密，并且按具体接口详细规范中定义的参数拼接，不要求参数顺序
例如：paras=XXTea((a=value1&b=value2&…)，appSecret)。 |
| sign | 签名算法公式：HMAC-SHA1(appId+paras，appSecret) |
paras参数解密得到以下数据：
| 字段标识 | 说明 | 数据类型 | 长度 | 可空 |
|---|---|---|---|---|
| result | 0：成功1：失败 | Integer | 10 | N |
| timeStamp | 时间戳yyyy-MM-dd HH:mm:ss，其中HH 取值为00-23，时区为东八区(接入方必须判断时间戳的有效性，以防重放攻击) | String | 19 | N |
返回结果:
重定向到传入的returnURL，如http://returnURL?appId=123¶s=123&sign=123。returnURL按照本接口规范定义的参数处理方式接收和处理。
3.2通过code获取Token
通过code获取accessToken接口，具体可到以下文档了解：
3.3获取用户信息
通过获取用户信息接口，在用户登录后可以获取用户昵称、手机号码、头像等信息，需要对接获取用户信息能力，具体可到以下文档了解：
3.4 “二维码登录”页接口（可选）
3.4.1 “二维码登录”接口说明
接口定义
| 接口名称 | openQrCodeLoginActivity |
| 接口描述 | 打开“二维码预登录”页 |
请求参数
| 名称 | 说明 | 数据类型 | 可空 |
|---|---|---|---|
| context | 传入当前调用的context(请传activity) | Context | N |
| accessToken | 访问令牌 | String | N |
| uuid | 客户端生成扫描二维码得到的uuid | String | N |
| CtListener | 监听类，请实现里面的callBack方法 | CtListener | N |
3.4.2 “二维码登录”接入流程说明
接入方APP接入“二维码登录”接口，需要按照如下步骤完成：
1）接入方首先需要完成二维码扫码功能开发，具备二维码扫码功能； 2）接入方在天翼账号开放平台获得appKey和appSecret; 3) 接入方根据“App接入SDK准备”完成导包，配置AndroidManifest.xml等工作； 4）获取用户有效token; 5) 扫描web页面二维码
下面从步骤4）开始介绍详细的接入步骤，如果对2）和3）不熟悉，请参考《Android应用开发指南》和《iOS应用开发指南》中的APP接入SDK准备。
3.4.2.1 获取用户token
使用免密登录或者其他登录方式，获取用户有效token。
3.4.2.2 扫描二维码
扫描web二维码后传入链接和用户有效的登录token,即可打开登录页面。
3.5 DEMO下载
为各位开发者提供更便捷的对接方法，我们提供DEMO，使用流程如下：
3.5.1 DEMO(JAVA)
介绍
1.导入lib里的jar包2.完善com._21cn.open.config.LoginboxConfig里TODO处的参数
3.执行com._21cn.open.main.WebLoginbox的main方法可得Web登录框地址
3.5.2 DEMO(PHP)
介绍
1.new LoginBoxDemo($appId, $appSecret, $returnURL)
2.执行$LoginBoxDemo->web()方法可得Web登录框地址