This plugins work with Balabit PAM/PSM (SCB) 5.3 and newer versions.

We provide two plugins with capabilities to be used as credential store plugin in PSM (SCB). With the plugin PSM can
retrieve credentials (both password and SSH keys) to automatically login to target systems without the user need to
provide or know the credential of the target account.

PSM can authenticate using 3 different methods:
 * Proxy account which is configured on the PSM box. In this case PSM uses the same user to retrieve all credentials,
   therefore this user need to have appropriate permissions.
 * Reuse gateway authentication password. When PSM uses password based gateway authentication the same username/password
   can be used to retrieve the credentials for the give target account.
 * Pass access token as a "token" parameter. This way PSM using the token can retrieve the user identity and also the
   credentials for the target account. This mode is especially useful to provide SSO and federated access as the user
   does not need to do a separate gateway authentication on PSM. (To use this mode the AA plugin needs to be deployed
   parallel to the credstore plugin to handle the token and to authenticate the user.)

The plugin searches the target and account by name. Administrator need to ensure that the targets are recorded by the
same name as refered by users during connections. The plugin can be configured to restrict searches under a specified
group sub-tree.

The plugin can also be configured to automatically reset the credentials after the user is successfully logged in to the
target account.

The credential store plugin uses an INI based configuration file with the following options:

[passman]
url=                # The base URL where PSM can reach passman, eg: https://passman.example.com:8443
ca=                 # The CA certificate in PEM format that can be optionally specified to check passman HTTPS certificate
check_host_name=    # When set to false (0) passman certificate CN is not checked to match the host name in URL
                    # only used when CA is provided and server certificate verification is done


[auth]
use_credential=     # Set what credential to use for authentication against passman
                    # * "token": use token based authentication, which requires AA plugin used for the connection
                    # * "explicit": use proxy account with explicitly configured credentials
                    # * "gateway": use username/password from previous gateway authentication
                    # "gatway" is the default
provider=           # Passman authentication provider to use when "explicit" authentication is used, default: "local"
domain=             # Domain of the authenticating user, default: "local"
username=           # Username to use when "explicit" authentication is used
password=           # Password to use when "explicit" authentication is used


[reset]
reset_credential=   # When set to true (1) credential is reset after successful login to target account

[search]
under_group=        # Optional parameter to control where targets are searched, group ID must be configured


In order to use credential store plugin in PSM (SCB) the following needs to be configured:

1, Upload the credential store plugin (and also the AA plugin when used with token based authentication)
Basic->Plugins

2, Add a Credential store policy that uses the Passman credstore plugin and configure it based on the above
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-credential-store-remote-plugin.html

3a, When token authentication is used configure the AA plugin
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-authentication-authorization-plugin.html

3b, When explicit or gateway authentication is used either configure an LDAP server or a Local user database
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-ldap.html
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-keymapping.html

4, Add a usermapping policy when shared accounts (eg: root/administrator) is accessed using personalized accounts
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-policies-usermapping.html
Optionally add local user lists to be used as a group in usermapping policies when local users database is used or
LDAP groups need to be extended:
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-user-list.html

5, In case of SSH, modify/add a SSH Authentication policy that does gateway authentication (not required in case of
token based authentication with AA plugin)
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-authentication-policy.html
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-authentication-policy-client.html

6, Add a connection policy with specifying the credential store policy
In case of token authentication select the configured AA Policy
In case of usermapping select the configured usermapping policy
In case of SSH select the configured SSH Authentication policy
In case of RDP follow the extra steps for setting up gateway authentication:
https://www.balabit.com/documents/scb-5.4-guides/en/scb-guide-admin/html/scb-rdp-tsgw-clients.html


To connect through PSM use the following SSH username:
gu=<gatewayuser>@<remote-user>

In case of token based authentication:
token=<access_token>@<remote-user>

When PSM is in non-transparent mode (the client is connecting to PSM directly and connection uses inband target
selection):
gu=<gatewayuser>@<remote-user>@<remote-target>

token=<access_token>@<remote-user>@<remote-target>

Note that when gateway authentication is used and no gu= is specified as part of the username, PSM prompts the user
to enter the username, so the following usernames can be used:
For transparent deployment: <remote-user>
For non-transparent deployment: <remote-user>@<remote-target>
