Introduction
The following sections provide an overview on creating custom Credential Store plugins that can be used to authenticate on the target servers using an external Credential Store server (for example, a password manager or SSH private key store). For details on using an existing plugin, see "Integrating external authentication and authorization systems" in the Administration Guide.
|
|
Caution:
Using custom plugins in SPS is recommended only if you are familiar with both Python and SPS. Product support applies only to SPS: that is, until the entry point of the Python code and passing the specified arguments to the Python code. One Identity is not responsible for the quality, resource requirements, or any bugs in the Python code, nor any crashes, service outages, or any other damage caused by the improper use of this feature, unless explicitly stated in a contract with One Identity. If you want to create a custom plugin, contact our Support Team for details and instructions. |
The Credential Store plugin is a Python module.One Identity Safeguard for Privileged Sessions (SPS) invokes the module to request the password or the SSH private key of the target user. The plugin processes the request, returns the result to SPS, and exits. SPS then processes the result.
The backup and restore functionality of SPS handles the uploaded credential store plugin as part of SPS's configuration. You do not need to create separate backups of your Credential Store plugin.
Structure of a plugin
An SPS plugin is a .zip file that contains a MANIFEST file (with no extension) and a Python module named main.py in its root directory. The plugin .zip file may also contain an optional default.cfg file that serves to provide an example configuration that you can use as a basis for customization if you wish to adapt the plugin to your site's needs. The size of the .zip file is limited to 20 megabytes.
The MANIFEST file
The MANIFEST file is a YAML file and should conform to version 1.2 of the YAML specification. It should contain the following information about the plugin:
- api: The version number of the SPS API. Must be 1.0.
- type: The type of the plugin. It must be credential store for a Credential Store plugin, and authentication and authorization plugin for an Authentication and Authorization plugin.
- name: The name of the plugin.
- version: The version number of the plugin. Must be in <major-version>.<minor-version> format, for example, 0.4, 1.5, 3.3, and so on.
- description: The description of the plugin. This description is displayed on the SPS web interface.
Example
api: 1.0 type: credentialstore name: MyCustomPlugin version: 1.0 description: Example plugin for SPS
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.
- 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, meaning the 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 signifies the lifetime of a logical connection: 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.