...
需求背景
在很多的应用项目中，客户会采用Windows域登录认证平台，要求 Smartbi 也能使用windows域账号密码进行验证，效果如下。在很多的应用项目中，客户会采用Windows域登录认证平台，使用本扩展包后， Smartbi 也能使用Windows域账号密码进行验证。
| 注意 |
|---|
用户组的信息在登录的时候进行同步，根据用户的组信息再自动创建组，这个组是AD域组的信息（另外配置的AD域用户也会自动同步过来） |
2. 使用说明
...
| 特性 | AD域 | LDAP协议 | LDAPS协议 |
|---|---|---|---|
| 性质 | 目录服务实现 | 访问目录服务的协议 | LDAP的安全版本 |
| 开发者 | 微软 | 开放标准（IETF） | 开放标准（IETF） |
| 加密 | 支持多种加密方式 | 默认不加密 | 强制SSL/TLS加密 |
| 端口 | 多端口（389，636，88，3268，3269，9389等） | 389 | 636 |
| 依赖关系 | 实现LDAP协议 | AD域使用LDAP作为通信协议 | 是LDAP的安全增强 |
使用说明
扩展包部署
...
| 注意 |
|---|
更新扩展包之前，请做好知识库以及扩展包的备份。 |
...
配置说明
1）获取ad1、获取ad.properties文件： 从这里点击下载该文件<ad.properties>
2）打开ad2、打开ad.properties文件，修改参数。
| 注意 |
|---|
如果包含中文，则需要将ad.properties重命名为ad_cn.properties，再使用<JDK>\bin\native2ascii.exe ad_cn.properties ad.properties转换中文字符后使用。 |
配置文件中的参数如下：锚 参数配置 参数配置
| 参数名 | 含义 | 原参数值 | 修改 |
|---|
provider_url
| 配置AD域服务器的地址与端口 | ldap\://ADServer\:389 | 值说明
例如
provider_url = ldap\://10.10.201.225\:389
provider_url = ldaps\://10.10.201.225\:636
参考
|
修改ADServer和3268为windows域服务器名及端口，ADServer为Window域服务器IP地址或服务器名，端口可以是389或3628
注意：当URL中使用的端口号为3268的时候，会获取不到组织相关的属性，若需要获取到这些属性，需要将端口设置为389端口，同时，389端口对应的配置文件baseName属性不能为空。
| ||||||||||
baseName
| AD域域名 | 值说明
例如 域名为ADLogin.com，此处值为 DC\=ADLogin,DC\=com baseName = DC\=ADLogin,DC\=com 域名为hr.corp.example.com，此处值为 DC\=hr,DC\=corp,DC\=example,DC\=com baseName = DC\=hr,DC\=corp,DC\=example,DC\=com 注意 可以使用 Softerra LDAP Browser 之类的工具查看对应的域名 | ||||||||
| login_user |
| 可以登录到windows域服务器的用户，用于获取用户信息 | username | 值说明 域用户的用户名 例如 login_user = administrator |
| login_password | 可以登录windows域服务器的用户的密码，用于获取用户信息 | password |
值说明 域用户的密码 例如 login_password = Smart2025 注意 请写明文密码，产品会自动加密回写 | |||
| principal_prefix | 配置用户名前缀 | MyDomain\\ | 值说明 通常是域的名称+\\ |
，这里域的名称是域名的第一个值 例如 域名为 smartbi.local，此处值为 smartbi\\ principal_prefix = smartbi\\
注意 此配置项与principal_suffix只能二选一，不可同时配置，一般情况下只配置principal_prefix即可 | |||
| principal_suffix | 配置用户名后缀 | 值说明 通常是@+ |
注意：此配置项与principal_prefix只能二选一，不可同时配置，一般情况下只配置principal_prefix即可，但若是配置principal
域的名称， 例如 域名为 smartbi.local，则此处值为 @smartbi.local principal_suffix = @smartbi.local
注意 此配置项与principal_prefix只能二选一，不可同时配置，若是配置principal_prefix并排除其他问题后，可考虑改为配置此项，配置此项时，principal_prefix需为空 |
AD域域名
| filterPrefix | 限制AD域查询范围的前缀 | (&(objectCategory\=Person)(sAMAccountName\= |
| 不需要修改 | ||
| filterSuffix | 限制AD域查询范围的后缀 | )) |
| 不需要修改 | ||
| initial_context_factory | JAVA通过该工厂类 | com.sun.jndi.ldap.LdapCtxFactory |
| 不需要修改 |
security_protocol |
|
在ad.properties中新增ldaps支持的配置项security_protocol，当使用的是ldaps时，使用security_protocol配置“ssl”，然后将provider_url设置为ldaps协议头和端口。
在ad.properties中新增moveDisabledGroup=xxxxx，配置一个自定义禁用组的ID未配置或者无值时，默认为DEPARTMENT。这个自定义的禁用组用于存放bi中有但AD中没有的用户，需要结合isDeleteUser来使用，当isDeleteUser=false时，这个配置项才会被用上。
在ad.properties中新增isDeleteUser=true/false，未配置或者无值时，默认为true。当isDelete=true时，在用户登录时，尝试登录一个AD域没有而bi中有且不在白名单中的用户时，会提示登录失败，并删除这个用户（即产品默认逻辑）。当isDeleteUser=false时，在用户尝试登录一个AD中没有但是BI中有，且这个用户不在BI的白名单中时，会提示登录失败，但是不会删除这个用户，而是将这个用户放置到上述配置的禁用组中。
| 当使用的是LDAPS时，需要设置 | 无值 | 值说明 填写LDAPS对应使用的加密通信方式，当前只支持 SSL。 同时provider_url设置为LDAPS协议头和端口，请参考 provider_url 例如 security_protocol = ssl 注意 无值时，等同于 不使用 ssl 加密通信方式 | |||||
| isDeleteUser | 在用户登录时，尝试登录一个AD域没有而Smartbi中有且不在白名单中的用户时，是否要删除该用户 | 无值 |
值说明
|
注意 无值时，等同于为 true | |||||||||
moveDisabledGroup
| 用于存放AD域没有而Smartbi中有的用户 注意：当isDeleteUser=false时，这个配置项才会被用上 | 无值 | 值说明 填写的是对应的用户组的ID 例如 moveDisabledGroup = DEPARTMENT 注意 无值时，等同于为 DEPARTMENT | ||||||
| white_show_setting | 是否在【系统选项】中显示【AD账号白名单】选项 | 无值 |
值说明
注意 |
| admin_default_login | admin账号是否可以绕过AD域验证而直接走Smartbi的自身的验证 注意：默认admin不进行AD域验证 | 无值 |
值说明
|
例如 admin_default_login = true 注意 无值时，等同于为 true | ||
| create_user_ad_check | Smartbi中创建用户时，是否在点击“保存”时，使用创建用户的“名称”（即用户名）到AD域中进行校验 | 无值 |
值说明
|
例如 create_user_ad_check = false 注意 无值时，等同于为 false | ||
| default_create_user | AD域用户登录时，是否同步该用户到Smartbi中 注意：默认会同步该用户到Smartbi中 | 无值 |
值说明
|
例如 default_create_user= true 注意 无值时，等同于为 true 场景 | ||
| default_syn_group | AD域用户登录时，是否同步该用户的组到Smartbi中 注意：默认会同步该用户的组到Smartbi中 | 无值 |
值说明
|
例如 default_syn_group= true 注意 无值时，等同于为 true |
3、启动Smartbi 3、启动Smartbi 系统后进入http://localhost:18080/smartbi/vision/config.jsp 配置界面， 3.1 配置为ad 配置界面
3.1、配置为ad.properties存放在服务器上的位置
3.2 修改
3.2、修改"用户管理"配置段中的"加密类型"为CLASS，"登录验证类"为 smartbi请按需填写，具体如下图所示。
- LDAP：smartbi.usermanager.auth.impl.
...
- ADAuthentication
...
- LDAPS：smartbi.ext.adauth.auth.LDAPSAuthenication
4、配置完成后，点击右下角的"保存"按钮，根据提示再重启Smartbi 后，即可使用AD域用户的用户名和密码登录Smartbi。
3.注意事项
若是配置后发现不能正常使用，可以通过下面方法来获取错误信息，以便定位到问题原因。
1.下载testldap.jsp文件，并根据实际情况进行下面修改：
...
修改ADServer和3268为windows域服务器名及端口，ADServer为Window域服务器IP地址或服务器名，端口可以是389或3628
注意：当URL中使用的端口号为3268的时候，会获取不到组织相关的属性，若需要获取到这些属性，需要将端口设置为389端口，同时，389端口对应的配置文件baseName属性不能为空。
...
通常是@+域的名称，例如域名为ADLogin.com，则此处值为@ADLogin.com
注意：此配置项与principal_prefix只能二选一，不可同时配置，一般情况下只配置principal_prefix即可，但若是配置principal_prefix并排除其他问题后，可考虑改为配置此项，配置此项时，principal_prefix需为空
...
AD域域名
...
...
| 注意 |
|---|
如果发现登录不成功，可以参考 问题排查。 |
注意事项
使用LDAPS证书配置
锚 使用LDAPS证书配置 使用LDAPS证书配置
| 使用LDAPS证书配置 | |
| 使用LDAPS证书配置 |
当在ad.properties中配置了security_protocol=ssl，在config.jsp中配置了LDAPS支持的登录验证类LDAPSAuthenication后，不设置相关证书会在登录时报错：
在已经获取到证书文件（.cer或.crt后缀的文件）后，通过命令行将证书导入到Java信任库
自行获取到目标服务器的证书文件
先备份Java的信任库cacerts，信任库位置：
$JAVA_HOME/jre/lib/security/cacerts
一般是
Smartbi/jdk/jre/ilb/security/cacerts
然后在上述证书所在的目录下进入cmd，使用keytool命令导入证书到Java的信任库中：
keytool -import -alias baseName -file server.crt -keystore $JAVA_HOME/jre/lib/security/cacerts
如：
keytool -import -alias 域名 -file 上述证书文件（包含后缀） -keystore $JAVA_HOME/jre/lib/security/cacerts
即：
| 代码块 | ||
|---|---|---|
| ||
keytool -import -alias baidu.com -file XXX.cer -keystore Smartbi/jdk/jre/lib/security/cacerts |
即可实现导入证书，注意名字只能使用域名，不可自定义，否则在登录时会报会报如下错误：
至此证书导入Java信任库完成，即可正常登录。
附：
用这个命令查看已经导入到Java信任库中的证书，看看名字有没有改对
| 代码块 | ||
|---|---|---|
| ||
keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts |
移除证书，通过指定别名来移除Java信任库中的证书
| 代码块 | ||
|---|---|---|
| ||
Keytool -delete -alias mycert -keystore $JAVA_HOME/jre/lib/security/cacerts |
| 注意 |
|---|
查看信任库中的证书时需要输入密码，默认密码为：changeit |
同步AD用户到Smartbi
锚 同步AD用户到Smartbi 同步AD用户到Smartbi
| 同步AD用户到Smartbi | |
| 同步AD用户到Smartbi |
场景：运维人员要提前对特定账户进行权限的设置（例如：领导），这时最好的方式是提前把AD域相关的用户全部同步到Smartbi上
配置：default_create_user = false
说明：扩展包支持使用计划任务，使用“全量”的形式同步AD用户到Smartbi。
自定义计划任务：
| 代码块 | ||||
|---|---|---|---|---|
| ||||
var paramMap = {
//分页大小（一次查询用户信息条数），若小于等于0，则不分页，当为空时默认分页10
pageSize : 800,
//“用户名”应该使用的AD域属性字段
usernameKey : "sAMAccountName",
//“用户别名”应该使用的AD域属性字段
userAliasKey : "displayName",
//“用户描述”应该使用的AD域属性字段
userDesKey : "mobile",
//同步时的默认密码
defaultPassword : "123456"
}
//以下内容不需要配置
var paramStr = JSON.stringify(paramMap);
connector.remoteInvoke("LDAPSAuthenicationModule", "synchronizeUser", [paramStr]); |
在任务脚本中粘贴上述内容，脚本的参数参考注释。保存，然后测试运行。
同步过来时，对于禁用的用户，只是状态禁用，不会放置在上面提到的禁用组中。上面的禁用组只是针对于Smartbi中有但是AD中没有的用户的。对于没有部门的用户，将会默认保存在DEPARTMENT根组下。
| 注意 |
|---|
同步前请务必备份好用户管理。 |
白名单配置
锚 白名单配置 白名单配置
| 白名单配置 | |
| 白名单配置 |
场景一
场景：在一些大型的集团，AD域只是管理集团员工，而集团的外包团队其实是没有AD域账号的，那对于这些外包人员登录Smartbi，就需要通过白名单的设置来避开AD域的验证。
配置：配置项 white_show_setting = true
入口：在【运维设置】- 【系统选项】 - 【用户管理】中，会增加【AD账号白名单】选项，可以把不需要AD域验证的 ”用户“，添加到 ”AD账号白名单“ 中
场景二
场景：客户安全要求很高，不允许任何人可以通过白名单的方式登录（必须要走AD域验证）。当AD域宕机后，要保证Smartbi可以继续使用，就可以临时用SQL插入用户的方式，当AD域恢复后，直接用SQL把t_ext_ad_whiteinfo表的数据清空即可。
配置：white_show_setting = false
方式：通过SQL的方式来设置白名单
| 代码块 | ||
|---|---|---|
| ||
INSERT INTO t_ext_ad_whiteinfo (c_id, c_type, c_is_descend, c_extend) VALUES ("ADMIN", "USER", "0", ""); |
参考：使用该扩展包后，会在知识库中加一张物理表来记录相关的信息
t_ext_ad_whiteinfo（用于记录白名单的用户)
字段名 | 类型 | 说明 |
c_id | varchar(255) | 用户ID |
c_type | varchar(255) | 类型（用户USER、用户组GROUP、角色ROLE，所有用户EVERYONE） |
c_is_descend | varchar(255) | 是否应用于子孙组用户（只对用户组生效） |
c_extend | longtext | 所选节点扩展内容（包含别名等信息） |
问题排查
锚 问题排查 问题排查
| 问题排查 | |
| 问题排查 |
若是配置后发现不能正常使用，可以通过下面方法来获取错误信息，以便定位到问题原因。
1、下载 testldap.jsp 文件，并根据实际情况进行修改，相关参数配置，请参考 参数配置
其中域名的获取方法可见下图：
异常访问的截图：
4.最后根据异常页面中的信息来判断哪里设置有误。
4、最后根据异常页面中的信息来判断哪里设置有误。
