Configure the Privileged Identity Plugin for Integration with Privileged Remote Access

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

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

To begin, download the BeyondTrust Endpoint Credential Manager (ECM) from BeyondTrust Support.
Start the BeyondTrust Endpoint Credential Manager Setup Wizard.
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.

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

Click Next on the Welcome screen.

Choose a location for the credential manager, and then click Next.
On the next screen, you can begin the installation or review any previous step.

Click Install when you are ready to begin.

The installation takes a few moments. On the Completed screen, click Finish.

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.

When ECMs are connected in a high availability configuration, the BeyondTrust Appliance B Seriesroutes requests to the ECM in the ECM Group that has been connected to the appliance the longest.

Install and Configure the Plugin

Once the BeyondTrust ECM is installed, extract and copy the plugin files to the installation directory (typically C:\Program Files\Bomgar\ECM).
Run the ECM Configurator to install the plugin.
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.

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

The following settings are available:

Setting Name	Description	Notes	Required
Endpoint URL	The full URL to the PI Web Service	e.g., https://<pi-server-hostname>/ERPMWebService/AuthService.svc	Yes
API User	Delegation identity created. Assign impersonation permissions for various other PI identities and/or roles		Yes
API Password	Password of the above delegation identity		Yes
API Registration Key	The Key for the API Registration created for the integration		Yes
Authenticator	The authenticator associated with the delegation identity	Typically, the NETBIOS domain name for domain accounts. Leave this blank if using an explicit account.	No
Default Domain for Local BeyondTrust Users	When a value is supplied, the plugin initially attempts to retrieve credentials for the user with the username from BeyondTrust and the configured default domain	This setting is necessary if some or all PRA users are local users but the corresponding accounts in PI are domain accounts with the same username portion.	No
Enable fall-back to local account if domain account not found	When checked, the plugin first attempts to retrieve credentials for the user as a domain user and then, if no match is found, makes a second attempt without the domain	This setting is necessary if some or all BeyondTrust users are domain users but the corresponding accounts in PI are domain accounts with the same username portion.	No
Global Approver	The username for the account created to allow automated approval of requests for credentials via the integration		Yes
Map Domains	Allows for the mapping of fully qualified domain names to their shorter NetBIOS names	This setting is necessary to match domain users in BeyondTrust to domain users in PI. BeyondTrust reports the logged-in user with the fully qualified domain name (FQDN), while PI may expect the NetBIOS name of the domain. It is also used for returning domain credentials for Windows endpoints when the domain of the endpoint is not known. These mappings must be done manually and can be entered one per line as FQDN=NetBIOS (e.g., Example.local=EX).	No
Include credentials from Shared Credential Lists	When checked, the plugin includes credentials from a shared credential list	In addition to retrieval of normal managed credentials, the integration can also retrieve endpoint-specific credentials from a shared list.	No
Include credentials where user only has Allow Remote Session permission	When checked, the plugin includes credentials for which the user only has Remote Session permissions	This setting allows for configuration of Privileged Identity users and credentials, where certain credentials are only available to the user for injection. Passwords for these credentials cannot be checked out via the web interface. It is also important to note that, because the individual users won't have the Recover Password permission, checkout and recovery of the credential also cannot take place via the API through the integration. As a result, if the user selects one of these credentials for injection, checkout must be performed as the configured API user account. If this setting is enabled, it is critical that the API user account have sufficient permissions to perform checkouts of the desired credentials.	No
If host domain is known, filter domain credentials for Windows Jump items	When checked, the plugin will filter the domain credentials based on the domain of the Windows endpoint to which the user is connecting	This setting is enabled by default to avoid returning domain credentials for other domains that likely can't be used on the endpoint. However, there may be cases where this behavior is not desired, such as in an organization where credentials exist across multiple domains, but there is also a trust relationship established between those domains. If no domain is known or reported by the configured Jump item, the default behavior to return domain credentials from all known domains remains the same whether this setting is enabled or not.	No
If host domain is known, filter local credentials for Windows Jump items	When checked, the plugin will filter the local credentials based on the domain of the Windows endpoint to which the user is connecting	This setting allows an admin to limit the potential results returned for a give Jump item by ensuring local credential results match the FQDN of the endpoint rather than just the hostname portion (normal behavior). This additional level of filtering only takes place for Windows endpoints (RDP and Jump Client items) and when the hostname and domain are both known by the ECM and plugin.	No
Include domain credentials for Shell Jump items	When checked, the plugin will include any available domain credentials when a user initiates a connection to a Shell Jump item	This allows user to inject their domain credentials (or others available to them) into Unix/Linux based systems that support them. Credentials are provided in each of the following three formats, allowing the user to select the appropriately formatted credential for injection for each Jump item: - username (only) - username@DOMAIN - DOMAIN\username	No
Include domain credentials for Web Jump items	When checked, the plugin will include any available domain credentials when a user initiates a connection to a Web Jump item	This allows users to inject their domain credentials (or others available to them) into many sites, internal or otherwise, that support them. Credentials are provided in each of the following three formats, allowing the user to select the appropriately formatted credential for injection for each Jump item: - username (only) - username@DOMAIN - DOMAIN\username	No
Prefer lookup of credentials by IP address over hostname	When checked, the plugin attempts to find credentials for the endpoint using its IP address, if available	If the IP address is not available, the plugin attempts to find credentials by using the hostname, which is the default behavior.	No
Enable creation of password spin jobs	When checked, the plugin creates password spin jobs for credentials checked out via the integration	Checking out credentials via the PI Web Service does NOT result in a spin job for managed passwords that would normally rotate when checked in via the web interface. To compensate for this, the plugin can examine the credential to see if it is set to auto-spin and then create a job to do so. No spin job is created for credentials that do not have random passwords or that are not configured to auto-spin.	No
Select your PI version	Selection determines which API calls will be made for the creation of spin jobs when session ends and a credential is released	As of PI 5.5.3.1, a new API was added which streamlines the auto-spin behavior by eliminating the need to create and configure template jobs and for the integration to manually submit new spin jobs based on those templates. The integration can now provide the details of the credential to spin and PI will handle the rest internally, mirroring the same behavior that occurs when a user checks in a Store Credential via the PI web interface. Admins can select their PI version in the plugin configuration. This will dictate which API calls are made and maintains backward compatibility for PI releases prior to 5.5.3.1.	No
Job Comment	A custom job comment can be configured to help distinguish jobs submitted as part of the integration	The string <username> replaces the username with the PI identity performing the check-out. It can be replaced anywhere in the string or removed, if desired.	No
Password Change Template Job IDs	The numeric IDs of the template job shown in the Jobs list in PI	It is recommended to create password change jobs that can be used as templates for future jobs submitted by the integration. The basic settings of these jobs are used for each subsequent job with only the password, endpoint-specific information, and scheduling being overridden. There must be a separate template job created and configured for each type of stored credential you would like to rotate. Make sure you do not delete the template jobs.	No

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.

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 (joe.user@acme-inc.com).
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.

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.

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.

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.