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.

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.

Tine 2.0 is a groupware and CRM which is available as open source and Enterprise Edition. Last weekend I met some guys from tine 2.0 in Kiel at the local Linux and open source conference. We again talked about two factor authentication and then we used a time slot to do a spontaneous workshop. I explained the easy authentication API of privacyIDEA. You can find it in the online documentation of readthedocs. After all it boils down to one simple ajax call. All other logic is handled within privacyIDEA.

After only half an hour the first stub was running. By the end of the afternoon everything was fine, mocked and tested!

This shows, that if you take some time to read the REST API, adding two factor authentication to your own application is easy as pie!

Secure your own Application

privacyIDEA is already integrated into many applications like TYPO3, WordPress, OTRS, ownCloud, Nextcloud, Contao, dokuwiki and Tine 2.0. Be the next one to increase security and implement 2FA securely and easy with privacyIDEA!

If you want to integrate privacyIDEA into your application and have any questions, join the gitter.im chat or the Google group.

A while ago I started using pycharm. There are many different IDEs out there.  I also used Aptana and Eclipse for a while. But pycharm just feels a bit quicker and navigation in the code seem to me more intuitive. vim is no IDE to me. But everyone is allowed to do what suites him best. privacyIDEA is a project with several layers – database, libraries, dependencies and APIs. It helps me to be able to browse the code and “find usages” and “refactor” functions and variables.

So, in this blog post I will show you, how you can set up the privacyIDEA project for development, running and debugging.

Get privacyIDEA

First get the privacyIDEA sources. You may as well first fork privacyIDEA into your own repository, so that you can commit changes and issue pull requests. We clone the repository locally and also setup a virtualenv, so that you have everything you need for development.

cd ~
git clone https://github.com/privacyidea/privacyidea.git
cd privacyidea
virtualenv venv
source venv/bin/activate
pip install -r requirements.txt

For pip install to run successfully, you might need to install additional development packages.

Get PyCharm

Go and get pycharm for your operating system. Follow the easy installation instructions on their website.

Setup privacyIDEA project

Now start pycharm and now we can set up the new privacyIDEA project.

Choose “Create New Project”. Select a “Pure Python” project with the Location of the folder, where you cloned the git repository.

We need to change the Interpreter. We want to use the Python Interpreter from our virtualenv. So click on the gear icon next to “Interpreter”, choose “Add local Python Interpreter” and select the python binary from your virtualenv.

pycharm is now indexing the python code in your project. This may take quite a while.

Meanwhile we can…

Set up your local privacyIDEA

We are running and debugging privacyIDEA from within pycharm. We will do this on the current code we are developing. Thus we need to setup privacyIDEA. In the root directory of the project you will find the script pi-manage.

We need to create encryption and signing keys and also the local database “data.sqlite”. This configuration is read from the internal config in privacyidea/config.py.

./pi-manage create_enckey
./pi-manage create_audit_keys
./pi-manage createdb
./pi-manage admin add <yourAdminAccount>

In the last step we create the first token administrator. You may think of a name and provide the administrators password.

Create Run and Debug Configurations

When indexing is done, we can create Run and Debug Configurations. These configurations help you to run tests, run the privacyIDEA server and also debug these runs.

On the upper right corner is a drop down box, which is initially empty. Choose “Edit Configurations…”.

First we will create a pure Python configuration we might call “run server”. The server can be run locally also using the script pi-manage. Thus we enter “pi-manage” as the Script and “runserver” as the parameter.

Please assure, to select the correct Python interpreter. This one in our virtualenv!

Also choose the project root directory as working directory. This way we do not have to install the privacyIDEA python module, but can just run on the current code.

We also create a second configuration which we use to run all integrated tests.

The test configuration lets us run all 700+ tests in the tests directory.

Run it!

Want to see, what I mean? Select the configuration “run server” and hit the green start triangle. pycharm will run privacyIDEA and it will listen on localhost:5000.

You can now navigate your browser to http://localhost:5000 and log in as the administrator, which you created earlier.

The Code

On the left side you can have different views like the project view (files) or the code structure of the current file.

There are many different ways to navigate the code and over time everyone will finds his preferred way. You can navigate via the tree views on the left, by navigating within the code by jumping the method and class definitions or by the breadcrumps above the main window.

Within the project you can also use Ctrl-H so search anything in the current sub folder.

privacyIDEA Code Structure

The basic structure in privacyIDEA looks like this:

You will find the database definition in privacyidea/models.py.

All library functions, which operate on the database are located in privacyidea/lib/. The REST API of the privacyIDEA server is defined in privacyidea/api/.

privacyidea/webui/ contains the jump in point for the UI. The privacyIDEA WebUI is implemented as a AngularJS Single Page Application. All this can be found in privacyidea/static/.

Debug it!

You may also select the configuration “run server” and hit the debug button. privacyIDEA will be started and listen on port 5000. But this time you can set breakpoints and step through the code. In the above example we set a breakpoint in the REST API /auth/ which is called when a user is trying to login to the WebUI. This way we can stept through the login process and monitor all variables.

Fork it!

I very much hope you liked this short introduction and it helps you to better understand the internals of privacyIDEA or to get started with privacyIDEA development. So go and fork privacyIDEA at github, get your pycharm, add new features and issue your pull requests!