10.6.11. Container Handler Module

The container event handler module is used to perform actions on containers and their tokens in certain events. The container is either identified by the container serial from the request, response or from an identified token.

This way you can define workflows to automatically modify containers, delete or even create new containers. Additionally, the tokens in the container can be modified.

10.6.11.1. Possible Actions

10.6.11.1.1. create

A new container will be created. This new container can be assigned to a user, which was identified in the request. Additionally, a token identified in the request can be added to the container.

The administrator has to specify the container type and can optionally specify a description. With the option user the container is assigned to the user in the request or to the token or container owner, and with the option token the token from the request is added to the container.

10.6.11.1.2. delete

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

10.6.11.1.3. unassign

The container which was identified in the request will be unassigned from all users if all conditions are matched. The tokens in the container will not be changed.

10.6.11.1.4. assign

The container which was identified in the request will be assigned to a user which was identified in the request. If the logged in user performing this action has the role ‘user’, it is always this user. The user is not assigned to the tokens in the container. A container has at most one owner. If it is already assigned to another user, the action fails; combine it with unassign first.

10.6.11.1.5. set states

The administrator can specify states that will be set on the container identified in the request. All other states will be removed.

The administrator can select the new states. At least one state has to be selected; if no state is selected, the states of the container are not changed.

10.6.11.1.6. add states

The administrator can specify states that will be added to the container identified in the request. Previous states that are excluded by the new states will be removed. All other states that are not exclusive are kept.

The administrator can select the new states. If no state is selected, nothing happens.

10.6.11.1.7. set description

For the container identified in the request a new description will be set.

The description may contain tags that are replaced when the event is handled. The tag {now} is replaced by the current timestamp and supports offsets like {now}+5d or {now}-30m (s, m, h, d); {current_time} is a deprecated alias for it. The tags of the notification handlers are available as well, for example {client_ip}, {ua_browser}, {ua_string}, {container_serial}, {username} and {userrealm}. {username} and {userrealm} describe the owner of the container, {admin} and {realm} the acting administrator. A tag that can not be replaced does not fail the event handling, the text is then written as it was entered.

10.6.11.1.8. remove all tokens

All tokens will be removed from the container identified in the request.

10.6.11.1.9. set container info

For the container identified in the request the container info will be set. All previous entries except the internal ones are removed. A key of an internal entry is not written (a warning is logged).

It requires the specification of a key and optionally a value. If no value is defined, it is set to an empty string “”.

The value may contain tags that are replaced when the event is handled. The tag {now} is replaced by the current timestamp and supports offsets like {now}+5d or {now}-30m (s, m, h, d); {current_time} is a deprecated alias for it. The tags of the notification handlers are available as well, for example {client_ip}, {ua_browser}, {ua_string}, {container_serial}, {username} and {userrealm}. {username} and {userrealm} describe the owner of the container, {admin} and {realm} the acting administrator. A tag that can not be replaced does not fail the event handling, the value is then written as it was entered.

10.6.11.1.10. add container info

For the container identified in the request the container info will be added. Previous entries will be kept. Only if the given key already exists, an old entry will be overwritten. Internal entries can not be overwritten: using the key of an internal entry makes the action fail.

It requires the specification of a key and optionally a value. If no value is defined, it is set to an empty string “”.

The value may contain tags that are replaced when the event is handled. The tag {now} is replaced by the current timestamp and supports offsets like {now}+5d or {now}-30m (s, m, h, d); {current_time} is a deprecated alias for it. The tags of the notification handlers are available as well, for example {client_ip}, {ua_browser}, {ua_string}, {container_serial}, {username} and {userrealm}. {username} and {userrealm} describe the owner of the container, {admin} and {realm} the acting administrator. A tag that can not be replaced does not fail the event handling, the value is then written as it was entered.

10.6.11.1.11. delete container info

For the container identified in the request all container info entries will be deleted. Internal entries are kept.

10.6.11.1.12. enable all tokens

For the container identified in the request all contained tokens will be enabled.

10.6.11.1.13. disable all tokens

For the container identified in the request all contained tokens will be disabled.

10.6.11.1.14. unregister

Only for smartphone containers: the registration of the container identified in the request is terminated, and synchronization with the smartphone is not possible anymore. For other container types the action fails.

10.6.11.2. Code

This is the event handler module for container actions.

class privacyidea.lib.eventhandler.containerhandler.ACTION_TYPE[source]

Allowed actions

ADD_CONTAINER_INFO = 'add container info'
ADD_STATES = 'add states'
ASSIGN = 'assign'
DELETE = 'delete'
DELETE_CONTAINER_INFO = 'delete container info'
DISABLE_TOKENS = 'disable all tokens'
ENABLE_TOKENS = 'enable all tokens'
INIT = 'create'
REMOVE_TOKENS = 'remove all tokens'
SET_CONTAINER_INFO = 'set container info'
SET_DESCRIPTION = 'set description'
SET_STATES = 'set states'
UNASSIGN = 'unassign'
UNREGISTER = 'unregister'
class privacyidea.lib.eventhandler.containerhandler.ContainerEventHandler[source]

This is the event handler for container actions.

property actions

This method returns a list of available actions, that are provided by this event handler.

Returns:

dictionary of actions.

property allowed_positions

This returns the allowed positions of the event handler definition. This can be “post” or “pre” or both.

Returns:

list of allowed positions

description = 'This event handler can trigger new actions on containers.'
do(action, options=None)[source]

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:

True if the action was successful, False otherwise (missing information, e.g. serial, user)

identifier = 'Container'