单机搭建KDC与Kerberos认证HDFS实战指南

1. 为什么要在单机环境里折腾KDC和Kerberos认证的HDFS很多做大数据的同学第一次接触Kerberos认证的HDFS都是在公司已经搭好的集群上写业务代码。本地开发的时候要么连的是测试集群的匿名访问端口要么干脆用本地文件系统模拟等代码上了生产才发现各种认证问题集中爆发。我自己就经历过这种尴尬本地跑得好好的一个数据同步任务部署到线上直接报GSS initiate failed排查了大半天才意识到是本地开发环境根本没有Kerberos认证这一层。所以后来我养成了一个习惯凡是涉及安全认证的组件本地一定要搭一套带认证的最小环境。KDC单机加Kerberos认证的HDFS就是大数据开发里最值得本地搭的一套环境。它解决的核心问题是让你在本地就能完整走通申请票据、认证、访问HDFS这条链路而不是等到上线才第一次面对认证报错。这套环境适合几类人一是刚接触Hadoop安全体系、想搞明白Kerberos到底怎么和HDFS配合的开发者二是需要本地调试带认证的HDFS客户端代码的工程师三是想理解KDC、Principal、Keytab、Ticket这些概念之间关系的运维或平台同学。整套环境跑在一台机器上不需要多节点资源占用可控但认证流程和生产集群是一致的。需要提前说明的是Kerberos本身概念不少但单机环境的好处是你可以随意重置、随意折腾把每个概念都亲手验证一遍。下面我会从整体架构讲起然后一步步把KDC、HDFS、客户端认证全部搭起来中间穿插我踩过的坑和排查思路。2. 单机KDC加HDFS的整体架构与核心概念拆解2.1 三个角色各自负责什么在动手之前先把这套环境里的三个角色理清楚不然后面配置项一多就容易晕。KDCKey Distribution Center是整个认证体系的核心它本质上是一个发证机构。你可以把它类比成公司的门禁卡办理中心所有需要进出受控区域的人都要先到这里证明身份然后领一张临时通行证。KDC内部又分两个部分一个是ASAuthentication Server负责验证你是谁并发放TGTTicket Granting Ticket另一个是TGSTicket Granting Server负责根据TGT发放具体服务的票据。HDFS相关服务在这里扮演的是受控资源的角色。NameNode、DataNode这些服务在开启Kerberos之后不再接受匿名访问客户端必须出示有效的服务票据才能通信。服务端自己也需要向KDC证明身份这就是为什么每个服务都要有自己的Principal和Keytab。客户端就是我们要认证的身份。开发时通常用两种方式一种是先用kinit命令获取票据然后程序复用这个票据缓存另一种是程序直接加载keytab文件自动认证。两种方式适用场景不同后面会详细对比。2.2 Principal、Keytab、Ticket三者的关系这三个词是Kerberos里最容易混淆的我用一个生活化的类比说清楚。Principal就是身份标识格式通常是主名称/实例REALM比如hdfs/namenodeEXAMPLE.COM。它回答的是我是谁这个问题。注意Principal里的实例部分服务类Principal一般写主机名或服务角色用户类Principal通常省略实例。Keytab是Principal对应的密钥文件里面存的是从Principal密码派生出来的密钥。你可以把它理解成不用输密码就能证明身份的一把钥匙。服务端必须用keytab因为服务启动时不可能有人手动输密码客户端自动化场景也常用keytab。Ticket是KDC签发的临时凭证有有效期。TGT是总通行证用它去换各种服务票据服务票据是专项通行证只能访问对应的服务。票据默认有效期一般10小时左右过期要重新申请。三者关系可以这样理解Principal是身份Keytab是证明身份的工具Ticket是认证通过后拿到的临时凭证。客户端拿Keytab或密码向KDC证明自己是某个PrincipalKDC验证通过后发Ticket客户端拿Ticket去访问HDFS。2.3 单机环境的目录规划单机搭建最怕的就是文件到处乱放后面排查问题找不到东西。我建议提前规划好目录我自己的习惯是这样用途建议路径说明KDC数据库与配置/etc/krb5kdcKDC主配置和数据库文件KDC日志/var/log/krb5kdc排查KDC问题必看Keytab存放/etc/security/keytabs各服务keytab统一放这里krb5客户端配置/etc/krb5.conf全局客户端配置HDFS配置$HADOOP_HOME/etc/hadoopHadoop配置文件目录票据缓存/tmp/krb5cc_$(id -u)默认票据缓存位置目录规划好之后后面所有配置都往对应位置放出问题的时候按目录逐个检查效率会高很多。3. 从零搭建KDC配置项背后的逻辑3.1 安装KDC组件与初始配置不同系统包名略有差异以常见的包管理为例KDC服务端和客户端工具通常分属不同的包。服务端提供krb5kdc和kadmin两个守护进程客户端提供kinit、klist这些命令。安装完成后第一件事是配置/etc/krb5.conf这个文件既是客户端配置KDC本身也会读取。krb5.conf的核心是[libdefaults]和[realms]两段。default_realm指定默认领域我习惯用EXAMPLE.COM这种全大写形式因为Kerberos领域名约定俗成用大写。[realms]里要指定KDC和kadmin服务的主机与端口单机环境都指向本机。[libdefaults] default_realm EXAMPLE.COM dns_lookup_realm false dns_lookup_kdc false ticket_lifetime 24h renew_lifetime 7d forwardable true [realms] EXAMPLE.COM { kdc localhost admin_server localhost } [domain_realm] .example.com EXAMPLE.COM example.com EXAMPLE.COM这里有两个配置项值得说明。dns_lookup_realm和dns_lookup_kdc我建议都设为false因为单机环境没有配DNS的TXT记录开着反而会导致解析失败或变慢。forwardable true允许票据被转发某些需要代理访问的场景会用到本地开发开着无妨。3.2 初始化KDC数据库配置好krb5.conf之后需要初始化KDC的数据库。这一步会创建KDC的主密钥和数据库文件命令是kdb5_util create -s。-s表示同时生成stash文件stash文件里存的是主密钥这样KDC启动时就不用交互式输入密码了。执行这个命令时会要求输入KDC主密码这个密码很重要它是加密整个数据库的根密钥。本地环境可以设一个自己记得住的但要知道它的作用一旦忘记整个数据库基本就废了只能重建。初始化完成后/var/kerberos/krb5kdc或/etc/krb5kdc取决于系统下会出现principal等数据库文件。这时候KDC还没启动需要先配置kdc.conf指定数据库路径、端口、支持的加密类型等。加密类型这块有个坑老版本Hadoop对某些新加密算法支持不好如果遇到票据加密报错可以检查一下supported_enctypes配置必要时加上aes256-cts:normal aes128-cts:normal这类常见算法。3.3 启动KDC并创建管理员Principal配置完成后启动KDC服务。启动方式取决于系统可能是systemctl start krb5kdc也可能是直接运行krb5kdc命令。启动后建议看一眼日志确认没有报错。接下来要创建管理员Principal否则没法用kadmin管理数据库。命令是kadmin.local -q addprinc admin/admin。注意kadmin.local是本地管理工具不需要认证就能用适合初始化阶段而kadmin需要先用管理员身份kinit才能用。创建管理员之后可以顺便把kadmin的ACL配好让admin这个Principal有管理权限。ACL文件通常在/var/kerberos/krb5kdc/kadm5.acl加一行*/adminEXAMPLE.COM *表示所有admin实例的Principal都有全部权限。到这一步KDC就算搭好了。可以用kinit admin/admin测试一下能不能拿到TGT再用klist看看票据。如果这一步就报错后面HDFS肯定也跑不起来所以务必先确认KDC本身工作正常。4. HDFS服务端接入Kerberos的关键配置4.1 为HDFS各服务创建Principal和KeytabHDFS开启Kerberos后NameNode、DataNode、SecondaryNameNode等每个服务都需要自己的Principal。命名规范一般是服务名/主机名REALM单机环境主机名统一用localhost或本机hostname。创建Principal用kadminkadmin.local -q addprinc -randkey nn/localhostEXAMPLE.COM kadmin.local -q addprinc -randkey dn/localhostEXAMPLE.COM kadmin.local -q addprinc -randkey hdfs/localhostEXAMPLE.COM-randkey表示用随机密钥因为服务不需要人记密码只需要keytab。创建完Principal后导出keytabkadmin.local -q ktadd -k /etc/security/keytabs/nn.service.keytab nn/localhostEXAMPLE.COM这里有个细节keytab文件的权限必须严格控制一般设为600属主设为运行HDFS服务的用户。如果权限太开放Kerberos客户端可能会拒绝加载报keytab permission之类的错误。我踩过一次排查半天才发现是keytab权限不对。4.2 core-site.xml与hdfs-site.xml的认证相关配置Hadoop的Kerberos配置主要集中在core-site.xml和hdfs-site.xml。core-site.xml里最关键的是hadoop.security.authentication和hadoop.security.authorizationproperty namehadoop.security.authentication/name valuekerberos/value /property property namehadoop.security.authorization/name valuetrue/value /property第一个把认证方式从simple改成kerberos第二个开启服务级授权。这两个是总开关不开的话后面配了也白搭。hdfs-site.xml里要配置各服务对应的Principal和Keytabproperty namedfs.namenode.kerberos.principal/name valuenn/_HOSTEXAMPLE.COM/value /property property namedfs.namenode.keytab.file/name value/etc/security/keytabs/nn.service.keytab/value /property注意_HOST这个占位符Hadoop会自动替换成本机hostname。用_HOST的好处是配置可以跨机器复用但前提是Principal创建时用的主机名要和实际hostname一致。如果创建Principal时用了localhost而hostname解析出来是别的名字就会认证失败。这是新手最容易踩的坑之一。4.3 数据目录权限与安全模式开启Kerberos后HDFS的数据目录权限也要注意。NameNode启动时会检查目录属主如果目录属主和运行用户不一致可能启动失败。建议在格式化之前就把目录准备好属主设为运行HDFS的用户。另外开启安全认证后HDFS会进入安全模式直到完成相关初始化。如果启动后一直卡在安全模式可以看NameNode日志通常是某个Principal认证失败或者keytab加载不了。日志里会明确写出是哪个Principal、什么原因按图索骥基本都能解决。启动顺序也有讲究先确保KDC正常运行再启动NameNode最后启动DataNode。因为DataNode启动时要向NameNode注册而注册过程需要认证如果NameNode还没起来或者认证没配好DataNode会反复重试。5. 客户端认证的两种方式与实操对比5.1 kinit加票据缓存方式这是最直观的方式适合交互式开发和调试。流程是先用kinit获取TGT然后运行HDFS客户端命令或程序客户端会自动从票据缓存里读取票据。kinit -kt /etc/security/keytabs/hdfs.keytab hdfs/localhostEXAMPLE.COM klist hdfs dfs -ls /klist能看到当前票据缓存里的TGT和服务票据。第一次执行hdfs dfs -ls时客户端会拿TGT去向KDC申请NameNode的服务票据然后缓存起来后续访问同一服务就不用再申请了。这种方式的优点是简单直接缺点是票据有有效期过期后要重新kinit。开发时如果长时间调试可能会遇到票据过期导致突然报错这时候重新kinit一下就行。另外票据缓存默认在/tmp下机器重启或缓存被清理后也要重新kinit。5.2 Keytab自动认证方式如果程序需要长期运行或者无人值守用keytab自动认证更合适。Java代码里通过UserGroupInformation来加载keytabUserGroupInformation.setConfiguration(conf); UserGroupInformation.loginUserFromKeytab( hdfs/localhostEXAMPLE.COM, /etc/security/keytabs/hdfs.keytab ); FileSystem fs FileSystem.get(conf);这段代码的关键是loginUserFromKeytab它会用keytab向KDC认证并拿到TGT之后所有HDFS操作都用这个身份。注意setConfiguration要在login之前调用否则可能用的还是simple认证。两种方式的对比对比项kinit票据缓存keytab自动认证适用场景交互式开发调试长期运行、无人值守票据有效期受kinit参数限制可配置自动续期安全性票据在缓存中keytab文件需严格保护使用复杂度简单命令行即可需要代码集成过期处理手动重新kinit可自动续期我个人的经验是本地开发调试用kinit就够了方便随时切换身份写正式代码或者做自动化任务时用keytab避免票据过期导致任务中断。5.3 认证失败的常见报错与排查路径认证失败是这套环境里最常遇到的问题我把常见的几类报错和排查思路整理一下。Unable to obtain password from user通常是keytab路径不对、文件不存在或权限不足。先确认路径再看权限最后确认keytab里确实包含对应的Principal用klist -kt查看。Server not found in Kerberos database说明请求的Principal在KDC里不存在。检查Principal名称拼写特别是主机名部分是否和实际一致。Clock skew too great这是时间不同步导致的。Kerberos对时间敏感默认允许的偏差是5分钟。单机环境一般不会出现但如果虚拟机休眠过或者手动改过时间就可能触发。同步一下时间即可。GSS initiate failed这个报错比较笼统底层原因可能是上面任何一种。建议看完整堆栈通常会带出更具体的原因。排查的时候有个技巧先确认KDC本身正常kinit能不能成功再确认服务端Principal和keytab正确最后看客户端配置。按这个顺序逐层排查比一上来就盯着客户端代码有效得多。6. 踩坑实录那些让我折腾半天的细节6.1 主机名解析不一致导致的认证失败这个坑我踩过不止一次。问题表现是kinit能成功但访问HDFS时报Principal找不到。根因是Principal创建时用的主机名和客户端实际解析出来的主机名不一致。比如创建Principal时用了nn/localhost但/etc/hosts里localhost解析到的是127.0.0.1而Hadoop配置里_HOST替换出来可能是本机真实hostname。两个名字对不上KDC里自然找不到对应的Principal。解决办法是统一主机名。要么全部用localhost要么全部用真实hostname并且确保/etc/hosts里的解析和实际一致。我现在的习惯是搭建前先hostname看一下然后所有Principal和配置都用这个hostname避免歧义。6.2 keytab权限与属主问题前面提过keytab权限这里再展开说一下。Kerberos客户端在加载keytab时某些实现会检查文件权限如果权限过于开放比如644可能直接拒绝加载。更隐蔽的问题是属主如果keytab属主是root而HDFS服务以hdfs用户运行hdfs用户读不了这个文件也会失败。正确的做法是keytab属主设为运行服务的用户权限600。可以用chown hdfs:hadoop xxx.keytab和chmod 600 xxx.keytab设置。如果服务是以多个用户运行的要确保每个用户都能读到对应的keytab。6.3 票据缓存位置与多身份切换默认票据缓存是/tmp/krb5cc_$(id -u)按用户ID区分。但如果你在同一台机器上用不同身份调试可能会互相干扰。比如先用admin身份kinit再用hdfs身份kinit后一次会覆盖前一次的缓存。解决办法是用KRB5CCNAME环境变量指定不同的缓存文件export KRB5CCNAME/tmp/krb5cc_hdfs kinit -kt hdfs.keytab hdfs/localhostEXAMPLE.COM这样不同身份用不同缓存互不影响。调试多身份场景时这个技巧很实用。6.4 加密算法不匹配的隐蔽问题有些环境下KDC默认生成的keytab用了较新的加密算法而老版本Hadoop客户端不支持导致认证时报加密相关的错误。这种问题比较隐蔽因为报错信息不一定直接指向加密算法。排查方法是用klist -kt查看keytab里的加密类型对比Hadoop支持的加密类型。如果确实不匹配可以在创建Principal时指定加密类型比如addprinc -e aes128-cts:normal或者在krb5.conf里配置default_tgs_enctypes等参数限制算法范围。7. 环境验证与日常维护的实用建议7.1 一套完整的验证清单环境搭好后建议按这个清单逐项验证确保每个环节都正常KDC服务运行中kinit admin/admin能成功拿到TGT各服务Principal已创建klist -kt能看到keytab内容NameNode、DataNode进程正常启动日志无认证报错用kinit获取hdfs身份票据后hdfs dfs -ls /能正常列出目录用keytab方式写一段简单Java代码能成功读写HDFS故意让票据过期验证重新kinit后能恢复访问这六项都通过说明整套环境是健康的。任何一项失败按前面讲的排查路径定位。7.2 日常维护的几个习惯单机环境虽然简单但养成好习惯能省很多事。我自己的习惯有这么几条。第一改动配置前先备份。Kerberos相关配置项多改错一个可能整个环境起不来备份一下随时能回滚。第二票据过期是常态别慌。看到认证报错先klist看一眼票据状态过期了就重新kinit这是最常见也最容易解决的原因。第三keytab和Principal的对应关系要记清楚。建议维护一个简单的表格记录哪个服务用哪个Principal、keytab放在哪排查时一目了然。第四KDC日志和Hadoop日志要会看。KDC日志在/var/log/krb5kdcHadoop日志在$HADOOP_HOME/logs大部分认证问题在这两个地方都能找到线索。7.3 这套环境还能怎么扩展单机环境跑通之后如果想进一步深入有几个方向可以扩展。一是加入Hive或HBase的Kerberos认证理解不同组件接入Kerberos的差异二是配置票据自动续期模拟长期运行服务的场景三是研究跨域信任Cross-Realm理解多领域之间如何互信。这些都是在单机环境基础上可以继续折腾的方向每深入一层对Kerberos和Hadoop安全体系的理解就更扎实一分。我个人在实际操作中的体会是Kerberos这东西看文档觉得概念多、配置杂但真正动手搭一遍、把每个报错都排查过之后那些概念就自然串起来了。单机环境最大的价值就是给你一个可以随便折腾、随便重置的沙盒把认证链路完整走通比看十篇原理文章都管用。