First, we setup three machines with Ubuntu Server 18.04 and provide similar /etc/hosts files to each of them. For a proper setup, Kolab requires a fully qualified domain name. We choose kolab.netknights.it.

127.0.0.1      localhost
127.0.1.1      kolab
192.168.56.200 kolab.netknights.it    kolab
192.168.56.201 pi.netknights.it       pi
192.168.56.202 keycloak.netknights.it keycloak

To put the system into action, one would have to configure DNS and NAT properly so that the server is reachable from the internet. DNS record of type A, AAAA and MX are crucial to do this. You may read about this requirement in the Kolab docs “preparing the system“. For this proof of concept we will not use any logical volumes nor discuss firewall setups or SSL transport layer security.

After updating the initial Ubuntu Server systems, we install privacyIDEA, Keycloak and Kolab following their general installing instructions. We start with Kolab, since in this scenario, we would like to attach the ds-389 LDAP directory delivered by Kolab to our backend, i.e. Keycloak and privacyIDEA.

Kolab 16 Installation

The primary OS supported by Kolab is CentOS, which is also supported by privacyIDEA. However, there are also Kolab and privacyIDEA packages available for Ubuntu 18.04. We will use these for our setup. The install instructions can be found at docs.kolab.org. We summarize them here for convenience

# Add repositories for apt to /etc/sources/ 
~$ echo 'deb http://obs.kolabsys.com/repositories/Kolab:/16/Ubuntu_18.04/ ./ deb-src http://obs.kolabsys.com/repositories/Kolab:/16/Ubuntu_18.04/ ./' \ 
| tee /etc/apt/sources.list.d/kolab.list 
# Add signing key 
~$ wget -q -O- https://ssl.kolabsys.com/community.asc | apt-key add - 
~$ echo -e 'Package: *\nPin: origin obs.kolabsys.com\nPin-Priority: 501' \ 
| tee /etc/apt/preferences.d/kolab 
~$ apt-get update
~$ apt-get install kolab

We let the postfix SMTP service be configured as “Internet with smarthost”. Outbound email will be relayed to another (trusted) mail server, e.g. the one of your ISP. Inbound mail will reach postfix on port 25 if your DNS records are configured correctly. After installation the configuration script is called via

~$ setup-kolab

It will ask for some information and several passwords. The password for the directory manager will be used to first login, so remember it. Also passwords for a the cyrus-imapd administrator, a kolab-service user, the mysql database root user and several database passwords are needed. Note, that all of them are stored in the /etc/kolab/kolab.conf file and only very few are needed for interactive logins.

Kolab comes without a predefined admin user. Only the directory admin is defined which should not be used for user administration. So we login as “cn=Directory Manager” and define a new admin user. In our default setup, the UID is generated from the surname (check the “System” tab), so we choose kolab-admin to differentiate from pi-admin and keycloak-admin later.

On the System tab we set the predefined kolab-admin role for the user to grant him access for user management. Also set a password.

Hit submit to complete the process. Next add another ordinary user to test the second factor login later on. We call this user test-user.

privacyIDEA 3.x Installation

Now, we setup privacyIDEA. Install instructions for the most recent version can be found at readthedocs.privacyidea.io. We install the official Ubuntu packages, specifically the privacyidea-apache2 package. The installation only takes few minutes. After creating the admin user, here called pi-admin, with

~$ pi-manage admin add pi-admin -e pi-admin@localhost

we login to the UI. privacyIDEA needs to access the LDAP directory provided by Kolab, so we create an LDAP resolver and use the Kolab service account created above via “Config->Users->New ldapresolver”. The dn and password for the kolab-service account can be checked in the file /etc/kolab/kolab.conf. We use the OpenLDAP preset given by privacyIDEA but change the UID type to “dn”. The resolver test buttons help to avoid typos and to check the connection. For the test, we leave TLS to be configured later.

The resolver is added to a new realm kolab_realm at “Config->Realms->Create Realm”.

You should now be able to see the users within privacyIDEA.

We will enroll an HOTP token for test-user with the privacyIDEA App, available from Google Play Store. You may alternatively use the Google Authenticator. Install the app and proceed with the enrollment as given below. The privacyIDEA UI auto-completes the username as you type. The generated QR code must be scanned with the App to complete the enrollment.

The OTP token is now assigned to the user test-user and the privacyIDEA app on your phone should display a six-digits OTP code.

To issue trigger challenges asking for an OTP key on user login, privacyIDEA needs an authorization. Since we do not want our pi-admin password to flow through the wire all the time, we create another, unpriviledged admin user on the privacyIDEA terminal.

~$ pi-manage admin add trigger-admin -e trigger-admin@localhost

The trigger-admin needs a superuser policy to restrict the access. In “Config->Policies”, first create a default superuser policy using the “superuser” template. Add only the pi-admin to the admin field. Then add another policy without template. Name it trigger_admin, select the scope admin, add the action triggerchallenge and add the created trigger-admin to the admin field. Now, we have two admin users. pi-admin has the default superuser access and trigger-admin has only very limited access allowing to trigger the challenge.

As privacyIDEA is now up and running, we proceed with the Keycloak server, which will act as the central element in the SSO environment.

Keycloak 9 Installation

Start the Keycloak installation by downloading the Keycloak standalone server from keycloak.org. General install information is found in the “getting started” guide. A detailed guide how to integrate Keycloak with systemd on Ubuntu Server 18.04 LTS is found here. The necessary steps are summarized below.

~$ sudo apt-get update
~$ sudo apt-get install default-jre-headless
# Install Keycloak 9
~$ mkdir -p /opt/keycloak /etc/keycloak
~$ wget https://downloads.jboss.org/keycloak/9.0.0/keycloak-9.0.0.tar.gz
~$ tar -xvzf keycloak-9.0.0.tar.gz
~$ mv keycloak-9.0.0.tar.gz /opt/keycloak
# Add keycloak user
~$ groupadd keycloak
~$ useradd -r -g keycloak -d /opt/keycloak -s /sbin/nologin keycloak
~$ chown -R keycloak: /opt/keycloak
~$ chmod o+x /opt/keycloak/bin/
# Place config file
~$ cp /opt/keycloak/docs/contrib/scripts/systemd/wildfly.conf /etc/keycloak/keycloak.conf
# Setup systemd files
~$ sed 's/wildfly/keycloak/' /opt/keycloak/docs/contrib/scripts/systemd/launch.sh \
| tee /opt/keycloak/bin/launch.sh
~$ chown keycloak: /opt/keycloak/bin/launch.sh
~$ sed 's/wildfly/keycloak/g' /opt/keycloak/docs/contrib/scripts/systemd/wildfly.service \
| tee /etc/systemd/system/keycloak.service
# Enable and start the daemon
~$ systemctl daemon-reload
~$ systemctl enable keycloak
~$ systemctl start keycloak
~$ systemctl status keycloak
# Add admin user
~$ /opt/keycloak/bin/add-user-keycloak.sh -r master -u keycloak-admin -p <password> 
~$ systemctl restart keycloak

Now you should be greeted by Keycloak at http://192.168.56.202:8080. Login with your created keycloak-admin user. As Keycloak should validate the user logins it has to have access to the user store. In “User Federation”, add an LDAP provider with the following settings. The kolab-service account is used as an unpriviledged bind and again we disable TLS for the test setup.

Hit “Synchronize all users” to pull the users from LDAP to Keycloak. You may enable the periodic sync to keep the Keycloak user store up-to-date.

Important: The keycloak-admin should not be required to provide a second factor to prevent locking the configuration while testing. For this purpose, define a no2fa group in “Groups” and add the keycloak-admin to that group in “Users”.

Next, privacyIDEA is integrated with Keycloak. Following our earlier article on the integration of Django with Keycloak and privacyIDEA, we download the two files PrivacyIDEA-Provider.jar and privacyIDEA.ftl of the most recent release of the privacyIDEA keycloak-provider and install it to Keycloak.

~$ wget https://github.com/privacyidea/keycloak-provider/releases/download/v0.3/PrivacyIDEA-Provider.jar
~$ wget https://github.com/privacyidea/keycloak-provider/releases/download/v0.3/privacyIDEA.ftl
~$ cp PrivacyIDEA-Provider.jar /opt/keycloak/standalone/deployment/
~$ cp privacyIDEA.ftl /opt/keycloak/themes/base/login/

In Keycloak, the authentication is managed in so called “Authentication Flows”. Copy the default browser-based flow below and rename it to PrivacyIDEA.

Add an execution to “PrivacyIDEA Forms” and choose the installed plugin called PrivacyIDEA from the list.

Delete the unnecessary items in the flow (or set them to disabled), so that only “PrivacyIDEA Forms” and “Cookie” remain. The authentication flow should now look like this:

We set PrivacyIDEA to REQUIRED here, which means that additionally to username and password, the second factor is required for all users. We have to configure the plugin to reach our privacyIDEA server at https://192.168.56.202. We disable SSL-verification for the self-signed certificate here, which you must not do in a productive environment. Members of the no2fa group, defined above will not be asked for their second factor. For issuing the trigger challenge a service account is needed. We use the trigger-admin account created in privacyIDEA earlier.

Set the edited authentication flow as default browser flow in “Bindings”.

So privacyIDEA is now configured to challenge the second factor for every user. The last step is to enable OpenID Connect logins in roundcubemail.

Installation of the Kolab SSO plugin

For the OIDC, Kolab provides the kolab_sso plugin for Roundcubemail which is available on git.kolab.org. Clone the repository and copy the plugin to the Roundcubemail directory to install it.

~$ git clone https://git.kolab.org/diffusion/RPK/roundcubemail-plugins-kolab.git
~$ cp -r roundcubemail-plugins-kolab/plugins/kolab_sso/ /usr/share/roundcubemail/plugins/

Place the default configuration file.

~$ cp /usr/share/roundcubemail/plugins/kolab_sso/config.inc.php.dist /etc/roundcubemail/kolab_sso.inc.php

Apache should redirect host.roundcube/sso to host.roundcube/?_task=login&_action=sso, since keycloak does not support parameters in urls. It will display “Invalid parameter: redirect_uri”. Add the redirect as follows to /etc/apache2/sites-enabled/roundcubemail.conf.

RewriteEngine On
RewriteCond %{REQUEST_URI} ^/roundcubemail
RewriteRule "^sso" "/roundcubemail/?_task=login&_action=sso" [L,QSA]

We proceed on the Keycloak machine and add Roundcubemail as a new OpenID Connect client as given below.

Save the form to access the “Credentials” tab. We will soon need the generated secret again.

The kolab_sso plugin needs the certificate of the Keycloak server during the OpenID Connect authentication process. It is available from the Keycloak management console in the “Realm Settings”.

Add the key and the client secret alongside the token_uri and auth_uri to the kolab_sso.inc.php configuration file. Make sure that the public key copied from keycloak is properly formatted. The IMAP, SMTP and LDAP credentials in the top part of the file are required for accessing the mailbox, sending emails and accessing the server addressbooks. Configure them accordingly.

After successfully testing the ordinary password login with Roundcubemail at http://192.168.56.200/roundcubemail, you may disable the password login to allow only OpenID Connect by setting

 $config['kolab_sso_disable_login'] = true;

in kolab_sso.inc.php.

Test the login

We are now ready to test the OpenID Connect login at Roundcubemail. Navigate once again to http://192.168.56.200/roundcubemail to test the login. You may monitor some log files during the process.

/var/log/privacyidea/privacyidea.log
/var/log/roundcubemail/*
/opt/keycloak/standalone/log/*

Conclusion

We demonstrated the integration of privacyIDEA with Keycloak to provide a solid basis to secure your applications with a second factor in a single sign-on (SSO) environment. For maximum flexibility, the system relies on standard protocols such as SAML or OpenID Connect (OIDC). The privacyIDEA keycloak-provider is designed to perfectly fit the two components together, uniting the rich identity management capabilities of Keycloak and the powerful multi factor management of privacyIDEA.

We chose the Roundcubemail webmailer of the Kolab Collaboration Server as an example application. The kolab_sso plugin provided the necessary interface to connect via OIDC to easily enhance security by adding a second factor managed by privacyIDEA. The setup of other popular open collaboration platforms such as Tine 2.0 or Open-Xchange work similarly.

Including additional applications in this setup is very easy as long as they support at least one SSO protocol. These applications do not even to be hosted on your own servers. Nowadays, most cloud-based applications offer both, the possibility to use an external identity provider and to use OIDC. Thus, you can also use remote services with your own user base, defining access-rules to fit your needs.

privacyIDEA is the Open Source Two Factor solution that runs at a central location in your network and can work as the 2FA instance for all your applications. privacyIDEA provides plugins for several applications directly (like WordPress, ownCloud, TYPO3, django, contao…) but also has plugins to serve standart authentication protocols like PAM, RADIUS, SAML2 and OpenID Connect.

You have the chance to use privacyIDEA everywhere – with every application.

Cornelius will give a talk about how privacyIDEA can be integrated with your preferred application at the Ohio Linuxfest in Columbus, Ohio. Your preferred application can be either connected via the before mentioned protocols or via the privacyIDEA REST API. In this talk you can learn, how this can be achieve to use a secure login with your own or preferred application.

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.