Dec 10

Using WiKID Two-Factor Authentication with SSH

I have found a couple of howtos on how to set up WiKID to use SSH, but I had a horrible, horrible time using them.  This is partially because of my version of Linux (RHEL 5 and 6) and partially because the howtos don’t do a good job of explaining why you are taking various steps.   I want to remedy that issue, so that others can learn from my pain.


Background information

Most of you probably know that on Linux, at least, ssh uses PAM to authenticate users.  PAM is a pluggable tool that allows you to control how different applications authenticate users when they try to log into a machine.   By default, typically, PAM will provide instructions and rules that ensure that users are authenticated against the /etc/passwd database.

But you can include other tools in the authentication system (and in fact, you can write you own).   One of these PAM rule libraries is focused on connecting PAM to RADIUS – an authentication protocol that was very popular back in the dial-up modem days.     It continues to live on in various implementations, including, most popularly, FreeRadius.


FreeRadius was built many years ago, and relatively recently, a new version was created: FreeRadius2.     Because of the relatively glacial pace of Linux software change (not necessarily a bad thing), many of the documents and howtos still reference FreeRadius, instead of FreeRadius2.   More frustratingly, FreeRadius2 is sometimes labelled as simply “FreeRadius”, which can be confusing.

FreeRadius and PAM

FreeRadius includes a module, specifically built to help integrate RADIUS with PAM.   That would be the aptly-named PAM Authentication and Accounting Module.  Now, as far as I can tell, it only comes as source, so be prepared to build it. (I hope you know how to use/install Make and cc/gcc, etc).

In addition, you can’t just download it and build it, you need to install the FreeRadius base RPM, as well as the developer and utility RPMs.   After that, you should have a pam_radius_auth.so which you can install into /lib/security or /lib64/security, depending on your OS.


This module is fairly straightforward – it attempts to find a configuration file called /etc/raddb/server, and looks in the file, to determine which RADIUS server to authenticate against.   It then sends that server UDP packets on port 1812, and if there’s a RADIUS server listening there, the server can answer and validate the username/password provided.

Updating PAM’s sshd configuration

On my system, I have to update the /etc/pam.d/sshd file in order to include the pam_radius_auth.so .  I found three different examples of how to do this on the Internet, and all three were different, so I won’t pretend that I know the “right” answer here.  Let me just say that I put my entry fairly early in the config file, which seemed like the correct thing to do.  On my system:

auth	   sufficient	pam_radius_auth.so  debug

Is the very first line.   debug is there so I could get some logging output of what was happening, to help troubleshoot.  Once you’re live, remove it.

The situation so far

At this point, if you’ve followed the steps  described above, when you log in with ssh, it will attempt to find a RADIUS server and authenticate against it.

“Well, I have just installed FreeRadius, why don’t I use that” your instincts might say, at this point.  But your instincts are wrong.

In my odyssey to get this software working, I have discovered that, at the end of the day, once you have the pam_radius_auth.so compiled, and you have configuration rules specified in /etc/raddb/server, you could (if you wanted) safely delete FreeRadius.  You don’t need it anymore.  Keep the utility and dev libraries though.  You’ll need those later.

Setting up /etc/raddb/server

Again, as I mentioned earlier, pam_radius_auth.so is preconfigured to look for a configuration file named /etc/raddb/server.  This file contains the following line:	your_shared_secret       3

What does this do?   Well, it tells that library (pam_radius_auth.so) that the RADIUS server it wants to talk to is running on localhost, on port 1812 (by default), and it “knows” the shared secret key “your_shared_secret“.

Completely unnecessary test

If you had a wild hare, or you just like billing by the hour, at this point, you could set up FreeRadius, add a fake user to /etc/raddb/users, and see if you could log in as that user, with the username and cleartext password specified in the /etc/raddb/users file, and the shared secret “your_shared_secret” specified in the /etc/raddb/client.conf  . There are already guides for doing this, if you feel compelled.

Will it work for ssh at this point?

No, not until you add that user to /etc/passwd.  LFMF!

Ok, done.  Now will it work for ssh?

Probably.  But that’s not what you want.  You want to use WiKID, right?  (otherwise, why are you here?).   That’s a bunch of additional steps along the path.

Ok, so how do I set it up with WiKID?

Well, first off, install WiKID.   Set up the server using their documentation.   Note that if you try to move it off of ports 80 and 443, you will be miserable.   LFMF!

When it comes time to set up a Network Client, set up a RADIUS client, using “your_shared_secret“.


When you do this, make sure that FreeRadius isn’t running.  Also, make sure that you restart WiKID after you add the new Network Client.

Basically, when you add a RADIUS network client to WiKID, WiKID becomes a RADIUS server!. I cannot stress this enough – it took me almost two weeks to realize that I was trying to connect a server to another server.  Yes, I am dumb.   LFMF!

Ok, I have a network client

Well, now you need to add a WiKID user.  This was relatively straightforward from the documentation, except for one little detail – when you install the wikid software token on a laptop, PC, phone, whatever, you have to:

a) Register it back with the WiKID server

b) Make sure that the user exists in /etc/passwd

c) You can’t ever re-use a registration with a given username.  So if you, say, end up testing the client on two different computers, with two different registrations, you have two different users. If you attempt to log in with the client token registered for user A, but with the username for user B, it will silently fail.


You could try ssh at this point, by following these steps:

1) get your wikid temporary passcode

2) ssh with the username associated with the passcode, and use the passcode as the password

3) If you have a shell, congrats!

If you have problems, there are some pretty good logs built in to the WiKID web ui.   Set various things to debug, and you’ll see more info.     Note that these logs disappear after restarting WiKID, so stay vigilant about turning them on.  note also that after a few failures, your users are silently disabled, which will cause logins to silently fail, even if everything else is correct.  Stay vigilant!

Note also that you can use the Freeradius test tool (radtest) to test your configuration, if ssh isn’t cooperating (or if you don’t want to change ssh until the very end).

Testing with radtest

radtest <username> <wikid_passcode> 0 <your_shared_secret>

username: the username in WiKID and also in /etc/passwd

wikid_passcode: the temporary 1 minute passcode you get from using the WiKID token client.

your_shared_secret :  the secret you used to configure the RADIUS Network Client in WiKID.

I can say that the logs you get from using radtest are easier to follow than using ssh directly.


At this point, you should be able to use ssh to log in, using the WiKID username, and the temporary passcode.   Good luck!















Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>