Therefore, we invite you to attend our free online events

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

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

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

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

Dates & Time

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

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

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

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

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

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

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

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

Setup CA in privacyIDEA

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

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

# pi-manage ca create -t local myLocalCA

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

# pi-manage  ca create -t local  myLocalCA

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

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

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

        Validity of issued certificates: 365

        CRL validity: 30
        CRL overlap : 5

Is this configuration correct? [y/n] y

You also need to fix the access to the directory

chown privacyidea -R /etc/privacyidea/ca

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

user:
    extenstions: "user"
    days: 365

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

You need to do some minor fixtues:

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

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

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

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

Now your CA is ready to go.

Setup PIV trusted certificates

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

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

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

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

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

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

Configure privacyIDEA policies

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

We create a policy to require an attestation certificate

scope: enrollment
action: certificate_require_attestation=require_and_verify

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

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

Enroll certificate

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

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

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

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

Prepare dependencies:

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

Create a virtualenv:

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

Enter the environment:

source piv-test/bin/activate

Install the privacyidea admin client:

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

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

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

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

ykman piv reset

Now you can enroll the yubikey certificate:

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

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

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

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

Conclusion

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

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

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

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

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

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

First event handler to store the authentication date

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

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

The Actions of the event handler look like this:

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

Second event handler to reset the failcounter

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

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

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

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

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

Effective behaviour

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

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

Kenneth Cummings gave a talk at the ownCloud Conference 2017 how to combine different components to setup such a 2FA reverse proxy.

Watch this video on YouTube.

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!

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.

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!

This is a cheap way to establish two-factor authentication with something you know and something you have.

Several attack vectors for Two-Factor Authentication with SMS OTP

But lateley there are again some news about the vularability of OTP values sent via SMS. There are different attack vectors. In one scenario the attacker can reroute or “steal” the SIM card by doing social engineering at the telephone provider. In another scenario a malicious software is installed on the smartphone, that can sniff the OTP value.

Yes, privacyIDEA also supports sending OTP values via SMS and privacyIDEA is also vulnarable to these attacks – since it is the basic concept that lacks the necessary security.

Security is shades of grey — or white

But you might have heard that “there is no 100% security”. And that “security is a process”. And now I add to these idioms “Security is Shades of Grey”.

You gain security by using a password on your account to lock the desktop. But are you secure? You gain further security by adding a second factor during authentication. But is your data secure, now? You gain further security by encrypting the harddisk (a.k.a. your data) of your desktop. But is it secure?

Yes, it is good to use a password. You should not use none.

And yes, it is goot to use SMS OTP. It is better than to not use it. In certain cases it might be OK to use SMS OTP being aware of the possible risks.

But there are further steps or other possiblities to increase security.

Choice of Security Level

With privacyIDEA you have the choice, which security level you are going to use. And this may even depend on the application and the client.

You may use SMS OTP, Email OTP, Smartphone Apps like the Google Authenticator, hardware key fobs and seedable tokens like the Yubikey. Using privacyIDEA’s policy definitions, you can define which token type is allowed to be used for authentication at which application. This way you can accept the risk of using e.g. SMS OTP for low security applications and hardware devices like the yubikey for applications requiring higher confidentiality.

See the online documentation on policies for more information or come to the Google Group mailing list.

If you require any professional assistance you may contact the maintainer of privacyIDEA.

Two factor authentication or multi factor authentication is ment to raise the bar for attackers. They ought to sniff, brute-force or social-engineer your password and in addition steal or “borrow” your hardware token for a “test”.

Still, I wish to think that the Yubikey – being the product of originally a sole Swedish company – has no back doors. So as long as the TISA does not know of side channel attacks or you used a static password with the Yubikey, you might be fine as long as you get the same Yubikey back – undestroyed.

Nevertheless there are additional measures you can take to improve your security with privacyIDEA.

Disclaimer: This will only help, if you are using your hardware token to authenticate to remote systems. If you use your hardware token to unlock let’s say encrypted harddisk of your notebook, you are carrying, this will not help.

Set up privacyIDEA

When you manage your hardware token for remote access with privacyIDEA and you are crossing borders or you are in situations where you

1. think your hardware token could be stolen or otherwise compromised and
2. you do not need the token explicitly (since you are on the plane without internet access)

you might want to call your trusted privacyIDEA administrator (some call it help desk) and have your hardware token locked.

This way the hardware token can not be used to access restricted resources. If TISA is still insisting to get your Yubikey, you can say:

“If you take it, you can keep it”

(No of course you can take it back, but you may see it as compromised and you might need to reenroll it.)

If TISA takes the Yubikey there is not use for them, since the token is locked.

If TISA did not get your Yubikey and you crossed the border, customs or control successfully, you may call your trusted privacyIDEA admin again to reactivate the hardware token.

Conclusion

This might sound a bit complicated but also to simple. But special events like travelling to certain rogue regimes may require special measures.