====== 客服云单点登录 ======

===== 概述 =====

单点登录功能允许为租户设置指向第三方系统的登录URL，坐席使用该第三方系统的账号登录后，可以直接进入客服系统。

单点登录功能为旗舰版功能。

===== 注意事项 =====

只有拥有独立三级域名（例如：example.kefu.easemob.com）的租户才可以使用单点登录功能。公有云的租户（kefu.easemob.com）无法使用。


===== 设置单点登录 =====

完成第三方平台登录页面的开发后，使用二级域名登录客服系统，并进入“管理员模式 > 设置 > 单点登录”页面，设置远程登录地址、生成共享密钥，并开启单点登录功能。

{{:cs:400systemintegration:admin-settings-sso.png?nolink|}}

===== 时序图 =====

下图为通过JWT的第三方单点登录（SSO）时序图。

注：此处以三级域名为“lcx.kefu.easemob.com”为例。

{{:cs:400systemintegration:sso-jwt-170118.jpg?nolink|}}
===== 第三方平台开发 =====

开发一个登陆页面，使用第三方自己的用户体系登录，比如：

<code>http://young-dawn-82093.herokuapp.com/chenxing/sso</code>

在第三方登录成功之后，使用约定好的jwt secret对email、name、state进行签名，生成的jwt有2分钟有效期。

<code>
email 必填 邮箱地址，当做环信用户名
name 必填 为昵称用于创建用户的时候使用
state 必填 为登录状态Online、Hidden
externalId 选填 如果第三方系统的邮箱不是用户名而是可以随时改变的一个资料信息，那么在这里填写真正登录使用的用户名
JWT_SECRET 必填 为“管理员模式 > 设置 > 单点登录”页面的“共享密钥”

String jwt = JWT.create()
        .withIssuedAt(new Date())
        .withJWTId(UUID.randomUUID().toString())
        .withClaim("email", email)
        .withClaim("name", "昵称")
		.withClaim("externalId", "如果第三方用户名不为email，这里填写用户名")
        .withClaim("state", "Online")
        .sign(Algorithm.HMAC256(JWT_SECRET));
</code>

生成好jwt之后，需要redirect回环信的地址：

<code>http://lcx.kefu.easemob.com/v1/access/jwt?jwt={jwt}&returnTo={return_to}</code>

参数说明：

  * jwt: 上述根据email、name、state进行签名后生成的jwt
  * returnTo: 可以使用跳转到第三方平台时url地址携带的returnTo地址

客服云系统根据jwt进行验证之后，会自动进行登录，并且跳转到return_to的地址。