举个例子说明应用场景:
当前客户认证服务器只能以文本形式返回认证结果,但是零信任只能解析XML和JSON格式的数据,则可以通过响应预处理把其他形式的数据修改成json或xml格式
示例:当前认证服务器返回的数据如下
{ "statusCode": 200, "data": { "headers": { "x-powered-by": "Express", "content-type": "text/plain; charset=utf-8", "content-length": "25", "etag": "W/\"19-fS1BRqWGLDnKMLdtuHUJLdd5nA8\"", "date": "Wed, 19 Jun 2024 15:32:25 GMT", "connection": "close" }, "body": "code,200,msg,认证通过" } }
{ "statusCode": 500, "data": { "headers": { "x-powered-by": "Express", "content-type": "text/plain; charset=utf-8", "content-length": "25", "etag": "W/\"19-zWxstyVfXjxdK4W07g7MTh18keE\"", "date": "Wed, 19 Jun 2024 15:34:04 GMT", "connection": "close" }, "body": "code,500,msg,认证失败" } }
标红位置表示认证结果信息,只是把数据排列起来,使用逗号做分割,不是json或xml格式,零信任收到后无法识别,需要通过预处理代码将认证结果信息转换成json格式
下图代码含义:将body字段使用逗号分割,将分割后的第一位的信息赋值给新建字段code,第三位的信息赋值给新建字段msg
使用发送测试检查配置是否可用:认证成功条件要求code为200,测试信息显示回复的信息是非json,但是测试仍然通过,说明预处理代码配置没问题,可以实现非json转json
工作流程示例如下:
4.1.5. 多步请求
典型场景就是令牌认证/企业微信验证码/钉钉验证码场景,但是很惭愧,这个场景没实践过,这里就不多说了
这部分建议通过2022年9月份的破雾计划学习,其中有具体场景的讲解如下链接和图片
https://bbs.sangfor.com.cn/plugin.php?id=sangfor_databases:index&mod=viewdatabase&tid=227005
4.1.6. Cookie代理下发
关于此功能的作用在设备上就有解释:启用后,将会把认证服务器返回的所有Cookie数据进行代理下发到指定的域名中。适用于业务系统需要访问认证服务器返回Cookie的场景,比如客户业务系统需要单点登录的场景。为了便于理解该功能,以深信服W3门户举例,用户通过oauth方式登录后,使用f12-应用程序-cookie页面中,可以看到有名为token的cookie,对应的domain域名为泛域名.atrust.sangfor.com,这个cookie就是用于单点登录的,作用就是使用浏览器访问.atrust.sangfor.com对应域名下(包括子域名)的网站时,都可以通过此cookie实现单点登录认证(只是举例,深信服w3是使用的oauth而不是https方式)
对应到控制中心配置页面上需要配置的域名,就是指具体需要使用认证服务器回复的cookie的域名,如下图
使用此功能的前提是认证服务器可以回复cookie才行,回复的格式就是正常http响应中的cookie,不能以响应参数类似的形式传输
注意事项:代理下发的cookie的域名,需要保证和零信任的域名为同根域
4.2. 发送测试:
零信任在https配置界面提供了简单的排错功能,可以借助发送测试功能检查请求返回参数格式及验证账号密码,效果如下图
4.3. SDK集成场景:
这里再简单介绍一下零信任的SDK方案(建议先去看23年7月的破雾计划中关于SDK的讲解),零信任的SDK可以理解成APP中的一个模块,此模块配置后会接管APP本身的认证和网络转发等功能,APP输入的账号密码会先发给SDK模块,由SDK传到零信任控制中心,控制中心认证后再把结果返回SDK,SDK再传给APP本身,流量同理。可以把SDK理解成认证和网络的代理服务器。建议结合如下流程图理解HTTPS+SDK
在本文前边讲解的关于请求和应答对应到上图就是第4、5步,接下来重点讲解关于2、7、3、6步骤的部分
4.3.1. 结合SDK集成文档学习
关于SDK集成中涉及https认证内容的部分是3.2.6外部认证,其中介绍了APP和SDK之间传参的代码配置内容,理解了代码就能更好的理解整个工作流程(具体代码怎么写不需要一线关心,只是借助代码理解工作流,形成基本沟通思路,尽可能的和三方研发平等交流)
https://bbs.sangfor.com.cn/atrustdeveloper/appsdk/android/android_sdk_other_auth.html
需要理解的内容如下:
以下两张图列举了请求和响应代码的示例
第一张图大意为:APP在开发时,需要把账号密码或者其他信息传到SDK的username和password字段中,然后SDK会把这两个字段传给零信任控制中心
第二张图大意为:零信任认证后的信息(成功和失败)会传到指定键值,APP直接从SDK的这个键值中提取结果就能获得认证结果
结合以上,将工作流细化为如下图:
4.3.2. SDK信息透传场景:
在SDK场景下,APP客户端和认证服务器之间可能存在个性化传参,因为APP客户端和认证服务器之间的信息传输都要经过SDK和零信任控制中心,所以需要零信任配合将个性化参数做透传,具体是两个场景:一是APP传参到认证服务器,二是认证服务器传参给APP
接下来介绍两个场景的需求示例/配置/实现原理
4.3.2.1. APP传参到认证服务器
具体场景举例:
APP生成自定义的客户端ID给到认证服务器,用于辅助认证或者标识用户和终端对应关系(具体作用和零信任无关,零信任只要负责传参即可)
认证服务器侧提供的接口文档如下,请求参数中定义了一个客户端ID的键值对,需要零信任把该字段透传到认证服务器
4.3.2.1.1. 原理及配置思路 首先看SDK集成文档中关于外部主认证传参部分介绍,下图红框完整内容为:
* 传递单个信息可以直接放到密码字段直接传递,如果传递多个字段,建议使用json格式(也可以不是json格式,只是示例,可以随意自定义格式)sdk把整个 userName 和 password 当作字符串透传到服务端,服务端再去解析具体的值,或者直接传递第三方认证服务端对接
意思就是,如果有个性化自定义的字段,直接放在password字段中即可,结合本案例,代码可以写成如下(如果有多个字段也可以依次添加): String password = "{client_id:1,password:"123456"}";
控制中心配置:
由于SDK中的password字段定义了两个键值对,一个是客户端id,一个是密码,那么password字段传输到控制中心后,字段名会变成user.userpassword,值为 client_id:1,password:123456
这时候直接调用user.userpassword的话,这一个字段的值就等于client_id:1,password:123456,传到认证服务器的话,认证服务器无法处理此数据(一般不行,但如果认证服务器单独开发识别此格式也可以),所以需要控制中心对此数据进行处理,此时就需要使用自定义请求变量功能,通过js代码将客户端id和密码字段分离,使请求参数/请求体可以单独调用,自定义请求变量代码如下图,代码含义为:将user.Password字段中的client_id和password字段分别赋值给两个新的自定义的键值对env.client_id和env.password
经过以上js代码的转换,请求参数/请求体在调用客户端和密码字段时,对应的键值对应该调用的是env.client和env.password,配置示例如下,代码含义为:根据认证服务器接口文档要求,账号、密码、客户端id三个字段名为user-name/user-password/clientid
这三个字段的值,分别取自SDK传来的默认值user.username和经过自定义请求变量处理过生成的新键值对env.Password和env.client
以上配置完毕即可实现APP到认证服务器间自定义参数的透传,具体流程图原理如下
4.3.2.2. 认证服务器传参给APP
具体场景举例:
APP内部的应用存在单点登录场景,需要认证服务器认证后产生token字段返回给APP,APP拿到token字段后,APP内部的应用利用token字段做单点登录(具体作用和零信任无关,零信任只要负责传参即可)
认证服务器侧提供的接口文档如下,返回参数中定义了token/url等字段,需要零信任认证服务器回复的这些字段透传给APP
4.3.2.2.1. 原理及配置思路:
先看SDK集成文档中对于透传返回参数的说明,意思就是认证服务器返回的内容会默认保存到名为mServerinfo的函数
而mServerinfo函数内容的来源对应到零信任配置中就是响应配置中的“扩展字段”,如下图配置,意思就是把认证服务器返回的名为msg的键值对,赋值到扩展字段
控制中心会把扩展字段的内容写到mServerinfo函数中,完成数据透传
结合本案例实际配置思路:
本案例中需要透传的返回信息有如下三个字段
但是零信任的特性是只允许透传一个字段,如果像下图一样分别将url和token解析到扩展字段,那么实际透传过去的只有最后一个token字段(机制就是透传最下边的)
透传多个参数思路:
1、将多个键值合并成一个键值调用(使用响应预处理的js代码处理,本文不做介绍)
2、调用父级字段(本案例适用)
思路2说明如下,分析响应示例代码,响应参数为json格式,需要透传的三个键值都是属于一个名为“result”的字段
所以只要调用result字段即可,整个result字段包含的三个键值都会传到SDK的mServerinfo函数中
经过以上配置思路即可实现认证服务器给APP信息的透传
流程图示例如下: