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.

An authentication processing filter is one step of the login process in simpleSAMLphp.
For example it can be useful, if you want to authenticate the first factor against LDAP and the second one against privacyIDEA.
If you enable privacyIDEA as an authsource, both factors will be authenticated against privacyIDEA.

With privacyIDEA as an authproc filter, you are much more flexible. You can expand and individualize the authentication process in many different ways. In this how-to we want to explain some of the features and show how to configure it in the best way.

How to setup privacyIDEA as an authproc filter

Authproc filters are configured in config.php (to use them every time) or in the metadata (to use it only, if the user comes from a specific service provider for example). Every authproc filter is listed in an array with a number, which shows the priority. The lowest number begins the login process.

privacyIDEA without special features (necessary)

'authproc' => array(
  20 => array(
    'class'             => 'privacyidea:serverconfig',
    'privacyideaserver' => 'https://your.privacyidea.server',
    'realm'             => 'realm1',
    'uidKey'            => 'uid',
    'sslverifyhost'     => true,
    'sslverifypeer'     => true,
    'serviceAccount'  => 'service',
    'servicePass'     => 'service',
  ),
  25 => array(
    'class'             => 'privacyidea:privacyidea',
  ),
),

This configuration enables the authentication against privacyIDEA. The first factor will be authenticated against the authsource (e.g. LDAP) and the second one against privacyIDEA.

• class: this enables the authproc filter. (Do not change it)
• privacyideaserver: here you can enter the url of your pricacyIDEA server
• realm: enter the user’s realm name
• uidKey: privacyIDEA has to know in which attribute the username is stored (it depends on your authsource)
• sslverifyhost: Check if the hostname matches the name in the certificate (set to true or false)
• sslverifypeer: Check if the certificate is valid, signed by a trusted CA (true or false)
• serviceAccount: The service account’s username
• servicePass: The service account’s password

Disable 2FA for users with specified ip addresses (optional)

You can disable 2FA for users with a special ip address (e.g. your local area network).
To do that, you have to enable and configure the authproc filter privacyidea:checkClientIP

21 => array (
  'class'             => 'privacyidea:checkClientIP',
  'excludeClientIPs'  => array("10.0.0.0-10.2.0.0", "192.168.178.10"),
),

This array has to be in the authproc array, which is mentioned above.

• class: this enables the authproc filter.
• excludeClientIPs: You can enter a single ip address or a range. These clients will not be asked to do 2FA.

Enroll new token, if the user does not have one (optional)

If a user does not have a second factor yet, it can be enrolled by simpleSAMLphp. To do that, a service account has to be configured and enabled. This can be done either above in privacyidea:privacyidea or here in privacyidea:tokenEnrollment)

24 => array(
  'class'           => 'privacyidea:tokenEnrollment',
  'tokenType'       => 'totp',
)

• class: this enables the authproc filter
• tokenType: Here you can enter the token type. It can be hotp or totp

You can overwrite the settings from privacyidea:serverconfig, if it is necessary. For example you can change the serviceAccount and servicePass. You only have to add it in this array.

Well, you might know, that privacyIDEA can do all this. Then you are welcome to skip this blog post and visit the privacyIDEA community to help answering questions there. Thanks a lot! If not – go on reading!

The tokeninfo table

Every token has its own Tokeninfo table, that can hold any additional arbitrary information. In the UI it looks like this:

It tells us that the used hashlib is “sha1” and the token was used 3 times for authentication.

On the database level the tokeninfo is a table on its own, which means that every token can hold as many token information as it needs to:

It does not matter where and how you add tokeninfos to this table. privacyIDEA will use them.

privacyIDEA knows some default or preserve keywords, for which it is using the tokeninfo table. This is the validity period of a token, that is denoted with “validity_period_start” and “validity_period_end”, the “count_auth” or “count_auth_success” and also markes that define for how many authentications a token can be used.

But you can also set any other value.

Event Handler and tokeninfo

There are probably many ways to set tokeninfo fields, but obviously the most interesting way is the event handler. If you do not know the event handler yet, you can either read about it in our blog or in the online documentation.

Using the Token Handler you can set a tokeninfo field during any REST API call. You could e.g. set a tokeninfo field “enrollment_date” and hook it to the event /token/init.

As mentioned, you can set any arbitrary tokeninfo field. In this case we set the “enrollment_date” to the current time. The timestamp of the current time will be saved in the token info.

Well, why not immediately and automatically set the validity period? No problem: The value can not only use tags, but also some other magic:

Setting the value of “validity_period_end” to “{current_time}+12” will result in a timestamp, that is 12 days in the future. Combining this with the reserved key “validity_period_end” we can automatically enroll tokens, that are only valid for 12 days!

How to use tokeninfo fields

privacyIDEA knows how to use the preserved tokeninfo fields. These actions are hard wired into the code.
Of course you can use any arbitrary field simply to pass information to a help desk employee or to store some notes. But there are again at lease two interesting way how to automatically use the tokeinfo field.

Again the event handler

Again – you can use the tokeninfo field with the event handler. But this time as a condition. For any REST API call you can check the tokeninfo field of the token involved. And if any arbitrary (I like this word!) tokeninfo field matches your condition, you can trigger a new action.

A condition could be anything or a fixed timestamp but also – again – “{now}”:

This way we can check if the tokeninfo field “validity_period_end” has a youger timestamp than the current moment. Only if the condition applies the defined action will be triggered.

But often “now” is not the right moment!

In this example the action will only trigger, if the “enrollment_date” is older than one week. You can use the tag “{now}-7d” which will result in a timestamp of last week!

Combined with the event handlers for notification, scripting, token handling or federation the administrator can probably define anything and automate a lot of processes!

Clean it! The token janitor

There is also another way of using the tokeninfo fields. It is the tokenjanitor script.

The privacyidea-token-janitor runs as a script from the command line and find specific tokens and perform actions on these tokens. It was first used to find orphaned tokens and possibly delete these orphaned tokens.

But of course the token-janitor can find tokens based on may conditions – also based on the tokeninfo field.

This way the administrator can use the tokeninfo field to mark tokens and e.g. delete all marked tokens. The condition can also be a timestamp in the tokeninfo field. Actions can also be to disable or enable a token or only to mark this token (in the tokeninfo field).

If you thought privacyIDEA is cool – you may realize you were wrong.

privacyIDEA is extremely cool!

So use it! – share your ideas at the community or enlighten use with your pull request at github!

If you also want to be cool – you may also apply for a job at the cool guys!

So learn more about the unlimited power of the event handling framework and how to use its flexibility to get a privacyIDEA setup, which fits your needs.

Event Handling Framework

When speaking of software or products the term “framework” might raise a connotation of “you have to do it yourself”, “things are not ready”, “the software is not usable”.

A javascript framework can help you to develop cool web front ends. A python framework can be the basis for developing microservices and the framework Qt still requires the developer to develop the real program with the business logic.

When speaking of the Event Handling Framework things might similar: We the developer do not know how you want to use privacyIDEA and thus we give you the biggest flexibility. We have not thought of all possibilities in which you – the administrator – could use this framework! So you can come up with usage scenarios or configuration combinations noone has ever seen before!

But when speaking of the Event Handling Framework things are a bit different: You do not have to be a developer to solve your ideas or have privacyIDEA run the way you want it to.

Using the Event Handling Framework you can get the highest flexibility out of a state of the art authentication server, just by easily configuring rules in an easy web interface.

The basic concept of Event Handlers

A top level view

Each API request is an event:

• An authentication request,
• the request to issue a token,
• to block a token
• or unassign a token.
• If a user logs in to the Web UI, this is an API request…

You can see the full list of all API calls here.

The Event Handling Framework allows the administrator to “attach” new actions to each and every API call/event. It roughly works like this:

event -> condition -> action

Conditions

But these actions are only triggered in case a list of conditions evaluate to true.  Conditions can be:

• if an authentication request was successful,
• if the role of the user in the request was “administrator” or “user”,
• if the token used was of a certain type
• but also more complex conditions like if a date contained in a tokeninfo field of the used token is before or after a certain timestamp or of a certain age.

There are currently 14 different, sometimes rather complex conditions and the number is growing.  For a full list of conditions see the online documentation.

Actions – The Event Handlers

Actions are performed by the event handlers. Currently there are three “groups”: Notifications, Token actions and scripts.

Roughly speaking the Notification actions will automatically notify administrators or users in case of certain events and if certain conditions apply. Notification can be done via email or SMS.

The administrator can also define that Token actions will happen. These are roughly all actions on tokens you can think of: enable, disable, set description and validity period, set abitrary tokeninfo fields, delete tokens and even enroll new tokens! This is probably the most important handler for automating tasks which e.g. can help large organizations with enrollment processes.

Finally there is the Script Handler, which can trigger shell scripts. The privacyIDEA administrator can write and define any number of shell scripts and thus gets unlimited possibilities. The usual use case we think about might be running backups or cleaning up orphaned tokens. But you will have probably a lot of other ideas.

Examples

Some of these examples might occur to you a bit far fetched. But after all these are examples of what is possible. So you may come up with your own scenarios which very probably will also work out nicely.

Notify the user in case his password is breached

The notification event handler can send an email or an SMS to the user, if “he” fails to authenticate. This way the user knows, if someone else tried to authenticate.

This can be combined with the condition of the tokentype. The tokentype is only known (and thus only the event handler will trigger) if the OTP PIN a.k.a. static password of the user is correct. Thus the user gets notified if someone guessed or sniffed his static password but fails at the second factor.

Limit token usage

If for any reason you need a token, that the user is only allowed to use for a limited time. E.g. the user would only be allowed to login 100 times.

You can create an event handler definition in the token handler to disable the token, if it either was successfully used more than 100 times or it was unsuccessfully used more than 50 times. (To whoever this may concern).

Automatically Unlock locked tokens

Starting with privacyIDEA 2.20 (currently under development) you can also use timestamp tags in the tokeninfo condition and settings. I.e. if one event occurs, the token event handler can use the “set tokeninfo” to set additional information like tokeninfo key=locked and tokeninfo value={now}. The tag “now” will be converted to the current timestamp. This action could be called on a failed authentication request. You could also mark the token for any other reason.

A second event handler can check for this timestamp. I.e. the condition can verify if the timestamp is past – lets say – one week/7 days. In this case a second action like unlocking the token can be performed.

This can be achieved by using the tokeninfo condition. This check can also check strings, integers and dates for being less, equal or greater. This helps to easily automate many tedious tasks.

Under the hood

The online documentation should contain the full developer view of the event handlers.

Decorators

privacyIDEA is based on the python framework Flask and uses a lot of decorators to structure code, reduce lines of code and improve testability. The event handler adds one decorator “@event”. E.g. this decorator decorates the endpoint “/validate/check”.

The decorator takes care of registering this endpoint in the event handler framework but also calling possible actions.

Event Handler Class

Each event handler (Notification, Token Handler, Scripts) is a python Class, that inherits from the Base Handler. Each handler could define its own conditions and its own actions and thus can work self-contained and add any functionality to privacyIDEA.

Do actions

As the event handler like the Token Event Handler use already existing code for diabling or enrolling tokens, these eventhandlers are relatively small and stable. E.g. the token event handler is roughly 100 lines of code defining the allowed actions and another 100 lines of code for calling existing lower level functions.

This is done in the main function “do” of the event handler.

Conditions

Each event handler could also define its own conditions, if this is necessary or makes sense. But for now all conditions are the same for all event handlers and thus only the base event handler class implements the method “check_conditions“.

Finally

Adding event handler definitions is a matter of a few clicks for the administrator. But it is a great step for the automation of your privacyIDEA installation.

Adding a new event handler class is also only a matter of inheriting the base handler class and starting with woughly 50 lines of code. The hardest thing is to come up with a new idea! But the only limit is your imagination!

If you can not attend or if you want to try this at home afterwards, here is what we will do!

Setup

10.0.2.201 ucs.tuebix.intranet (LDAP) Univention Corporate Server 4.2
10.0.2.202 privacyidea.tuebix.intranet, Ubuntu 16.04 LTS
10.0.2.203 wordpress.tuebix.intranet, Ubuntu 16.04 LTS with latest wordpress
10.0.2.204 owncloud.tuebix.intranet, Ubuntu 16.04 LTS with ownCloud 10

LDAP

BaseDN: cn=users,dc=tuebix,dc=intranet

The UCS has the following users:

• admininistrator
• user1
• user2
• user3

ownCloud

ownCloud is connected via LDAP, so the LDAP users can connect to ownCloud.

The ownCloud Administrator is called: admin

WordPress

WordPress only has internal users. Nevertheless the user are also called:

• administrator
• user1
• user2
• user3

What we will do – our Agenda

• We will install privacyIDEA and connect privacyIDEA to the UCS, so that privacyIDEA knows the users from the LDAP directory
• Then we will enroll different kind of tokens to the users.
  • The administrator can enroll a token for the users but
  • users can also login to the webui with their LDAP password an enroll a token for themselves.
• Then we start connecting applications to privacyIDEA to add 2FA to the applications
  • WordPress with “strong authentication” plugin
  • ownCloud with the “privacyIDEA ownCloud App” from the market place
  • SSH login with 2FA for users user1, user2, user3

privacyIDEA

Install

privacyIDEA can be installed in many different ways on different Linux distributions. We will install privacyIDEA on our Ubuntu 16.04 machine 10.0.2.202.

As root:

add-apt-repository ppa:privacyidea/privacyidea

apt update

apt install privacyidea-apache2

privacyidea-apache2 is a meta package which will install MySQL, Apache and set up privacyIDEA. Finally we only need to create the first token administrator.

pi-manage add admin super

Now we have an administrator called “super”

Configure

privacyIDEA can be configured via command line, API or the web UI.

https://10.0.2.202

We need to configure the Resolver tuebix_users as Active Directory. For this we need to fetch the certificate of the UCS server.

• LDAP Resolver to ldaps://ucs.tuebix.intranet
• Base DN cn=users,dc=tuebix,dc=intranet
• Bind DN cn=administrator,cn=users,dc=tuebix,dc=intranet
• Preset AD

And a Realm tuebix with the resolver tuebix_users.

We can also take a look at the policies and configure a policy to use otppin=userstore.

Enroll tokens

Enroll tokens as administrator and as normal user…

• Enroll Smartphone App
• Yubikey
• U2F Token
• Feitian C200 (import File Feitian.csv)

ownCloud with 2FA

For ownCloud X we login as administrator and install the “privacyIDEA ownCloud App” from the Marketplace.

We need to configure the App against privacyIDEA:

• https://privacyidea.tuebix.intranet
• no realm
• no ssl check

Note: The privacyIDEA ownCloud App will authenticate all users with a 2nd factor!

After this, users need to present a 2nd factor against privacyIDEA when they log in.

WordPress with 2FA

Install the “strong authentication” plugin.

We need to configure the Plugin against privacyIDEA:

• https://privacyidea.tuebix.intranet…

Note: Users need to enter both factors in the password field at the same time.

The WordPress plugin authenticates users only against privacyIDEA; while with ownCloud users are authenticated by ownCloud and by privacyIDEA.

SSH with 2FA

On either owncloud machine or wordpress machine we install the privacyIDEA PAM module:

add-apt-repository ppa:privacyidea/privacyidea

apt update

apt install privacyidea-pam

…and configure it accordingly against https://privacyidea.tuebix.intranet.

Note: Users need to match!

privacyIDEA LDAP Proxy

Bonus!

Download and create VM

Download the privacyIDEA image. This is a ready installed privacyIDEA Authentication Server on a Ubuntu 16.04 LTS system. The qcow image is supposed to run in KVM.

First you need to unpack the image:

lzma -d privacyidea-template-1604.qcow2.lzma

Now you can create a new Linux virtual machine version “Ubuntu 16.04” with this very image as hard disk and you can boot the machine.

Configure and getting started

You can login using the root account with the password “privacyidea”.

The ethernet interface is configured as DHCP, so the machine might like your network directly. OpenSSH is installed, so that you can also login remotely.

privacyIDEA is installed with the Apache2 Webserver.

You probably should reset the root password! Here are further necessary steps you might want to take:

apt update

apt upgrade

Then you should reset the password of the token administrator “super”:

pi-manage admin add super

Now you can login at the WebUI and start configure user sources and enrolling tokens.

This is a demo version with pregenerated keys! You should NEVER use this system in productive environment!

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.

privacyIDEA REST API

privacyIDEA provides a great and simple REST API which lets you automate and integrate all tasks into other workflows. In fact the privacyIDEA Web UI as a single page application uses this REST API. Thus you could easily open the developer tools of your browser and monitor the HTTP requests that are sent.

Authenticating a user

A user needs to authenticate at the Web UI and also at the REST API. This is done by issuing the request

POST /auth

The auth request takes the username and the users password. Which password the user needs to provide, depends on the login_mode policy in the WebUI scope. The auth request returns an authorization token which needs to be added to each subsequent request.

You can also issue a test request using httpie from the command line like this:

% http --verify no --pretty all --json POST https://localhost/auth username=secureuser password=test
/usr/lib/python2.7/dist-packages/urllib3/connectionpool.py:794: InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.org/en/latest/security.html
 InsecureRequestWarning)
HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: keep-alive
Content-Length: 843
Content-Type: application/json
Date: Tue, 01 Nov 2016 07:28:55 GMT
Server: nginx/1.10.0 (Ubuntu)

{
 "id": 1, 
 "jsonrpc": "2.0", 
 "result": {
 "status": true, 
 "value": {
 "default_tokentype": "totp", 
 "log_level": 30, 
 "logout_time": 120, 
 "menus": [], 
 "policy_template_url": "https://raw.githubusercontent.com/privacyidea/policy-templates/master/templates/", 
 "realm": "secure", 
 "rights": [], 
 "role": "user", 
 "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InNlY3VyZXVzZXIiLCJub25jZSI6IjQyYjhhMWIzNDEzYTA5ZmQzMDljMDI3NzY3Mjc4N2I5MmFiNWI2ZWUiLCJhdXRodHlwZSI6InBhc3N3b3JkIiwicmVhbG0iOiJzZWN1cmUiLCJyaWdodHMiOltdLCJyb2xlIjoidXNlciIsImV4cCI6MTQ3Nzk4ODkzNX0.vCXNNV4Bmt2UuC0FMuc2qMbr8i_8zweROadvfLYcJzU", 
 "token_page_size": 15, 
 "token_wizard": false, 
 "token_wizard_2nd": false, 
 "user_details": false, 
 "user_page_size": 15, 
 "username": "secureuser"
 }
 }, 
 "time": 1477985335.376939, 
 "version": "privacyIDEA 2.16.dev3", 
 "versionnumber": "2.16.dev3"
}

Using the authorization token

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InNlY3VyZXVzZXIiLCJub25jZSI6IjQyYjhhMWIzNDEzYTA5ZmQzMDljMDI3NzY3Mjc4N2I5MmFiNWI2ZWUiLCJhdXRodHlwZSI6InBhc3N3b3JkIiwicmVhbG0iOiJzZWN1cmUiLCJyaWdodHMiOltdLCJyb2xlIjoidXNlciIsImV4cCI6MTQ3Nzk4ODkzNX0.vCXNNV4Bmt2UuC0FMuc2qMbr8i_8zweROadvfLYcJzU

for subsequent call.

Enrolling a token

Now the user can enroll a token using the token endpoints. You need to issue a /token/init request.

To enroll an TOTP token the user would have to issue such a request:

http --verify no --pretty all --json POST https://localhost/token/init \
     PI-Authorization:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InNlY3VyZXVzZXIiLCJub25jZSI6IjQyYjhhMWIzNDEzYTA5ZmQzMDljMDI3NzY3Mjc4N2I5MmFiNWI2ZWUiLCJhdXRodHlwZSI6InBhc3N3b3JkIiwicmVhbG0iOiJzZWN1cmUiLCJyaWdodHMiOltdLCJyb2xlIjoidXNlciIsImV4cCI6MTQ3Nzk4ODkzNX0.vCXNNV4Bmt2UuC0FMuc2qMbr8i_8zweROadvfLYcJzU \
     type=totp genkey=1 otplen=6

The secret and also the image of the QR code to be scanned with a smartphone app is contained in the response:

 "googleurl": {
 "description": "URL for google Authenticator", 
 "img": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAeoAAAHqAQAAAADjFjCXAAAD90lEQVR4nO2dTY6jSBBGXwxItQSpD+Cj4JuN6khzAziKbwBLS6CYRWaQ6epZGUaW218sEJR5SqUUiv+kzDkg019HaBAuXLhw4cKFCxd+Lm5ZWuzKZkw9MKVHsOtS7uLV63mrC/80HHd3Z3B397lx9xmgc2fwNd/Rxd0wN14R41vvXfir8SWbL7t2Kz4CTH3jDDczoHGGeTMAzKw9eXXhn4W3P559MrDh1q4M49Y6rC3DCA6Nw3Lq6sKFAzDMjee4rm/crkuLf/cAi9n/vrrwj8I7dx8JD+t+txzh7c41KSHg7uvJqwv/SHwyM7MeYGmx6/KVzBxAfvx7BmBLKeypqwv/MDwpVmmL+XTJhsxZNvPpsuKwpkfoHjtob7134a/Co3ISRZNUFxkBH2myig0zJIc7+Ir73KhyIvwMfDOzy4pdSSbNk66N3Yp/X1ZySWX5cqZ+k4cVfkCictKtLcM/X85kjdtwM5zubs7y5ZZeW3qM7m4++BbYW+9d+Kvw7GEh27XsTZObbTzZurHbXwEgpbnysMKflRLIAdERG2bIHTEeumSlVaa4TvjzEtkElGZsJBeNl/ShqKMXkdYJfx7374t71X2YerArAMuXA1tqxuYGrfqwwo9JMVwM1SVGAKqSyhxhXlVheeu9C38V/pA5QK7I5fQh+9pcQ2FXPVSvE35IstZ1/ptUypWS26yYOcyT1gl/WrL+zECaZeo8HGlys8XDQsk1ZOuEH5Bi61Idboy54VC9ukFWzJy0TvgBiSrx7j4jrsuXsH/p5fyoep3wQ1JZsxLN7XoVZeH9h4j1pHXCD0j4y1wRybLnsLA7170jIQ8r/Bj+0Gno9kkTGi9tsTrh6B7t31vvXfir8Lpysg/UVWU5Qv8i4Nt7s9I64U9LZBNF/1bKVEnKZpNznR9eka0T/rwU9xljTLuvjZmT/N4M+Tw26ogJPyRVbpD1L8py46P+7YlsXch7670LfxX+4EjnaLf+R4RXXdyldcIPSVYf4pzr8Gjr9kDuR29CWif8gFS2rrT7PSadqiGn6qJZYuEn4O63Frt2ax7ZzHObUTnJh8I2g+5umuoUfl4fNs8yVVavLtDlBhmgcxPCD+LV2X+HNX/Oaf9byGbO8mtlGMGmfo4f33rvwl+Ll291Ml3u9WfqhqpLAbC0MNzkYYWfgA+lVBzHc1JZeOqhfDAxVYmn/uTVhX8Y/nAyMc7j1DMnUTQpbYmCKa4Tfh4eZ1/zecQ8bjdDjKU0iuuEH5Eftq7MDVcTxOkzieWT2MphhR+Tug9bHfFv6t7sGKNN0TnTpJPwQxL1OmAvC5ejiOzzdWHhVnRGTPhB3PTf64QLFy5cuHDhwv8I/F/uK4F3xSCgRwAAAABJRU5ErkJggg==", 
 "value": "otpauth://totp/TOTP0008C54E?secret=ND2QFT6LIMFXCEARWIMTBT456NY6K7H5&counter=1&digits=6&issuer=privacyIDEA"
 },

In the same way you could let the user manage his tokens, delete them, reset PINs etc…

For more information see the complete REST API documentation.

Users who might want to use privacyIDEA will wonder how crypto is handled. So this makes it easier for them to get a first impression without having to study the source code.

In fact this is also a good review for the project itself, too. At several places we still use hard coded SHA256. With the hashing of the OTP Pins and the signing of the Audit data.

But having this crypto paper at hand, we know, which places we need to touch in only a few years!

Watch this video on YouTube.

This way you can add two factor authentication with cheap and easy to use U2F devices to your network. You can implement the SAML IdP using simpleSAMLphp and the privacyIDEA plugin.