Quick Start: Integrating eDirectory 8.8 SP8 & Kerberos with the NetIQ KPA (Kerberos Password Agent)

  • 7015607
  • 28-Aug-2014
  • 19-Sep-2014


SUSE Linux Enterprise Server 11 Service Pack 3 (SLES 11 SP3)
MIT Kerberos 5 Release 1.6.3
NetIQ eDirectory 8.8 SP8 (888)
NetIQ Modular Authentication Service (NMAS)
NetIQ iManager 2.7 SP7 (277)
NetIQ Kerberos Password Agent (KPA) 1.0


eDirectory has had the capability of integrating with Kerberos for some time.  However, keeping passwords in sync between the KDC server and eDirectory can be a challenge.  If a user's password is changed in eDirectory the KDC server would not be notified.  Therefore, the user's password also had to be changed on the KDC server resulting in increased administration.
This TID also provides the solution of updating the keystores for the following issues:
- The Kerberos plugin will not work.  Error -1.  Error -5875.
- The Radius plugin will not work.  SSL errors in iManager debug trace.
- KDB5_LDAP_UTIL: Can't contact LDAP server while initializing database.


The Kerberos Password Agent (KPA) provides the functionality that allows for an eDirectory NMAS Universal Password (UP) change to also be consumed by the KDC service so that the user's principals' keys can be updated on the KDC as well.  The KDC server must be configured to use eDirectory as its back-end rather than using its provided Berkeley database.  This Quick Start Guide is intended to provide a quick way to get this solution up and running from scratch in a lab environment.  This guide assumes the lab has no DNS SRV or TXT records being served (recommeded), therefore, this will be a non-DNS installation: only the hosts file will be used.
Important Notes:

UP must be enabled.
Extended characters in the password are not supported.
Password synchronization occurs one-way: from eDirectory to the KDC.
The key type selected during creation of the realm in the KDC and in eDirectory must match or the passwords cannot be unwrapped on the KDC side.

The following is an overview of the major steps involved.
- Install required Kerberos rpms
- Ensure resolves and NTP are taken care of
- Install and configure eDirectory, iManager and its plugins
- Populate the keystores read by the Kerberos plugin and the kdb5_ldap_util utility with the tree's Trusted Root
- Install the Kerberos LDAP extensions and extend schema for eDirectory
- Configure the KDC krb5.conf file
- Create the realm in the KDC and eDirectory
- Create the realm service objects, add their ACLs and stash their passwords
- Set the realm master key in eDirectory
- Start the krb5kdc and kadmind daemons
- Enable UP on the realm in eDirectory
- Create and\or verify that a NMAS UP policy is in place
- Create a user in eDirectory then on the KDC create for him both a merged and a linked standalone principal
- "Kerberize" that user object in eDirectory by modifing his krbPrincipalReferences attribute to point to his standalone principal object.
- Install the KPA and verify password changes are synchronizing from NMAS to the KDC service.

Realm:  SAMPLE
DNS:  hv5.lab.novell.com
Backend:  LDAP
LDAP Server URL:  ldaps://
Kerberos Container:  cn=Kerberos,cn=Security
KDC bind DN:  cn=kb-kdc,o=emg
Kadmin bind DN:  cn=krb-admin,o=emg
Server: 888_Kerb_Svr.emg
Kerberos container:      Kerberos.Security.HV_KRB_TREE
Realm container:           SAMPLE.Kerberos.Security.HV_KRB_TREE
Principal Container:      emg.HV_KRB_TREE
Realm Sub Tree:          emg.HV_KRB_TREE
Subtree Scope:            Subtree
Users Container:          krbusers.emg.HV_KRB_TREE


1. Install SLES 11 SP3 + Kerberos
A. Install a minimal SLES11 instance (also de-selecting the Print Server and App Armor selections).
B. Install the three required Kerberos packages
- krb5-server
- krb5-client
- krb5-plugin-kdb-ldap
2. Setup the hosts file
----------------------------       localhost
# special IPv6 addresses
::1                        localhost ipv6-localhost ipv6-loopback
fe00::0                 ipv6-localnet
ff00::0                  ipv6-mcastprefix
ff02::1                  ipv6-allnodes
ff02::2                  ipv6-allrouters
ff02::3                  ipv6-allhosts  hv5.lab.novell.com
#Manual Entries - last four are optional for this excercise SAMPLE hv5.SAMPLE hv5 kerberos.SAMPLE kerberos _kerberos._udp.SAMPLE _kerberos._tcp.SAMPLE _kerberos-adm._tcp.SAMPLE
3. Setup DNS resolves in /etc/resolv.conf
  A. Ensure this server's address is first in the list of name servers.
search SAMPLE
nameserver x.x.x.x
nameserver x.x.x.x

B. Verify that the /etc/nsswitch file's hosts: section has files before dns
# group:  files nis
passwd: compat
group:  compat
hosts:          files dns
networks:       files dns
services:       files
protocols:      files
rpc:            files
ethers:         files
netmasks:       files
netgroup:       files nis
publickey:      files
4. Setup NTP to get time from a trusted source.  Kerberos is very dependandant on a reliable time source.
Ensure that the source is configured for the correct address in the file and that the fallback hardware clock sections have been commented out.
server mode 5 prefer
## Undisciplined Local Clock. This is a fake driver intended for backup
## and when no outside source of synchronized time is available.
#server             # local clock (LCL)
#fudge stratum 10  # LCL is unsynchronized
5. Install eDirectory 8.8 SP8 and iManager 2.7 SP7 as well as their latest patches.  The latest eDirectory, NMAS and Kerberos plugins will also need to be installed.  At the time of this writing they were:
- eDirectory88 Plugins 2.7.20140406
- NetIQ Kerberos Plugin 2.7.20140406
- NMAS Plug-ins for iManager 8.880.20130826
- Novell iManager Password Management 10.7.20120601

6. Enable iManager to perform non-TLS binds then refresh the LDAP server.  This can be reenabled after all steps have been completed.
  A. iManager - LDAP - LDAP Options - Group - Information - uncheck to require TLS for simple binds.
  B. iManager - LDAP - LDAP Options - Server - Information - Refresh.
7.  Populate KeyStores (iMgr\Tomcat & kdb5_ldap_util \OpenLDAP)
In order for the Kerberos plugin to work the following steps will need to be performed so that the tree Root CA's certificate is trusted by placing it in the appropriate keystores.
A. iManager Keystore
  The Kerberos plugin does not use the default iManager keystore but "system's".
    1. Copy the Root CA's exported certificate to the iManager 'system' keystore and use the password 'changeit' when prompted.
/opt/novell/jdk1.7.0_25/bin/keytool -import -alias "krb" -file /root/hvaughan/cert.der -keystore
    2. Restart Tomcat
/etc/init.d/novell-tomcat7 restart
B.  OpenLDAP client
  The kdb5_ldap_util utility uses the openLDAP client configuration files (ldap.conf, .ldaprc).  Once the OpenLDAP client is aware of the trust the kdb5_ldap_util utility will also share that trust.
     1. Copy the tree Root CA certificate (example: cp /var/opt/novell/eDirectory/data/SSCert.pem /etc/ssl/certs)
      2. Run c_rehash
      3. Edit ldap.conf (On SLES, the file is under /etc/openldap/) to specify the trusted CA certificate:
    TLS_CACERTDIR /etc/ssl/certs
     4. Verify the openLDAP client works with this configuration by performing a secure ldapsearch on eDir, over LDAPS. 
/usr/bin/ldapsearch -x -H ldaps://hv5.lab.novell.com:636 -D cn=admin,o=emg cn 
If this fails due to a problem with the reverse address just use the server's ip address instead of the DNS name above.
8. LDAP Extensions
The Kerberos LDAP extensions must be in place for the Kerberos iManager plugin to work.  The GSSAPI method is not required for the KPA to function.
   A. Unzip the nmasmethods_8881.zip file within the 8882 patch
   B. Navigate to the extracted directory: NmasMethods/Novell/GSSAPI/64bit/GSSAPI/Kerberos_ldap_extensions/Linux
   C. Run the following command: ./krbLdapConfig -i -D cn=admin,o=emg -w novell -h -p 389
9. Extend Schema
Now that the plugin should be working, extend schema using the Kerberos plugin.
iManager - Kerberos Management - Extend Schema
10. Customize the /etc/krb5.conf file for the environment
        default_realm = SAMPLE
        SAMPLE = {
                kdc = hv5.lab.novell.com
                admin_server = hv5.lab.novell.com
                database_module = ldapconf
                key_stash_file = /var/lib/kerberos/krb5kdc/masterpwstash
                master_key_type = "aes256-cts-hmac-sha1-96"
        ldapconf = {
                db_library = kldap
                ldap_kerberos_container_dn = "cn=Kerberos,cn=Security"
                # this object needs to have read rights on
                # the realm container, principal container and realm sub-trees
                ldap_kdc_dn = "cn=krb-kdc,o=emg"
                # this object needs to have read and write rights on
                # the realm container, principal container and realm sub-trees
                ldap_kadmind_dn = "cn=krb-admin,o=emg"
                ldap_service_password_file = /var/lib/kerberos/krb5kdc/service.keyfile
                ldap_servers = ldaps://
                ldap_conns_per_server = 5
        lab.novell.com = SAMPLE
        .lab.novell.com = SAMPLE
    kdc = FILE:/var/log/krb5/krb5kdc.log
    admin_server = FILE:/var/log/krb5/kadmind.log

11. Copy the trusted root
cp /var/opt/novell/eDirectory/data/SSCert.der /opt/novell/kerberos/Trustedroot.der
12. Create the Realm in eDirectory from the KDC.
NOTE: The master password and master key type on the filesystem used by KDC must match that of the master key being created for the realm in iManager during a later step.  When configuring a realm using kdb5_ldap_util, by default, DES3-CBC-SHA1 is used as the key type of the master key.  The iManager plugin supports DES3, AES128 and AES256.  The recommended key type of aes256-cts-hmac-sha1-96 will be choosen for each.  Therefore, this key type is placed in the krb5.conf file as the default key type and is also specified on the command line during realm creation. 
NOTE: If the keys are mismatched the following error will be seen in the KDC log when attempting to get a ticket via kinit:
- krb5kdc: Cannot find/read stored master key - while fetching master key
Run the command to create the realm on the KDC as well as in eDirectory. 
kdb5_ldap_util -D cn=admin,o=emg -w novell -H ldaps:// create -k aes256-cts-hmac-sha1-96 -subtrees o=emg -sscope sub -containerref o=emg -r SAMPLE -P novell -sf /var/lib/kerberos/krb5kdc/masterpwstash
If the kdb5_ldap utility cannot be found on the file system the krb5-plugin-kdb-ldap plug-in was not installed in the first step, otherwise, success of the command returns:
Initializing database for realm 'SAMPLE'
Kerberos container is missing. Creating now...
13. Create the Service Objects in eDirectory and add their ACLs.  Also the Security container must have its krbContainerReference attribute point to the Kerberos realm container (Kerberos.Security).
This is best done from a LDIF script.
  1. ldapmodify -x -h -D "cn=admin,o=emg" -w novell -f /root/hv5/krb_services.ldif
Sample krb_services.ldif:
acl: 48#subtree#cn=krb-admin,o=emg#[Entry Rights]
acl: 48#subtree#cn=krb-admin,o=emg#[All Attributes Rights]
acl: 33#subtree#cn=krb-kdc,o=emg#[Entry Rights]
acl: 3#subtree#cn=krb-kdc,o=emg#[All Attributes Rights]
acl: 48#subtree#cn=krb-admin,o=emg#[Entry Rights]
acl: 48#subtree#cn=krb-admin,o=emg#[All Attributes Rights]
acl: 33#subtree#cn=krb-kdc,o=emg#[Entry Rights]
acl: 3#subtree#cn=krb-kdc,o=emg#[All Attributes Rights]
14. Stash the passwords of the service objects in a stash file on the KDC.
kdb5_ldap_util -D cn=admin,o=emg -w novell -H ldaps:// stashsrvpw -f /var/lib/kerberos/krb5kdc/service.keyfile cn=krb-kdc,o=emg
kdb5_ldap_util -D cn=admin,o=emg -w novell -H ldaps:// stashsrvpw -f /var/lib/kerberos/krb5kdc/service.keyfile cn=krb-admin,o=emg 
15. Ensure that krbContainerReference attribute on the Security container points to the Kerberos.Security container.  iMonitor makes this easy.
16. Set the realm master key in eDirectory using iManager -> Kerberos Management -> Set Master Key.
Realm name: SAMPLE.Kerberos.Security.  
Key Type: AES256-CTS-HMAC-SHA1-96
NOTE: As noted earlier, the master key on the filesystem used by KDC must match that of the master key being created in iManager.  Both master passwords must also match.  All passwords used in this lab are set to: novell.
17.  Fire up the KDC daemons.
- /etc/init.d/krb5kdc start
- /etc/init.d/kadmind start
B. Run chkconfig against the daemons so they will start when NDSD starts.
- chkconfig krb5kdc on -level 235
- chkconfig kadmind on -level 235
- chkconfig krb5kdc --list
- chkconfig kadmind --list

18. Using the Kerberos plugin's "Edit Realm" task, enable UP for the realm
iManager - Kerberos Management - Edit Realm - SAMPLE.Kerberos.Security - place a check in the check box for Use Universal Password
NOTE: Many of other fields that are displayed in the plugin are not applicable to using the KPA and eDir as a back-end to KDC so they are ignored.
19. Ensure a UP password policy is in place and assigned to the user.
- Verify that the "Synchronize Distribution Password while setting Universal Password" option is enabled in the password policy.
- Verify the policy either does not have the advanced rules enabled or does not allow extended characters by deselecting the options "Allow non-alphanumeric characters" and "Allow non-US ASCII characters".
20.  Create a user's principals on the KDC and associate them to the user object in eDirectory.
 A. Create the user container: krbusers.emg.HV_KRB_TREE in iManager.
 B. Create a user: user1.krbusers.emg.HV_KRB_TREE in iManager.
 C. Create the user's principals on the KDC service.
    1. kadmin.local -q 'ank -x dn=cn=user1,ou=krbusers,o=emg princ1'
    This creates a merged principal - the user object will contain the kerberos principal held in it's krbPrincipalName attribute.
    2. kadmin.local -q 'ank -x linkdn=cn=user1,ou=krbusers,o=emg princ2'
    This creates a linked standalone principal that will point to the user object.

Note: For KPA to work for these principals, the user object must be "Kerberized" meaning its attribute, krbPrincipalReferences, points to the principal object DN (princ2@SAMPLE.emg).  In order to add this attribute the user object will be extended with the krbPrincRefAux auxiliary class.  Below are the steps to perform this action.
 D. Add the krbPrincRefAux aux class and populate the krbPrincipalReferences attribute on the user object
   1. iManager - Schema - Object Extensions - user1.krbusers.emg - Add - krbPrincRefAux

  2. iManager - Directory Administration - Modify Object - user1.krbusers.emg - Other tab - Select krbPrincipalReferences - Click on left arrow - use the object selector and select the standalone principal object created earlier: princ2@SAMPLE.emg
21. Install and load the KPA
rpm --install novell-kerberos-password-agent-1.0-1.x86_64.rpm
/opt/novell/kerberos/sbin/kpa -l
By default, this service does not autorun.  It is recommended that it be placed with those in the nds-modules.conf file so it will start along with eDirectory. 

22. Verify KPA is synchronizing the password changes.
 A. Change the user's UP password in iManager
 iManager - Passwords - Set Universal Password - user1.krbusers.emg
 B. Check if the Agent has synchronized to the password of the associated principal.  Load ndstrace, enable the MISC tag and look at the KPA trace messages.  A successful operation will output traces similar to these:
KPA: Universal Password has been set or modified
KPA: FDN of the object in Dot Form: .CN=user1.OU=krbusers.O=emg.T=HV_KRB_KPA_TREE.
KPA: Change in Universal Password detected for user: "\T=HV_KRB_KPA_TREE\O=emg\OU=krbusers\CN=user1"
KPA: Realm container is CN=Security\CN=Kerberos
KPA: Resolving to realm CN=Security\CN=Kerberos\cn=SAMPLE
KPA: Realm SAMPLE is Universal Password enabled
KPA: Reading master key of realm SAMPLE succeeded
KPA: Successfully modified the password of principal princ1@SAMPLE
KPA: Successfully modified the password of principal princ2@SAMPLE
KPA: Principals of user \T=HV_KRB_KPA_TREE\O=emg\OU=krbusers\CN=user1 successfully updated with Universal Password
( Sending operation result 0:"":"" to connection 0xd567c00
23. Verify that the KPA synchronized user1's changed password to the KDC by updating his associated principals.  Use the new password to get a ticket for that user.  In this excercise novell2 was used.
Principle 1 
- kinit princ1@SAMPLE
Password for princ1@SAMPLE:
- klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: princ1@SAMPLE
Valid starting     Expires            Service principal
09/08/14 14:46:07  09/09/14 14:46:07  krbtgt/SAMPLE@SAMPLE
Kerberos 4 ticket cache: /tmp/tkt0
klist: You have no tickets cached
Principal 2
- kinit princ2@SAMPLE
Password for princ2@SAMPLE:
- klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: princ2@SAMPLE
Valid starting     Expires            Service principal
09/08/14 14:47:34  09/09/14 14:47:34  krbtgt/SAMPLE@SAMPLE
Kerberos 4 ticket cache: /tmp/tkt0
klist: You have no tickets cached


KPA documentation in the eDirectory 8.8 SP8 Administration Guide:  https://www.netiq.com/documentation/edir88/edir88/data/bs3o4p9.html