10.6.3. Script Handler Module

The script event handler module is used to trigger external scripts in case of certain events.

This way you can even add external actions to your workflows. You could trigger a database dump, an external printing device, a backup and much more.

10.6.3.1. Possible Actions

The actions of the script event handler are the scripts located in a certain script directory. The default script directory is /etc/privacyidea/scripts.

You can change the location of the script directory and give the new directory in the parameter PI_SCRIPT_HANDLER_DIRECTORY in your pi.cfg file.

10.6.3.2. Possible Options

Options can be passed to the script. Your script has to take care of the parsing of these parameters.

10.6.3.2.1. background

This option is required. With wait privacyIDEA waits for the script to complete, which can block the request. With background the script runs in the background and the HTTP request returns early.

10.6.3.2.2. logged_in_role

Add the role of the logged in user. This can be either admin or user. If there is no logged in user, none will be passed.

The script will be called with the parameter:

--logged_in_role <role>

10.6.3.2.3. logged_in_user

Add the logged in user. If there is no logged in user (e.g. on /validate/check), none@none will be passed. For an internal administrator the realm part is empty (admin@).

The script will be called with the parameter:

--logged_in_user <username>@<realm>

10.6.3.2.4. raise_error

Only available if background is set to wait. If the script can not be started or fails with an error code, an exception is raised in the HTTP request.

10.6.3.2.5. realm

Add --realm <realm> of the user the request is about as script parameter: the realm of the user the request names; on the token endpoints, for a token given only by its serial, the realm of the token owner; for a logged in user, the realm of this user. If the request has no user (e.g. /validate/check with only a serial), none will be passed.

10.6.3.2.6. serial

Add --serial <serial number> as script parameter. If no serial number is given, none will be passed.

10.6.3.2.7. sync_to_database

Finish current transaction before running the script. This is useful if changes to the database should be made available to the script or the running request.

10.6.3.2.8. user

Add --user <username> of the user the request is about as script parameter: the user the request names; on the token endpoints, for a token given only by its serial, the owner of the token; for a logged in user, this user. If the request has no user (e.g. /validate/check with only a serial), none will be passed.

Note

The script handler only runs scripts from its script directory and only passes the parameters above. To call a tool like privacyidea-get-unused-tokens, which expects its own command and arguments, put a small wrapper script into the script directory that ignores the parameters and calls the tool.

10.6.3.3. Code

This is the event handler module for calling external scripts. You can put any script in the directory specified in PI_SCRIPT_HANDLER_DIRECTORY and call this script in any event.

The scripts can take parameters like

• serial

• user

• realm

• logged_in_user

• logged_in_role

class privacyidea.lib.eventhandler.scripthandler.ScriptEventHandler

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

Returns:

list of allowed positions

description = 'This event handler can trigger external scripts.'

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 = 'Script'