Privileged Identity

⚠️

Important

You must purchase this integration separately from your BeyondTrust Privileged Remote Access solution. For more information, contact BeyondTrust's Sales team.

BeyondTrust's Privileged Remote Access plugin integration with Privileged Identity enables automatic password injection to authorized systems through encrypted BeyondTrust connections, removing the need to share and expose credentials to privileged accounts. In addition to the retrieval and automatic rotation of standard credentials, the integration also has the ability to retrieve shared credential lists, giving domain admins and other privileged users access to those credentials for use on the targeted systems.

ℹ️

Note

Auto-rotation occurs only if configured.

The integration between BeyondTrust PRA and PI enables:

• One-click password injection and session spawning
• Credentials never exposed to authorized users of BeyondTrust
• Access to systems on or off the network with no pre-configured VPN or other routing in place
• Passwords always stored securely in the Privileged Identity server

The BeyondTrust Endpoint Credential Manager (ECM) enables the communication between Privileged Identity and Privileged Remote Access. The ECM is deployed to a hardened Windows Server inside the firewall, typically in the same network as Privileged Identity. Once the ECM is deployed, BeyondTrust 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 an access session, and the user is automatically logged in, having never seen the username/password combination.

Privileged Identity handles all elements of securing and managing the passwords, so policies that require the password to be rotated after use are supported with additional configuration provided by the plugin. Privileged Remote Access handles creating and managing access to the endpoint and then recording the session and controlling the level of access granted to the user, including what the user can see and do on that endpoint.

Prerequisites

To complete this integration, ensure that you have:

• the necessary software installed and configured as indicated in this guide, accounting for any network considerations. The integration is provided in the form of a plugin (ZIP archive containing the necessary DLL files and other supporting files) for use within BeyondTrust's Endpoint Credential Manager (ECM).
• acquired the proper version of the ECM to be compliant with the version of BeyondTrust Privileged Remote Access. See Configure the plugin for more information.

Applicable versions

• Privileged Remote Access: 15.x and newer
• Privileged Identity: 5.4.0 and newer

Network considerations

The following network communication channels must be open for the integration to work properly.

Configure Privileged Identity

The integration requires minimal setup within Privileged Identity and should work with your existing data as it stands. The two main requirements are a delegation identity that can impersonate Privileged Identity web users and the installation of the Privileged Identity SDK Web Services.

Delegation identity

1. Under Delegation > Web Application Identity Impersonation Mappings, select Create Mapping.
2. If an identity already exists that you would like to use for the integration, select it and skip to step three below. Otherwise, continue with the following steps:
   • Click Add Identity, and then select Explicit Identity.
   • Enter the desired username and password, and then click OK.
3. Select the desired identity, and then click OK.
4. Select the identities or roles the above user should be able to impersonate, and then click OK.
5. Verify the new mappings, and then click OK to close the dialog.

ℹ️

Note

If configuring the integration to auto-spin passwords upon check-in, the above account requires the All Access permission. If you are not using this feature, you can skip the steps listed below.

1. Go to Delegation > Web Application Global Delegation Permissions.
2. Add the All Access permission.
3. Select the identities or groups on the left to assign permission to that identity or group.
4. Check the Ignore Password Checkout box.
5. Click OK.

This permission allows users to retrieve and inject credentials regardless of whether the credential is checked out to a different user in the Privileged Identity web application. It only affects the programmatic access to checked-out credentials and does not allow them to check out a credential in the web application when in use by another user.

Privileged Identity SDK Web Services

Consult the Privileged Identity Admin Guide for instructions on installing and enabling the SDK Web Services. In newer versions of Privileged Identity, the SDK Web Services can be enabled directly from the Privileged Identity console in the Manage Web Appliance section.

Configure Privileged Remote Access

Several configuration changes are necessary on the B Series Appliance to integrate with Privileged Identity.

All of the steps in this section take place in the Privileged Remote Access /login administrative interface. Access your Privileged Remote Access interface by going to the hostname of your B Series Appliance followed by /login (e.g., https://access.example.com/login).

Create an OAuth API account

The Privileged Identity API account is used from within Privileged Identity 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 Privileged Identity.

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, contact your site administrator.

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

Allow ECM connections

**PRA 20.1 and later

1. Go to /login > Management > API Configuration.
2. Add or edit an API account.
3. Under Permissions, check Allow Access for Endpoint Credential Manager API.

Configure the plugin

Install the Endpoint Credential Manager

The Endpoint Credential Manager (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

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 Delinea 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, 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 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 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.

Clear token cache

To avoid excessive authentication calls to Privileged Identity, the plugin caches authentication tokens (in an encrypted form) for users as they attempt to retrieve secrets through the integration. Subsequent calls use the cached token until it expires. At that point, a new authentication token is retrieved and cached. The Clear Token Cache button allows an admin to clear all cached authentication tokens if such action becomes necessary for maintenance, testing, etc.

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, it is recommended to enable DEBUG level logging. To enable this setting, follow these steps.

1. Open the Bomgar-ECMService.exe config file in a text editor.
2. Edit the file by changing the line <level value="INFO"/> to <level value="DEBUG"/>.
3. Save the file and restart the ECM service.

Common issues and resolution steps