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!

Event Handler Framework

The event handler framework is great. It is used by a lot of people to adapt their workflows. So we enhanced the UserNotification module. It comes with a lot of new conditions and can send notifications to tokenowners or administrators. You can use the user object, groups or simple email addresses. The administrator can define conditions in which cases the notification should be sent. 

The notification template can contain a lot of new tags:

• {admin} name of the logged in user.
• {realm} realm of the logged in user.
• {action} the action that the logged in user performed.
• {serial} the serial number of the token.
• {url} the URL of the privacyIDEA system.
• {user} the given name of the token owner.
• {givenname} the given name of the token owner.
• {surname} the surname of the token owner.
• {username} the loginname of the token owner.
• {userrealm} the realm of the token owner.
• {tokentyp} the type of the token.
• {registrationcode} the registration code in the detail response.
• {recipient_givenname} the given name of the recipient.
• {recipient_surname} the surname of the recipient.

The registrationcode is an interesting tag, which can be used to automatically notify the user about his new registration token.

Hardware Security Module

In addition to the PKCS11 module a second AES based Security Module was added. The system administrator can use the security module to encrypt and decrypt data like the OTP seeds in a network attached hardware security module (HSM) boosting your overall security.

This way you do not have to worry about seeds or encryption keys getting compromized.

Managing Subscriptions

It is true. Not all client components communicating with privacyIDEA are free. privacyIDEA helps to manage subscriptions for such components like the privacyIDEA ownCloud App. You can upload subscription files by NetKnights and other 3rd party vendors to assure the communication with the corresponding applications.

Changelog

Please see the complete changelog:

Featurs

• Add HSM support via AES keys (#534)
• Improved Event Handler for flexible notification (#511)
• Signed subscription files for adding and checking for extra functionality during authentication request (#502)

Enhancements

• Allow additional filter attributes in the Audit Log (#519)
• Show or hide realms in the login dialog via policy (#517)
• Improve UI if admin is not allowed for certain actions (#516, #512)
• Disable OTP PIN during enrollment via policy (#439)
• Allow automatic sending of registration code via email (#514)

Fixes

• Allow compatibility with ldap3 >= 2.0.7 (#533 #535)
• Fix problem with Notification when no tokenowner is available (#528)
• Fix confusion of client HTTP parameters (#529)
• Fix enabled flag with certain database types (#527)
• Catch error in case of faulty overrideClient definition (#526)
• Truncate Audit lines, that are too long for the DB table (#525)

Install or update privacyIDEA according to the installation instructions.

Today we released privacyIDEA 2.14 just as planned in regards to our Milestones on Github.

PGP encrypted Seed Files

Seed Files can be transmitted and imported in a PGP encrypted way. This eases the transport of those files from the token vendor to your installation. You can create a unique PGP key pair for your privacyIDEA installation and hand the public key to the token distributor. The seed file does not need to be decrypted. Just import the encrypted seed file.

Event Handler for user with enhanced functionality

Then we enhanced the Event Handler Framework. User notifications can be sent based on administrators and user actions. You may define a detailed manner under which conditions the events will trigger an action. The UserNotification Event Handler has the conditions: realm, login-type (user or admin), result-value and token-locked. This way the user can be notified on failed authentication requests or if the token is locked.

Better performance for high user numbers or slow networks

The lookup of the LDAP resolver was heavily improved. Also the program cycles during authentication requests were optimized.

You can see the complete changelog on github.

Feel free to follow us on twitter, star the github repository or join the google group.

Text message (SMS) enhancements

Nevertheless privacyIDEA 2.13 comes with improved SMS handling. But be sure, SMS can not only be used for authentication but for many other things. privacyIDEA 2.13 now lets you define a central list of SMS gateways – just like with centrally defined SMTP servers and RADIUS servers. Now privacyIDEA can centrally define all communication channels it needs. Defining your SMS gateway centrally eases the setup of your SMS token type.

But text messages now can also be used to notify users in case of certain events. The event handling with user notification was added in version 2.12 with notification via email – now you can also use text messages.

These SMS gateways could be used for other features in the future like notifying administrators in case of certain errors… Feel free to open any feature request on github.

PIN handling

The second main features is PIN handling. You may have noticed the new logo of privacyIDEA.

You can see the bottom line “Authentication System”. Already a while ago privacyIDEA left the track of a pure OTP system, when adding support for SSH keys, certificates and Yubikeys for LUKS.

privacyIDEA can now take care about PIN policies and require the user to change the PIN after a defined time span. You can also set a policy that a user will have to change the PIN after first use! I am curious what you think about the PIN thing. If you have any further ideas about passwords and PINs drop us a note, write a comment or and issue on github.

Further Enhancements

…are

• Performence enhancements in the Web UI regarding the token view and the audit log.
• An additional log level below “DEBUG”. Debug will log no passwords. If you need passwords in your debug output, set the loglevel to “9”.
• Quick actions in the token list. Try and click on the Failcounter or the “active” column.
• Intelligent proxy handling or “OverrideAuthorizationClient” setting, which allows to define, which proxy server is allowed to change the client information.

The full changelog can be found here.

The classical concept of privacyIDEA was: You have a user database – a user store – and privacyIDEA just reads this user store. In classical scenarios such as the enterprise environment with the Active Directory user base this is a perfect concept, because users are already existing. Over time I had to learn that this covers only 95% of the real world. So in version 2.4 we added user management – or editable userIdResolvers.

Editable UserIdResolvers

The editable UserIdResolvers that allow the administrator to manage users from within the privacyIDEA Web UI is an important step for the upcoming version 2.10. The editable UserIdResolvers are only implemented for SQL databases at the moment, but the connector for the LDAP databases like Active Directory or OpenLDAP could be easily enhanced accordingly. But at the moment I don’t think, that someone would like to have his Active Directory modified by privacyIDEA.

Anyway – privacyIDEA 2.4 already contained an importand method in the SQL connector, the method to created a new user in the SQL database.

User Self Registration

Thinking of new use cases with privacyIDEA we came up with the idea to provide a privacyIDEA instance to the public. Or a company or a hotel could provide a privacyIDEA instance to guests, where guests could register a guest account. If it is possible to restrict the registration of a new account to let’s say email addresses, we could control which email addresses are allowed to created a new account. This way it could also be used within an huge organization without reading the users from an existing user source but by having the users (identified by the email address) register their own account.

I am sure, at the moment we do not see the whole potential of this new feature.

How does it work

The administrator needs to define a policy, that allows the registration of a user in the defined UserIdResolver. If this policy is defined, an additional link “Register” is displayed in the login page. Then users may enter account information and will receive a registration token (a kind of registration code) to be able to login with these two factors (The password they defined and the registration code, they received via email).

Notification

During the registration process the user receives an email with the registration token. Again – privacyIDEA needs to notify the user via an email. privacyIDEA already sends emails for the Email token type or the SMTP SMS Gateway token. Also, there is the PIN handler, which could send the OTP PIN, if a random token PIN was created during enrollment.

So you see, that there already were several places in privacyIDEA, where it could be necessary to define an Email connection. Sending the notification during the registration process would be the fourth occasion to send an email.

Now is the time to refactor the email notification code in privacyIDEA.

System wide SMTP server configuration

So the privacyIDEA database for privacyIDEA 2.10 will come with a new database table, where the administrator can define as many SMTP servers as he needs to.

In all occasions, when privacyIDEA needs to send an email, the configuration will only refer to the identifier of this SMTP configuration. Usually defining one SMTP configuration will be enough an this single SMTP server will be used for sending the email of an Email token and the registration emails and all other notification information to come.

But privacyIDEA would not be privacyIDEA if it did not let you the freedom and choice to define as many different SMTP connections as you will need.

More to come

With all these building blocks

• editable UserIdResolvers
• simple token implementations
• simple email notification

new ideas can be implemented easily and quickly. You can see this in the really short release cycles of privacyIDEA.

We are anxious to hear of your ideas, which I am certain of, can be easily implemented, too. Please join us on the Google group or drop your idea at privacyIDEA’s Github issues.

Happy new year and happy authenticating!