.. _tokenhandler: Token Handler Module -------------------- .. index:: Token Handler, Handler Modules 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. Possible Actions ~~~~~~~~~~~~~~~~ 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*. delete ...... The token which was identified in the request will be deleted if all conditions are matched. unassign ........ The token which was identified in the request will be unassign from the user if all conditions are matched. disable ....... The token which was identified in the request will be disabled if all conditions are matched. enable ...... The token which was identified in the request will be enabled if all conditions are matched. .. _event_token_enroll: 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. By default the generation of the token will use the parameter ``genkey``, to generate the otp key. (see :ref:`rest_token`). The action ``enroll`` also can take the options **dynamic_phone** (in case of tokentype SMS) and **dynamic_email** (in case of tokentype email). Then these tokens are created with a dynamic loadable phone number or email address, that is read from the user store on each authentication request. Finally the administrator can specify the option **additional_params**. This needs to be a dictionary with parameters, that get passed to the init request. You can specify all parameters, that would be used in a ``/token/init`` request: {"hashlib": "sha256", "type": "totp", "genkey": 0, "otpkey": "31323334"} would create a TOTP token, that uses the SHA256 hashing algorithm instead of SHA1. ``genkey: 0`` overrides the default behaviour of generating an OTP secret. Instead the fixed OTP secret "31323334" (``otpkey``) is used. If the tokentype is set to "email" or "sms", you can also specify an SMTP server or SMS gateway configuration for the token enrolled by selecting a configuration in the corresponding field (**smtp_identifier** or **sms_identifier**). If none is selected, then the default system configuration will be used. 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}`` or ``{now}`` to set the current timestamp. In addition you can append an offset to *current_time* or *now* like ``{now}-12d`` or ``{now}+10m``. This would write a timestamp which is 12 days in the past or 10 minutes in the future. The plus or minus must follow without blank, allowed time identifiers are s (seconds), m (minutes), h (hours) and d (days). Other tags are ``{client_ip}`` for the client IP address and ``{ua_browser}`` and ``{ua_string}`` for information on the user agent. 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. set countwindow ............... Here the count window of a token can be set. This requires an integer value. 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. In addition you can append an offset to *current_time* or *now* like ``{now}-12d`` or ``{now}+10m``. This would write a timestamp which is 12 days in the passt or 10 minutes in the future. The plus or minus must follow without blank, allowed time identifiers are s (seconds), m (minutes), h (hours) and d (days). Other tags are ``{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 :ref:`faq_initial_synchronization`. set failcounter ............... Using the action ``set failcounter`` you can reset the fail counter by setting it to 0 or also "block" the token by setting the fail counter to what ever value the "max_fail" is, e.g. 10. Only integer values are allowed. See :term:`failcount`. change failcounter .................. Using the action ``change failcounter`` you can increase or decrease the fail counter. Positive and negative integer values are allowed. Positive values will increase the fail counter, negative values will decrease it. .. note:: To limit a token handler in decreasing the fail counter, you may use the event handler condition **failcounter** (c.f. :ref:`handlerconditions`) and set it to e.g. ">-5". Once this condition is not met anymore, the event handler will not be triggered. set max failcount ................. Using the action ``set max failcount`` you can set the maximum failcounter of a token to the specific value. Only integer values are allowed. See :term:`failcount`. set random pin .............. Sets a random PIN for the handled token. The PIN is then added to the response in ``detail->pin``. This can be used in the *notification handler*. Please take care, that probably the PIN needs to be removed from the response using the *response mangler handler* after handling it with the notification handler. add tokengroup .............. The token is assigned to the given tokengroup. .. Note:: A token can be assigned to several different tokengroups at the same time. remove tokengroup ................. The token is unassigned from the given tokengroup. Code ~~~~ .. automodule:: privacyidea.lib.eventhandler.tokenhandler :members: :undoc-members: