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.

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.

Cornelius will do a workshop there about installing privacyIDEA, enrolling tokens and authenticating at SSH. You should get an IDEA how easy it is to protect your private data and authenticate with two factors. Especially with a second factor that is totally under your control and not issued to you by any need-to-trust-me “authority” or “vendor”.

Therefor each attendee will get his own Yubikey, which he can initialized so that the cryptographic key material is only know to YOU. And you only.

You can also hear a lightning talk about the concept of locking your desktop with your smartphone but with an additional challenge response mechanism, which is more trustworthy then just a simple bluetooth coupling.

Watch this video on YouTube.

In short this is:

add-apt-repository ppa:privacyidea/privacyidea

apt-get update

apt-get install privacyidea-apache2

You can also take a look at the online documentation.

privacyIDEA 2.0 is a migration and rewrite to Flask and AngularJS.

The old privacyIDEA was based on the pylons web framework, which was not actively maintained for a while anymore, which also lead to some version conflicts. Using Flask now makes privacyIDEA a lightweight installation with a cleaner design. AngularJS is used for the WebUI which is implemented as a single page application. The two way data binding of AngularJS provides a rapid development on the UI side.

The internal code structure is hopefully kept clean. As an example there are unit tests for all levels of the code, which run on their own. The policies which were woven into the code very deeply in version 1.5 are now implemented using decorators. Thus the original functions stay clean from policies and the policies just wrap the original functionality but leave the code untouched.

The Changelog looks like this:

• Migrate privacyIDEA to Flask Web framework
• The WebUI was migrated to bootstrap and angularJS
• The database model was restructered to allow an easier handling and programming
• Use the pi-manage.py tool to migrate old data
• Provide ubuntu packages for privacyidea base package and privacyidea-apache2 and privacyidea-nginx
• Provide pi-manage.py tool to manage the installation and create new admins.
• Policies are restructured. Internally the policies now use decorators to have a minimum code impact. No all policies are migrated, yet.
• OCRA token and Email token is not migrated, yet.

privacyIDEA is available at the python package index and as ready made packages for Ubuntu 14.04LTS. The way to install these is described in the online documentation.

Take a glimpse at privacyIDEA 2.0 in this video or see the demo site.

Starting with privacyIDEA 1.2 a debian package for Ubuntu 14.04 is availble.

Please note, that you will not be able to install it on 12.04, since there would be missing requirements. privacyIDEA depends on the following packages:

 python-setuptools python-pylons python-qrcode python-netaddr python-ldap python-pyrad python-yaml python-configobj python-repoze.who python-httplib2 python-crypto python-docutils python-repoze.who-plugins

There are two PPA repositories available on launchpad: privacyidea/privacyidea-dev and privacyidea/privacyidea. The -dev repository is for development releases and testing. The privacyidea/privacyidea repo should contain stable releases.

Add the repository to your system and install privacyIDEA

To add the repository to your system run the following command:

add-apt-repository ppa:privacyidea/privacyidea

Fetch information on new content:

apt-get update

Install it:

apt-get install privacyidea

The package creates an SQLite database at /var/lib/privacyidea/token.sqlite. Of course you can use any other database backend. But using sqlite gets you up and running quickly.

Moreover the package contains a start-script /etc/init.d/privacyidea, that is running privacyidea in python-paster, a simple, lightweight webserver.

To start privacyidea run:

service privacyidea start

privacyIDEA is now listening on port 5001.

Create your admin account

Finally you need to create a first admin account to log in to the management interface:

privacyidea-create-pwidresolver-user -u admin -p test -i 1000 >> /etc/privacyidea/admin-users

Instead of using the weak password test, you should make up a cooler one.

Now you can login at https://yourserver:5001/ with the username “admin@admin” and the password you created.

Some performance data

The paster is a small webserver. The SQLite is not a state-of-the-art database.

So I always would recommend running privacyIDEA with Apache. This is describe in this post.

I was wondering what this paster and sqlite could do, So I created a realm containing the local users from /etc/passwd and assigned a simple pass token to one of these users.

Now I was able to issue an authentication request by calling the API like this:

 https://myserver:5001/validate/check?user=man&pass=test

Now I used ApacheBench to call this URL:

% ab -n 1000 -c 10 -s 5 https://172.16.200.139:5001/validate/check?user=man\&pass=test
This is ApacheBench, Version 2.3 <$Revision: 1528965 $>
Copyright 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
Licensed to The Apache Software Foundation, http://www.apache.org/

Benchmarking 172.16.200.139 (be patient)
Completed 100 requests
Completed 200 requests
Completed 300 requests
Completed 400 requests
Completed 500 requests
Completed 600 requests
Completed 700 requests
Completed 800 requests
Completed 900 requests
Completed 1000 requests
Finished 1000 requests


Server Software:        PasteWSGIServer/0.5
Server Hostname:        172.16.200.139
Server Port:            5001
SSL/TLS Protocol:       TLSv1.2,AES256-GCM-SHA384,2048,256

Document Path:          /validate/check?user=man&pass=test
Document Length:        135 bytes

Concurrency Level:      10
Time taken for tests:   41.964 seconds
Complete requests:      1000
Failed requests:        0
Total transferred:      373000 bytes
HTML transferred:       135000 bytes
Requests per second:    23.83 [#/sec] (mean)
Time per request:       419.643 [ms] (mean)
Time per request:       41.964 [ms] (mean, across all concurrent requests)
Transfer rate:          8.68 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        2   11  14.4      9     218
Processing:   121  407 270.7    332    3340
Waiting:      120  406 270.8    332    3340
Total:        126  418 272.0    342    3350

Percentage of the requests served within a certain time (ms)
  50%    342
  66%    401
  75%    456
  80%    499
  90%    678
  95%    948
  98%   1318
  99%   1632
 100%   3350 (longest request)

This was done on a Virtual Machine running in VirtualBox with 2 processors and 2GB of RAM. The host machine is an Intel i7-4702MQ CPU @ 2.20GHz.

24 Authentications per seconds, no failed requests look rather good to me.

So why not give it a try?