8.6.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.

8.6.2.1. Possible Actions

8.6.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.

8.6.2.1.2. delete

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

8.6.2.1.3. unassign

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

8.6.2.1.4. disable

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

8.6.2.1.5. enable

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

8.6.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. By default the generation of the token will use the parameter genkey, to generate the otp key. (see Token endpoints).

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.

8.6.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} 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.

8.6.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

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.

8.6.2.1.9. set countwindow

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

8.6.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. 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 Automatic initial synchronization.

8.6.2.1.11. 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 failcount.

8.6.2.1.12. 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. Conditions) and set it to e.g. “>-5”. Once this condition is not met anymore, the event handler will not be triggered.

8.6.2.1.13. 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 failcount.

8.6.2.1.14. 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.

8.6.2.1.15. add tokengroup

The token is assigned to the given tokengroup.

Note

A token can be assigned to several different tokengroups at the same time.

8.6.2.1.16. remove tokengroup

The token is unassigned from the given tokengroup.

8.6.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 edumfa.lib.eventhandler.tokenhandler.ACTION_TYPE

Allowed actions

ADD_TOKENGROUP = 'add tokengroup'

ATTACH_APPLICATION = 'attach application'

CHANGE_FAILCOUNTER = 'change failcounter'

DELETE = 'delete'

DELETE_TOKENINFO = 'delete tokeninfo'

DISABLE = 'disable'

ENABLE = 'enable'

INIT = 'enroll'

REMOVE_TOKENGROUP = 'remove tokengroup'

SET_COUNTWINDOW = 'set countwindow'

SET_DESCRIPTION = 'set description'

SET_FAILCOUNTER = 'set failcounter'

SET_MAXFAIL = 'set max failcount'

SET_RANDOM_PIN = 'set random pin'

SET_TOKENINFO = 'set tokeninfo'

SET_TOKENREALM = 'set tokenrealm'

SET_VALIDITY = 'set validity'

UNASSIGN = 'unassign'

class edumfa.lib.eventhandler.tokenhandler.TOKEN_APPLICATIONS

LUKS = 'luks'

OFFLINE = 'offline'

SSH = 'ssh'

class edumfa.lib.eventhandler.tokenhandler.TokenEventHandler

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

property actions

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

Returns:

dict with actions

property allowed_positions

This returns the allowed positions of the event handler definition. :return: list of allowed positions

description = 'This event handler can trigger new actions on tokens.'

do(action, options=None)

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 edumfa.lib.eventhandler.tokenhandler.VALIDITY

Allowed validity options

END = 'valid till'

START = 'valid from'