Therefore, we invite you to attend the following online webinars:

“privacyIDEA as a replacement for DUO and Okta” on March 12 and “Management of SSH Keys with privacyIDEA” on March 24.

In these free online events, we will show you how you can use privacyIDEA to design your authentication processes flexibly, securely, and independently.

In addition, Cornelius Kölbel, Founder of privacyIDEA with more than 25 years of experience in the field of multi-factor authentication, will answer your questions.

Take advantage of this opportunity to gain new insights for your authentication project and get answers to your questions!

Dates & Time

• privacyIDEA as a Replacement for DUO and Okta (12.03.2026, 5:00 pm – 5:45 pm CET)
• SSH Key Management with privacyIDEA (24.03.2026, 5:00 pm – 5:45 pm CET)

Secure your spot and learn more about MFA with privacyIDEA!

Registration via: https://netknights.it/en/privacyidea-webinar-anmeldung/

Therefore, we invite you to attend our free online webinars:

“Central MFA with privacyIDEA” on February 10 and “privacyIDEA Basics” on February 26.

In these free online events, we will show you how you can use privacyIDEA to design your authentication processes flexibly, securely, and independently.

In addition, Cornelius Kölbel, Founder of privacyIDEA with more than 20 years of experience in the field of multi-factor authentication, will answer your questions.

Take advantage of this opportunity to gain new insights for your authentication project and get answers to your questions!

Dates & Time

• Central MFA with privacyIDEA (10.02.2026, 5:00 pm – 5:45 pm CET)
  
• privacyIDEA Basics (26.02.2026, 5:00 pm – 5:45 pm CET)
  

Secure your spot and learn more about MFA with privacyIDEA!

Registration via: https://netknights.it/en/privacyidea-webinar-anmeldung/

Therefore, we invite you to attend our free online events

“Central MFA with privacyIDEA” on August 19 or 28 and “privacyIDEA – Your replacement for DUO and OKTA” on September 16.

In these free online events, we will show you how you can use privacyIDEA to design your authentication processes flexibly, securely, and independently.

In addition, Cornelius Kölbel, CEO of NetKnights with more than 15 years of experience in the field of multi-factor authentication, will personally answer your questions.

Take advantage of this opportunity to gain new insights for your authentication project and get answers to your questions!

Dates & Time

19 August, Central MFA with privacyIDEA, 3 pm-3:45 pm Central European Time

28 August, Central MFA with privacyIDEA, 7pm-7:45 pm Central European Time

16 September, privacyIDEA – Your replacement for DUO and OKTA, 7 pm-7:45 pm Central European Time

Secure your free spot and learn more about MFA with privacyIDEA!

Registration via: https://netknights.it/privacyidea-webinar-registration

We look forward to your participation. If you have any further questions about the webinars, do not hesitate to contact us via marketing@netknights.it

You could then use the Yubikey with the x509 certificate to login to you desktop, sign or decrypt emails. These application examples are not topic of this blog post and might be covered in later posts.

You will need a Yubikey 5 and a privacyIDEA installation with version 3.5. We also assume in this example, that you are running Linux on your desktop.

Setup CA in privacyIDEA

First we have to setup a certificate authority (CA), that will sign the certificate signing request (CSR) generated by the Yubikey. privacyIDEA currently only supports local openssl based CAs. This could however be a sub CA to your existing enterprise CA. In this example, we create a new root CA.

Note: You need read access to pi.cfg and write access to /etc/privacyidea/ca

# pi-manage ca create -t local myLocalCA

This pi-manage command will create the CA files and also the CA configuration within privacyIDEA. You are asked a couple of questions and answer them accordingly:

# pi-manage  ca create -t local  myLocalCA

             _                    _______  _______
   ___  ____(_)  _____ _______ __/  _/ _ \/ __/ _ |
  / _ \/ __/ / |/ / _ `/ __/ // // // // / _// __ |
 / .__/_/ /_/|___/\_,_/\__/\_, /___/____/___/_/ |_|
/_/                       /___/

Creating CA connector of type local.
In which directory do you want to create the CA [./ca]: /etc/privacyidea/ca
What should be the keysize of the CA (2048/4096/8192)[4096]: 
How many days should the CA be valid [1800]: 
What is the DN of the CA [/CN=myLocalCA]: 
How many days should the CRL be valid [30]: 
What should be the overlap period of the CRL in days [5]: 
============================================================

        Directory  : /etc/privacyidea/ca
        CA DN      : /CN=myLocalCA
        CA Keysize : 4096
        CA Validity: 1800

        Validity of issued certificates: 365

        CRL validity: 30
        CRL overlap : 5

Is this configuration correct? [y/n] y

You also need to fix the access to the directory

chown privacyidea -R /etc/privacyidea/ca

and create a file /etc/privacyidea/ca/templates.yaml with the contents:

user:
    extenstions: "user"
    days: 365

which will ensure, that the certificate will created as a user certificate with a validity period of 365 days.

You need to do some minor fixtues:

cd /etc/privacyidea/ca
openssl rand -writerand .rnd 
touch index.txt.attr 
chown privacyidea .rnd index.txt.attr

For simplicity comment out two lines (crlDistributionPoints and authorityInformationAccess) in the section “user” in the file /etc/privacyidea/ca/openssl.cnf

[ user ]
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
basicConstraints = CA:FALSE
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer:always
#crlDistributionPoints = @crl_dp_policy
#authorityInfoAccess = caIssuers;URI:http://www.example.com/yourCA.crt

As a last step, go to the Web UI in Config->CA and add the “Certificate template file” /etc/privacyidea/ca/templates.yaml.

Now your CA is ready to go.

Setup PIV trusted certificates

The attestation certificate verifies that the private key was generated on the Yubikey. You can tell privacyIDEA, which attestation certificates should be trusted. Here we will use the Yubikey, so we need to fetch the Yubico PIV CA from their web site.

mkdir /etc/privacyidea/attestation    
wget https://developers.yubico.com/PIV/Introduction/piv-attestation-ca.pem \
     -O /etc/privacyidea/attestation/yubico.pem

The PIV Root CA has signed the attestation CA, that is contained on each Yubikey. We need to retrieve this from the Yubikey. Do do so insert a Yubikey and run the following command:

yubico-piv-tool --action=read-certificate \ 
      --slot=f9 >> /etc/privacyidea/attestation/yubico.pem

The certificate we read from the Yubikey from slot f9 is the attestation CA, that was signed by the Yubico CA. The attestation CA will sign the attestation certificate, that testifies, that the CSR was created on the yubikey. The file yubico.pem now contains the certificate chain of the PIV Root CA and the Attestation CA.

Note: With new production charges Yubico might put a new attestation CA on the yubikeys. So if you buy 100 yubikeys, they will most probably have the same attestation CA, but if you buy another 100 yubikeys several month later, they might have another attestation CA, so you need to repeat this step and put the new certificate chain in a second file.

Configure privacyIDEA policies

privacyIDEA can already enroll x509 certificates. But to ensure, that it will only enroll certificates from CSRs, that are created on the Yubikey, we need to define a new policy, which is available starting with privacyIDEA 3.5.

We create a policy to require an attestation certificate

scope: enrollment
action: certificate_require_attestation=require_and_verify

In this example we will have the administrator enroll yubikeys, so we set an admin policy, that specifies, where the trusted CA chains can be found:

scope: admin
action: certificate_trusted_Attestation_CA_path=/etc/privacyidea/attestation/

Enroll certificate

Now the admin needs to pass the CSR and in addition an attestation certificate, if he wants to have the CSR signed and receive a certificate. The admin could do this manually with the yubico own tools and using the privacyIDEA REST API.

However, in this example we use the privacyidea admin client, which can be found at github.

Note: You can run the command line client on any other computer, it does not need to be your privacyIDEA server.

In this case we are running it on an Ubuntu Linux desktop.

Prepare dependencies:

sudo apt-add-repository ppa:yubico/stable
sudo apt update
sudo apt install yubikey-manager
sudo apt install ykcs11

Create a virtualenv:

virtualenv -p /usr/bin/python3 piv-test

Enter the environment:

source piv-test/bin/activate

Install the privacyidea admin client:

git clone https://github.com/privacyidea/privacyideaadm
cd privacyideaadm
pip install .

Now you can use the current development branch of the admin client in your virtualenv.

Note: You need to have enough hardware access rights, otherwise you might get errors like ” Failed to transmit with protocol T1. Reader is unavailable”

If necessary, you can reset the PIV data on your yubikey:

ykman piv reset

Now you can enroll the yubikey certificate:

privacyidea-enroll-yubikey-piv init-cert -s cornelius -u cornelius \
     -U https://localhost -a super -p test -c myLocalCA -n -P 123456

This will create a CSR on the Yubikey, with the subject “CN=cornelius” and access the Yubikey with the PIN “123456”. The CSR and the attestation certificate will be sent to privacyIDEA at “https://localhost”, the admin will authenticate as user “super” with the password “test” and enroll the certificate to the user “cornelius”. privacyIDEA will verify the attestation certificate, sign the CSR and the certificate will be imported to the Yubikey.

Note: If you have problems enrolling and try to reenroll, you might need to delete temporary files _*.

You can now use the Yubikey with the certificate on it to sign emails or login to your Desktop. As mentioned, this can be a topic for future blog posts.

Conclusion

We showed here how an administrator can enroll a Yubikey with an x509 certificate to a user. At the same time privacyIDEA ensures, that the private key is really generated on the Yubikey. This is an important aspect, when using smartcards for authentication. This ensures, that the private key is unique and can not be copied, neither during the enrollment process nor lateron, making the smartcard a unique authentication factor.

The same way, a user could issue a CSR that was generated on a smartcard to privacyIDEA, making the enrollment process more robust.

This is an important fist step for privacyIDEA to deal with smartcards. We will continue working on smartcard functionalities, smoothening the workflow and enhancing policies.

In an enterprise environment managing x509 certificates and smartcards on a central location is crucial. The Yubikey could contain several certificates. It can contain Webauthn profiles or HOTP slots. If a Yubikey is lost, the service desk should be able to revoke the one hardware key and the central management should know, which certificates and which HOTP slots are affected. With privacyIDEA we are working on this, to ease the life of administrators and service desk users.

We will use the privacyIDEA logging facility to let the server not only store its system logs and audit locally but also feed them to a remote Logstash server. We will also show how to use the new Logging module of the Event Handler, introduced in privacyIDEA 3.3, to customize the logged information. The usual path of information is displayed in the following picture.

Setup the Base System

As the installation Logstash, Elasticsearch and Kibana is documented at the vendors website, we will not go into detail here. In any case, you need a java runtime environment. For Ubuntu you can use the package default-jre. Once you have the elastic stack up and running, turn towards privacyIDEA.

The installation of privacyIDEA is documented at privacyidea.readthedocs.io. For a quick start, there is a community package repository for Ubuntu 18.04 LTS available. Install the privacyIDEA server and become a little familiar to the WebUI, which is the primary management interface.

The base configuration of privacyIDEA is set in the configuration file pi.cfg and the dedicated logging configuration file logging.cfg or logging.yml. In the default Ubuntu 18.04 package installation, those are located in /etc/privacyidea/. To be able to view the audit logs in the WebUI and send them at the same time to the python logger, the ContainerAudit module is used.

# /etc/privacyidea/pi.cfg
PI_AUDIT_MODULE = 'privacyidea.lib.auditmodules.containeraudit'
PI_AUDIT_CONTAINER_WRITE = ['privacyidea.lib.auditmodules.sqlaudit','privacyidea.lib.auditmodules.loggeraudit']
PI_AUDIT_CONTAINER_READ = 'privacyidea.lib.auditmodules.sqlaudit'
PI_AUDIT_LOGGER_QUALNAME = 'pi-audit'
PI_LOGCONFIG = '/etc/privacyidea/logging.cfg'

Note that we use a custom audit logger name “pi-audit” in the above configuration. See the documentation of the Logger Audit.

Send privacyIDEA logs to Logstash

The logging module privacyidea.lib.auditmodules.loggeraudit sends the audit messages to the python logging system and makes it available to the configuration by logging.yml. To send both the privacyIDEA server logs and the audit log to Logstash, the module python-logstash-async comes in handy. It can be installed through pip by

~$ pip install python-logstash-async

The module can be used in a logging.cfg or logging.yml in YAML and INI format respectively. Minimal examples for the configuration of the logstash-async module are found on Github Gist. A more detailed YAML configuration file is also available, which provides a good basis for this test case.

Restart privacyidea for the changes to have effect. If you used the extended configuration from gist, you should now see the audit log in /var/log/privacyidea/audit.log.

Receive privacyIDEA logs with Logstash

On the other end, Logstash is configured to listen on port 5959 and to forward the logs to Elasticsearch using different indices for the qualnames pi-audit, pi-eventlog and all the rest (privacyidea.*).

# /etc/logstash/conf.d/privacyidea_elasticsearch.conf
# privacyIDEA input is logged by the python-logstash-async module
input {
   tcp {
      port => 5959
      codec => json
      tags => ["privacyidea"]
   }
}
# filter adds metadata field according to logger to
# separate the privacyIDEA audit log from the rest
filter {
   if [extra][logger_name] == "pi-audit" or [extra][logger_name] == "privacyidea.lib.auditmodules.loggeraudit" {
      mutate { add_field => { "[@metadata][indexPrefix]" => "pi-audit" } }
   } else if [extra][logger_name] == "pi-eventlog" {
      mutate { add_field => { "[@metadata][indexPrefix]" => "pi-eventlog" } }
   } else {
      mutate { add_field => { "[@metadata][indexPrefix]" => "privacyidea" } }
   }
}
# Logs are sent to elasticsearch using the indexPrefix
output {
   elasticsearch {
      index => "%{[@metadata][indexPrefix]}-%{+YYYY.MM.dd}"
   }
   # additional output to syslog
   stdout {
      codec => rubydebug
   }
}

Restart logstash afterwards. The output section contains an additional part for logging to stdout. On a systemd-driven system (check ~$ ps -p 1), it can be viewed by

~# journalctl -f -u logstash

Once you interact with the privacyIDEA server, you should see the incoming audit log messages in json format in the journalctl ountput on the logstash machine. The example below is the audit message for viewing the audit log in the privacyIDEA WebUI:

{
          "extra" => {
                    "logger_name" => "pi-audit",
                   "process_name" => "MainProcess",
                    "thread_name" => "MainThread",
                           "line" => 85,
         "logstash_async_version" => "1.6.4",
                           "path" => "/opt/privacyidea/privacyidea/lib/auditmodules/loggeraudit.py",
                      "func_name" => "finalize_log",
                    "interpreter" => "/opt/privacyidea/venv/bin/python",
            "interpreter_version" => "3.6.9"
     },
          "level" => "INFO",
        "program" => "/opt/privacyidea/pi-manage",
           "port" => 47962,
            "pid" => 10047,
      "logsource" => "myhost",
     "@timestamp" => 2020-03-25T15:32:42.748Z,
       "@version" => "1",
           "type" => "python-logstash",
        "message" => "{'success': True, 'serial': '', 'user': '', 'realm': '**', 'resolver': '', 'token_type': '', 'client': '127.0.0.1', 'client_user_agent': 'firefox', 'privacyidea_server': 'localhost:5000', 'action': 'GET /audit/', 'action_detail': '', 'info': '', 'administrator': 'admin', 'policies': '', 'timestamp': datetime.datetime(2020, 3, 25, 15, 32, 42, 748526)}",
           "host" => "henning-t470"
 }

Display privacyIDEA logs with Kibana

The logs received by Logstash are sent to Elasticsearch which talks to the Kibana instance. The Elasticsearch indices should appear in Kibana’s index management, available from the home screen.

The privacyIDEA indices will look like shown below.

Note: the yellow health status is due to a default index setting "index.number_of_replicas": "1". Changing it to zero will result in a green status. Under “Data Views” create a new data view with the index-pattern “privacyidea*,pi-audit-*,pi-event*”.

In the Logs view, select the privacyIDEA data view you can select the log columns (“selected fields”) to be shown. The privacyIDEA log messages are now nicely displayed.

Don’t forget to save!

Event-based logging from privacyIDEA to Logstash

New in privacyIDEA 3.3 is the Event Handler module “Logging”. With this module, custom logging messages can be bound to any event. This opens the door to a whole new world of monitoring possibilities in privacyIDEA. To demonstrate the feature, we simply log whenever a token is disabled — a silly example, of course. The Event Handler is created as shown below.

For the Logging module, only one action is available. The log level, the name of the logger and a custom message are required. The message field supports variables known from the user notification module (see documentation). Note, that it depends on the context of the RESTful API event if a certain variable is available or not.

The chosen logger name has to be added as a logger in logging.yml to send it to Logstash.

loggers:
  pi-eventlog:
    handlers:
      - logfile
      - logstash_async
    level: DEBUG

Restart privacyIDEA to apply the changes in the config file logging.yml. After triggering the event by disabling a token in privacyIDEA, Kibana shows the notification.

Of course, you can use the logging event handler for more reasonable purposes like not to send the full audit log to logstash but to single-out the important validate-check events. You can even apply some more conditions, if you like making use of the powerful condition properties of the privacyIDEA Event Handlers. This not only spares bandwidth and storage space but prevents important information to be buried by other data. The message field in privacyIDEA can be used for a custom log message with contextual information. The configurable logger name (e.g. pi-validate-check) provides an additional identifier. In the case of suspicious behavior or a security incident, all the information is there to quickly track down the threat.

Conclusion

With this demonstration of the logging facility, privacyIDEA proves again to be extraordinarily scalable. It integrates well with logging systems like Logstash and Splunk since the privacyIDEA server builds on the standard python logging library. For Logstash, this article showed the detailed steps how to integrate privacyIDEA via the loggeraudit and a small third-party python module called python-logstash-async.

In privacyIDEA 3.3 the logging capabilities have been further extended by an Event Handler module which enables to conditionally log arbitrary events to the python logging system. We showed that also these messages can easily be passed to Logstash and open a vast playground custom logging.

The solution shown here is only one possible approach. Since privacyIDEA is available as open source an licensed under the AGPL, another possibility would be of course to write your very own logger module to do whatever you want. privacyIDEA is and will be always open source and therefore it will always stay in your hands.

If you would like to have a custom logger module, but have no time to implement it yourself, you can always request a quote from Netknights, the company which drives the privacyIDEA innovation via Github. They also provide professional support for privacyIDEA, including enterprise repositories for Ubuntu and CentOS/RHEL containing the server and a number of additional components and tools.

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.

However with iOS devices things are a bit more complicated and additional steps have to be taken. These additional steps are described in this blog post.

Apple push apps – different than Android

The Firebase service can not directly push to apple devices. Instead, the Firebase service pushes to the Apple Notification Service. While Android allows an app to be connected to different Firebase projects, an iOS app with it’s app identifier can only be connected to one Apple Push project.

What does this mean?

For the Android devices you created a Firebase project. Your own Firebase project. You configure the data in the privacyIDEA server and the information about the Firebase project is passed to the privacyIDEA Authenticator for Android during the rollout process. This means that a privacyIDEA installation running with organization A connects the push tokens to their own Firebase project and organization B will connect their push tokens to a totally different own Firebase project.

Unfortunately this is not possible with the Apple Notification Service. NetKnights, the company behind privacyIDEA, created one Apple Notification Service project. The secret push key of this project is connected to the app identifier “privacyidea.authenticator” of the privacyIDEA Authenticator App for iOS. The privacyIDEA installation in organization A sends the push notification for an iOS device to the organization’s own Firebase project, but then the Firebase project will forward the notification to the general Apple Notification Service project. This second step will be the same for all Push notifications to iOS devices connected to any privacyIDEA installation on this planet. This probably arises from Apples cloud-centric idea, that probably an app will only receive notifications from one central cloud service.

However, during enrollment of the iOS privacyIDEA Authenticator the app sends a random device identifier to your privacyIDEA server. Your privacyIDEA installation then uses this random identifier to send the push notification to this very device. It seems unlikely for another privacyIDEA installation to guess the device identifier of a foreign Apple device. If an attacker was able to guess a random device identifier the attacker could send arbitrary notifications to the iOS device. But in addition the iOS privacyIDEA Authenticator is also registered to your own Firebase project. This means, that the attacker indeed could send an arbitrary notification but such notification would not be processed by the privacyIDEA Authenticator.

If you do not like this (which we would understand) you need to recompile the privacyIDEA Authenticator for iOS with your own Apple Notification Service project, with your own Apple developer account, your own certificate and push notification key and with your own app identifier. Just like all other privacyIDEA code, the privacyidea-authenticator-ios is available on github.

NetKnights hopes to be able to provide customization services one day to create customer specific apps as part of a privacyIDEA Authenticator Enterprise Edition, to circumvent this problem.

After this lengthy disclaimer lets now connect Firebase with the Apple Notification Service especially with the privacyIDEA Authenticator.

Note: This howto discloses the secret project key, which is needed so that Firebase can send messages to the Apple Notification Service. This means, that an attacker could – after successfully guessing a device identifier – potentially spam messages to devices connected to the privacyIDEA Apple Notification Service. However, the impact on login security is none, since all messages are digitally signed in both directions. Again: This downside is due to the cloud-centric design or the Apple Notification Service and can only be avoided by compiling your own Authenticator app and publishing it to the Apple app store.

But let’s do the iOS device, now!

Add new Firebase App

In the Firebase console, you need to create a new App in your Firebase project. Do so so click the button “+ Add app”.

The new app you want to create, is an iOS app. So click the round button “iOS”.

In the app registration dialog you need to create an iOS bundle ID. Creating a nickname is optional. For the bundle ID you need to enter “privacyidea.authenticator”. Choose a nickname to your likings.

In the second step of the app registration you need to download the plist file. Save it for later, you need to enter the settings from within this file in your privacyIDEA policy.

In the third step you do not need to take any actions. You do not bother with the SDK, since the privacyIDEA Authenticator iOS app already exists!

Also in the next step you do not need to take any action. Simply press “Next”.

Now you are done registering your iOS app and you can “Continue to console”.

Adding the secret iOS Authentication key

After you have told the Firebase service, that also iOS devices are going to connect to it, you now need to tell Firebase, how it can talk to the Apple Notification Service. For this you need the secret key we talked about at the beginning of this article. If you do not want to compile your own app and publish it in the app store, you unfortunately have to share the “secret” key with all other default installations of privacyIDEA. Download the secret key file to your computer and save it for later.

Still in the Firebase console, first go to the “Project settings” in the upper left corner

In the “Settings” go to the tab “Cloud Messaging”.

In “Cloud Messaging” you will find the “iOS app configuration”. There you can hit “Upload” to upload the secret key file.

Now select the secret key file (AuthKey_2FZRBAT74S.p8) to upload it to the Firebase console.

Enter the Key ID (2FZRBAT74S) and Team ID (627QALYL3B) exactly as stated in the image below.

After hitting the “Upload” button you should be fine and your Firebase Push Service is connected to the Apple Notification Service for the privacyIDEA Authenticator iOS App.

Configure iOS Authenticator in privacyIDEA

Now open the plist file you saved earlier. Find the entries API_KEY and GOOGLE_APP_ID. It will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        ...
	<key>API_KEY</key>
	<string>example-key_value</string>
        ...
    	<key>GOOGLE_APP_ID</key>
	<string>1:example:ios:appid</string>
</dict>
</plist>

You need to enter the value “example-key_value” in apikeyios and the value “1:example:ios:appid” in appidios.

Now you are ready to register iOS devices with your privacyIDEA Push setup and use your iPhones to authenticate via Push notification.

If you want to stay tuned for the enterprise edition, please consider contacting the company NetKnights.

We learnt this in a lot of set ups and are claiming it since 2018 at the LinuxFest North West. One-solution-fits-all does not work out! Nowadays a company or organization wants to deploy 2FA to not only secure a certain login to a certain application, but also wants to have secure workflows around the authentication process. Thus the perfect 2FA or MFA software needs to adapt to the needs of such company or organisation.

The beauty of the event handlers

privacyIDEA introduced the Event Handlers already in version 2.12, May 2016. The script event handlers, which I want to talk about today, followed in version 2.17, December 2016.

Event Handlers were used quite actively since then. Only the script handles seemed special and awkward. It has been quiet around this one for a while. But recently a comment and question of a German partner (IT-Schmid), who was implementing a roll out concept for a customer, caught my attention and reactivated the thinking about the beauty of the script handlers.

privacyIDEA is implemented in a very modular way – on a horizontal but also on a vertical level. Database level, library level, the REST API and the Web UI are different, separated parts. And this helps us a lot with the script handlers. It is easily possible to write python scripts, that are using the library level, without the need to issue REST Requests that are processed through the web server. This improves performance of such scripts and it gives you access to ready made library functions, that allow you to address tasks with a few lines of code.

Script collection at Github repository

We realized, that it makes sense to provide a collection of example scripts, to give you a better understanding, what scripts can do and how this could be done. A new repository has been added at Github to host such example scripts. The first script is a script is a few lines, that can reassign a token from a username in one realm to a username in another realm. This can be a useful step during more complex rollout scenario. But automating such tasks of course reduces complexity and efforts to be taken.

We are happy to receive ideas and pull requests with new interesting scripts, which could enhance the scenarios with privacyIDEA to unexpected widths.

Visit our community forum for further discussions!

In Version 2.0 the privacyIDEA Authenticator implementes the Push Token. During Rollout the Push Token exchanges asymmetric keys between the privacyIDEA Server and the privacyIDEA Authenticator.

During authentication the privacyIDEA Server sends a cryptographic challenge via Firebase to the smartphone. The privacyIDEA Authenticator verifies the signature of the privacyIDEA Server and asks the user to confirm the login request. The App then signs the challenge and sends it back to the privacyIDEA Server.

The internals are described at our github wiki page.

Join the Beta Test

The privacyIDEA Authenticator 2.0 is available for Android phones at the moment. iOS will follow shortly.

We are happy if you want to participate in the public beta test. Simply go to this site and follow the steps to join the beta test. You can install the privacyIDEA Authenticator 2.0 on your Android device (Minimum version “kitkat” – we do not recommend this!

Set up for your tests

In this blog post we want to give you an overview to get started. For a deeper understanding you can read more about the push token in the online documentation and at github.

Get components

Get privacyIDEA 3.0 and the privacyIDEA Authenticator 2.0.

Network connectivity

Assure, that your smartphone can reach your privacyIDEA server, e.g. by placing your smartphone in the same Wireless LAN like your privacyIDEA Server. The smartphone needs to connect to privacyIDEA during enrollment and during authentication.

Firebase project

In the Firebase console you need to create your own Firebase Cloud Messaging project.

From the console you can download the relevant project information.

The relevant information is the “Web API Key”, “App ID”, “Project ID” and the project number, which is the number part of the “Public-facing name”. Copy these values to create a new provider in privacyIDEA.

Download the file google-services.json and fetch the values “project_number”, “project_id”, “mobilesdk_app_id” and “api_key” from this file.

In addition you need to create a new service account for your Firebase project:

You can download the settings of this service account in a JSON file, which you need to copy to the privacyIDEA machine and later add in your privacyIDEA SMS Provider in the next step.

Firebase SMS Provider

In privacyIDEA you need to create an “SMS Gateway” of type “Firebase” with the Firebase project you created in the previous step. The privacyIDEA Server will connect to Firebase with this project.

Enter the data and json file, you downloaded from the Firebase console. E.g. the JSON config file needs to be copied to the privacyIDEA Server and you need to specify a local path on the privacyIDEA Server.

Finally you also need to enter the registration URL. This is the URL of the privacyIDEA Server which the privacyIDEA Authenticator contacts during the enrollment process. So you need to be sure, that this URL is in a format (FQDN, IP), which the smartphone can connect to. Unless you know otherwise the path or the URL should be /ttype/push.

Policies

Now you need to configure your privacyIDEA system. You need to create two policies, one for the enrollment and the other one for the authentication.

The enrollment policy contains the name of the Firebase SMS Provider you created in the previous step.

The authentication policy can contain the text, that should be displayed in the notification:

Testing

You can now test you setup by

1. Enroll a new Push token and assign it to a user. Give the Push token a PIN.
2. In your browser you can simply issue an authentication request using the API https://your.privacyidea.server/validate/check?user=testuser&pass=yourpin
3. You should receive a notification on your enrolled smartphone, which you can confirm.

Your help and feedback

The missing link currently is the Application that is supposed to poll for the confirmed authentication.

We need your feedback, to know on which application we should start working first. As an alternative we are also planning to add a delayed response.

Event handlers are really very flexible and provide you with a lot of possibilities, we did not think of, when we developed them. In this blog post we show you, how you can use event handlers to reset this failcounter.

To do so, we use two event handlers. The first one we call “Write Authentication” the second one “Reset Failcounter”.

First event handler to store the authentication date

The first event handler stores the date when the failcounter is allowed to be reset again. It does this on every authentication request. I.e. each authentication request pushes a blocked token forward in time. An attacker would increase this date of the token even while the token is blocked. (You could change this behavior by adding more logic to the event handler).

The event handler “Write Authentication” is a token handler and does not need any additional conditions. It is important that you provide a higher order to this event handler. In this case we set the “Order” to “2”.

The Actions of the event handler look like this:

This event handler sets a “tokeninfo” entry on each authentication request. The key of the tokeninfo is “allow_counter_reset”. The value is the current time (“{now}”) plus certain minutes. So this is a timestamp in the future, when the failcounter should be allowed to reset.

Second event handler to reset the failcounter

The second event hanlder is actually ment to reset the failcounter.

Note, that the order (priority) must have a lower value than the first event handler. This way this reset event hanlder gets executed before the event handler, that sets the timestamp!

The conditions of this event handler now check for the timestamp we set in the first event handler:

This event handler will trigger, if the token is locked (the failcounter has reached the maximum value) and the tokeninfo “allow_counter_reset” lies in the past. I.e. the specified minutes in the first event handler are actually over.

The action of this event handler simply resets the fail counter:

Effective behaviour

An authentication request, that occurs after the specified time will actually reset the failcounter. But since this event handler can only be executed after the authentication request, an authentication request with a valid OTP value will reset the failcounter, but it will not succeed, since the request has already been handled.

Thus a user has to authenticate twice to first unlock the token and then to actually successfully authenticate.