Plugin development
------------------

Follow the steps in :ref:`gettingstarted-label` to set up the correct Python environment. There are administrative
steps bellow to describe the plugin. After adding some code to the plugin, the directory can be packaged in a ZIP file
and uploaded to SPS.

Administrative tasks
^^^^^^^^^^^^^^^^^^^^

Update the following files with information correct for your plugin:

``MANIFEST``: plugin name, descriptions, etc. For details consult the
*Creating custom Credential Store plugins* developer's guide.

``Pipfile``: describes what additional Python3 PIP packages to package in the eventual plugin and also what packages to
use at development time. Note that the Plugin SDK should *not* be listed in the [packages] section,
as the Plugin SDK is pre-installed on Safeguard for Privileges Sessions. There are other pre-installed python packages
on the system, consult the developer's guide for more information. In most cases the Plugin SDK should *not* be listed
in the [dev-packages] section either as it is installed manually as explained in :ref:`gettingstarted-label`.

Basic functionality
^^^^^^^^^^^^^^^^^^^

Inherit the Plugin class from
:class:`CredentialStorePlugin <safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin>` and implement
the appropriate user defined functions:
:meth:`do_get_password_list()\
<safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.do_get_password_list>`,
:meth:`do_get_private_key_list()\
<safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.do_get_private_key_list>`,
:meth:`do_check_in_credential()\
<safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.do_check_in_credential>`,
:meth:`do_authentication_completed()\
<safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.do_authentication_completed>` or
:meth:`do_session_ended()\
<safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.do_session_ended>`.
The expected return values are defined in the technical document
*Creating custom Credential Store plugins*.

This is a basic example in which the credential store does not rotate passwords, just simply stores them:

.. code-block:: python

    #!/usr/bin/env pluginwrapper3

    from safeguard.sessions.plugin import CredentialStorePlugin

    class Plugin(CredentialStorePlugin):
        def do_get_password_list(self):
            #
            # logic to fetch password based on self.account and self.asset and any other
            #   data in self.connection, self.configuration, etc.
            #
            password = ...
            return {'passwords': [password]}


In the next example the credential store does rotate passwords and it will give a checkout identifier to be used
for checking in the password later.

.. code-block:: python

    #!/usr/bin/env pluginwrapper3

    from safeguard.sessions.plugin import CredentialStorePlugin
    from safeguard.sessions.plugin.plugin_base import cookie_property

    class Plugin(CredentialStorePlugin):
        @cookie_property
        def checkout_id(self):
            return None

        def do_get_password_list(self):
            #
            # logic to fetch password and checkout id based on self.account and self.asset and
            #   any other data in self.connection, self.configuration, etc.
            #
            self.checkout_id = ...
            password = ...
            return {'passwords': [password]}

        def do_check_in_credential(self):
            # logic to check in the password using self.checkout_id and/or self.account, self.asset


Pre-defined attributes on self
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following attributes are available in all the above methods, except where otherwise noted.

:class:`self.connection <safeguard.sessions.plugin.connection_info.ConnectionInfo>` which is a read-only object to show
a record of the SPS connection that is being processed. For example to find out the protocol used in the connection,
write ``self.connection.protocol``. Note: only 'session_id' is available in
:meth:`do_authentication_completed() \
<safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.do_authentication_completed>`
:meth:`do_check_in_credential()\
<safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.do_check_in_credential>` and
:meth:`do_session_ended() <safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.do_session_ended>`
methods.

:py:attr:`self.cookie <safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.cookie>` represents the
cookie passed to and returned by the plugin.

:py:attr:`self.session_cookie <safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.session_cookie>`
represents the session cookie passed to and returned by the plugin.

:py:attr:`self.account <safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.account>` represents the
account name.

:py:attr:`self.asset <safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin.asset>` represents the
asset name.