免登功能 - 答疑篇

本篇基础：BOS平台的二开编程(论坛)，C#编程(ms)，python语法，json语法，xml语法，VistualStudio2012(up)工具(ms)，http/https基础知识，iis基础知识

统一认证登录的免登功能--答疑篇

目标：第三方sso五花八门，通过答疑方式，快速帮助现场定位金蝶云星空统一认证入口接入的疑问与方案，快速指导二开与实施。

疑1、管理员账户Administrator无法自动登录系统？
答：管理员administrator帐号不允许自动登录。只有业务账户才允许自动登录系统。

疑2、为何生成的链接无法登录系统？
答：

1、检查有没有部署插件，启用插件；
2、确认当前版本支持该功能，并安装了该版本的最新功能补丁；（6.x V1，7.x V2）
3、修改完Common.config后，需要重启IIS,启动命令为IISRESET；

4、错误修改成ManageSite/App_Data目录下的Common.config配置文件, 而没有修改WebSite/App_Data目录下的；

5、是不是Common.config配置了多次“StartAppPlugin”导致配置冲突，删除多余配置，只保留一个；

6、检查是否存在ud参数是V2协议，但配置的启动插件是V1协议，或者反之。ud参数与解析启动插件版本不匹配问题；（如果还在使用V1协议，建议统一改成V2协议，ud参数也按V2协议编码，V2协议参考本文附录文章 ）

7、用户名是否存在中文或双字节字符，但服务器是英文或其他语种的（参考：疑6  、疑7），或者考虑是编码错误，可以采用附件【Base64.zip】工具解码验证；

8、检查Common.config的校验组件配置，如果单点校验是二开商提供的组件，请暂时恢复为星空默认出厂配置进行验证确认没有问题，就可以定位是二开组件编写有问题，请联系二开商进行二开组件修复即可；（星空默认出厂配置参考9）

9、星空默认出厂配置如下：

<!--启动服务插件 V2.0-->
<add key="StartAppPlugin" value="Default" />
<!--启动服务插件 V1.0 -->
<add key="StartAppPlugin" value="Kingdee.BOS.ServiceFacade.StartApp.MacVerify,Kingdee.BOS.ServiceFacade.StartApp" />

疑3、如何获取数据库的ID？
答：1、由管理员查询管理中心数据库；
2、通过“管理第三方系统登陆授权”测试功能“生成Silverlight入口链接”功能获取；

疑4、数据库ID会变吗？
答：在数据库注册到管理中心后产生一个固定ID。一旦重新注册该数据库，就会为数据库重新分配新的ID。

疑5、SingedData生成过程中数据的排序方式是什么？
答：字符串正向排序规则。

疑6、用户名或者其他参数存在中文或其他Unicode字符怎么办？
答：简单的方法就是针对生成好的ud参数整体进行基于Utf-8的Base64的编码，然后在启动校验插件中进行base64解码。（在K/3Cloud的出厂Demo插件已经默认支持Base64解码了。），
例如： 【http://xxxx/k3cloud/html5/index.aspx?ud=|563073d2b90b4f|Developer|hr|cf6e86aed7d40b1534cf9a1ea557a073626a30ac|1458613257|2052】 
  中的ud参数部分进行整体的基于Utf-8的Base64编码成
【http://xxxx/k3cloud/html5/index.aspx?ud=fDU2MzA3M2QyYjkwYjRmfERldmVsb3BlcnxocnxjZjZlODZhZWQ3ZDQwYjE1MzRjZjlhMWVhNTU3YTA3MzYyNmEzMGFjfDE0NTg2MTMyNTd8MjA1Mg==】
即可。

疑7、服务器是英文的操作系统，但客户的用户名称却是中文的，如用户名为“爱中华”，导致自动登录老报用户名签名失败？
答：两个方案可供选择 >>

方案1、(私有云，单租户) 简单的方法就是针对生成好的ud参数整体进行基于Utf-8的Base64的编码，然后在应用服务端的 website/app_data/Common.config  配置中增加 StartAppPluginUDConfig 的配置项，参考 (https://vip.kingdee.com/article/8927 ) 的4.2 部署配置说明。

<add key="StartAppPluginUDConfig" value="{encoding:'utf-8'}" />

方案2、(私有云，单租户, 多租户 PT-146869 [7.6.0.202103] 2021/3/25  7.6.2122.7 发布功能 )对生成好的ud参数整体进行基于Utf-8的Base64的编码，并在url地址增加url参数 &udencoding=utf-8即可。例如：https://xxx/k3cloud/html5/index.aspx?udencoding=utf-8&ud=### 

疑8、用java编写生成url的时候，老报签名错误？
答：一般的存在两个错误：
1、不要引用外部的编码组件，这个问题是因为引用错误的base64组件导致编码错误，例如：org.apache.commons.codec.binary.Base64；
2、签名字符串没有在数组排序后生成，导致签名错误，参考下面代码：

 【免登功能 - 使用Java代码生成简单认证参数例子篇】

   https://vip.kingdee.com/article/171816 

疑9、直接访问云星空站点，或注销后如何退回统一登录界面，而不是金蝶云星空的登录界面？

答：通过编写web.config的moduler可以实现，参考：

 【云星空登录index.aspx页面自动转向统一认证页面】

   https://vip.kingdee.com/article/170637 

疑10、[应用Id] 会不会过期？[链接有效时间] 是什么意思？

答：[链接有效时间] 可使用管理员登陆云星空后，在【第三方系统登陆授权】功能 中查看：

1、应用Id不会过期，应用密钥也不会过期，用这个密钥生成的签名数据才会有过期的说法，参考下面2【链接有效时间】的内容。

2、【链接有效时间】字段指生成的ud参数的有效时间，它是按下面的会话有效期来确定的：

比如你设置了会话有效时间为99分钟。那么你在8点钟生成的ud参数在(8点+99分钟>9点39时)就过期了。

疑11、"appSecret 公钥字符串，来自administrator管理中第三方系统登陆授权功能分配的加密钥匙" 中appSecure是什么来源 ？

答：

1、管理员登陆云星空后，第三方系统登陆授权功能 中获取的【应用密钥】字段。

2、如下图：

疑12、免登各种情况提示语如何进行初步诊断？

答：提示语分析汇集如下：

tips1 -- 第三方应用：XXX 未授权，请联系系统管理员！

解 -- appid未注册

tips2 -- 第三方应用：XXX 已被禁用，请联系系统管理员！

解 -- appid已注册但被管理员禁用

tips3 -- 第三方应用：XXX 验证签名失败，请联系系统管理员！

解 -- 应用密钥与appid不匹配，或传入的时间戳参数与生成签名数据的时间戳不一致，或者是第三方使用java编程，但组件不正确导致，可以参考【疑8】解决，或者是编码错误，存在双字节字符的参数没有使用utf8编码后转base64，可以采用附件【Base64.zip】工具解码验证。

tips4 -- 时间戳验证失败，请求链接已失效，请重试！

解 -- 签名数据超时时间到。或者终端电脑的时间与服务器不一致，或第三方服务器时间与星空服务器时间是否一致，就需要修复系统时间。

tips5 -- 用户：XXX 不存在，请联系系统管理员！

解 -- 系统中未找到该签名用户

tips6 -- 登录参数的格式或编码异常，如存在双字节字符，请使用UTF8格式对参数编码。xxx

解 -- 一般为免登参数中存在非ansii编码字符，例如用户名称为中文“爱中华”，这时建议采用【疑7】的解决方案

疑13、如何实现在第三方统一认证页面登录后在跳转云星空

答：参考【关于CAS SSO的集成问题】 https://vip.kingdee.com/article/11227  其他认证系统类似，同时结合 

【云星空登录index.aspx页面自动转向统一认证页面】   https://vip.kingdee.com/article/170637  来实现完整应用。

疑14、如何单点打开多个业务单据，而不会踢出原来打开的单据。

答：通过webapi判断当前的用户状态并写入待打开单据ID到数据库，另外在已经打开的定制动态表单中n秒轮训查看待打开单据ID列表，这样可以避免同一用户同时在多个单据界面并修改同一个单据导致网络控制失效，从而导致数据错误。也可以避免lic泄漏。具体参考帖子-》https://vip.kingdee.com/questions/15738 ，其中判断方法参考【宇】的答复。

疑15、用openmode=single的方式打开的单据，如何在按F5刷新浏览器不要跳出到登录而是留在当前二开单据上？

答：可以利用iis的moduler功能，登录时写入session 标识的ud参数，刷新时跳回登录后判断如果有ud参数，就重新单点进去就可以了。moduler的编写可以参考下面地址。【云星空登录index.aspx页面自动转向统一认证页面】  https://vip.kingdee.com/article/170637

疑16、如何通过免登直接打开待办任务列表，如何第三方集成金蝶云星空工作流

答：建议参考二次开发指导《第三方系统集成金蝶云星空工作流》 https://vip.kingdee.com/article/183922 

疑17、使用IE11 之后 星空单点登录全部都失效，用Chrome浏览器就没有问题。

答：建议IE浏览器取消兼容模式就可以了。IE在兼容模式下相当于IE-7.0 ，参考下图。尤其是使用“在兼容性视图中显示Intranet站点”不要勾选，该选项会强制 所有局域网站点 都使用IE-7.0的兼容模式，就会导致站点不能用。但对于广域网站点，没有命中这个规则的都跑在IE-11.0模式下，因此广域网站点就没有问题。

疑18、按照【第三方系统单点登录到金蝶云指南V2】编程，发现没有命名空间Kingdee.BOS.BusinessEntity.Login和类SimplePassportLoginArg 。

答：必须安装到 PT131268  [7.3.1150.7] 2019-1-24 之后的补丁才会有该命名空间Kingdee.BOS.BusinessEntity.Login和类SimplePassportLoginArg 提供使用。

疑19、单点登录后直接打开一些复杂单据或报表，需要准备很多参数，如何实现？

答：单点登录由于是url传递数据，不建议传递太多数据，可能导致url超过浏览器限制。

* 例如一些定制报表这种复杂报表单据B，建议二开动态表单A来嵌套这种复杂报表单据B，二开的动态表单A准备好查询上下文条件，然后在传入复杂报表单据B进行查询。如何开发二开动态表单可以查询论坛相关帖子或咨询平台，具体复杂单据或报表需要准备什么查询条件和数据，咨询具体功能业务组。对于没有特殊权限或参数控制的功能，系统默认支持以下功能表单 --单据，动态表单，列表，普通报表，Sql报表等。

    a* 表单类型可以参考：【自动登录后，实现自动打开某个单据的功能】https://vip.kingdee.com/article/10881  中的代码读取StartAppHomePageArgs类型的参数对象 。

    b* 如果是比较简单格式的表单参数，也可使用formargs 免登参数，参考 https://vip.kingdee.com/article/8928 中的【1.2、协议内容解析】的formargs 免登参数用法。

    c* 如果没有参数，可以直接使用本篇【疑23】的方法。

    d* 如果是工作流相关参考上面答疑“16、如何通过免登直接打开待办任务列表，如何第三方集成金蝶云星空工作流”。

    e* 如果BOS平台二开表单有困难，可以在论坛中搜索“BOS平台二开”相关资料参考。

疑20、单点登录每增加一个用户都要生成一个秘钥匹配，做不了自动，很麻烦？

答：秘钥是适用于所有当前应用的所有用户的。这里的集成用户仅是用于【生成测试链接】进行测试使用。

特别提示：“每增加一个用户都要生成一个秘钥，应用秘钥是和具体用户绑定的”这样的理解【不--正--确】。

疑21、单点登录插件定制后，如何制作安装包实现快速部署？

答：二开安装包制作的帖子，可以参考下：https://vip.kingdee.com/article/5204

疑22、公有云单点登录后，定制功能扩展了HTML5主控台BOS_HtmlConsoleMain表单和挂插件，但没有效果？

答：原因是扩展了错误的主控表单导致。相关表单参考如下：

      1、HTML5端入口表单是 BOS_HtmlConsole，公有云主控台表单BOS_O2OHtmlConsoleMain，私有云或开发环境的主控台表单为BOS_HtmlConsoleMain。

      2、GUI/SL端入口和主控台：公有云主控表单：97bcb5b2-8dfb-490c-bcfa-9f1021ae8968 (扩展自BOS_MainConsoleSutra)，私有云或开发环境的主控台表单为BOS_MainConsoleSutra。

疑23、系统免登成功进入主控，默认打开列表和单据正常，默认打开一些其他报表或功能就提示一些错误或没有数据？

答：免登成功能够进入主控，说明免登功能已经OK。主要问题是默认打开的具体功能有问题。这些问题分为两类：

1、没有复杂的ShowForm显示功能参数准备的，例如没有额外参数可以直接发布到主控台的，一般是formtype设置错误。

formtype = 单据：bill或空, 列表：list, 万能报表：wnreport, 直接sql报表：sqlreport, 系统报表：sysreport， 树形报表：treereport, 移动报表：movereport， 动态表单：dynamicform。

2、有复杂功能参数的，this.View.ShowForm时需要额外参数准备的，就需要有初始化参数或定制权限等的复杂报表或单据，建议二开动态表单来嵌套这种复杂单据，二开的动态表单作为上下文查询数据准备，然后再传入指定的复杂报表或单据。（可以参考：【疑16、如何通过免登直接打开待办任务列表，如何第三方集成金蝶云星空工作流】、【疑19、单点登录后直接打开一些复杂单据或报表，需要准备很多参数，如何实现？】）

疑24、如何做到系统免登成功进入主控，默认不打开列表和单据，或其他功能，只要主控就好？

答：不传formid 等参数即可 :<)，参数说明参考：https://vip.kingdee.com/article/8928 

疑25、客户端登陆界面也想定制，如何定制？

答：定制桌面客户端登陆界面可以参考 https://vip.kingdee.com/article/11230， 

    1、实现GetLoginfo接口时，AuthenticateType = AuthenticationType.SimplePassportAuthentication， 同时初始化SignedData属性即可，SignedData生成和网页的ud参数中的SignedData一直。

var ret = new Kingdee.BOS.Authentication.LoginInfo()

{

    PasswordIsEncrypted = false,

    Password = "xxxx",//任意字符串，但不能为空

    // 此处是强制使用【简单证书】登陆

    AuthenticateType = AuthenticationType.SimplePassportAuthentication,

    AcctID = "xxxx", //数据中心ID 

    Username = “username”,

    Lcid = 2052,

    AppId = “xx”, //第三方系统appid

    Timestamp = DateTime.Now.GetTimestamp().ToString(), //时间戳,

    //// 第三方系统登陆授权生成签名数据，参考：

    //Kingdee.BOS.Util.SHA1Util.GetSignature(

    //  new string[] { 

    //      dbId, usserName, appId, appSecret, timestamp.ToString() 

    //  });

    SignedData = "####" //signeddata

};

return  ret;

    2、默认参数传递可以通过下面代码传递给主控台：

    可在 GetLoginfo接口 中增加以下代码即可把自定义参数传入主控首页。ud参数生成参考：https://vip.kingdee.com/article/8928 。

Kingdee.BOS.Client.Core.ClientAppProxy.Current.StartAppVerifyCustomArgs = [base64格式的utf-8编码格式的ud参数]。

    3、客户端与第三方sso服务集成，可以参考【疑问32】

疑26、如何从第三方系统注销用户？

答：第三方系统通过post方式发生http请求调用服务器的第三方注销地址即可实现。

具体参数参考：https://vip.kingdee.com/article/9788  文章的【4   从第三方系统注销用户】

疑27、云之家如何创建登入云星空系统的入口？

答：

1、参考【云之家单点登陆金蝶云K/3cloud实施指南】  https://vip.kingdee.com/article/34650   创建云之家入口；

2、参考 【启动插件校验机制实现免登录功能-支持云之家集成与JSON参数】https://vip.kingdee.com/article/8928 生成云之家到云星空的url链接；

疑28、webapi如何实现sso登入？

答：参考webapi接口说明文档 https://vip.kingdee.com/article/72264871240336640 

疑29、涉及到较多星空Common.config的配置设置，不知道怎么配置？

答：common.config 位置在应用服务器的 website/app_data/ 目录下， 具体配置方法可以参考 【Common.config配置】

https://vip.kingdee.com/article/146280

疑30、客户端Kingdee.BOS.XPF.exe能否通过命令行参数实现免登功能？

答：客户端单点登录建议不要用通过命令行参数，这是一种不稳定，局限性较大，有安全隐患的方案，因为

    1、命令行传递参数在不同系统下有不同的长度限制，导致可能参数被截断；

    2、无法处理注销后的逻辑或转向等定制需求；

    3、客户端组件无法自动校验更新（新补丁安装后）；

    客户端免登需求的实习可以参考【答疑篇】第25条，这是一个完整的客户端集成方案，可以自己画登录界面，你要画什么都可以。然后注销回到你画的界面上。组件部署在服务器上，自动下载更新。登入前和注销后的逻辑都可以自己定制。这个方案具有完整性好，安全性高，稳定性佳，逻辑定制灵活，部署规范等优点。

疑31、免登后进入系统，没有默认打开指定表单？

答：免登能够进入主控，说明登录部分的参数解析和配置基本没有问题，主要问题出现在登录后默认打开表单参数的配置上。考虑以下情况：

      1、用Fiddler抓取免登url请求，找到免登请求提取ud参数，fiddler使用参考 【如何使用Fiddler工具抓取请求saz文件https://vip.kingdee.com/article/56714444616541696  】；

      2、用base64工具解开ud参数；

      3、检查默认打开参数表单参数，可对照【疑14，15，16，19，23，24】检查；

      4、由于默认打开逻辑需要依赖主控台出厂插件逻辑来打开，需要检查是否主控台出厂插件被二开扩展停用了；对于HTML5单功能Single模式主要依赖入口表单的出厂插件逻辑来打开，需要检查是否入口表单出厂插件被二开扩展停用了；

      5、如果二开扩展需要停用出厂主控插件，那么需要参考【自动登录后，实现自动打开某个单据的功能  https://vip.kingdee.com/article/10881  】实现默认打开具体功能逻辑；

      6、入口与主控台表单参考 【疑22】；

疑32、星空单点登录的方式是哪一种协议呢，SAML2.0还是OAUTH2.0？

答：星空单点登入是一个通用的解决方案，不是具体什么协议，这个方案支持URL参数集成，因此支持市面上大部分的sso服务的二开集成登入。SAML2.0还是OAUTH2.0、或Cas X.0，或其他协议本身就是第三方的SSO服务，企业根据自己实际情况进行选用不同的SSO服务，然后通过星空免登方案进行集成。 

    具体集成二开方法可以参考 : 【云星空集成外部第三方SSO二开通用参考方案】   https://vip.kingdee.com/article/251021508447762944 

疑33、免登后进入系统，如何给默认打开的指定表单传递简单参数，兼容BOSIDE发布的定制参数功能？

答：免登能够进入主控，打开默认表单后，在ud参数中增加属性formargs，该属性为json格式的字符串。即可兼容BOSIDE发布的自定义参数。(私有云，单租户, 多租户 PT-146869 [7.6.0.202103] 2021/3/25  7.6.2122.7 发布功能 )

{"dbid": "5f15047c6708f9", "username": "demo",  ... ... 省略其他参数 , "formargs": "{\"KD_Html5_FormTheme_Name\":\"Galaxy\"}"}  。

其中：formargs 为json格式字符串，例如：{"KD_Html5_FormTheme_Name":"Galaxy"}, 可以通过JSON对象生成。

在星空表单插件中可以用如下代码生成：

var args = new JSONObject(); 
args["KD_Html5_FormTheme_Name"] = "Galaxy"; 
string formargs = args.ToString();

疑34、没有使用系统出厂的默认default免登逻辑，而是二次开发了免登插件后，ud参数的内容比如openmode等参数如何传递给主控表单，可以在主控的二开插件中读取利用？

答：二次开发了免登插件后，登录如果成功，可以把参数按下面代码实现通过框架传递给主控插件。

代码文件需要增加引用 Kingdee.BOS.dll; 注意只有ud参数为V2协议json格式的才支持，V1格式不支持。

using Kingdee.BOS.JSON;

using Kingdee.BOS.Authentication;

public override StartAppResult Verify(KDServiceContext context, string argStr)
{
    // 校验登录逻辑
    .....  
    // 整理参数    
    if (ret.ResultType == StartAppResultType.Success)
    {
        StartAppParameterProtocol sapp = StartAppParameterUtils.GetParameter(JSONObject.Parse(argStr));
        StartAppHomePageArgs hpArgs = sapp.GetStartAppHomePageArgs();
        ret.CustomArgs = hpArgs.ToBase64String();
    }
    return ret;
}

疑35、公有云和私有云，单租户和多租户都支持免登集成吗？

答：都支持的，公有云单租户和私有云支持自定义插件免登集成，当然也推荐使用出厂的通行证校验模式。公有云多租户不支持自定义插件逻辑，但可以使用出厂的通行证校验模式。云星空集成方法是通过秘钥生成第三方登入url来集成登入星空系统，因此适用性很强。具体出厂的通行证校验模式参考：【第三方系统单点登录到金蝶云指南V2】 https://vip.kingdee.com/article/9788 ，其他相关疑问可以参考上面的答疑内容。

疑36、用免登连接打开单据耗时比一般静态页面要多，是什么原因，需要如何优化？

答：   免登入口打开表单，需要加载动态领域模型渲染完整组件，业务数据也由服务端动态驱动，对比一般静态网页来说，这种架构的可扩展性更好，但会更消耗性能和内存，因此会比一般静态页面要消耗大。

    动态领域模型说明：云星空实现基于领域模型的数据驱动和动态渲染架构，动态请求是依据服务端业务逻辑，通过数据指令来动态发起请求，同时实现一种类似分批增量取数的机制，实现请求时同步增量渲染，从而提高渲染效率。这种架构带来高业务扩展性，和架构弹性，配合BOS平台设计器，可最大程度的支持行业特性的二次开发，来满足各个行业特性需求。云星空HTML5整体采用SPA模式实现最大的内存资源复用。

    第三方单点连接点击在浏览器打开连接的方式相当于MPA模式，因此每个连接打开都是一个全新应用，相关动态领域渲染模型组件都需要重新加载。可优化方案如下（1-3为动态领域模型下的提升方案，4为另外的二开方案）：

        1、设置chrome为默认浏览器，从而使得邮件连接默认用chrome来打开。chrome采用V8引擎，比IE内核的Trident引擎快1倍以上，因此微软新的浏览器也采用了谷歌内核；

        2、使用轻量级入口地址：【http://xxx.xxx.xxx.xxx/k3cloud/html5/lightstartapp.aspx?ud=...】优化资源。 参考：https://vip.kingdee.com/article/8928 章节【1.1.1】；

        3、单点登入采用 openmode=single 的无主控直达目标单据模式，避免加载主控内容，提升载入性能； 参考：https://vip.kingdee.com/article/8928 章节【1.2、协议内容解析】

--附录---------------- 参考帖子区 ----------------------

【星空第三方免登资料参考链接】

https://vip.kingdee.com/article/221201966503051264 

------------------------------------------------------

创建于2020年1月6日 17:25:30

... ...

编辑于2021年7月1日 15:57:14

编辑于2021年8月10日 10:10:20