9.4.2. Token Handler Module

The token event handler module is used to perform actions on tokens in certain events.

This way you can define workflows to automatically modify tokens, delete or even create new tokens.

9.4.2.1. Possible Actions

9.4.2.1.1. set tokenrealm

Here you can set the token realms of the token.

E.g. You could use this action to automatically put all newly enrolled tokens
into a special realm by attaching this action to the event token_init.

9.4.2.1.2. delete

The token which was identified in the request will be deleted if all conditions are matched.

9.4.2.1.3. unassign

The token which was identified in the request will be unassign from the user if all conditions are matched.

9.4.2.1.4. disable

The token which was identified in the request will be disabled if all conditions are matched.

9.4.2.1.5. enable

The token which was identified in the request will be enabled if all conditions are matched.

9.4.2.1.6. enroll

If all conditions are matched a new token will be enrolled. This new token can be assigned to a user, which was identified in the request.

The administrator can specify the tokentype and the realms of the new
token.

9.4.2.1.7. set description

If all conditions are matched the description of the token identified in the request will be set.

You can use the tag {current_time} to set the current timestamp, {client_ip} for the client IP address and {ua_browser} and {ua_string} for information on the user agent.

9.4.2.1.8. set validity

If all conditions are matched the validity period of the token will be set.

There are different possibilities to set the start and the end of the validity period. The event definition can either contain a fixed date and time or if can contain a time offset.

Fixed Time

A fixed time can be specified in the following formats.

Only date without time:

  • 2016/12/23
  • 23.12.2016

Date with time:

  • 2016/12/23 9:30am
  • 2016/12/23 11:20:pm
  • 23.12.2016 9:30
  • 23.12.2016 23:20

Starting with version 2.19 we recommend setting the fixed time in the ISO 8601 corresponding time format

  • 2016-12-23T15:30+0600

Time Offset

You can also specify a time offset. In this case the validity period will be set such many days after the event occurred. This is indicated by using a “+” and a specifier for days (d), hours (h) and minutes (m).

E.g. +30m will set to start the validity period in 30 minutes after the event occurred.

+30d could set the validity period to end 30 days after an event occurred.

Note

This way you could easily define a event definition, which will set newly enrolled tokens to be only valid for a certain amount of days.

9.4.2.1.9. set countwindow

Here the count window of a token can be set. This requires an integer value.

9.4.2.1.10. set tokeninfo

Using the action set tokeninfo you can set any arbitrary tokeninfo attribute for the token. You need to specify the key of the tokeninfo and the value.

In the value field you can use the tag {current_time} to set the current timestamp, {client_ip} for the client IP address and {ua_browser} and {ua_string} for information on the user agent and {username} and {realm} for information on the user in the parameters.

Note

Some tokens have token specific attributes that are stored in the tokeninfo. The TOTP token type has a timeWindow. The TOTP and the HOTP token store the hashlib in the tokeninfo, the SMS token stores the phone number.

Note

You can use this to set the timeWindow of a TOTP token for Automatic initial synchronization.

9.4.2.2. Code

This is the event handler module for token actions. You can attach token actions like enable, disable, delete, unassign,... of the

  • current token
  • all the user’s tokens
  • all unassigned tokens
  • all disabled tokens
  • ...
class privacyidea.lib.eventhandler.tokenhandler.ACTION_TYPE[source]

Allowed actions

DELETE = 'delete'
DISABLE = 'disable'
ENABLE = 'enable'
INIT = 'enroll'
SET_COUNTWINDOW = 'set countwindow'
SET_DESCRIPTION = 'set description'
SET_TOKENINFO = 'set tokeninfo'
SET_TOKENREALM = 'set tokenrealm'
SET_VALIDITY = 'set validity'
UNASSIGN = 'unassign'
class privacyidea.lib.eventhandler.tokenhandler.TokenEventHandler[source]

An Eventhandler needs to return a list of actions, which it can handle.

It also returns a list of allowed action and conditions

It returns an identifier, which can be used in the eventhandlig definitions

actions

This method returns a dictionary of allowed actions and possible options in this handler module.

Returns:dict with actions
description = 'This event handler can trigger new actions on tokens.'
do(action, options=None)[source]

This method executes the defined action in the given event.

Parameters:
  • action
  • options (dict) – Contains the flask parameters g, request, response and the handler_def configuration
Returns:

identifier = 'Token'
class privacyidea.lib.eventhandler.tokenhandler.VALIDITY[source]

Allowed validity options

END = 'valid till'
START = 'valid from'