免登到授客学堂方案

应用场景

在已同步通讯录到授客学堂的前提下（非必须，请参考Scope说明），可实现在第三应用和企业内部系统如OA，HR等系统通过“免登录URL”跳转到授客学堂时进行免登录。

关于网页授权的可信域名

redirect_uri的域名，必须是正确的授客学堂域名（生产：saas.soke.cn 测试：saas.eduto.com），否则跳转时会提示“redirect_uri参数错误”
1、redirect_uri支持PC学员端，H5学员端，后台管理端，系统会从redirect_uri中自动识别进行跳转。
2、redirect_uri必须进行urlencode进行编码处理。

免登录授客学堂流程图

scope授权作用域

scope所对应的安全级别和能力有所区别，企业可以根实际据情况来确定使用的场景：
1、base 静默登录，匹配成员dept_user_id, 前提是和授客学堂通讯录进行同步，未匹配到dept_user_id的成员会提示登录失败。
2、base_register 静默登录（可不提前同步到授客学堂通讯录），在base的基础上对未匹配到dept_user_id的成员可以自动注册，不会像base一样提示登录失败，需要在ticket中携带成员信息，字段请参考“创建用户”接口。
使用base_register授权作用域时，需自行对业务进行详细评估，注意以下两点：
（1）免登传参全靠GET传值，ticket携带的用户JSON信息需要用AES加密，如果携带的信息长度过长可能有超出浏览器请求长度限制的风险。
（2）成员不存在时自动创建成员所在的部门必须提前创建好，否则成员会自动注册失败。

免登URL拼接

请求方式： GET（HTTPS）

请求地址：

  生产环境：

    PC端、H5端统一入口：https://saas.soke.cn/openssoLogin

  测试环境：

    PC端、H5端统一入口：https://saas.eduto.com/openssoLogin

请求参数：

scope=$scope&appid=$appid&corpid=$corpid&timestamp=$timestamp&nonce=$nonce&sign=$signature&ticket=urlencode($encrypt)&redirect_uri=urlencode($redirectUrl)

请求参数说明：

参数	必须	说明
scope	是	授权作用域，支持base、base_register
appid	是	合作商ID
corpid	是	企业ID（如果是合作商，必须是合作商所创建的企业）
timestamp	是	UNIX时间戳（秒），和授客学堂服务器时差30分钟以上可能会出现错误，由开发者自行生成
nonce	是	1-10位随机字段串（字母和数字），由开发者自行生成
sign	是	数字签名，见加密算法，即加密对象的msg_signature字段
ticket	是	登录票据（urlencode编码）即加密对象的encrypt字段，即加密后的JSON用户信息
redirect_uri	是	跳转的授客学堂应用页面URL（urlencode编码），可以是具体某个页面

授客学堂应用首页URL（即默认redirect_uri）：

  生产环境：

    PC首页：https://saas.soke.cn/pcHome/dist/
    H5首页：https://saas.soke.cn/mobile/dist/
    管理后台：https://saas.soke.cn/pcAdmin/dist/

  测试环境：

    PC首页：https://saas.eduto.com/pcHome/dist/
    H5首页：https://saas.eduto.com/mobile/dist/
    管理后台：https://saas.eduto.com/pcAdmin/dist/

需要特别注意的是：

1、免登录链接只能消费一次，不能重复请求，即每次必须重新计算签名和消息体生成新的免登录URL
2、上面的ticket和sign字段需要通过加密算法后返回
3、具体加密算法请参考 加解密及算法SDK及DEMO
4、scope对应的ticket和sign的加密原文如下：

Scope	加密前原文(JSON格式)
scope=base	{"dept_user_id": "zhangshan"}	dept_user_id是必传字段
scope=base_register	{"dept_user_id": "zhangshan", "dept_user_name": "张三", "position": "产品经理", "dept_ids":"1,23,102"}	dept_user_name是必传字段，其它为可选字段

5、如果出现免登录失败，建议开发者先检查生成的免登录URL是否正确，然后尝试解密ticket字段是否和加密原文一致
最终生成的免登录链接如下（仅供参考）：
https://saas.soke.cn/openssoLogin?scope=base&appid=429C0C89-FEB5-479E-8AB0-5D6938974A22&corpid=SOKExtWfkS1693909780&nonce=oLWdCnoO4YZQGUeN&timestamp=1594013217&ticket=U2FsdGVkX1%2Bj92urO6DeFa01xjmDJQDmEoEyfqU%2FNbV7ikxR6ZlmGQGgEd28lIPv%0AcuFn2crs2edgGnz37LjDEnBYmmNnjEpORyNZIetCLWkgzcMV%2FuQ0rcP06wwuxyZf%0A85rZNlX8xInPg107I5Mn1pmKvJPHfNm23dMtDXr9iubx%2FaeIfWegwogzeh2WKOUA%0Ap5m5BjmB%2FiMRIHSxKmzhgw&sign=h67f7ab5f4e9e3c0c65desh75649031330b4sf43&redirect_uri=https%3A%2F%2Fsaas.soke.cn%2FpcHome%2Fdist%2F

实现原理：

通过对用户信息如{"dept_user_id": "zhangshan", "dept_user_name": "张三", "dept_ids":"1,23,102"}加密后生成的ticket和sign等参数，授客学堂对请求的免登录URL进行对应的解密，验证通过后得到登录的用户信息来实现免登录。

进阶场景：

完成上面的免登适配，则实现了从第三方平台免登跳转到授客学堂这个方向的免登链路。
但在授客学堂应用使用过程中，如遇到用户登录状态失效、扫码签到等场景，授客学堂需要引导用户跳转到第三方平台进行重新登录，然后通过第三方平台跳转回来，完成免登。
为实现这个场景，需要第三方平台向授客学堂提供一个引导用户登录的URL。例：https://xxx.xxx.com/userLogin
遇到免登失效或扫码签到这类场景时，授客学堂会添加redirect_uri=xxxx参数(参数值是经base64编码后的回跳地址)跳转到第三平台给的URL 例：https://xxx.xxx.com/userLogin?redirect_uri=xxxx
第三方平台需要引导客户在第三方平台进行登录，并在登录成功后重新拼接授客学堂免登地址跳回到授客学堂，重新拼接的免登地址中redirect_uri参数就是我们给第三方URL传的redirect_uri参数值（保留base64编码后的格式）