Configure the Privileged Identity Plugin for Integration with Privileged Remote Access
You must purchase this integration separately from both your BeyondTrust Privileged Remote Access and Privileged Identity solutions. For more information, contact BeyondTrust sales.
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
- 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. Mark the checkbox if you agree, and 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 Install.
- Choose a location for the credential manager and 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 screen, click Finish.
To ensure optimal up-time, administrators can install up to five ECMs on different Windows machines to communicate with the same site on the PRA Appliance. A list of the ECMs connected to the appliance site can be found at /login > Status > Information > ECM Clients.
When multiple ECMs are connected to a BeyondTrust site, the PRA Appliance routes requests to the ECM 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\BeyondTrust\ECM).
- Run the ECM Configurator to install the plugin.
- The Configurator attempts to detect the plugin and load it. If successful, 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 BomgarPIPlugin.dll.
- After selecting the DLL, click the gear icon in the Configurator window to configure plugin settings.
- The following settings are available:
|Endpoint URL||The full URL to the PI SDK Web Services||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|
|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 SDK Web Services 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|
|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.
The settings specific to Privileged Identity can be tested directly from the plugin configuration screen using the Test Settings button.
Enter a user account from which to retrieve credentials.
- Enter an endpoint for which the user account has one or more credentials.
- View the resulting list.
No actual passwords are retrieved or displayed, only the list of credentials.
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.