8.3. CredentialStorePlugin

8.3.1. CredentialStorePlugin way of working

When SPS calls the CredentialStorePlugin, it does so by creating a CredentialStorePlugin (or more likely derived class) instance. The initialization of the instance processes the given plugin configuration and sets the logging level appropriately.

On the new plugin instance SPS will make a call to get_password_list and/or get_private_key_list to fetch passwords and ssh private keys to be used against the target server of the user session. If the authentication on the server is successful, then SPS will once again instantiate the plugin and call authentication_completed. Note that this step is not called if the authentication fails. When the session is closed, SPS will call the session_ended method of yet another instance of the plugin.

In all cases CredentialStorePlugin implements the methods above and first collects the input parameters in self.connection and sets up self.cookie.

When self is set up, CredentialStorePlugin calls the user defined implementation in do_get_password_list(), do_get_private_key_list() for all account, asset pairs generated by _generate_accounts(), _generate_assets() methods until either a credential is found or there are no more accounts to check. The self.account and self.asset attributes are set to the account, asset to be checked out and are also put into the cookie so they are available in the later plugin invocations.

The do_authentication_completed() and do_session_ended() may be implemented to implement different methods regarding successful authentication on the target server and at the end of the session.

To ensure that credentials are checked in even in the case of failed target server authentication, the do_check_in_credential() method should be implemented which is called in these cases:

• authentication_completed when authentication on the target server was successful,

• get_password_list when a private key was checked out previously, but was not successfully used on the target server,

• session_ended when authentication on the target server failed.

8.3.2. CredentialStorePlugin methods and attributes

class safeguard.sessions.plugin.credentialstore_plugin.CredentialStorePlugin(configuration, defaults=None, logger=None)

The CredentialStorePlugin class implements the common functionality of credential store plugins. The following methods and attributes are available outside the constructor - on top of the ones inherited from PluginBase <safeguard.sessions.plugin.plugin_base.PluginBase class:

New in version 1.2.0.

connection

The self.connection provides a read-only view of the parameters passed to the currently executing plugin hook, e.g. do_get_password_list().

cookie

The self.cookie attribute is a dict that retains its contents between invocations of do_get_password_list(), do_get_private_key_list(), do_authentication_completed(), do_check_in_credential() and do_session_ended(). This is the way to pass data between these functions.

When the plugin returns the contents are automatically returned to SPS.

session_cookie

The self.session_cookie is similar to self.cookie, but it is also visible in other plugins in the same session. When the plugin returns the contents are automatically returned to SPS.

account

The self.account attribute contains the account identifier that should be checked out. This value is also kept in the cookie. The list of candidates is generated by the _generate_accounts() method.

asset

The self.asset attribute contains the asset identifier that should be checked out. This value is also kept in the cookie. The list of candidates is generated by the _generate_assets() method.

do_get_password_list()

The do_get_password_list() method should implement fetching passwords for the given account name and possible assets names.

Returns

a dict containing a list of passwords: {‘passwords’: [‘secret’, ‘topsecret’]} or empty list [] if no password could be fetched.

do_get_private_key_list()

The do_get_private_key_list() method should be implemented like do_get_password_list(), but return ssh private keys instead. :return: a dict containing a list of ssh private keys: {‘private_keys’: [(‘ssh-rsa’, ‘secret-rsa-key-data’), (‘ssh-dss’: ‘secret-dsa-key-data’)]} or empty list [] if no private keys could be fetched.

do_authentication_completed()

The do_authentication_completed() method can be used to implement logic to run in case of successful authentication on the target server.

Note: self.connection will only contain session_id.

Returns

None

do_check_in_credential()

The do_check_in_credential() method can be used to implement logic to check-in the passwords and keys previously checked out by do_get_password_list or do_get_private_key_list.

Note: self.connection will only contain session_id.

Returns

None

do_session_ended()

The do_session_ended() method can be used to implement logic related to the end of a session.

Note: self.connection will only contain session_id.

Returns

None

_generate_accounts()

The _generate_accounts() method generates a list of account identifiers in the credential store.

Returns

a generator of account identifiers.

_generate_assets()

The _generate_assets() method generates a list of asset identifiers in the credential store.

Returns

a generator of asset identifiers.