Password Safe

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. If enabled within the Privileged Remote Access /login administrative software, Password Safe Managed RDP and shell systems can be searched and accessed from the Privileged Remote Access desktop and web access consoles.

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 Privileged Remote Access. 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 passwords, so policies that require password rotation after use are inherently supported. Privileged Remote Access handles creating and managing 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 Privileged Remote Access and Password Safe.

Prerequisites

• Password Safe Cloud or On-premises 21.2 or later release
• Privileged Remote Access
• TCP Port 443 must be open for communication between the Password Safe API and the Privileged Remote Access API
• Searching and accessing Password Safe Managed Systems from the PRA access consoles requires:
  • A deployed Jumpoint in PRA.
  • The Password Safe installation must use the same user authentication method as Privileged Remote Access.
  • The Endpoint Credential Manager software must be version 1.6 or higher.

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 Privileged Remote Access

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 Privileged Remote Access Command API calls to Privileged Remote Access.

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 are used during the OAuth configuration step in Password Safe.

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 Group feature is only present if enabled when your site is built. If it is not present, please contact your site administrator.

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

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:

• Configure the Secure Remote Access connection settings to use Password Safe as a credential source.
• Add users to the auto-created Secure Remote Access Requesters group.
• 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 Privileged Remote Access instance.

3. Obtain the OAuth Client ID and OAuth Client Secret for the API account you created in Privileged Remote Access, 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.

2. Select the managed account, and then click the vertical ellipsis button.

3. Select Edit Account.

4. Under Account Settings, toggle the slider to API Enabled (yes).

5. 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 Privileged Remote Access using credentials stored in Password Safe.

Configure the ECM plugin

The ECM must be installed on a system with the following 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 Support.

2. Start the BeyondTrust Endpoint Credential Manager Setup Wizard.

3. Agree to the EULA terms and conditions. Check the box 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 three ECMs on different Windows machines to communicate with the same credential store. A list of the ECMs connected to the appliance site can be found at /login > Status > Information > ECM Clients.

ℹ️

Note

When ECMs are connected in a high availability configuration, the BeyondTrust Appliance B Series routes requests to the ECM in the ECM Group that has been connected to the 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\BeyondTrust\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:

   • First, ensure that the DLL is not blocked. Right-click on the DLL and select Properties.
   • On the General tab, look at the bottom of the pane. If there is a Security section with an Unblock button, click the button.
   • Repeat these steps for any other DLLs packaged with the plugin.
   • 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 access 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 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 that 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 the 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 that 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.

Search external Jump Items using PRA consoles

Prerequisites and limitations

The Password Safe and ECM integration must be fully configured before Managed Systems can be searched and accessed from PRA Consoles. The Password Safe installation must use the same user authentication method as Privileged Remote Access.

Searching and accessing Password Safe Managed Systems requires a deployed Jumpoint in PRA, as all sessions started from External Jump Items are performed using a Jumpoint. A Jumpoint must be positioned on the network to have connectivity to potentially any of the External Jump Items returned by the ECM. In the case where multiple Jumpoints are deployed on endpoints across segmented networks, the Jumpoint used may be selected automatically by matching against an External Jump Item's Network ID.

This feature is available for Managed RDP and shell systems. Web Jump is not available, but is planned for a future release.

Clustered Jumpoints can be used, and external Jump Items do not count toward the endpoint license count.

Enable external Jump Items search

Search for External Jump Items must be enabled before use.

1. In /login, navigate to Management > Security.
2. Scroll down to the Access Console section.
3. Check Allow Search for External Jump Items.
   • This setting does not take effect until the software is restarted.
   • A pop-up window provides the option to restart now by clicking Yes or to restart later by clicking No. If you click No, you can restart PRA later from the Status page in /login.
4. Select the Jumpoint for External Jump Item Sessions from the dropdown list of available Jumpoints, or leave the default selection of Automatically Selected by External Jump Item Network ID to allow PRA to determine which Jumpoint handles the session.
   • This setting is available only when Allow Search for External Jump Items is checked.
   • The External Jump Item Network ID is an attribute you must set on the Jumpoint from Jump > Jumpoint in /login. It is equivalent to the Workgroup attribute on managed systems in Password Safe. Its value is matched against the Network ID property for external Jump Items returned by the ECM to determine the Jumpoint to handle a session.
5. Optionally, enter an External Jump Item Group Name, or leave the default of External Jump Items.
   • This setting is available only when Allow Search for External Jump Items is checked.
   • This name displays as the Jump Group name when viewing Jump Items in the Access Console or the Web Access Console.
   • Click Save if you have modified the default group name.

Search for external Jump Items

Once configured and enabled, external Jumpoints can be searched in the Access Console or the Web Access Console.

1. From the console, view the list of Jump Items.
2. Select the Jump Group for external Jump Items. The name of this group is the name provided when you enabled the external Jump Items search.

ℹ️

Note

You can skip this step and run the search from the default My Jump Groups, as the search includes external Jump Items with other results.

3. No entries appear in this group until a search is run. Enter a search term or characters to see available endpoints found in Password Safe.
   • In the Access Console, details displayed about each Jump Item (endpoint) include the Hostname/IP, Jump Method (RDP or shell), and Comments. Click the Jump Item (endpoint) for additional information and the option to Jump.
   • In the Web Access Console, details displayed also include Status and Last Accessed. Click the i icon at the right end of the row for additional information and the option to Jump.

ℹ️

Note

Jump Items may display but not be available, and show the comment Jumpoint for External Jump Items not configured. This occurs when an appropriate Jumpoint for External Jump Item Sessions has not been selected when enabling external Jump Items search.

4. Once a Jump Item (endpoint) has been accessed, it is available in the Recently Used group.

Configure database connection to enable PRA dashboard in BeyondInsight

Administrators can leverage the Privileged Remote Access Dashboard in the BeyondInsight console to view session details and reports of Privileged Remote Access sessions. Administrators who utilize the existing reporting functionality of /login can continue to view session details, reports, and session recordings in the /login interface.

The Privileged Remote Access integration with BeyondInsight relies on the BeyondTrust Integration Client for session reporting data. BeyondInsight interacts with the Integration Client's BGSessions database directly.

A username and password are required to access the Integration Client's BGSessions database, and this user must have access to the BGSessions tables. We recommend this user have read-only access. Once the username and password are set up, review the below prerequisites and network considerations, and then follow the steps to configure the database connection in BeyondInsight.

ℹ️

Note

For more information on the BeyondTrust Integration Client, please see the Integration Client Guide.

Prerequisites

The following software is required:

• BeyondTrust Integration Client (version 1.7.0 or later)
• BeyondInsight (version 6.10 or later)
• Privileged Remote Access (version 19.2.1 or later)

Network considerations

TCP ports 443 and 1433 must be open.

• The BeyondTrust Integration Client uses port 443 to make API calls to Privileged Remote Access.
• The BeyondTrust Integration Client uses port 1433 to store Privileged Remote Access session data in the BGSessions SQL server database.
• BeyondInsight uses port 1433 to query the BGSessions SQL server database to retrieve Privileged Remote Access session data.

Configure database to enable Privileged Remote Access integration

1. From the home page or left menu in BeyondInsight, click Configuration.

2. Under Secure Remote Access, click Database Configuration.

3. Provide the settings to connect to your Integration Client's BGSessions database where the Privileged Remote Access session data is stored:

   • Server: Hostname or IP address for the SQL Server hosting the Integration Client’s BGSessions database.
   • Database Name: Name of the database that contains the Privileged Remote Access session data. BGSessions is default.
   • Integrated Security: If toggled to yes, the current Windows account credentials are used for authentication. If toggled to no, the username and password are specified in the connection.
   • SQL User: Username used to the access the BGSessions database.
   • SQL Password: Password for the SQL User.
   • Connection Timeout: Timeout in seconds to wait for a connection to open.
   • Query Timeout: Timeout in seconds to wait for the command to execute.

4. Click Test Connection to verify connectivity to the database.

5. Click Update Settings.

ℹ️

Note

After initial setup, you must refresh your browser for the Privileged Remote Access option to display in the left menu in BeyondInsight. Clicking the Privileged Remote Access option brings you to the Privileged Remote Access Dashboard.

View the Privileged Remote Access dashboard in BeyondInsight

1. From the left menu in BeyondInsight, click Privileged Remote Access.

2. In the Dashboard, you can quickly view a summary of Privileged Remote Access session data in each card.

3. Click the items within each card to review the specific records for that item in a grid view, which can be sorted, filtered, and exported as required.

ℹ️

Note

You can customize the Privileged Remote Access Dashboard by adding and removing tiles, and rearranging tiles from the Dashboard Editor page in BeyondInsight.

To access the Dashboard Editor, click Dashboard (Preview) the left menu in BeyondInsight, and then select Privileged Remote Access Dashboard from the Your Dashboards list.

Database recommendation

To assist with troubleshooting potential performance issues between the Privileged Remote Access Dashboard and the BGSessions database, the following indexes are recommended in the BGSessions database:

create index session__start_time_ndx on session(start_time);

create index session__host_name_ndx on session(host_name);

create index session__host_name_ndx on session(host_name);

create index session__jump_group_name_ndx on session(jump_group_name);

create index session__lsid_ndx on session(lsid);

create index session_event__type_performed_by_type_ndx on session_event(type, performed_by_type);

create index session_event__session_id_ndx on session_event(session_id);

create index session_event__type_destination_ndx on session_event(type, destination);

create index session_event__type_performed_by_ndx on session_event(type, performed_by);

create index session_event_data__session_event_id_ndx on session_event_data(session_event_id);

create index session_event_data__name_ndx on session_event_data(name);

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 <level value="INFO"/>, under the root tag, to <level value="DEBUG"/>.
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 the 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 the 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 begin 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 to reestablish 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, i.e., 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 the 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