Highest flexibility with the tokeninfo fields

On a wish list for another OTP solutions I saw the requirement to have an “enrollment date” or a “last use date” of a token.

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! 😉