1. 概述
1.1 版本
| FineBI 版本 | 功能变动 |
|---|---|
| 5.1.14 | 使用隔离插件的情况下，支持 Kerberos 认证 |
1.2 功能简介
1）Kerberos 认证 是 Hadoop 生态的一种通用的认证方式。
2）配置 Kerberos 认证的方式有两种：
直接使用数据连接配置界面中的 Kerberos 认证：主要用于 Hive、HBase 等驱动的认证连接。
配置 JVM 参数后再进入数据连接配置界面进行认证：主要用于按要求填写数据连接配置界面认证成功，创建连接依然抛错的情况，比如 CDH 的 Impala 等数据库。
1.2 支持的数据库
FineBI 在配置指定的数据连接时支持 Kerberos 认证，支持的数据库类型如下图所示：
| 数据库 |
|---|
| Apache Impala |
| Hadoop Hive |
| Spark |
| Transwarp Inceptor（星环） |
| Apache Phoenix |
| HBase |
1.3 数据连接前的准备工作
1）下载环境上的配置文件 krb5.conf、XXX.keytab 。
2）principal 为注册过 KDC 的客户端名称。格式通常为：用户名/部门@公司 。
3） XXX.keytab 为密钥表文件，需要在提供 Kerberos 服务的应用服务器上找到该文件的对应位置。在不同服务器上 keytab 的文件名称可能不一样，这里用 XXX 代替。
4）集群环境配置 kerberos 认证， keytab 文件需要放在各个节点。
2. 操作方式
2.1 复制配置文件
将 krb5.conf 和 XXX.keytab 放到相同目录下，例如放到%FineBI%\webapps\webroot\WEB-INF\resources目录下。
注：当有多个 Kerberos 认证时，keytab 文件最好不要都放置在 reources 目录下，可能会导致认证冲突。此时可以在 resources 下新建各自的文件夹，放置对应的认证文件。
2.2 配置 hosts 文件
配置本地 hosts 文件，例如在路径C:\Windows\System32\drivers\etc\hosts下配置远端映射：192.168.5.127 quickstart.cloudera 。映射格式为「 IP 机器名」。如下图所示：
2.3 设置数据连接
1）选择数据连接配置面板的认证方式为「Kerberos 认证」，按要求填写客户端 principal 和 keytab 密钥路径，keytab 的名称根据实际情况修改。其他按 配置数据连接 中的说明进行数据连接。注意 URL 后需要添加客户端 principal 。数据连接信息示例如下所示：
| 选项 | 值 |
URL | jdbc:hive2://192.168.5.127:10000/default;principal=hive/quickstart.cloudera@QUICKSTART.CLOUDERA |
客户端 principal | hive/quickstart.cloudera@QUICKSTART.CLOUDERA |
keytab 密钥路径 | %FineBI%\webapps\webroot\WEB-INF\resources\hive.keytab |
如下图所示：
注：此处需确保 krb5.conf 和 XXX.keytab 放置在相同目录下。
2）点击测试连接，连接成功如下图所示：
3. 方法二：配置 JVM 参数后再进入数据连接配置界面
以 Apache Impala 为例。这里以本地部署下的 BI 为例，若为部署在 Tomcat 下的工程，则配置步骤一致，只需将地址修改为 Tomcat 下的对应地址即可。
3.1 复制配置文件
下载环境上的配置文件 krb5.conf 和 impala.keytab 放置到%FineBI%\webapps\webroot\WEB-INF\resources目录下。
注：当有多个 Kerberos 认证时，keytab 文件最好不要都放置在 reources 目录下，可能会导致认证冲突。此时可以在 resources 下新建各自的文件夹，放置对应的认证文件。
3.2 配置 krb5.ini 文件
准备 krb5.ini 文件，并将该 krb5.ini 文件放置到%FineBI%\webapps\webroot\WEB-INF\resources目录下，内容如下所示：
Client {
com.sun.security.auth.module.Krb5LoginModule required doNotPrompt = true
useKeyTab = true
keyTab = "%FineBI%\webapps\webroot\WEB-INF\resources\XXX.keytab"
principal = "dummy@SOME.REALM"
debug = true;
};
若使用的是 ibm 的 JDK ，在使用 websphere 容器部署工程时，krb5.ini 文件内容需要改为：
Client {
com.ibm.security.auth.module.Krb5LoginModule required
credsType=both
useKeytab="E:\\tomcat\\apache-tomcat-9.0.37\\webapps\\webroot\\WEB-INF\\resources\\impala\\impala.keytab"
principal="impala/quickstart.cloudera@QUICKSTART.CLOUDERA";
};
3.3 添加 JVM 参数
1）进入 FineBI 安装目录 %FineBI%\bin ，找到 finebi.vmoptions 文件，编辑该文件，增加下面 2 个 JVM 参数，如下所示：
-Djava.security.krb5.conf=%FineBI%\webapps\webroot\WEB-INF\resources\krb5.conf
-Djava.security.auth.login.config=%FineBI%\webapps\webroot\WEB-INF\resources\krb5.ini注：两个参数的值为 krb5.conf 和 krb5.ini 文件的绝对路径。
编辑完成的 finebi.vmoptions 文件示例如下：
-Djava.security.krb5.conf=%FineBI%\webapps\webroot\WEB-INF\resources\krb5.conf
-Djava.security.auth.login.config=%FineBI%\webapps\webroot\WEB-INF\resources\krb5.ini
-Xmx4018m
-Dfile.encoding=UTF-8
-Djava.io.tmpdir=.\temp注：此处若使用的不是单机版，而是 Spider 分布式引擎，则需要在该文件中再添加一个参数：-Dzookeeper.sasl.client=false，因为zookeeper 默认认证模式会受到 kerberos 配置的影响而导致 BI 无法启动。
-Dzookeeper.sasl.client=false
2）此时同样也需要配置远端的映射，与方法一一致，详见本文 2.1 章节第 2 小点。
3）选择数据连接配置面板的认证方式为「Kerberos 认证」，按要求填写客户端 principal 和 keytab 密钥路径，keytab 的名称根据实际情况修改。其他按 配置数据连接 中的说明进行数据连接。注意 URL 后面需要加上 AuthMech、KrbHostFQDN、KrbServiceName 三个参数，数据连接信息如下所示：
| 选项 | 值 | 含义 |
| URL | jdbc:impala://192.168.5.127:21050/default;AuthMech=1;KrbHostFQDN=quickstart.cloudera;KrbServiceName=impala | AuthMech=1 表示使用 kerberos 认证； KrbHostFQDN 为 impala server，为 krb5.conf 文件中 admin_server 的值； KrbServiceName为对应的服务名（请自行通过搜索引擎了解） |
| 客户端 principal | impala/quickstart.cloudera@QUICKSTART.CLOUDERA | |
| keytab 密钥路径 | %FineBI%\webapps\webroot\WEB-INF\resources\impala.keytab | 存放 impala.keytab 的路径 |
数据连接界面如下图所示：
4）点击测试连接成功即可。如下图所示：
注1：尽管 Apache Impala 和 Hive 本身驱动不冲突，但是目前不支持同时对 Apache Impala 和 Hive 做 Kerberos 认证，因为 Kerberos 驱动本身会涉及到全局参数，如果被 Apache Impala 使用，那么 Hive 就无法使用。
注2：在5.1.14之前的版本，若使用驱动隔离插件不支持 Kerberos 认证，5.1.14及之后的版本，驱动隔离插件支持 Kerberos 认证。
4. 注意事项
4.1 检查服务器及认证信息
| 检查内容 | 要求 |
| 检查 FineBI 服务器所在机器和数据库服务器的系统时间差 | 通常要求时间差小于 5 分钟 |
检查配置 FineBI 服务器所在机器的 hosts 文件 | 需确认能通过主机名/域名 ping 通数据库服务器 |
| FineBI 自带的 zookeeper 包与数据库服务端的 zookeeper 版本需要匹配 | 例如：华为 HD 平台连接可能会出现此类报错 |
| 检查 principal 名称是否正确 | principal 的格式通常为用户名/部门@公司，确认 principal 是否正确的方式是在数据库服务端 shell 执行klist 或者 kinit -k -t /path/to/keytab name_of_principal。或直接通过 beeline、impala-shell 等工具连接开启认证的服务，并查看对应的 principal 信息 例如：Hive 服务对应 principal 为 hive /bigdata@XXX.COM，而 Impala 服务对应的 principal为impala/bigdata@XXX.COM。 |
| 检查 FineBI 的工程路径 | 确保不带有空格（如 tomcat 9），因为 Kerberos 认证不支持带有空格路径。 |
4.2 无法连接处理方式
1）若连接失败，可与平台数据库管理员确认相关服务的安全认证配置是否正确，并联系帆软技术支持并提供相关报错日志（提添加 JVM 安全调试参数，如下所示），数据平台数据库版本、对应驱动 JAR 包、相关连接信息、Java 认证连接测试代码或者能连接认证数据库的 shell 工具等。
jvm 安全调试日志参数：
-Djava.security.debug=gssloginconfig,configfile,configparser,logincontext
-Djava.security.krb5.debug=true2）特殊情况下，如果 Windows 系统下无法连接，可以把 FineBI 测试服务器部署在 Linux 系统上。需保证该服务器能通过相关 shell 工具连上数据库，通过 klist 能看到已缓存的 kgt 信息。
4.3 报错
4.3.1 Unable to obtain Principal Name for authentication
问题描述：
cdh 连接抛错：Unable to obtain Principal Name for authentication
原因分析：
JDK 默认安装的 JCE 不能处理超过 128 位的对称密钥。
解决方案：
更新 JRE 的 JCE 扩展包。
JCE 安装详情参见：扩展包安装连接 。通常直接到第 4 步即可，下载解压得到 JCE 扩展 JAR 包，然后到 JRE 的指定目录替换文件即可。
4.3.2 GSS initiate failed
问题描述：
Transwarp Inceptor（星环）数据库报错 GSS initiate failed 。
排查步骤：
驱动本身做了静态全局的操作，kerberos 中心刷新后，驱动内部的静态全局还残留，故数据连接连不上。重启 BI 服务器查看是否依旧有该报错。若仍然有，采取下面的排查步骤：
（密码错误）keytab 文件与用户不匹配，可以在客户端服务器中kinit-k-t keytab用户进行检查。
本地服务器和远程服务器的（时钟偏移）时间不匹配，请检查ntp到远程服务器。
（aes256不支持）默认情况下aes256不支持jdk/jre，需要从/opt/huawei/Bigdata/jdk/jre/lib/security路径中的远程服务器复制local_policy.jar和US_export_policy.jar。
（无规则）主体格式默认不支持，需要添加属性hadoop.security.auth_to_local（在core site.xml中）值规则：[1:$1]规则：[2:$1]。
（超时）无法连接到kdc服务器或网络中存在防火墙。
4.3.3 报错：31300010 kdc服务器不连通
原因：连接超时
解决方法：改大超时时间
