How To
Summary
This document will give instructions on how to set up AIX as a KRB5LDAP client, including SSL setup for LDAP. By skipping the KRB5 portion of this document, this will be valid for setting up AIX as a plain LDAP client, as well.
Steps
LDAP client configuration
Things you must know to start:
1) Bind DN: this will be the service account that AIX uses to bind to the LDAP server
2) Password for the Bind DN
3) Base DN: this is where users and groups are located. For example, if you have users and groups like:
2) Password for the Bind DN
3) Base DN: this is where users and groups are located. For example, if you have users and groups like:
CN=User1,OU=Users,DC=domain,DC=com
and
CN=Group1,OU=Groups,DC=domain,DC=com
...then the base DN is 'DC=domain,DC=com', since it is the common starting point to find users and groups.
4) If you will be setting up SSL communication, you'll need an appropriate certificate generated from the LDAP server side and exported to a file which might be in PEM, DER, or CRT format.
Preparation needed on LDAP server side:
1) Users must have Unix attributes set - user name, user ID number, primary group ID number, home directory, and login shell.
This is typically going to need to be manually set for each user if using a Windows AD server - set uid (username), uidnumber, gidnumber (primary group ID), unixhomedirectory, and loginshell.
2) Groups must have Unix attributes set as well. The group name should be defined in the 'cn' attribute, and the group ID number should be defined in 'gidnumber'. The group's member list might be in an attribute called 'member', 'memberuid', or other variations depending on the OS of the LDAP server. You must have a group defined that has a group ID number that matches the 'gidnumber' / primary group ID number of each of your users. Authentication will be impossible if the users don't have a valid primary group.
3) An SSL certificate must be generated for use on the AIX client if you will be setting up SSL communication.
Preparation needed on the AIX client side:
1) Obtain the latest idsldap and IBM Global Security Kit (GSKit) packages from the most recent AIX media. The idsldap filesets should be on AIX base media, and the IBM GSKit filesets should be on the AIX Expansion Pack.
You can also find the filesets at Fix Central:
At Fix Central, choose:
Product Selector: IBM Security Verify Directory
Installed Version: Choose the latest offered
Platform: AIX
Choose Browse for fixes, and then select the the 'standard' version of the software.
The Java package that is offered is not needed; download only the 'isvd-<version>*' package that is offered.
This will contain both the idsldap and GSKit filesets.
2) Install the packages according to the instructions here:
Some notes I'll add to those instructions:
2a) The instructions (at the time of this writing) mention the path /opt/IBM/ldap/V6.4/bin. Since you will be installing the most recent filesets, the V6.4 portion will need to be changed to V10.0, V10.0.1, V10.0.2, etc depending on what you've actually installed.
2b) The 'slibclean' and 'start-secldapclntd' should not be performed if this is your first time configuring the client.
2c) If you are planning on implementing SSL communication, be sure to install the idsldap 'max_crypto' filesets in addition to IBM GSKit, as mentioned in that link.
3) If you are not configuring SSL communication, you can skip to step 4. If you are, then you must create a key database file and import your SSL certificate.
3a) Create the key database file:
/usr/opt/ibm/gsk8_64/bin/gsk8capicmd_64 -keydb -create -db /etc/security/ldap/client.kdb -pw secret
That assumes you want to call the database '/etc/security/ldap/client.kdb' and have the password be 'secret' - choose whatever you like for your own purposes, but I'll use those in my examples.
3b) Next, you need to import the SSL certificate into this key database. For this example, I am assuming the certificate is provided in a binary/DER-encoded file called /tmp/server.der:
/usr/opt/ibm/gsk8_64/bin/gsk8capicmd_64 -cert -add -db /etc/security/ldap/client.kdb -pw secret -file /tmp/server.der
3c) Once you've done that, you can run this command to verify that the certificate was successfully added to the key database:
/usr/opt/ibm/gsk8_64/bin/gsk8capicmd_64 -cert -list -db /etc/security/ldap/client.kdb -pw secret
3d) If you need to see details on the certificate, get the label of the cert from the command previous, and run:
/usr/opt/ibm/gsk8_64/bin/gsk8capicmd_64 -cert -details -label <label of cert> -db /etc/security/ldap/client.kdb -pw secret
3e) You can validate any certificate you have added to ensure you aren't missing any part of the certificate chain:
gsk8capicmd_64 -cert -validate -db /etc/security/ldap/client.kdb -pw <password> -label "<cert label>"
4) Run the mksecldap command to configure the LDAP client. This will fail if you do not have the correct base DN, or users do not have Unix attributes defined. It makes its best attempt to figure out and set your userbasedn and groupbasedn - it may not get it perfect, so it might be necessary to make manual modifications to the ldap.cfg file afterwards.
If you are not using SSL, run:
mksecldap -c -h <server name> -a <bind DN> -p <bind dn pwd> -d <base dn> -A ldap_auth
If you are using SSL, run:
mksecldap -c -h <server name> -a <bind DN> -p <bind dn pwd> -d <base dn> -A ldap_auth -k <path to kdb file> -w <pwd for kdb file> -j SSL
Note #1: do not use the '-j TLS' setting unless you know you specifically want to use StartTLS. The '-j SSL' setting is the standard choice that will allow use of the entire SSL/TLS protocol list - up to TLS1.2 at the time of this writing.
Note #2: in general, SSL is recommended to encrypt traffic. The main reason is that ldap_auth authentication passes a cleartext password to the LDAP server - if SSL is not in use, this could expose the password to anyone examining network packets. SSL encryption will prevent this. If you later integrate KRB5 in with LDAP, KRB5 will handle authentication and encrypt this authentication-related traffic itself, but SSL encryption would still be recommended so that other LDAP traffic (user / group queries) are encrypted, as well. Furthermore, some LDAP servers such as Windows AD will reject user modifications (password changes or changes to attributes) if SSL is not in use.
Note #3: if you are using SSL but would prefer to not have to keep track of your SSL key database file's password, you can create a stash file for it. Please see instructions related to that at the bottom of this link:
When using a stash file, the '-w <pwd for kdb file>' option can be left out of the mksecldap command line.
5) Set LDAP as a default authentication method:
chsec -f /etc/security/user -s default -a "SYSTEM=compat or LDAP"
6) Verify LDAP users and groups are found. Run:
lsuser -R LDAP ALL
lsgroup -R LDAP ALL
lsldap -a passwd
lsldap -a group
The lsuser/lsgroup commands should list all LDAP-defined users and groups with their AIX attributes, as long as they have essential attributes defined such as uidnumber and gidnumber.
The lsldap commands will also list LDAP-defined user and groups, but will list their attributes exactly as defined on the LDAP server.
7) attempt login as an LDAP user. Use the password that is defined for this user on the LDAP server.
8) If things are not working as you expect - for example, users or groups are not found - you may need to make some modifications. The mksecldap command makes a best guess at figuring out your configuration, including setting the userbasedn and groupbasedn. These are the base DN's at which it will start searching the LDAP server for users or groups. You may find you need to add additional user or group base DN's if you have users and groups defined in more than one location on the server.
The attribute map files also need to be considered. mksecldap will set userattrmappath and groupattrmappath according to what it thinks your server's schema is. Take a look at these files and you can see how it maps AIX attributes to their corresponding LDAP attributes.
If you are using Windows AD as your LDAP server, for example, your userattrmappath should be set to /etc/security/ldap/sfur2user.map. Depending on your needs, you may need to modify this file - a common modification when using Windows AD is to change the lastupdate AIX attribute to point to the AD LDAP attribute called pwdLastSet, which stores the time that the user's password was last modified:
#lastupdate SEC_INT shadowLastChange s days yes
lastupdate SEC_INT pwdLastSet s UTC yes
In the same file, to allow users to change their Windows AD passwords, a common modification will be:
#spassword SEC_CHAR userPassword s na yes
spassword SEC_CHAR unicodePwd s na yes
Likewise, the groupattrmappath for Windows AD should be set to /etc/security/ldap/sfur2group.map. You may need to change the mapping for the group member list to either the LDAP attribute member or memberUid, based on what your server is using:
#users SEC_LIST memberUid m na yes
users SEC_LIST member m na yes
Similar changes may need to be made for other attributes depending on what your LDAP server's schema requires.
You may also need to check/modify the userclasses/groupclasses shown in ldap.cfg. For example:
userclasses:user,person,organizationalperson
groupclasses:group
This assumes that all users will have object class 'user' and groups will have object class 'group'. Modify that if the users or groups have a different object class.
A note on this - despite the example above showing a list for userclasses, only the first item in the list is used. So, in effect, only one class type is allowed for users or groups, and it must be first. The ability to incorporate multiple class types was never added into secldapclntd.
KRB5 client configuration
Things you must know to start:
The Kerberos KDC hostname
The realm of your Kerberos KDC server
The realm of your Kerberos KDC server
Steps:
1) Download the IBM Network Authentication Service (NAS) KRB5 packages here:
Download the latest version, which is 1.16.1.6 at the time of this writing. Install the krb5.client.rte and krb5.lic packages.
2) Configure the system as a Kerberos client:
mkkrb5clnt -c <KDC hostname> -s <admin server hostname> -r <REALM> -d <domain of KDC>
Note - be sure to give the realm in all uppercase - for example: -r REALM.DOMAIN.COM
The admin server is likely to be the same as the KDC, but not necessarily.
Although mkkrb5clnt provides flags such as -i to configure integrated login, I am leaving that out so that you can better understand the steps that go into configuring this.
Since mkkrb5clnt is a wrapper to config.krb5 (which does most of the work), and we're not using any other flags for mkkrb5clnt, this command will be equivalent to the command shown above:
config.krb5 -C -c <KDC hostname> -s <admin server hostname> -r <REALM> -d <domain of KDC>
If multiple realms or KDCs need to be added into your configuration, modify the /etc/krb5/krb5.conf file manually to add them.
3) modify the /etc/methods.cfg file to add a KRB5 stanza:
If using a KDC that is running IBM NAS software, the KRB5 stanza should be:
KRB5:
program = /usr/lib/security/KRB5
program_64 = /usr/lib/security/KRB5_64
options = authonly,kadmind=no
Regarding the 'kadmind=no' option - if not set, it defaults to 'yes'. I recommend starting with this set to no; see the corresponding section titled 'kadmind Lookups' further below if you want to turn this on.
If the KDC is running different software (Windows AD, IPA, etc) use this KRB5 stanza - the 'is_kadmind_compat=no' option is used to take it down a non-IBM NAS code path:
KRB5:
program = /usr/lib/security/KRB5
program_64 = /usr/lib/security/KRB5_64
options = authonly,is_kadmind_compat=no,tgt_verify=no
Regarding the 'tgt_verify=no' option - see the corresponding section at the bottom of this technote titled 'TGT Verification' if you would like to turn this option on, but I recommend you start with it turned off. The tgt_verify option is only needed when using the non-NAS 'is_kadmind_compat=no' option. Likewise, there is no need to set 'kadmind=no' since that is only for the NAS code path.
4) verify that kinit works. Run:
/usr/krb5/bin/kinit <username>
If no error is given, that means success - run this to verify ticket details:
/usr/krb5/bin/klist
Note - if you'd like to not have to give full pathname to these krb5 commands, add /usr/krb5/bin to your PATH definition, ensuring that it is located before any Java-related paths.
Integrate KRB5 and LDAP together
1) Add the following stanza to methods.cfg:
KRB5LDAP:
options = db=LDAP,auth=KRB5
2) Change the default authentication method to use KRB5LDAP :
chsec -f /etc/security/user -s default -a "SYSTEM=compat or KRB5LDAP"
3) Attempt login using the password defined for this user on the Kerberos KDC. If login succeeds, run the following to verify a Kerberos ticket was granted:
/usr/krb5/bin/klist
4) If your users have AIX user names that are different than their KDC principal name, you can use the 'auth_name' attribute to specify their KDC principal name. Similarly, if the user belongs to a KDC realm that is not the default_realm in krb5.conf, you can use the 'auth_domain' attribute to specify the correct realm for this user. Since we are working with LDAP users, the best option is to add a mapping to your attribute map file (userattrmappath in ldap.cfg) and ensure auth_name and auth_domain are mapped to valid attributes in your LDAP servers's schema. You can also add stanzas for LDAP users in the local /etc/security/user file if you need to do that to specify these attributes.
TGT Verification
TGT verification adds an extra layer of security; as a user is logging in to the AIX client and authenticating through Kerberos, the AIX client must present a host principal to the KDC in order to prove its identity. TGT verification is only possible when using the non-NAS "is_kadmind_compat=no" option.
To use TGT verification, you must first create host principal for your AIX client. If your client is aixclient.austin.ibm.com and the realm is AUSTINLABS, for example, this host principal would be in the form:
host/aixclient.austin.ibm.com@AUSTINLABS
To maintain convention and prevent possible problems, make sure the hostname and domain are in all lower case, and the Kerberos realm in upper case.
To create a host principal and keytab file on Windows AD:
It will be best to consult with AD documentation in case anything has changed, but the instructions below work as of this writing.
1) Create a 'user' object that you will map the host principal to. This object can have any name, but for my example I will use the same name as the hostname of my AIX client - 'aixclient'. Assign it a random password; this password is not necessary to be remembered.
2) Create a keytab with the ktpass command, and during this step, map 'host/aixclient.austin.ibm.com' to the user object you created in step 1:
ktpass -princ host/aixclient.austin.ibm.com@AUSTINLABS -mapuser aixclient +rndpass -ptype KRB5_NT_PRINCIPAL -crypto All -out aixclient.keytab
To create a host principal for any other type of KDC that you may be using, please consult its documentation.
PLEASE NOTE: any time a principal is exported to a keytab, its associated kvno (key version number) will be incremented. This has the effect of invalidating any keytabs that had been created previously and have a lower kvno. For example, let's say you have exported the host principal to a keytab on your KDC, imported it on your AIX client, and TGT verification is working. If you then go back to the KDC and export the principal to keytab again, the keytab you previously imported to AIX will no longer work - you'll have to get this newest version of the keytab imported again to the AIX client.
Import the keytab on your AIX client:
To import this keytab on your AIX client, first copy the aixclient.keytab file to your AIX client. Then, use the ktutil command to import it into your default keytab file, which will typically be /etc/krb5/krb5.keytab:
# /usr/krb5/sbin/ktutil
ktutil: rkt /tmp/aixclient.keytab
ktutil: wkt /etc/krb5/krb5.keytab
ktutil: quit
Check to make sure the keytab works by using kinit on it:
/usr/krb5/bin/kinit -kt /etc/krb5/krb5.keytab host/aixclient.austin.ibm.com@AUSTINLABS
If it does not display any errors, running /usr/krb5/bin/klist should shows the credential has been stored in the ticket cache file. You can then use /usr/krb5/bin/kdestroy to empty the ticket cache file.
At this point, if kinit showed no errors, you can change 'tgt_verify=no' to 'tgt_verify=yes' in the KRB5 stanza of /etc/methods.cfg and attempt login.
If login fails, switch it back to 'no', and check:
1) Does /etc/krb5.conf exist as a soft link to /etc/krb5/krb5.conf? This will be necessary for IBM NAS krb5 filesets 1.16 and higher
2) Does the AIX client system's IP address resolve to the hostname/domain combination you used for the host principal?
3) In your keytab file, is hostname/domain in lower case and realm in upper case?
4) Verify that kinit still works without error for your keytab / host principal
2) Does the AIX client system's IP address resolve to the hostname/domain combination you used for the host principal?
3) In your keytab file, is hostname/domain in lower case and realm in upper case?
4) Verify that kinit still works without error for your keytab / host principal
kadmind Lookups
kadmind lookups are only possible when using the NAS code path for an IBM NAS server; this option defaults to 'yes' when using an IBM NAS server, so it must be explicitly turned off if you don't want it. It is not necessary to explicitly turn this off if you have the 'is_kadmind_compat=no' option in your KRB5 stanza, since that is the non-NAS code path.
kadmind lookups require a host principal and keytab in the same way that TGT verification needs it, but since this only happens when using an IBM NAS Kerberos KDC, the instructions for creating the principal are specific to the IBM NAS product.
To create a host principal and keytab file when using an AIX NAS Kerberos KDC:
1) Start up the kadmin utility:
/usr/krb5/sbin/kadmin -p admin/admin
This can be run on either the NAS server or the NAS client. The admin principal is typically called 'admin/admin'; if there is a different admin principal in your environment, adjust command line options accordingly.
2) At the kadmin prompt, use addprinc to create the host principal:
addprinc -randkey host/aixclient.austin.ibm.com@AUSTINLABS
3) At the kadmin prompt, use ktadd to export this host principal to a keytab file:
ktadd -k /tmp/aixclient.keytab host/aixclient.austin.ibm.com@AUSTINLABS
As noted in the TGT verification section above, any time a keytab is exported, the kvno increases. This has the effect of invalidating any previously-generated keytab for this principal.
4) Use 'quit' to exit the kadmin utility
5) Use the instructions regarding 'Import the keytab on your AIX client' in the TGT verification section above in order to import this keytab into your default keytab file
6) Create a link, using the hostname and domain of your AIX client (aixclient.austin.ibm.com in this example):
ln -s /etc/krb5/krb5.keytab /var/krb5/security/keytab/aixclient.austin.ibm.com.keytab
7) Now you can set the 'kadmind=yes' option in the KRB5 stanza of methods.cfg
If any problems arise, please contact IBM support.
Related Information
Document Location
Worldwide
[{"Type":"MASTER","Line of Business":{"code":"LOB08","label":"Cognitive Systems"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG10","label":"AIX"},"ARM Category":[{"code":"a8m3p000000hAyZAAU","label":"Communication Applications-\u003EKerberos"},{"code":"a8m3p000000hBBEAA2","label":"Communication Applications-\u003ELDAP"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]
Was this topic helpful?
Document Information
Modified date:
14 August 2025
UID
ibm16551164