We will use the privacyIDEA logging facility to let the server not only store its system logs and audit locally but also feed them to a remote Logstash server. We will also show how to use the new Logging module of the Event Handler, introduced in privacyIDEA 3.3, to customize the logged information. The usual path of information is displayed in the following picture.

Setup the Base System

As the installation Logstash, Elasticsearch and Kibana is documented at the vendors website, we will not go into detail here. In any case, you need a java runtime environment. For Ubuntu you can use the package default-jre. Once you have the elastic stack up and running, turn towards privacyIDEA.

The installation of privacyIDEA is documented at privacyidea.readthedocs.io. For a quick start, there is a community package repository for Ubuntu 18.04 LTS available. Install the privacyIDEA server and become a little familiar to the WebUI, which is the primary management interface.

The base configuration of privacyIDEA is set in the configuration file pi.cfg and the dedicated logging configuration file logging.cfg or logging.yml. In the default Ubuntu 18.04 package installation, those are located in /etc/privacyidea/. To be able to view the audit logs in the WebUI and send them at the same time to the python logger, the ContainerAudit module is used.

# /etc/privacyidea/pi.cfg
PI_AUDIT_MODULE = 'privacyidea.lib.auditmodules.containeraudit'
PI_AUDIT_CONTAINER_WRITE = ['privacyidea.lib.auditmodules.sqlaudit','privacyidea.lib.auditmodules.loggeraudit']
PI_AUDIT_CONTAINER_READ = 'privacyidea.lib.auditmodules.sqlaudit'
PI_AUDIT_LOGGER_QUALNAME = 'pi-audit'
PI_LOGCONFIG = '/etc/privacyidea/logging.cfg'

Note that we use a custom audit logger name “pi-audit” in the above configuration. See the documentation of the Logger Audit.

Send privacyIDEA logs to Logstash

The logging module privacyidea.lib.auditmodules.loggeraudit sends the audit messages to the python logging system and makes it available to the configuration by logging.yml. To send both the privacyIDEA server logs and the audit log to Logstash, the module python-logstash-async comes in handy. It can be installed through pip by

~$ pip install python-logstash-async

The module can be used in a logging.cfg or logging.yml in YAML and INI format respectively. Minimal examples for the configuration of the logstash-async module are found on Github Gist. A more detailed YAML configuration file is also available, which provides a good basis for this test case.

Restart privacyidea for the changes to have effect. If you used the extended configuration from gist, you should now see the audit log in /var/log/privacyidea/audit.log.

Receive privacyIDEA logs with Logstash

On the other end, Logstash is configured to listen on port 5959 and to forward the logs to Elasticsearch using different indices for the qualnames pi-audit, pi-eventlog and all the rest (privacyidea.*).

# /etc/logstash/conf.d/privacyidea_elasticsearch.conf
# privacyIDEA input is logged by the python-logstash-async module
input {
   tcp {
      port => 5959
      codec => json
      tags => ["privacyidea"]
   }
}
# filter adds metadata field according to logger to
# separate the privacyIDEA audit log from the rest
filter {
   if [extra][logger_name] == "pi-audit" or [extra][logger_name] == "privacyidea.lib.auditmodules.loggeraudit" {
      mutate { add_field => { "[@metadata][indexPrefix]" => "pi-audit" } }
   } else if [extra][logger_name] == "pi-eventlog" {
      mutate { add_field => { "[@metadata][indexPrefix]" => "pi-eventlog" } }
   } else {
      mutate { add_field => { "[@metadata][indexPrefix]" => "privacyidea" } }
   }
}
# Logs are sent to elasticsearch using the indexPrefix
output {
   elasticsearch {
      index => "%{[@metadata][indexPrefix]}-%{+YYYY.MM.dd}"
   }
   # additional output to syslog
   stdout {
      codec => rubydebug
   }
}

Restart logstash afterwards. The output section contains an additional part for logging to stdout. On a systemd-driven system (check ~$ ps -p 1), it can be viewed by

~# journalctl -f -u logstash

Once you interact with the privacyIDEA server, you should see the incoming audit log messages in json format in the journalctl ountput on the logstash machine. The example below is the audit message for viewing the audit log in the privacyIDEA WebUI:

{
          "extra" => {
                    "logger_name" => "pi-audit",
                   "process_name" => "MainProcess",
                    "thread_name" => "MainThread",
                           "line" => 85,
         "logstash_async_version" => "1.6.4",
                           "path" => "/opt/privacyidea/privacyidea/lib/auditmodules/loggeraudit.py",
                      "func_name" => "finalize_log",
                    "interpreter" => "/opt/privacyidea/venv/bin/python",
            "interpreter_version" => "3.6.9"
     },
          "level" => "INFO",
        "program" => "/opt/privacyidea/pi-manage",
           "port" => 47962,
            "pid" => 10047,
      "logsource" => "myhost",
     "@timestamp" => 2020-03-25T15:32:42.748Z,
       "@version" => "1",
           "type" => "python-logstash",
        "message" => "{'success': True, 'serial': '', 'user': '', 'realm': '**', 'resolver': '', 'token_type': '', 'client': '127.0.0.1', 'client_user_agent': 'firefox', 'privacyidea_server': 'localhost:5000', 'action': 'GET /audit/', 'action_detail': '', 'info': '', 'administrator': 'admin', 'policies': '', 'timestamp': datetime.datetime(2020, 3, 25, 15, 32, 42, 748526)}",
           "host" => "henning-t470"
 }

Display privacyIDEA logs with Kibana

The logs received by Logstash are sent to Elasticsearch which talks to the Kibana instance. The Elasticsearch indices should appear in Kibana’s index management, available from the home screen.

The privacyIDEA indices will look like shown below.

Note: the yellow health status is due to a default index setting "index.number_of_replicas": "1". Changing it to zero will result in a green status. Under “Data Views” create a new data view with the index-pattern “privacyidea*,pi-audit-*,pi-event*”.

In the Logs view, select the privacyIDEA data view you can select the log columns (“selected fields”) to be shown. The privacyIDEA log messages are now nicely displayed.

Don’t forget to save!

Event-based logging from privacyIDEA to Logstash

New in privacyIDEA 3.3 is the Event Handler module “Logging”. With this module, custom logging messages can be bound to any event. This opens the door to a whole new world of monitoring possibilities in privacyIDEA. To demonstrate the feature, we simply log whenever a token is disabled — a silly example, of course. The Event Handler is created as shown below.

For the Logging module, only one action is available. The log level, the name of the logger and a custom message are required. The message field supports variables known from the user notification module (see documentation). Note, that it depends on the context of the RESTful API event if a certain variable is available or not.

The chosen logger name has to be added as a logger in logging.yml to send it to Logstash.

loggers:
  pi-eventlog:
    handlers:
      - logfile
      - logstash_async
    level: DEBUG

Restart privacyIDEA to apply the changes in the config file logging.yml. After triggering the event by disabling a token in privacyIDEA, Kibana shows the notification.

Of course, you can use the logging event handler for more reasonable purposes like not to send the full audit log to logstash but to single-out the important validate-check events. You can even apply some more conditions, if you like making use of the powerful condition properties of the privacyIDEA Event Handlers. This not only spares bandwidth and storage space but prevents important information to be buried by other data. The message field in privacyIDEA can be used for a custom log message with contextual information. The configurable logger name (e.g. pi-validate-check) provides an additional identifier. In the case of suspicious behavior or a security incident, all the information is there to quickly track down the threat.

Conclusion

With this demonstration of the logging facility, privacyIDEA proves again to be extraordinarily scalable. It integrates well with logging systems like Logstash and Splunk since the privacyIDEA server builds on the standard python logging library. For Logstash, this article showed the detailed steps how to integrate privacyIDEA via the loggeraudit and a small third-party python module called python-logstash-async.

In privacyIDEA 3.3 the logging capabilities have been further extended by an Event Handler module which enables to conditionally log arbitrary events to the python logging system. We showed that also these messages can easily be passed to Logstash and open a vast playground custom logging.

The solution shown here is only one possible approach. Since privacyIDEA is available as open source an licensed under the AGPL, another possibility would be of course to write your very own logger module to do whatever you want. privacyIDEA is and will be always open source and therefore it will always stay in your hands.

If you would like to have a custom logger module, but have no time to implement it yourself, you can always request a quote from Netknights, the company which drives the privacyIDEA innovation via Github. They also provide professional support for privacyIDEA, including enterprise repositories for Ubuntu and CentOS/RHEL containing the server and a number of additional components and tools.

Today we release privacyIDEA 3.2. Two new event handler modules allow for even more flexible workflows. Integrating with external logging tools like Logstash or Splunk are much easier now using the container audit module and the file audit module. Using Trusted JWTs makes it much more robust to integrate any existing portal with privacyIDEA.

Request and Response Event Handler

The event handlers have been around sind version 2.12. Every version somehow improved the event handler. They allow for a very flexible way to define actions and responses in privacyIDEA. Read a recent post about the script event handler or take a look at the complete list of event handlers.

With version 3.2 the administrator gets two new event handlers – the Request Mangler Handler and the Response Mangler Handler. You notice the word mangle – these handler allow to modify, delete or add any arbitrary REST request parameter or JSON response parameter, given the administrator unseen flexibility to flex the privacyIDEA system to the very specific need!

The Response Handler could be used to delete certain response information, after it is used e.g. by a notification handler. For example the notification handler could read this information to notify the user but then the Response handler would delete this information, so that a help desk user is maybe not able to read a randomly set password in a response. The resulting possibilities are unimaginable.

We are very excited to see how administrators will use these features!

Audit data everywhere

privacyIDEA runs in big environments. Because it integrates so well. privacyIDEA also creates an Audit log (and a log file – for debugging purposes). However, the log file is great, since every HTTP request has its dedicated audit entry.

It should be easier to add the audit data to these locations, where bigger organizations aggregate and keep their Log data. These are systems and services like Logstash or Splunk. As a first step privacyIDEA 3.2 comes with two new audit modules, the File Audit Module, that can write audit information to a plain text/log file and a Container Audit Module, that can combine any number of Audit Modules, so that privacyIDEA can write audit data to all of these modules.

We hope that this is a big leap forward to get your information to the right place!

The trusted JWTs

Did you ever want to have users manage their privacyIDEA tokens in an existing local portal? Or your helpdesk users get privacyIDEA information into the ticket system they are using? With privacyIDEA 3.2 it gets much easier now. The administrator can define trusted JWTs. I.e. he can define trusted public keys and which user this public key can impersonate.

The mentioned portal will simply use its private key to create JWTs, that are then trusted by privacyIDEA. No need to create service accounts, share passwords or other credentials.

The complete changelog

There are a lot of new enhancements, which administrators and helpdesk users will probably like for a daily use. A lot of enhancements, which we needed to provide better and easier service for certain installations.

Besides the event handlers also policies have been improved. The administrator can now use any arbitrary HTTP header in the policy condition. This way policies could be strictly bound to certain http_agents.

To improve the roll out process, the event handlers can match for the roll out state of a token. The notification handler, that was already able to send email or SMS, can now also write files to a spool directory. This way information can be easily passed to 3rd party systems or this data can be processed further like printing PIN letters.

We also did some improvement of the authentication process for the PUSH token so that it is not necessary to require a service account to verify the answered challenges.

The complete changelog can be found at github.

Go and get it

privacyIDEA 3.2 can be installed from source from github, via the Python Package Index or using ready made packages for Ubuntu 16.04 LTS and 18.04 LTS. The builds for Ubuntu are now based on Python 3.

Image by BarbaraALane on Pixabay.

We learnt this in a lot of set ups and are claiming it since 2018 at the LinuxFest North West. One-solution-fits-all does not work out! Nowadays a company or organization wants to deploy 2FA to not only secure a certain login to a certain application, but also wants to have secure workflows around the authentication process. Thus the perfect 2FA or MFA software needs to adapt to the needs of such company or organisation.

The beauty of the event handlers

privacyIDEA introduced the Event Handlers already in version 2.12, May 2016. The script event handlers, which I want to talk about today, followed in version 2.17, December 2016.

Event Handlers were used quite actively since then. Only the script handles seemed special and awkward. It has been quiet around this one for a while. But recently a comment and question of a German partner (IT-Schmid), who was implementing a roll out concept for a customer, caught my attention and reactivated the thinking about the beauty of the script handlers.

privacyIDEA is implemented in a very modular way – on a horizontal but also on a vertical level. Database level, library level, the REST API and the Web UI are different, separated parts. And this helps us a lot with the script handlers. It is easily possible to write python scripts, that are using the library level, without the need to issue REST Requests that are processed through the web server. This improves performance of such scripts and it gives you access to ready made library functions, that allow you to address tasks with a few lines of code.

Script collection at Github repository

We realized, that it makes sense to provide a collection of example scripts, to give you a better understanding, what scripts can do and how this could be done. A new repository has been added at Github to host such example scripts. The first script is a script is a few lines, that can reassign a token from a username in one realm to a username in another realm. This can be a useful step during more complex rollout scenario. But automating such tasks of course reduces complexity and efforts to be taken.

We are happy to receive ideas and pull requests with new interesting scripts, which could enhance the scenarios with privacyIDEA to unexpected widths.

Visit our community forum for further discussions!

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.

It was a long way, but finally pieces started to fit together.

We are proud to present to you privacyIDEA version 2.23!

Monitoring and Statistics

To be able to provide a flexible and modular monitoring and to create any arbitrary statistics we created a framework of periodic tasks.

Using specific modules the administrator can define, what should happen in certain time intervals or at certain dates. These modules can collect system information for statistics, but such modules could also do anything else. Currently we provide two modules – the Event Counter and Simple Stats. 

The Event Counter can be used in conjunction with the Event Handler to record the occurrence of any arbitrary event. The periodic task scheduler will write the number of these events to a time series. The Simple Stats module reads predefined values from the privacyIDEA system (like number of tokens, number of assigned tokens, number of not assigned hardware tokens) and also writes those to a time series.

The administrator can easily use tools like Grafana to view the time span of interest in an expressive graph.

Pre-Event-Handling

Event Handlers were already added to privacyIDEA in Version 2.12. Using event handlers the administrator can connect any event to new actions like user notification, token management or any arbitrary script. If such an event occurs, the defined action is triggered.

With version 2.23 these actions can now be triggered, before the original event is processed. We distinguish Post-Event-Handling and Pre-Event-Handling. E.g. the administrator can define, that a user, who has no token assigned and tries to authenticate, gets a new token enrolled. And this newly enrolled token will be directly used during this authentication request. The logon experience for the user is totally transparent. There is no additional effort for the administrator.

This way a lot of tasks, which would otherwise be done manually or called by a script, will be executed automatically just at the right moment within privacyIDEA. This way the administrator can cope with unforeseen scenarios and can automate actions accordingly.

Ordered Policies

Policies have been around in privacyIDEA since day One. Policies define the way how privacyIDEA should respond to an API request. Policy definitions can become very complex. Policies also depend on time and the source IP address of the request. So in certain cases policies could overlap and the logic would not be clear, how privacyIDEA should respond.

To solve this problem we introduced a policy order in privacyIDEA 2.23. The administrator can give each policy an order number. This way the administrator can define which policy should come first and should take precedence if something should be unclear.

This can help in bigger, complex setups to make configuring privacyIDEA a lot easier.

Your next steps

We also added a lot more minor features and improved the SQL and HSM performance. For a complete Changelog please take a look at Github. You can install or update privacyIDEA via the Ubuntu Launchpad repositories or via the Python Package Index.

When you update, please see read_before_update.

If you have any questions, please have a look at the community forum.

Visitors will be able to talk to the core developer team of privacyIDEA and see the new features of the upcoming release 2.23, including Monitoring and Statistics and Pre-Event Handler. Once again these implementations will prove, that privacyIDEA is the most flexible two factor authentication system. The administrator can define freely which kind of values or event he wants to monitor. The pre-event handling opens unforeseen possibilties to design workflows like automagically enrolling Email tokens to the user just upon authentication.

Come and gape! The privacyIDEA booth is in the Mensa next to the ownCloud booth. And as privacyIDEA also integrates well with ownCloud, there will also be a workshop on integrating enterprise ready 2FA with the open file sharing solution on Sunday.

You should always take a look at the Changelog, but starting with privacyIDEA we added a document READ_BEFORE_UPDATE, which contains important information to consider before upgrade.

New Features: RADIUS integration, VASCO support, Offline Refill and more

With privacyIDEA 2.22 we added the possibility to pass more useful userinformation to a RADIUS client like a VPN. The administrator can add a policy to include the resolver and the realm of a user who authenticated successfully. This response data can then be used in the FreeRADIUS plugin and modified by regular expressions to add any arbitrary RADIUS attribute in the RADIUS response, which then would be sent to the VPN. This additional information can be used by Cisco ASA, Citrix Netscaler or any other enterprise grade VPN to put the user into certain subnets or to assign resource to the user.

VASCO token support

privacyIDEA is Open Source. We love Open Source and open standards. But sometimes you have to communicate with proprietary partners, so that they have the chance to become open. This is why privacyIDEA 2.22 comes with support for the proprietary VASCO Digipass tokens. This way it is easier to run VASCO tokens and open standards tokens like HOTP, TOTP or Yuibkeys in parallel and maybe even one day migrate all VASCO tokens – after the batteries have died – to other devices.

If you want to learn more about migrating your VASCO tokens, please contact NetKnights for professional sevices.

Offline Refill

We are improving the offline capability of privacyIDEA in conjunction with the PAM module and the privacyIDEA Credential Provider. The new offline refill will allow to automatically refill the hashed OTP values on the notebooks, which are available for authentication, if the notebook is offline. This way users or administrators will not have to worry anymore when taking the hardware on a business trip.

Send SMS via SMPP

SMPP (Short Message Peer-to-Peer) is a protocol used by carriers for sending SMS. privacyIDEA 2.22 comes with a new SMS Provider to send SMS via SMPP. This can be used for sending SMS in the SMS token during authentication but also for sending SMS in the notification event handler, to notify users or administrators on certain events.

Use Counter handler for monitoring and statistics

We often see, that the event handler is a mighty tool to cope with many different requirements. In addition to the notification handler, token handler, script handler and federation handler privacyIDEA 2.22 now comes with a simply but very flexible counter handler. Just like every handler it can be attached to any event (API call) and will trigger under defined conditions. The counter handler simply increses a counter in the database for this very event.

These counters can now be used for statistics or monitoring, e.g. when increasing a certain counter on the event failed authentication with HOTP token. This way the administrator could monitor the number of failed authentications per time interval.

Each token has a tokenkind

Many installations use hardware tokens and software tokens at the same time. To be more flexible in distinguishing these tokens when it comes to deleting tokens or deciding giving access, we added an additional class attribute to tokens. The “tokenkind”. In contrast to the tokentype, which is simply the mathematics of the token, the tokenkind defines if this very token object is  hardware token, a software token or a virtual token.

Use arbitrary tokeninfo in authorization policies

Authorization policies are used to decide if an authenticated user should get access or not. As the arbitrary tokeninfo fields are getting used more in more in event handler definitions, the tokeninfo can now also be used in the authorization policies to grant or deny access.

This way event handlers could modify token information and this modified token information can be used for granting access. Event handling and authorization thus get connected more tightly.

Lots of enhancements

There are further enhancements of existing features in privacyIDEA. We improved the token export the PSKC files – we will also export PW token types and the counter values of HOTP and TOTP tokens. The export can now also be used to reencrypt a token database.

The SMS and Email token types can now either use the fixed mobile number or email address in the token data or read the mobile/email dynamically from the user store on each authentication event.

The administrator can define a policy so that the validity of the U2F attestation certificate will be ignored. Some U2F devices come with a attestation certificate with an invalid validity period.

We improved the speed of the LinOTP migration script, so that a database with tens of thousands of tokens can be easily migrated.

The pi-manage script can now generate API tokens with a freely chosen validity time.

The user can now set the description of HOTP and TOTP tokens during enrollment.

The administrator can add a timeout to the SMTP server configuration.

The email tokens can now use a complex html template for sending emails.

The LDAP resolver allows to define each attribute as a multivalue attribute.

The event handler condition can trigger on failed authentication.

For the complete changelog with also contains all the fixes, please take a look a the Github repository.

Enterprise Edition

If you are running large mission critical setups, privacyIDEA is also available as Enterprise Edition with support and warranty/liability.

privacyIDEA at Grazer Linuxtage and Linuxfest Northwest

At the end of April you can hear a talk about privacyIDEA in Austria at the Grazer Linuxtage. You will learn, how you can easily migrate an old, existing, proprietary 2FA system to privacyIDEA. Project member Friedrich Weber will also host a workshop at the Grazer Linuxtage, where you can participate in installing privacyIDEA and configuring to your needs.

At the same time Cornelius Kölbel will give a talk in Bellingham Technical Colleage, U.S.A. At the LinuxFest NorthWest 2018 you can learn about what makes privacyIDEA so unique in regards to workflow integrations using the privacyIDEA Event Handler system automating a lot of individual tasks.

Join the discussion

Join the discussion a community.privacyidea.org.

You want to use two factor authentication for all your users? But you are always wondering how you should enroll an authentication device to every single of your users? Existing solutions do not provide convenient ways to equip thousands of users easily with a second factor?

Using automated processes with a REST API and an automating event handler privacyIDEA provides the necessary means to easily do this task.

At FOSDEM Cornelius will give a talk about how easy it can be using privayIDEA to enroll second factors to all your lots of users. Join FOSDEM in Brussels and February 4th and learn about those great features of privacyIDEA.

Secure Rollout of a smartphone app

The central new feature of privacyIDEA 2.21 is the possibility to enroll a smartphone token in a more secure way. privacyIDEA supported smartphone Apps like the Google Authenticator and FreeOTP right from the start. But you already might be aware of the problems with enrolling smartphone tokens.

This is why we added a 2-step enrollment in privacyIDEA 2.21.

2-Step enrollment in privacyIDEA 2.21

Using privacyIDEA you have now the possibility to enroll a smartphone token in a much securer way. The sensitive secret key is created from a part generated on the server side and a second part generated on the phone side. This way an attacker can no longer easily copy the smartphone token during the enrollment process. You can find a more technical specification of the two step enrollment in the online documentation.

The new privacyIDEA Authenticator App will support this new two step enrollment and is also backward compatible to the normal Google Authenticator enrollment URI. Ask the company NetKnights to be part of the beta testing phase of the privacyIDEA Authenticator App.

Easy administration

Many enhancements will make the daily life easier for the token administrator. The root user can now export an encrypted PSKC file. The data can then be imported to another privacyIDEA instance or to any other RFC6030 complient applicantion. The event handlers were also improved: The Notification handler now has more tags to be used in the body and the Federation handler can forward administrative requests.

Clean-up Audit log

Audit Log can be rotated in a more sophisticated way. The administrator can specify retention times for different log entries.

Better HSM support

Hardware Securtiy Modules can now be used to generate random numbers at many different places within privacyIDEA:

You can view a complete changelog at github.

Enterprise Edition

If you are running large mission critical setups, privacyIDEA is also available as Enterprise Edition with support and warranty/liability.

privacyIDEA going FOSDEM

The privacyIDEA project will be at FOSDEM 2018 on February 3rd and 4th. We have a stand in building H. Please join us there!

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

The tokeninfo table

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

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

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

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

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

But you can also set any other value.

Event Handler and tokeninfo

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

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

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

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

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

How to use tokeninfo fields

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

Again the event handler

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

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

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

But often “now” is not the right moment!

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

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

Clean it! The token janitor

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

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

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

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

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

privacyIDEA is extremely cool!

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

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