YubiKey LDAP — schema and tools for YubiKey LDAP support
Yubico YubiKey is an affordable OTP generator with a convenient USB
interface. One of the strenghts of YubiKeys is a very mature Linux
support, for example the ability to use it for PAM authentication.
Sadly there is a catch...
PAM authentication with YubiKey requires a list of YubiKey IDs
for each user who is allowed to login. Typically in the form of
a system file, for example /etc/yubikeys with entries similar to
these:
joe.user:abcdefgh1234:xyzxyz123456:...
some.one:hgfedcba9876:hijklmnopqrs:...
The pam_yubico module is then used with authfile=/etc/yubikeys
parameter:
auth require pam_yubico.so authfile=/etc/yubikeys ...
That works well for one or two servers. However once you begin
deploying YubiKey authentication across a handful or more servers
you soon realise that a manual synchronisation of /etc/yubikeys
file is PITA.
If you already authenticate your users against LDAP it would
only make sense to keep these YubiKey IDs in LDAP as well,
together with all other user details.
Sadly there seems to be no "official" LDAP schema provided by
Yubico, the company behind YubiKeys. Their official stance, as of
the time of this writing, is to store the YubiKey IDs in one of
the unused LDAP attributes. What? Seriously?
Search no more. Follow the instructions below to cleanly add
YubiKey IDs to your LDAP database:
dn: uid=joe.user,ou=People,cn=example,cn=com
objectClass: posixAccount
objectClass: yubiKeyUser
objectClass: ...
uid: joe.user
...
yubiKeyId: abcdefgh1234
yubiKeyId: xyzxyz123456
This is the way to keep the YubiKey IDs in LDAP. Not through
exploiting some 'shoeSize' or 'favouriteColour' attribute, OMG!
Download & Installation
Here are the files you need:
Alternatively check out our LDAP
schema and tools for Yubico YubiKey authentication project on the
GitHub and follow the instructions in the README
file. Come back for more when you're done.
Figure out the YubiKey ID
This is very simple - insert YubiKey to your USB slot, open a
text editor and touch the key. You'll see something like:
abcdefgh1234uunnvfjueirijbtkneubfdefgddkgflv
The first 12 characters are the ID: abcdefgh1234
Simple as that.
Storing the YubiKey IDs
Now that we've got the yubico schema installed it's time to
store some keys. There are two steps involved:
- Add
objectClass: yubiKeyUser to each .. well .. YubiKey User
object.
- Store his YubiKey IDs to .. well ..
yubiKeyID attributes
(Quite a self-explanatory naming, isn't it? ;)
You can indeed use your LDAP manager of choice, or rely on the
classic proven command line tools as we do here.
Open yubikey-add.ldif and enter the following few lines (change
the dn: and they yubiKeyId: values of course!):
#
# Sample LDIF that stores two YubiKey IDs to uid=joe.user
#
dn: uid=joe.user,ou=People,dc=example,dc=com
changetype: modify
add: objectClass
objectClass: yubiKeyUser
-
add: yubiKeyId
yubiKeyId: abcdefgh1234
yubiKeyId: xyzxyz123456
Now run ldapmodify to make the changes and verify with
ldapsearch:
~# ldapmodify -W -x -D cn=Manager,dc=example,dc=com -f yubikey-add.ldif
modifying entry "uid=joe.user,ou=People,dc=example,dc=com"
~# ldapsearch -W -x -D cn=Manager,dc=example,dc=com '(uid=joe.user)'
# ...
dn: uid=joe.user,ou=People,cn=example,cn=com
objectClass: posixAccount
objectClass: yubiKeyUser
objectClass: ...
uid: joe.user
...
yubiKeyId: abcdefgh1234
yubiKeyId: xyzxyz123456
YubiKey + PAM + LDAP
Again this change is very simple. Simply replace authfile= with
the LDAP parameters:
auth require pam_yubico.so authfile=/etc/yubikeys \
ldap_uri=ldap://ldap.example.com/ \
ldapdn=ou=People,dc=example,dc=com \
user_attr=uid \
yubi_attr=yubiKeyId ...
That's it. Try to SSH to the target system as joe.user, enter the
password immediately followed by the YubiKey and you should be
logged in :)
Troubleshooting
If things don't quite work as expected check the following:
- Is SELinux enabled? Are egress firewalls
enabled?
- Note that for YubiCloud authentication the server daemon (e.g.
sshd) has to make a HTTPS connection to the YubiCloud servers.
Firewalls or SELinux may prevent it to do that.
- Can the SSH server connect to LDAP server?
- Again, there could be a firewall, broken DNS, etc.
- Can each user read its yubiKeyId LDAP attributes?
- Your LDAP access control lists (ACL) may prevent that (by
default they shouldn't but check that with ldapsearch logging
in as
uid=joe.user.
- Temporarily add 'debug' at the end of pam_yubico parameters
list. It will spit out a lot of potentially useful debug
informations.
Donations
Have you found this LDAP schema useful? Do you use it in production? Support its author by a PayPal or CreditCard donation.
