Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 5.10.0 - Creating custom Authentication and Authorization plugins


The following sections provide an overview on creating custom plugins for One Identity Safeguard for Privileged Sessions (SPS) to authenticate your users to external services in addition to the authentication performed on the target server. For example, such plugins can implement two-factor (2FA) or multi-factor authentication (MFA) methods, or request the user to provide a valid ticket ID for the connection. 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.

    Every SPS plugin is a Python module. SPS invokes the module to request the password 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 plugins as part of SPS's configuration. You do not need to create separate backups of your plugins.

  • How the Authentication and Authorization plugin works

    If a Connection Policy has an Authentication and Authorization plugin (AA plugin) configured, SPS executes the plugin as the last step of the connection authorization phase. SPS can request the client to perform other type of authentication before executing the plugin. Using an AA plugin in a Connection Policy is treated as a gateway authentication if:

    • the plugin authenticates the user,
    • authentication is successful,
    • the plugin returns the gateway_user and gateway_groups values, identifying the user it has authenticated.

    Other types of gateway authentication will come before authentication by the AA plugin, so information from any other type of gateway authentication (for example, the username and usergroups of this authentication) will already be available (and therefore can be used by the plugin). If the AA plugin does perform gateway authentication, you can use a Credential Store as well.

    However, for technical reasons, the web-based gateway authentication (that is, authenticating on the SPS web interface if the Require Gatweay Authentication on the SPS Web Interface option is selected in the Connection Policy) is performed after the AA plugin, so using AA plugin and ticking Require Gateway Authentication on the SPS Web Interface at the same time is not a valid configuration.

    SPS executes the authorize method after the authentication method and any inband gateway authentication or inband destination selection steps. As a result, the authorize method already has access to the IP address of the target server and the remote username (the username used in the server-side connection).

    In the RDP, SSH, and Telnet protocols, the plugin can interactively request additional information from the client.

    Optionally, the plugin can return the gateway_user and gateway_groups values. SPS will only update the gateway username and gateway groups fields in the connection database if the plugin returns the gateway_user and gateway_groups values. The returned gateway_user and gateway_groups values override any such attributes already available on SPS about the connection (that means that channel policy evaluations will be affected), so make sure that the plugin uses the original values appropriately.

    If the plugin returns the gateway_user and gateway_groups values, you may have to configure an appropriate Usermapping policy in the Connection Policy. If the plugin returns a gateway_user that is different from the remote user, the connection will fail without a usermapping policy. For details on usermapping policies, see "Configuring usermapping policies" in the Administration Guide.


    Structure of a plugin

    An SPS plugin is a .zip file that contains a MANIFEST file (with no extension) and a Python module named 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.
    api: 1.0
        type: credentialstore
        name: MyCustomPlugin
        version: 1.0
        description: Example plugin for SPS
    Self Service Tools
    Knowledge Base
    Notifications & Alerts
    Product Support
    Software Downloads
    Technical Documentation
    User Forums
    Video Tutorials
    RSS Feed
    Contact Us
    Licensing Assistance
    Technical Support
    View All
    Related Documents

    The document was helpful.

    Select Rating

    I easily found the information I needed.

    Select Rating