The MANIFEST file
The MANIFEST file is a YAML file and should conform to version 1.2 of the YAML specification.
It must contain the following information about the plugin:
- name: The identifier of the plugin during the upload to SPS. The initial character must be an alphabetical character, while the rest may be alphabetical characters, numerals or '_'. While case sensitivity is supported, special characters (for example, '@' or '&') are not permitted.
- description: The description of the plugin. This description is displayed on the SPS web interface.
- version: The version number of the plugin. It must begin with a numeral (for example, 2.0.3).
- type: The type of the plugin. It must be credentialstore for a Credential Store plugin and aa for an Authentication and Authorization plugin.
- api: The version number of the required SPS API. The current version number is 1.1.
It may contain the following elements:
- entry_point: main.py: The custom entry point of the plugin. If ommitted, the plugin will be executed with Python2 interpreter. If included, the plugin will be executed with an interpreter specified on the first line of the main.py file. For more information, see the available Python environments.
- scb_min_version: The minimum syslog-ng Store Box product version compatible with the plugin. For example, 5.10.0 means 5F10.
- scb_max_version: The maximum compatible syslog-ng Store Box product version. To allow any version below a certain value, add the ~charater. For example, 5.11.0~ means "any version up till, but not including, 5.11.0".
Example
name: name: SPS_RADIUS
description: RADIUS (RSA) MFA plugin plugin
version: 2.0.3
type: aa
api: 1.1
entry_point: main.pyAPI versioning
SPS supports only a single version of the plugin API.
The required version of SPS API must be in <major number>.<minor number> format.
|
|
NOTE:
SPS uses semantic versioning for the API. That is, if the plugin requires API version <x>.<y>, the API version's <major number> must be equal to <x> and the <minor number> must be equal to, or greater than, <y>. Otherwise the plugin cannot be uploaded. For example, if the API version of SPS is 1.3, SPS can use plugins with the required API version numbers 1.0, 1.1, 1.2, and 1.3. Versions 1.4 and 2.0 will not work. Currently the API version number is 1.1. |
Plugin versioning with Python2 legacy plugins
For Python2 legacy plugins the api: version should be 1.0.
Plugin versioning for Python3 plugins using the Plugin SDK module
For Python3 plugins using the Plugin SDK module the api: version should be the same as the <major number>.<minor number> version of the Plugin SDK. That is, if the Plugin SDK version is 1.2, write api: 1.2 in the MANIFEST file.
|
|
NOTE:
The plugin does not need to be upgraded as long as the <major number> version remains the same, therefore the plugin should work with 1.3, 1.4 or higher API versions. |
The available Python environments
If you have no entry_point in the MANIFEST file
The plugins must be compatible with Python version 2.6.5, and have access to the following Python modules:
-
dns
-
httplib
-
json
-
lxml
-
openssl
-
urllib
-
urllib2
-
xml
-
xmllib
-
xmlrpclib
If you have entry_point: main.py in the MANIFEST file (the main.py starting with '#!/usr/bin/env pluginwrapper3')
In this case, the plugin must be Python 3.6.7 compatible. The plugin has access to these Python 3 modules:
oneidentity_safeguard_sessions_plugin_sdk (version == 1.1.2, https://oneidentity.github.io/safeguard-sessions-plugin-sdk/1.1.2/)
|
|
NOTE:
The <major> and <minor> version number of Plugin SDK is always equal to the SPS API version of the same release. |
The Plugin SDK module mentioned above is a tool that allows you to reliably access SPS features and can be downloaded from Downloads page. In addition, the Plugin SDK module also allows you to develop or test plugins outside SPS. For more detailed information about the Plugin SDK module, see the Developer's Guide here.
- pyOpenSSL (version >= 17.5.0, https://pyopenssl.org/en/17.5.0/index.html)
- python-ldap (version >= 3.0.0, https://www.python-ldap.org/en/python-ldap-3.0.0/)
- requests (version >= 2.18.4, http://docs.python-requests.org/en/master/)
- urllib3 (version >= 1.22, https://urllib3.readthedocs.io/en/latest/)
- pyyaml (version >= 3.12, https://pyyaml.org/)
The main.py module
The main.py file is a Python module that the framework attempts to execute. The following restrictions apply:
- The main.py module must contain the Plugin class. SPS searches for the plugin hook implementations under the Plugin class. SPS instantiates this class and invokes the hooks on the resulting instance.
- The Plugin class must have an __init__(self, configuration="") method. This is how the Configuration (for example, at Policies >AA Plugin Configuration > Configuration or Policies > Credential Stores > Configuration) is passed to the Plugin instance as string.
- The Plugin class must have member methods for all defined hooks.
The plugin is executed when a predefined entry point (hook method) is invoked. After returning the result, the plugin exits immediately.
|
|
NOTE:
Plugins have a global timeout limit. The plugin timeout is half of the timeout value of the protocol proxy that uses the plugin (configured on the <Protocol name> Control > Settings page of the SPS web interface). By default, the proxy timeout is 600 seconds,therefore the default plugin timeout is 300 seconds. |
Hooks can be defined with zero or more arguments and can usually return None or a dict with the appropriate keys. The order of the hook arguments is not defined. Instead, all arguments are passed by name.
All arguments are optional. Only the arguments actually used in the hook need to be specified.
No global state is preserved inbetween calls. Therefore, you have to use the cookie key in the returned dictionary to persist data between subsequent calls of the same plugin or between the different methods of a plugin. The cookie should be a dictionary containing simple data items. It has to be serializable to JSON. To persist data between two different plugins used in the same session, use the session_cookie key.
You can use (**kwargs) to get all possible call arguments in a hook, including the cookie argument.
The following hooks must all be implemented:
- authenticate: Called to identify the user connecting through SPS.
- authorize: Called when the remote username and the address of the target server are available (after the authentication hook and any inband gateway authentication or inband destination selection are completed).
- session_ended: Called when the session is closed. It is called exactly once for the same session. For example, you can use this hook to send a log message related to the entire session, or close the ticket related to the session if the plugin interacts with a ticketing system.