Optimize the 用户登录认证体系.md

Author: wushengyeyouya

zh_CN/使用文档/DSS新增用户方式.md

@@ -0,0 +1,129 @@
+# DataSphere Studio 用户登录认证体系
+
+> DSS 默认只提供了管理员账号，用户登录鉴权依托于 Linkis 的 LDAP 用户登录认证体系。
+> 本文将详细介绍 Linkis 目前已经支持的用户登录认证方式。
+
+## 一、基本介绍
+
+1. DSS 超级管理员的用户名为部署用户名，如部署用户为 hadoop，则管理员的用户名和密码为 hadoop/hadoop，具体用户可在 [DSS单机部署文档](../安装部署/DSS&Linkis一键部署文档单机版.md) 查看。
+
+2. DSS的用户登录鉴权，依托于 Linkis 的用户登录认证体系。除管理员以外，Linkis 还支持以下用户登录认证方式： 
+  
+  - Token 登录方式
+  - 代理用户模式
+  - 接入SSO单点登录  
+
+## 二、Token登录方式
+
+该方式是给第三方系统访问 Linkis 和 DSS 使用的。
+
+第三方系统调用 Linkis 和 DSS 后台接口时，只需通过 token 模式即可直接跳过登录。
+
+在 `linkis/linkis-gateway/conf/linkis.properties` 指定如下参数：
+
+```properties
+    # 打开token模式
+    wds.linkis.gateway.conf.enable.token.auth=true
+    # 指定token配置文件
+    wds.linkis.gateway.conf.token.auth.config=token.properties
+```
+
+在 `linkis/linkis-gateway/conf` 目录下，创建 `token.properties` 文件，内容如下：
+
+```properties
+    # 格式如下：
+    ${TOKEN_NAME}=${USER1},${USER2}
+    # 例如：
+    AZKABAN=*
+```
+
+TOKEN_NAME 指分配给第三方系统的 tokenId，后面的 value 为可跳过登录的用户，如果完全信任该系统的所有请求，可直接等于*，表示全部授权。
+
+第三方系统在请求 DSS 和 Linkis，在 request 的 header 或 cookie 中，写入如下两个参数即可：
+
+```json
+    {
+      "Token-Code": "${TOKEN_NAME}",
+      "Token-User": "${USER}"
+    }
+```
+
+## 三、代理用户模式
+
+该方式允许登录用户和实际使用 DSS 的用户不同，主要作用：控制用户登录时必须为实名用户，但是实际使用大数据平台时，是非实名用户。
+
+在 `linkis/linkis-gateway/conf/linkis.properties` 指定如下参数：
+
+```properties
+    # 打开代理模式
+    wds.linkis.gateway.conf.enable.proxy.user=true
+    # 指定代理配置文件
+    wds.linkis.gateway.conf.proxy.user.config=proxy.properties
+```
+
+在 `linkis/linkis-gateway/conf` 目录下，创建 `proxy.properties` 文件，内容如下：
+
+```properties
+    # 格式如下：
+    ${LOGIN_USER}=${PROXY_USER}
+    # 例如：
+    enjoyyin=hadoop
+```
+
+如果现有的代理模式不能满足您的需求，您也可以手动修改：`com.webank.wedatasphere.linkis.gateway.security.ProxyUserUtils`。
+
+## 四、接入SSO单点登录
+
+接入您公司的 SSO 单点登录体系要复杂一些。
+
+首先，您需要打开 SSO 单点验证功能，请在 `linkis/linkis-gateway/conf/linkis.properties` 指定如下参数：
+
+```properties
+    wds.linkis.gateway.conf.enable.sso=true
+```
+
+然后，您需要实现SSOInterceptor接口：
+
+```scala
+trait SSOInterceptor {
+
+  /**
+    * 如果打开SSO单点登录功能，当前端跳转SSO登录页面登录成功后，会重新跳回到DSS首页，这时DSS前端再次请求gateway，
+    *     gateway会通过调用该方法获取已SSO登录的用户，然后将用户写入cookie，保证后续请求可直接放行。
+    * 您需实现该方法，通过Request返回用户名。
+    * @param gatewayContext
+    * @return
+    */
+  def getUser(gatewayContext: GatewayContext): String
+
+  /**
+    * 通过DSS首页Url，用户生成一个可重定向的SSO登录页面URL。
+    * 要求：需带上requestUrl，以便SSO登录成功后能跳转回来
+    * @param requestUrl DSS首页URL
+    * @return 例如：https://${sso_host}:${sso_port}/cas/login?redirectUrl=${requestUrl}
+    */
+  def redirectTo(requestUrl: URI): String
+
+  /**
+    * 用户退出登录时，gateway会调用此接口，以保证gateway清除cookie后，SSO单点登录也会把登录信息清除掉
+    * @param gatewayContext
+    */
+  def logout(gatewayContext: GatewayContext): Unit
+
+}
+```
+
+将您的 SSO 实现类，打成 jar 包，放入 `linkis/linkis-gateway/lib` 目录。
+
+Linkis 提供了两种加载您 SSO 实现类的方式：
+
+将 SSO 实现类声明为 Spring bean，这种方式要求您只需在类名上面加上 `@Component` 注解即可。
+
+在 `linkis/linkis-gateway/conf/linkis.properties` 指定如下参数：
+
+```properties
+    #请指定为您的SSO实现类
+    wds.linkis.gateway.conf.sso.interceptor=com.webank.wedatasphere.linkis.gateway.security.sso.SSOInterceptor
+```
+
+重启 linkis-gateway，SSO 单点登录即可生效。