Plugin Developer
To enable a certain type of service for WaTTS, a corresponding plugin is needed. Sometimes there are even multiple plugins for the same type of service, e.g. due to different local policies.
The communication between WaTTS and the plugin is done by passing one argument to the script or sending it to stdin of the plugin and parsing the stdout
of the script. If it will be passed as parameter or sent via stdin is configured automatically at startup. See Listing Supported Parameter / Supported Features / stdin.
Plugin Input
If stdin is enabled the parameter will be sent via stdin and when done an EOF (end of file) will be sent.
The parameter coming from the WaTTS is a base64url
encoded json
object.
The decoded json
object has the following format:
The items of the object are:
Listing The Supported Parameter (action = parameter)
WaTTS requests the supported parameter of the plugin by setting the action
to parameter
. This is always passed as parameter on the command line, subsequent request will be sent via stdin, if supported by the plugin.
The expected result is:
The result MUST be OK and the version should describe the version of your plugin so e.g. errors can be tracked. All entries are mandatory.
Version (version)
WaTTS expects a version to be present in the response so it can list the version for later debugging and helping the development of plugins.
Email of the developer/team (developer_email)
If this is present WaTTS expects it to be a vaild email address and, if configured, sends emails on invalid behaviour of the plugin to the developer.
Supported features (features)
This is a JSON object containing keys with additional information. The supported keys and the meaning/format of their value are listed in the table below.
Config Parameter (conf_params)
Each config parameter consists of an json
object with three key-value pairs:
name: the name of the parameter, MUST consists of only [a-z0-9_]
type: the datatype of the parameter, currently supported are
boolean
andstring
default: the default value to use if not configured, please ensure safe defaults
Request Parameter Sets (request_params)
The supported request parameters are grouped into sets. A set is a group of parameters that belong together logically. At the web interface, a parameter set is shown in one dialog page, to switch between them press 'left' or 'right' in the carousel of sets.
The Advanced
button at the web-interface is enabled if at least one non empty parameter set exists. The Request
button is enabled if either the empty set exists (see example above), or a set exists with no mandatory parameters.
Each entry in a set is described with five key-value pairs:
key: a key used to pass the value, this is also the key to lookup the information when performing a request, MUST consist only of [a-z0-9_].
name: a short nice name, displayed to the user
description: a longer description, also shown to the user
type: the input type to use, currently only supported
textarea
mandatory: either
True
orFalse
, indicates whether this field MUST be filled
Performing a Request (action = request)
When the action
is set to request
, it means that a user or a service on a user's behalf wants to create a credential. The plugin should perform any necessary action to create the credential for the user and print a json
object on stdout
.
The expected format of the json
object for a credential is:
The expected format of a request to perform an additional login is:
please keep in mind that the user may deny the request.
In case of an error, the expected json is:
The entries in the credential object (part of the list in 'credential' above) are:
Performing a Revoke (action = revoke)
When the action
is set to revoke
, the credential identified by the state
should be invalidated or removed, depending on the type of service. In the SSH plugin, e.g., the created ssh-key is removed from the authorized keys. When performing a request, WaTTS expects the stdout
to be a json
object. In case of revoke, it may contain one of the two elements:
or in case of an error:
Therefore, if only the result key is present in the object, WaTTS assumes that everything went fine, however, if the error key is present it assumes that something went bad and does not remove the credential state from its database.
Last updated