Two factor authentication has been added this way to ownCloud/Nextcloud, OTRS, dokuwiki, WordPress, TYPO3, Django, Kopano (Zarafa) and SimpleSAMLphp. See the plugin section of the privacyIDEA online documentation.

Two different concepts

There are basically two ways for the user to provide a second factor during authentication. The first one is to completely replace the authentication of your webapplication. In this case your application delegates the complete authentication process to privacyIDEA. This is implemented e.g. in the OTRS plugin and the WordPress plugin. In this case the plugin will take care of the first and second factor. And in certain cases it will also take care of the WebUI Login Screen.

The other possiblity is that your application uses its normal password based authentication, but after the user has successfully authenticated with his usual username and the application password, your application decides, not to immediately allow access, but hand over the authentication to the 2FA plugin, which will take care of quering the second factor. This is implemented in the privacyIDEA ownCloud App.

In addition we already published some basic requirements for modular two factor authentication in a web application.

Hand complete authentication process to the 2FA plugin

Your application should allow to register or configure a 3rd party module or class. This class would have to provide a method like authenticate_user for verifying the users input. The easiest way would be, that such a plugin does not even has to change or bring its own login screen. In such simple case, the authentication method authenticate_user would simple receive the credentials, that were entered at your applications default login screen. It then would return True or False or maybe raise an exception.

The privacyIDEA plugin for your webapplication would use this username and this password to issue a call to the privacyIDEA REST API. The plugin would call the /validate/check endpoint with username and password as parameters and simply evaluate the JSON response.

Managing users, returning user attributes or listing users would be out of scope of such an authentication plugin. Authorization would be out of scope, just as it is with the Unix PAM stack.

Example OTRS

An example implementation of the complete authentication replacement is the OTRS plugin for privacyIDEA.

In this case the administrator can configure in OTRS which Perl module should be used for authenticating the user. Note: Not for verifying if the user exists and not for fetching attributes like given name or email address of the user.

The Perl module has to provide a function Auth, which takes a dictionary/hash with the keys User and Pw. If the credentials were verified successfully this function returns the Username of the user, otherwise an empty string.

See the implementation at github.

In this case, privacyIDEA takes care of verifying two factors. The user has entered a knowledge and a One Time Password (2nd factor: possession) into the password field. privacyIDEA knows how to verify the static password (knowledge) and the OTP value.

Example WordPress

The WordPress plugin works the same. It does not modify the login screen, as this is not necessary. The user enters his static password and his one time password in the password field. The WordPress plugin registers or overwrites the function wp_authenticate, which takes the credentials that were entered by the user. WordPress relies on the return value of this function, which again is either a WordPress User object or null.

Within this function of the plugin, the credentials are verified against the configured privacyIDEA server. In this case this is done using curl.

Note: All authentication requests are forwarded to privacyIDEA. WordPress does not know if the user has a second factor or not. It does not know, which kind of second factor a user has. This is all handled by privacyIDEA. This way the plugin can be kept rather light weight.

Only hand second factor to the 2FA plugin

Instead of passing the complete authentication process to the 3rd party plugin, you can also design your authentication framework this way, that your application still verifies the static user password and request an additional authentication on top.

This can be interesting, if your application needs to know the user password, since it is used to contact email servers or encrypt data.

Your application will verify the password as before. But in addition it will pass the controll the the 2FA plugin

Example ownCloud

The ownCloud 2FA Framework is implemented this way.

In the first step the user has to authenticate against ownCloud with the ownCloud password.

If the user entered the correct password, which is still verified by ownCloud, the web application (ownCloud) calls the 2FA plugin to ask for the second factor.

The ownCloud 2FA framework requires the plugin to register a Class that is derived from a certain 2FA base class. This way the web application (ownCloud) knows, if two factor authentication can be used for the user, who is already authenticated in the first step.

The 2FA framework then asks the plugin/class to provide a template for the 2nd step of the Login UI. Finally the 2FA framework calls a class method in the plugin to verify the 2nd factor.

This good thing about it is, that ownCloud can know the user’s password and thus use the user’s for encryption and sending emails. The drawback of this design is, that the authentication workflow might be a bit more complicated, exspecially if it comes to special scenarios like challenge response authentication.

Special case for Challenge Response token like SMS and Email

Although NIST recommended to not use SMS for two factor authentication it is still an attractive and easy way. In addition privacyIDEA can run any combination of authentication devices. Some users may use Yubikeys, others Google Authenticators, some users use key fob tokens and another group could use SMS.

But privacyIDEA needs additional information to trigger an SMS. Not everybody can trigger the sending of an SMS, otherwise the user would get spammed with SMS on his mobile phone.

There are two ways to trigger and SMS:

1. The user authenticates with his OTP PIN (static password). privacyIDEA realizes, that this is the correct password for an SMS token and will send the SMS.
2. An administrative or system account requests the sending of an SMS for this specific user.

In both cases the 2FA framework of your application has to provide the possibility to issue a REST request before the user authenticats. Because this first REST request will send the user the code, which he then can use to finally authenticate.

Most applications do not allow this easily today.

There is a beta implementation for the ownCloud 2FA framework, which is not that perfect. The SMS is triggered when the Login UI is rendered. This has the side effect that the SMS is triggered again, if the user entered a wrong OTP value, since the UI is rendered again.

When designing the authentication framework of your web applications, you could have such corner cases in mind.

Now it is your turn!

If you want to add 2FA to your web application, please contact us in our Google Group.

Thus you have the following authentication factors:

1. SSH Key (soft possession factor – copyable!)
2. optional passphrase on the SSH Key, which is not controlled by the server! (knowledge)
3. OTP token supported by privacyIDEA like Google Authenticator or preferable a Yubikey (hard possession factor – not copyable)
4. an optional OTP PIN controlled by privacyIDEA (knowledge)

Connect SSH to privacyIDEA

Connecting SSH to privacyIDEA is described in this video. It uses the privacyIDEA PAM Module in the online documentation.

In the SSH configuration you need to set

UsePAM yes

This way SSH will authenticate the user against the PAM stack using /etc/pam.d/sshd.

This howto will assume you are using a Ubuntu system. Other systems like CentOS use slightly different PAM configuration, but the idea is the same.

Install privacyIDEA PAM

To use PAM with privacyIDEA you need the privacyIDEA PAM authentication module. On a Ubuntu 14.04 you can install it like

add-apt-repository ppa:privacyidea/privacyidea
apt-get update
apt-get install privacyidea-pam

In other cases you can get it from github with the above mentioned link.

Configure SSH PAM

Now lets take a look at the PAM config for SSH. The file /etc/pam.d/sshd contains a line

@include common-auth

Change this line to

@include common-auth-pi

By creating such a new file it is easier for us to add two factors to every PAM enabled service.

Copy the file /etc/pam.d/common-auth to /etc/pam.d/common-auth-pi. The file /etc/pam.d/common-auth-pi will look like this:

auth     [success=1 default=ignore] pam_python.so /lib/security/privacyidea_pam.py url=https://yourserver \ 
                                                  nosslverify debug
auth    requisite   pam_deny.so
auth    required    pam_permit.so
auth    optional    pam_cap.so

In the file common-auth-pi we replace pam_unix.so with privacyidea_pam. You need to specify the URL of your privacyIDEA server. If everything is working out fine, you can remove the debug parameter. If you have a trusted certificate you can remove nosslverify.

Please assure, that you are logged in to your system or that you have other mean to login like ssh keys. Modifying the PAM stack for SSH can result in not being able to login with a password via SSH anymore.

Now that you have configured

• /etc/ssh/sshd_config
• /etc/pam.d/common-auth-pi
• /etc/pam.d/sshd

you can restart the SSH server for the changes to take effect.

When you now try to login via SSH, the username and password will be sent to privacyIDEA for verification. You can not use you OTP PIN and Yubikey to login.

If you experience any problems, take a look at /var/log/auth.log.

If everything is working fine, you are now authenticating with:

1. OTP token supported by privacyIDEA like Google Authenticator or preferable a Yubikey (hard possession factor – not copyable)
2. an optional OTP PIN controlled by privacyIDEA (knowledge)

Add SSH Keys

You may realize, that if you have an SSH key in the authorized_keys you will not be asked for the OTP. At the moment you either login with SSH key or with OTP. Let’s change this now, that you can use SSH key and OTP.

The current OpenSSH comes with the options AuthenticationMethods. This is used to concatenate required authentication methods. See the man page of sshd_config for more details.

In the file /etc/ssh/sshd_config we add this line:

AuthenticationMethods publickey,password

This means that SSH will require that you pass a trusted SSH key and after this ask you for a password (PIN+OTP), which will be verified by privacyIDEA.

The login will look like this:

root@gawain ~ # ssh root@privacyidea
Authenticated with partial success.
root@privacyidea's password: 
Welcome to Ubuntu 14.04.3 LTS (GNU/Linux 3.13.0-66-generic x86_64)

The “Authenticated with partial success” means, that the authentication with the SSH key succeeded. Now you need to specify the One Time Password to be sent to privacyIDEA.

Note: If you want to login as user “root”, be sure to add “PermitRootLogin yes” to your sshd_config.

Finally we managed to authenticate the users with:

1. SSH Key (soft possession factor – copyable!)
2. optional passphrase on the SSH Key, which is not controlled by the server! (knowledge)
3. OTP token supported by privacyIDEA like Google Authenticator or preferable a Yubikey (hard possession factor – not copyable)
4. an optional OTP PIN controlled by privacyIDEA (knowledge)

Manage SSH Keys with privacyIDEA

Wait! Are you still there? One thing might still strike you:

While all OTP tokens are centrally managed by privacyIDEA, users still put their public SSH keys on all the machines and you are wondering where the SSH keys of all the users are floating around.

There is no easy way for you to revoke a compromized SSH key.

But you can also solve this with privacyIDEA. Users can upload their public SSH keys to privacyIDEA with the tokentype SSH Key.

This way you can also manage all SSH keys in privacyIDEA. In sshd_config you need to use the AuthorizedKeysCommand to retrieve the SSH keys from privayyIDEA just in time. Deleting an SSH key in privacyIDEA will deny access for this user immediatly.

You can read SSH Key Management with privacyIDEA to set this up.

This way you have three strong factors to secure the access to SSH.

There is a new Howto at howtoforge.com, that describes how you can secure your wordpress login using privacyIDEA.