We are happy to announce, that today the first major release of the new privacyIDEA 3 series was pushed to the repositories. It is available via the Python Package Index and on the Ubuntu repositories for Ubuntu 16.04LTS and 18.04LTS.

With privacyIDEA 3.1 the administrator can configure policies that will only be bound to users with certain user attributes. This way the admin can define different policies for users in the same user resolver.

Migration from proprietary 2FA solutions gets even simpler with automatic token assignment and PIN setting.

Even more flexible policies

The administrator can now define policies based on any arbitrary attributes. To do so, privacyIDEA can provide different attribute modules for the policy conditions. This version of privacyIDEA comes with a user-attribute module. Up to the latest version policies could only be assigned to a complete user resolver. This was difficult, when rights of users changed and only some users from a certain user resolver should get new policies in privacyIDEA.

Now the administrator can set an attribute e.g. in the LDAP dirctory of a user, and as soon as this is set the policy will be automatically bound to this user. This provides a bigger flexibility with handling access rights or in migration or enrollment scenarios.

We also added new policy actions for administrators. Administrators now can get a special read right on any configuration setting. This way the super user can define, which administrator is allowed to read certain configuration or which configuration should be hidden from which help desk user. The migration script, which runs automatically in the ubuntu package update will create new migration policies so that the current behaviour of the installation does not change after the update.

We did a lot of work on policies in this release – we called in polishing policies.

Migration of proprietary 2FA solutions

Again we improved the possibility to migrate from existing, proprietary 2FA solutions. Proprietary software goes end of life and sometimes leaves the user with a mess. Cornelius wrote a blog article about that problem.

The administrator can import an existing seed file from the old system. privacyIDEA then basically knows the old tokens. On authentication request privacyIDEA can automatically find out, which token belongs to which user. In addition it will set the old OTP PIN of the tokens. This way neither the user nor the administrator have anything to do to migrate to privacyIDEA.

This is possible since privacyIDEA will at first forward the authentication request to the old system. If authentication is successful privacyIDEA will use the used OTP value to identify the token for the user and it will use the rest of the passed credential to automatically set the OTP PIN.

Many enhancements

Further work was done on the TiQR-Token in privacyIDEA. This is an older concept where a challenge is passed to the user’s smartphone via a QR code, which is displayed during the login process. The user simply accepts the login request on his smartphone.

In addition with privacyIDEA 3.1 there come a lot of minor enhancements and bug fixes.

The complete changelog can be found at Github. privacyIDEA will be at the ownCloud conference in Nuremberg in September. Stop by and get safe!

One important thing is, that you can use pi-manage to manage policies! This way the root user can for example deactivate policies, if the token admin misconfigured something in the Web UI.

But you can even use pi-manage to setup poliies.

Setting up simple policies

To view all configured policies run

pi-manage policy list

This will give you a list of the policies with their names, and whether they are active or not.

To create a new policy use

pi-manage policy create <parameters>

The “create” command accepts the positional arguments “name”, “scope” and “action”.

So to create a policy, that sets otppin=userstore, so that users should authenticate with their LDAP password, you need to run

pi-manage policy create policyname1 authentication otppin=userstore

This quickly creates a policy with the name “policyname1”. Please note, that this does not allow for more complex policies, like with several actions or with user or IP restrictions.

Anyway, this is a quick and easy way to bootstrap your privacyIDEA installation.

If you need more complex setups, you can use the parameter “filename”.

Setting up more complex policies

Maybe you want to create a policy, that requires users to present their LDAP password, but you also want to pass authentication if the user has no tokens or the user does not exist.

But only for a specific realm! Then you can create a JSON config file, that describes this policy and use this file to bootstrap the privacyIDEA configuration.

The file contains a dictionary with the following content:

{ 'action': { 
       u'otppin': u'userstore', 
      'passOnNoUser':True, 
      'passOnNoToken':True },
   'active': False,
   'adminrealm': [],
   'check_all_resolvers': False,
   'client': [],
   'condition': 0,
   'name': u'policyname2',
   'priority': 17,
   'realm': ['userrealm'],
   'resolver': [],
   'scope': u'authentication',
   'time': u'',
   'user': []
}

This way you can set all parameters of a policy. In this case we bound the policy to the userrealm “userrealm” and initially deactivated the policy.

You see that using the policy subcommands of the pi-manage tool gives you a lot of possibilities to setup your privacyIDEA system automatically or reconfigure it to a previously defined state.

There are a lot more subcommands of the pi-manage tool, check out the manpage and stop by at the community forum, if you want to discuss any aspects of policies.

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!

Today I want to give you an idea about the current development in privacyIDEA. You may like privacyIDEA because it is probably the most flexible and extensible multi factor authentication system due to its sophisticated policies and event handler framework.

But I just pushed a small enhancement in regards to the policies, which my ease your life. You are now able to not only define policies based on realms, resolvers and list of users, but you may also use regular expressions for the users in policies. This will be part of privacyIDEA 2.18 which is scheduled for midth of March 2017.

This way you do not need to rely on the user realms and user resolvers. You can also specify, that a certain policy should be bound to all users matching customer_.* or admin_.*.

This can help to ease things, since you do not need to split up a realm into many resolvers.

Tell us, what you like. Join the Google Group, post your issues at Github or subscribe to the Youtube Channel.

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.

Certificates and Hardware Security Modules

The certificate handling in privacyIDEA was improved. Administrators can now enroll a certificate token for a user and also generate the RSA key pair. Users can download the certificate and the private key as a PKCS12/PFX container. This is useful in certain scenarios where a VPN client requires the local installation of a client certificate that stays on the machine.

In addition support for hardware security modules like the Nitrokey HSM was added. This was done by adding a PKCS11 security module.

Time Dependent Policies

It is now possible to restrict policies to certain times. Thus you can allow the login outside of the office hours only with a yubikey while allowing login with a Google Authenticator only during daylight. Or the token management of the C-level group tokens could only be allowed on mondays…

…do what you want!

Event Handler Framework

The event handler is a complete new concept of allowing new workflows in privacyIDEA. Depending on certain conditions each event (REST API calls) may trigger a new action. The administrator may configure the triggered actions in the most flexible manner.

E.g. if a token is enrolled or assigned, the user may be notified about this. The event handler framework allows for any kind of thinkable workflow. Please read our previous post on this topic.

…do what you want!

Changelog

This is the complete changelog.

Features

• Event Handler Framework #360
• local CA connector can enroll certificates for users. Users can download PKCS12 file. #383
• Add and edit users in LDAP resolvers #372
• Hardware Security Module support via PKCS11
• Time dependent policies #358

Enhancements

• Policy for web UI enrollment wizard #402
• Realm dropdown box at login screen #400
• Apply user policy settings #390
• Improve QR Code for TOTP token enrollment #384
• Add documentation for enrollment wizard #381
• Improve pi-manage backup to use pymysql #375
• Use X-Forwarded-For HTTP header as client IP #356
• Add meta-package privacyidea-mysql #376

Fixes

• Adduser honors resolver setting in policy #403
• Add documentation for SPASS token #399
• Hide enrollment link (WebUI) is user can not enroll #398
• Fix getSerial for TOTP tokens #393
• Fix system config checkboxes #378
• Allow a realm to be remove from a token #363
• Improve the date handling in emails #352
• Sending test emails #350
• Authentication with active token not possible if the user has a disabled token #339

This will be things like:

• Event handler to trigger certain actions depending on events
• Improved certificate support
• Editable user resolvers – even in LDAP
• Improvements in the WebUI and policies
• Easy Migration with RADIUS passthru policy

Tübix is a Linux event in the south of Germany, so the talk will be in German. But much time to discuss things, also in the evening utilizing a cold beer.

• Affected version: up to privacyIDEA 2.11.2
• Propability: Medium
• Security Severity: High

Technical Background

The passOnNoUser policy is supposed to check if an authenticating user exists. If the user exists, normal authentication is performed. If the user does not exist in the user store authentication is immediately successful. This is useful in special scenarios, where the Application has several levels of authentication and privacyIDEA is just the second level. Users that do not exist in privacyIDEA will only authenticate with the first level and users, that have an account in privacyIDEA will need to authenticate with the second level.

The Bug: If the policy passOnNoUser is set, it is not checked, if the user exists. I.e. even users that do exist are successfully authenticated, without checking their OTP value or password.

Advisory

You need to disable a policy containing the passOnNoUser action or remove the passOnNoUser action from you policies immediately.

Fix

You should update to version 2.11.3 which is released today.

Self Registration and Password Reset

privacyIDEA comes with a new policy scope “register”. If this policy is set new users may create a new account. The creation of the account can be limited to certain realms or to certain email addresses. This way you can define, that only user with an email address from a certain domain are allowed to register.

The user will get an email with a registration token, that can be used to access the privacyIDEA Web UI.

User registration was also introduced in a previous blog post.

User registration is possible due to the concept of writeable userstores, which was introduced earlier. Another possibility that arises from the writeable userstores and which is introduced in version 2.10 is User Password Reset. In a user-policy you may define, if a user should be allowed to reset his userstore password.

Token Wizard

Enrolling tokens to the user is always quite a challenge. No project or installation works the same, has the same requirements and chooses the very same enrollment strategy. It always seems very tempting to let users enroll their tokens, hoping that this strategy will not generate high traffic and costs in the help desk.

With privacyIDEA 2.10 the token user selfenrollment was drastically simplified providing a token enrollment wizard. The token enrollment wizard can be enabled using a policy. The enrollment wizard will jump in, if the user has no token. When the user logs in to the WebUI he will be presented a two step enrollment without any distracting additional questions or choices.

The tokenwizard works for all kind of tokens. In this example it is a smartphone based Google Authenticator HOTP token.

Email

After all this user stuff another important feature is the configuration of the Email-capabilities in privacyIDEA. Emails are used at different locations like EMail Token, SMS Token, Registration process and Password Reset. Therefore you can defined SMTP Server configurations centrally and choose which SMTP configuration you want to use for the specified task.

ChangeLog

This is the complete changelog of version 2.10:

Version 2.10, 2016-02-11

Features

• User Registration: A user may register himself and thus create his new user account.
• Password Reset: Using a recovery token a user may issue a password reset without bothering the administrator or the help desk.
• Enrollment Wizard for easy user token enrollment
• SMTP Servers: Define several system wide SMTP settings and use these for
  • Email token,
  • SMTP SMS Provider,
  • registration process,
  • or password reset.

Enhancements

• Ease the Smartphone App (Google Authenticator) rollout. Hide otplen, hash, timestep in the UI if a policy is defined.
• Add import of Aladdin/SafeNet XML file.
• Add import of password encrypted PSKC files.
• Add import of key encrypted PSKC files.

Fixes

• Support LDAP passwords with special non-ascii characters.
• Support LDAP BIND with special non-ascii characters.
• Fix problem with encrypted encryption key.
• Fix upgrading DB Schema for postgresql+psycopg2.
• Fix UI displaying of saved SMS Provider.
• Do not start challenge response with a locked/disabled token.

privacyIDEA provides the possibility to verify credentials that arrive via a REST API. You can attach arbitrary applications to privacyIDEA. But this could also result in arbitrary data being sent. This is why we just pushed a new feature for the next release 2.5 of privacyIDEA.

Authentication Data Mangling

Just like many other features this can be configured flexibly via an authentication policy. The Authentication Data Mangling allows you to modify incoming authentication data, before these data are processed by privacyIDEA. Thus you can modify the username, the password or the realm sent in the authentication request.

Imagine a system, that sends malformed usernames. You can strip all whitespaces or only use a certain part of the sent username to find the user within privacyIDEA. You can use regular expressions to transform the sent username into a the username to be found in privacyIDEA.

You can also do funny things by modifying the password. A policy action like:

mangle=pass/.*(.{6})$/otppin\\1/

will only use the last 6 characters of the sent password (probably the OTP value) and put the fixed string “otppin” in front of it. Ok – no matter which OTP PIN the user enters, the authentication request will always use “otppin”.

Or you could change the order of OTP PIN and OTP values like this:

mangle=pass/(.*)(.{6})$/\\2\\1/

As you can also define these mangling-policies for certain clients, you can define – for which reason ever – clients where the <OTP PIN>+<OTP Value> are to be entered and other clients with <OTP value>+<OTP PIN>.

Authentication Data Mangling seems a mighty and flexible feature to me. I can not see all possible use cases, yet. So tell us what you think!