需求背景

在很多的应用项目中，客户会采用Windows域登录认证平台，要求 Smartbi 也能使用windows域账号密码进行验证，效果如下。

用户组的信息在登录的时候进行同步，根据用户的组信息再自动创建组，这个组是AD域组的信息（另外配置的AD域用户也会自动同步过来）

特性	AD域	LDAP协议	LDAPS协议
性质	目录服务实现	访问目录服务的协议	LDAP的安全版本
开发者	微软	开放标准（IETF）	开放标准（IETF）
加密	支持多种加密方式	默认不加密	强制SSL/TLS加密
端口	多端口（389，636，88，3268，3269，9389等）	389	636
依赖关系	实现LDAP协议	AD域使用LDAP作为通信协议	是LDAP的安全增强

使用说明

扩展包部署

扩展包：Smartbi_Special_ADAuth

详细说明请参考Wiki链接：扩展包部署

更新扩展包之前，请做好知识库以及扩展包的备份。

配置说明

1、获取ad.properties文件：ad.properties

2、打开ad.properties文件，修改参数。

如果包含中文，则需要将ad.properties重命名为ad_cn.properties，再使用<JDK>\bin\native2ascii.exe ad_cn.properties ad.properties转换中文字符后使用。

配置文件中的参数如下：

参数名

含义

原参数值

修改

provider_url

配置AD域服务器的地址与端口

ldap\://ADServer\:389

值说明

ADServer为Window域服务器IP地址或服务器名
端口可以是389，636，3268，3269
- 389：可以会获取到组织相关的属性，同时baseName属性不能为空，请参考 AD域（LDAP/LDAPS）登录验证（完善中）。
- 3268：会获取不到组织相关的属性。

例如

LDAP

provider_url = ldap\://10.10.201.225\:389

LDAPS

provider_url = ldaps\://10.10.201.225\:636

使用LDAPS，还需要进行相关的配置

1）需要配置对应的证书，请参考 AD域（LDAP/LDAPS）登录验证（完善中）

2）同时需要配置 security_protocol = ssl ，请参考 AD域（LDAP/LDAPS）登录验证（完善中）

参考

服务	协议	默认端口	用途
LDAP	TCP	389	普通目录查询
LDAPS	TCP	636	加密目录查询
Kerberos	TCP/UDP	88	身份认证
DNS	TCP/UDP	53	域名解析
SMB	TCP	445	文件共享、域登录
Global Catalog (LDAP)	TCP	3268	跨域查询
Global Catalog (LDAPS)	TCP	3269	加密跨域查询
AD Web Services	TCP	9389	PowerShell管理AD

baseName

AD域域名

值说明

若provider_url配置的端口为389，此处不能为空，值为域名
若provider_url配置的端口是3628，此处可为空

例如

域名为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

配置用户名后缀

值说明

通常是@+域的名称，

例如

域名为 smartbi.local，则此处值为 @smartbi.local

principal_suffix = @smartbi.local

注意

此配置项与principal_prefix只能二选一，不可同时配置，若是配置principal_prefix并排除其他问题后，可考虑改为配置此项，配置此项时，principal_prefix需为空

filterPrefix

限制AD域查询范围的前缀

(&(objectCategory\=Person)(sAMAccountName\=

不需要修改

filterSuffix

限制AD域查询范围的后缀

))

不需要修改

initial_context_factory

JAVA通过该工厂类

com.sun.jndi.ldap.LdapCtxFactory

不需要修改

security_protocol

当使用的是LDAPS时，需要设置

无值

值说明

填写LDAPS对应使用的加密通信方式，当前只支持 SSL。

同时provider_url设置为LDAPS协议头和端口，请参考 AD域（LDAP/LDAPS）登录验证（完善中）

例如

security_protocol = ssl

注意

无值时，等同于不使用 ssl 加密通信方式

isDeleteUser

在用户登录时，尝试登录一个AD域没有而Smartbi中有且不在白名单中的用户时，是否要删除该用户

无值

值说明

true：在用户登录时，尝试登录一个AD域没有而Smartbi中有且不在白名单中的用户时，会提示登录失败，并删除该用户
false：在用户登录时，尝试登录一个AD域没有而Smartbi中有且不在白名单中的用户时，会提示登录失败，会把该用户迁移到 moveDisabledGroup 配置的禁用组中，请参考 AD域（LDAP/LDAPS）登录验证（完善中）

注意

无值时，等同于为 true

moveDisabledGroup

用于存放AD域没有而Smartbi中有的用户

注意：当isDeleteUser=false时，这个配置项才会被用上

无值

值说明

填写的是对应的用户组的ID

例如

moveDisabledGroup = DEPARTMENT

注意

无值时，等同于为 DEPARTMENT

white_show_setting

是否在【系统选项】中显示【AD账号白名单】选项

无值

值说明

true：在【系统选项】中显示【AD账号白名单】选项
false：在【系统选项】中不显示【AD账号白名单】选项

注意

无值时，等同于为 true

场景

参考 AD域（LDAP/LDAPS）登录验证（完善中）

admin_default_login

admin账号是否可以绕过AD域验证而直接走Smartbi的自身的验证

注意：默认admin不进行AD域验证

无值

值说明

true：admin账号可以绕过AD域验证而直接走Smartbi的自身的验证
false：非白名单情况下，admin账号不允许通过账号密码方式登录到Smartbi

例如

admin_default_login = true

注意

无值时，等同于为 true

create_user_ad_check

Smartbi中创建用户时，是否在点击“保存”时，使用创建用户的“名称”（即用户名）到AD域中进行校验

无值

值说明

true：创建用户时进行AD检查。如果这个用户名在AD域中存在，则会创建成功，否则会创建失败并提示“非AD域下用户无法自行创建”。
false：创建用户时不进行AD检查

例如

create_user_ad_check = false

注意

无值时，等同于为 false

default_create_user

AD域用户登录时，是否同步该用户到Smartbi中

注意：默认会同步该用户到Smartbi中

无值

值说明

true：执行产品默认逻辑，会同步用户
false：AD域用户登录时，不同步该用户到Smartbi中。如果Smartbi中没有这个用户，则抛出账号密码错误异常。

例如

default_create_user= true

注意

无值时，等同于为 true

场景

参考 AD域（LDAP/LDAPS）登录验证（完善中）

default_syn_group

AD域用户登录时，是否同步该用户的组到Smartbi中

注意：默认会同步该用户的组到Smartbi中

无值

值说明

true：执行产品默认逻辑，会同步用户的组
false：AD域用户登录时，不同步该用户的组到Smartbi中

例如

default_syn_group= true

注意

无值时，等同于为 true

3、启动Smartbi 系统后进入http://localhost:18080/smartbi/vision/config.jsp 配置界面

3.1、配置为ad.properties存放在服务器上的位置

3.2、修改"用户管理"配置段中的"加密类型"为CLASS，"登录验证类"请按需填写，具体如下图所示。

LDAP：smartbi.usermanager.auth.impl.ADAuthentication
LDAPS：smartbi.ext.adauth.auth.LDAPSAuthenication

4、配置完成后，点击右下角的"保存"按钮，根据提示再重启Smartbi 后，即可使用AD域用户的用户名和密码登录Smartbi。

如果发现登录不成功，可以参考 AD域（LDAP/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上

配置：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 文件，并根据实际情况进行修改，相关参数配置，请参考 AD域（LDAP/LDAPS）登录验证（完善中）

其中域名的获取方法可见下图：

2、将修改后的testldap.jsp文件放到smartbi.war/vision/目录中，并重启服务器；

3、启动服务器后访问附件文件，访问地址为：http://ip:port/smartbi/vision/testldap.jsp（这里ip和port改成访问smartbi时的ip和端口）

正常的访问截图如下：

异常访问的截图：

4、最后根据异常页面中的信息来判断哪里设置有误。

关注我们

服务支持

页面树结构

AD域（LDAP/LDAPS）登录验证（完善中）

需求背景

使用说明

扩展包部署

配置说明

注意事项

使用LDAPS证书配置

同步AD用户到Smartbi

白名单配置

问题排查