API 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:
- get_password_list: Called when a password is required to login on the target.
- get_private_key_list: Called when a private key is required to login on the target.
- authentication_completed: Called after a successful login attempt.
- session_ended: A session is the logical unit of user connections: it starts with logging in to the target, and ends when the connection ends. The session_ended hook is the notification for the end of the session. It is called exactly once for the same session.
get_password_list
Called when a password is required to login on the target. Can be called multiple times for the same session.