Password Safe

What is the Password Safe integration, and how is it useful?

The Endpoint Credential Manager (ECM) service integration with Password Safe enables automatic password injection to authorized systems through an encrypted BeyondTrust connection and removes the need to share and expose credentials to privileged accounts. In addition to the automatic rotation and retrieval of managed local accounts, Password Safe can also retrieve linked accounts, giving domain admins and other privileged users access to those credentials on the targeted system.

The integration enables:

• One-click password injection and session spawning
• Credentials to never be exposed to authorized users of BeyondTrust
• Access to systems on or off the network with no preconfigured VPN or other routing in place
• Passwords to be securely stored in Password Safe

The BeyondTrust ECM service enables communication between Password Safe and Remote Support. The ECM service is pre-installed with Password Safe, and configuring Secure Remote Access in Password Safe configures the API user, group, and registration. Once a Secure Remote Access connection is configured within Password Safe, users see a list of administrator-defined credentials for the endpoints they are authorized to access. A set of these credentials can be selected when challenged with a login screen during a remote session, and the user is automatically logged in, having never seen the username/password combination.

Password Safe handles all elements of securing and managing the passwords, so policies that require password rotation after use are inherently supported. Remote Support handles creating and managing the access to the endpoint, as well as recording and controlling the level of access granted to the user. This includes what the user can see and do on that endpoint.

ℹ️

Note

In the case where you need to deploy the ECM plugin separately, as opposed to using the ECM service that is bundled with Password Safe, the ECM is deployed to a hardened Windows Server inside the firewall, typically in the same network as the Password Safe instance.

If you are not using the bundled ECM plugin, Contact Support for assistance integrating BeyondTrust Remote Support and Password Safe.

Prerequisites

The following software is required:

• Password Safe Cloud or On-premises 21.2 or later release
• Remote Support
• TCP Port 443 must be open for communication between the Password Safe API and the Remote Support API

For integrations with Password Safe Cloud, a resource broker can be installed on the same server as the Jumpoint. For large scale deployments, these services may need dedicated systems.

Configure Password Safe

The integration requires minimal setup within Password Safe and is designed to work with your existing data as it stands. The following steps are required:

1. Configure the Secure Remote Access connection settings to use Password Safe as a credential source.
2. Add users to the auto-created Secure Remote Access Requesters group.
3. Enable managed accounts for API use.

Configure the Secure Remote Access connection

1. In the  BeyondInsight Console, navigate to Configuration > Secure Remote Access > Connect to Secure Remote Access.
2. Provide the Host and Port information to connect to your Remote Support instance.
3. Obtain the OAuth Client ID and OAuth Client Secret for the API account you created in Remote Support, and enter these into the Client ID and API Key fields.
4. Set the number of minutes for the Release Duration.
5. Click Update Settings.

Upon completion of this form, BeyondInsight does the following:

• Creates an all-day auto-approve access policy called Secure Remote Access Approval Policy
• Creates an API registration called Secure Remote Access Integration
• Creates a group called Secure Remote Access Requesters that uses the Secure Remote Access Approval Policy and the Secure Remote Access Integration API registration
• Configures the ECM application with the Secure Remote Access Integration API registration

ℹ️

Note

Although BeyondInsight creates a default access policy, API registration, and group to use for Secure Remote Access integration to simplify your configuration steps, you may use groups, access policies, and API registrations that you manually create, or you may modify these auto-generated ones to suit your needs.

Add users to the Secure Remote Access requesters group

1. In the BeyondInsight Console, under Role Based Access, click User Management.
2. Locate the Secure Remote Access Requesters group and click the vertical ellipsis button for the group.
3. Select View Group Details.
4. Under Group Details, select Users, and then assign users to the group.

Enable managed accounts for API use

By default, managed accounts are not accessible via the API. The accounts need to be configured to allow access through the integration.

1. In the BeyondInsight console, select Managed Accounts from the left navigation.
2. Click the vertical ellipsis button for the managed account, and then select Edit Account.
3. Under Account Settings, toggle the slider to API Enabled (yes).
4. Click Update Account.

ℹ️

Note

Admins also have the option to automate this step by adding Manage Account Settings under Actions in the smart rule, and setting the API Enabled option to yes.

Once Secure Remote Access is successfully configured and your managed accounts are enabled for API use within Password Safe, you can then access systems within Remote Support using credentials stored in Password Safe.

Configure Remote Support

Minimal configuration is necessary on the BeyondTrust Appliance B Series, as follows:

Create an OAuth API account

The Password Safe API account is used from within Password Safe to make Remote Support Command API calls to Remote Support.

1. In /login, navigate to Management > API Configuration.
2. Click Add.
3. Check Enabled.
4. Enter a name for the account.
5. OAuth Client ID and OAuth Client Secret is used during the OAuth configuration step in Autotask.
6. Set the following Permissions:
   • Command API: Full Access.
   • Reporting API: Allow Access to Access Session Reports and Recordings.
   • Endpoint Credential Manager API: Allow Access.
     • If ECM groups are enabled on the site, select which ECM Group to use. ECMs that are not associated with a group come under Default.

ℹ️

Note

The ECM Groups feature is only present if enabled when your site is built. If it is not present, contact your site administrator.

7. Click Save at the top of the page to create the account.

Configure the ECM plugin

The Endpoint Credential Manager (ECM) must be installed on a system with the following requirements:

System requirements

• Windows Vista or newer, 64-bit only
• .NET 4.5 or newer
• Processor: 2GHz or faster
• Memory: 2GB or greater
• Available Disk Space: 80GB or greater

Install the Endpoint Credential Manager

1. To begin, download the BeyondTrust Endpoint Credential Manager (ECM) from BeyondTrust Technical Support

2. Start the BeyondTrust Endpoint Credential Manager Setup Wizard.

3. Agree to the EULA terms and conditions. Mark the checkbox if you agree, and then click Install.

   If you need to modify the ECM installation path, click the Options button to customize the installation location.

ℹ️

Note

You are not allowed to proceed with the installation unless you agree to the EULA.

4. Click Next on the Welcome screen.
5. Choose a location for the credential manager, and then click Next.
6. On the next screen, you can begin the installation or review any previous step.
7. Click Install when you are ready to begin.
8. The installation takes a few moments. On the Completed screen, click Finish.

ℹ️

Note

• To ensure optimal up-time, administrators can install up to five ECMs on different Windows machines to communicate with the same site on the BeyondTrust Appliance B Series. A list of the ECMs connected to the B Series Appliance site can be found at /login > Status > Information > ECM Clients.
• When multiple ECMs are connected to a BeyondTrust site, the B Series Appliance routes requests to the ECM that has been connected to the B Series Appliance the longest.

Install and configure the plugin

1. Once the BeyondTrust ECM is installed, extract and copy the plugin files to the installation directory (typically C:\Program Files\Bomgar\ECM).

2. Run the ECM Configurator to install the plugin.

3. The Configurator should automatically detect the plugin and load it. If so, skip to step 4 below. Otherwise, follow these steps:

   1. Ensure that the DLL is not blocked. Right-click on the DLL and select Properties.
   2. On the General tab, look at the bottom of the pane. If there is a Security section with an Unblock button, click the button.
   3. Repeat these steps for any other DLLs packaged with the plugin.
   4. In the Configurator, click the Choose Plugin button and browse to the location of the plugin DLL.

4. Click the gear icon in the Configurator window to configure plugin settings.

5. The following settings are available:

Test plugin settings

You can test the settings specific to Password Safe directly from the plugin configuration screen using the Test Settings button.

The test functionality allows you to test new or updated configuration without the need to go through the representative console or to save the changes first. The form collects information to simulate a request from the B Series Appliance to the ECM. This means you can test the settings without having the ECM service running or connected to the B Series Appliance.

ℹ️

Note

While the test does simulate a request from the B Series Appliance to the ECM, it does not in any way test configuration or connectivity to the B Series Appliance. It is used only for configuration, connectivity, permissions, etc., related to the password vault system.

Console user information

The fields collected in this section simulate the information that is sent to the ECM about the user logged into the console and requesting credentials from the password vault.

• SRA console username: The username of the console user. Depending on the type of security provider and how it is configured, this might be username-only ( joe.user), which is the most common format, or it might include other information and in other formats, such as down-level domain info (ACME\joe.user) or email / UPN ([email protected]).
• Distinguished name: For LDAP Security Providers, the provider often populates the Distinguished Name of the user in addition to the username. The Distinguished Name includes domain information which is extracted by the integration and used to help identify the matching account in the password vault. An example DN is: uid=joe.user,ou=HelpDesk,dc=acme-inc,dc=com.

Jump Item information

The fields collected in this section simulate the information that is sent to the ECM about the endpoint or Jump Item to which the console user may connect.

• Jump Item type: Because different Jump Items result in different pieces of information being sent to the ECM, as well as how the ECM may query the password vault for applicable credentials, it is important to identify the type of Jump Item you wish to simulate as part of the test process.

ℹ️

Note

The Jump Client type should be used to simulate Remote Jump and Local Jump Items as well.

• Hostname / IP address: For most types of Jump Items, the primary piece of information used to find credentials in the password vault is the endpoint's hostname or IP address.
• Website URL: For Web Jump Items, rather than a hostname, the ECM is provided with the URL to which the item points. This field validates that the supplied string appears to be an actual URL.
• Additional IP address: For Jump Client items, in addition to the machine's name, the installed client also makes the machine's public and private IP addresses available to the ECM. Some integrations use this information to query for credentials in addition to or even instead of those which match the hostname value.
• Application name: For testing credential retrieval for injection into an application via an RDP + SecureApp item, the ECM is provided with both a value to identify the endpoint (Hostname / IP Address) and one to identify the specific application. The required value for Application Name may vary across integrations. The integration specific installation guides should contain more information on possible values.

Test results

If the test fails for any reason, error information is displayed to assist in diagnosing the cause of the failure. In most cases these errors are handled and then assigned a type, such as an authentication-related error, and then displayed with the inputs as well as any specific error messages. However, there may still be some instances where a particular error might not be anticipated, so the information is displayed in a more raw form.

ℹ️

Note

It's important to note that, either way, the same information is included in the Configurator.log, along with more detail as to exactly what point in the execution the failure occurred.

It's possible that the test succeeds in that it doesn't encounter any errors and yet it doesn't return any credentials. Because this is a perfectly valid result, it is not treated as an error.

In either case, if the test succeeds but the results do not match what is expected, it's important to make note of the inputs which led to those results and verify permissions and access to credentials within the password vault.

When the search does yield one or more matching credentials, the test does allow for one additional level of verification by allowing a tester to retrieve a specific credential as would occur if it were selected for injection within the console. The tester simply clicks the Retrieve Credential button in the right column of the results list, and the integration then attempts to retrieve that credential on behalf of the supplied user.

The test displays the result of the attempt to retrieve the credential, but for security reasons no password is ever displayed in clear text.

ℹ️

Note

Only credentials are retrieved; no actual passwords are retrieved or displayed. The settings used for the test are the ones currently entered on the screen, not necessarily what is saved.

Troubleshooting

To assist you, a list of common issues experienced during the integration process has been provided and steps for resolving these issues are noted.

For any issues that involve the ECM service, we recommend you enable DEBUG level logging.

1. Open the BeyondTrust-ECMService.exe.config file in a text editor.
2. Edit the file by changing the line , under the root tag, to .
3. Save the file, and then restart the ECM service.

Endpoint Credential Manager considerations

There are three possible ECM configurations:

• On-premises built in
• Cloud built in
• Standalone server

As a general rule, it is easier to use the on-premises or cloud built-in ECM integration, but a standalone ECM server is required in some installations.

In on-premises scenarios, it is easier to use built-in ECM integration as the necessary configuration is automatically generated when using the connect to SRA menu in PWS, and the ECM log is included in the support pack when generated.

In cloud scenarios, it is easier to use built-in ECM integration as the necessary configuration is automatically generated when using the connect to SRA menu in PWS, and the cloud instance spins up two ECM clients. If one were to fail, the second can be used. With two clients, the cloud instance cycles them in the event we began seeing the health check async failing, indicating comms issues, so that the configuration can be restored without user intervention.

A standalone ECM server is required to use the Optional Includes files. These provide custom configurations for a customer, when necessary to use the integration.

ℹ️

Note

To connect multiple SRA instances, the standalone server must be used along with the built in. The built in configuration can only support one instance at a time, so an additional ECM standalone server must be installed for each additional SRA instance to integrate.

ECM configuration details

ECM on-premises built in

• Configured in the config -> connect to SRA menu in PWS, requiring only the SRA Hostname and Client ID/Secret to be complete.
• Automatically creates the Secure Remote Accessors API Registration in PWS, Secure Remote Accessors User group in user management with the API registration enabled, and enables the All managed accounts Smart Group with a requestor role and default SRA access policy.
• ECM log is included within the PWS support pack when generated from the console.
• ECM Client install location is accessible on the Appliance when accessing the UVM directly, allowing the use of the ECM Configurator tool and logging.

ℹ️

Note

Use of the Optional Includes is not recommended.

ECM cloud built in

• Configured in the config -> connect to SRA menu in PWS, requiring only SRA Hostname and Client ID/Secret to be complete.
• Automatically creates the Secure Remote Accessors API Registration in PWS, Secure Remote Accessors User group in user management with the API registration enabled, and enables the All managed accounts Smart Group with a requestor role and default SRA access policy.
• Manages two ECM clients for the integration whereas the built in on-premises integration only provides one client per UVM. These ECM clients are monitored by the instance and, should they begin to fail, the clients are cycled to attempt reestablishing the integration.

ℹ️

Note

• Cannot use Optional Includes.
• Cannot use the ECM configurator tool.
• The only logs available are those found in system event viewer.
• May require support to complete integration.

ECM standalone server

• Requires the download and install of the client and Plugin on a standalone server.
• Requires the configuration of the entire ECM configurator for the integration to work, ie. SRA and PWS information to input.
• Allows the use of the Optional Includes file to provide customization to the integration should a customer have specific needs to fit in injecting credentials or needs to perform something unsupported by default.
• Allows the use of the full ECM configurator for testing, and admins can access install location to review logs.

ℹ️

Note

Subject to the server it is installed on. This can be an RB but cannot be a UVM. Remains at the version it was installed as, whereas built ins upgrade with the appliance.

Common issues and resolution steps